cmake find_path

最新推荐文章于 2025-08-18 18:18:09 发布

原创最新推荐文章于 2025-08-18 18:18:09 发布 · 4.1k 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#cmake

make/cmake 专栏收录该内容

2 篇文章

订阅专栏

本文详细介绍了CMake中find_path命令的使用方法及其在寻找头文件时遇到的问题。当试图搜索libuio.h时，发现find_path不会在指定路径下递归搜索。解决方法包括直接指定完整路径或使用PATH_SUFFIXES选项添加额外子路径。CMake的搜索路径包括默认路径、HINTS、PATHS等多个层级，并可以通过NO_*选项调整搜索顺序。理解并正确使用find_path对于CMake项目配置至关重要。

记录一个camke find_path无法找到指定文件问题

问题描述

现象

尝试使用以下语句搜索 libuio.h头文件

find_path(LIBUIO_INCLUDE_DIR          
  NAMES                               
      libuio.h                        
  PATHS                               
    /home/xx/work/libuio
)

libuio.h文件实际所在文件路径

/home/xx/work/libuio/libuio

问题说明

预期：按照find_path语法猜测，cmake是在PATHS中指定的路径搜索NAMES指定的文件，效果应该与直接执行find命令一致。但是实际并未按照预期搜索得到想要的头文件
实际情况：find_path并不会在指定的路径中递归搜索

解决方法

解决方案1：指定完整路径

find_path(LIBUIO_INCLUDE_DIR          
  NAMES                               
      libuio.h                        
  PATHS                               
    /home/chehejia/work/libuio/libuio
)

解决方案2：使用`PATH_SUFFIXES`选项

该选项使用场景举例：

如指定搜索路径为/usr，PATH_SUFFIXES为include，则会搜索/usr和/usr/include两个路径

find_path(LIBUIO_INCLUDE_DIR          
  NAMES                               
      libuio.h                        
  PATHS                               
    /home/chehejia/work/libuio
  PATH_SUFFIXES
   libuio
)

官方文档说明

官方文档地址：https://cmake.org/cmake/help/latest/command/find_path.html

find_path(v3.22.1)

find_path (<VAR> name1 [path1 path2 ...])

find_path (
          <VAR>
          name | NAMES name1 [name2 ...]
          [HINTS [path | ENV var]... ]
          [PATHS [path | ENV var]... ]
          [PATH_SUFFIXES suffix1 [suffix2 ...]]
          [DOC "cache documentation string"]
          [NO_CACHE]
          [REQUIRED]
          [NO_DEFAULT_PATH]
          [NO_PACKAGE_ROOT_PATH]
          [NO_CMAKE_PATH]
          [NO_CMAKE_ENVIRONMENT_PATH]
          [NO_SYSTEM_ENVIRONMENT_PATH]
          [NO_CMAKE_SYSTEM_PATH]
          [CMAKE_FIND_ROOT_PATH_BOTH |
           ONLY_CMAKE_FIND_ROOT_PATH |
           NO_CMAKE_FIND_ROOT_PATH]
         )

说明：
此命令用于查找包含指定文件名的目录。

搜索结果被保存到一个cache entry中，如果指定了NO_CACHE选项，则保存到普通变量<VAR>中

如果没有找到指定文件，则设置结果为<VAR>-NOTFOUND。

选项说明

NAMES ：
指定一个或多个可能的文件名。
当使用此选项指定包含或不包含版本后缀的文件时，我们建议首先指定unversioned name，以便本地构建的软件包可以优先系统软件包被找到。

HINTS，PATHS
指定默认搜索路径之外的额外搜索路径
ENV var子选项，从系统环境变量读取路径

PATH_SUFFIXES
指定搜索路径中的额外子路径
举例，如指定文件名为某头文件a.h，指定搜索路径为/usr，指定PATH_SUFFIXES为include，则除了在/usr目录中查找a.h文件之外，还在/usr/include中查找该文件。默认不递归搜索

DOC
为<VAR>cache entry指定文档字符串

NO_CACHE
3.21版本新特性
搜索结果保存在正常变量而不是cache entry中

REQUIRED
3.18版本新特性
如果未搜索到指定文件，则抛出错误消息，并停止cmake执行过程

搜索路径
如果指定NO_DEFAULT_PATH，则不会增加额外的搜索路径，如果未指定该变量，则搜索执行流程如下：
1. New in version 3.12：如果是从find_package或find等流程中调用，
则顺序为：<CurrentPackage>_ROOT, ENV{<CurrentPackage>_ROOT}, <ParentPackage>_ROOT, ENV{ParentPackage}_ROOT
如果配置了NO_PACKAGE_ROOT_PATH或将CMAKE_FIND_USE_PACKAGE_ROOT_PATH设置成FALSE，则将跳过该步骤搜索
具体路径为
<prefix>/include/<arch>
<prefix>/include，其中prefix为<PackageName>_ROOTcmake变量和<PackageName>_ROOT环境变量中包含的所有package的prefix路径

2. 搜索cmake指定的cache变量：为了在命令行中指定变量使用，如-DVAR=value，value按都好分割的列表的方式解析
如果配置了NO_CMAKE_PATH或将CMAKE_FIND_USE_CMAKE_PATH设置成FALSE，则将跳过该步骤搜索

3. 搜索camke指定的cmake环境变量：用于使用用户在shell中配置的cmake环境变量
如果配置了NO_CMAKE_ENVIRONMENT_PATH或将CMAKE_FIND_USE_CMAKE_ENVIRONENT_PATH设置成FALSE，则将跳过该步骤搜索

4. 搜索HINTS选项指定的路径：这些应该是由系统推测的路径，例如由已经找到的另一个项的位置提供的提示。硬编码的猜测应该用PATHS选项指定。
5. 搜索标准的系统环境变量：
如果配置了NO_SYSTEM_ENVIRONMENT_PATH或将CMAKE_FIND_USE_SYSTEM_ENVIRONENT_PATH设置成FALSE，则将跳过该步骤搜索

6. 搜索当前系统平台文件中定义的cmake变量：
如果配置了NO_CMAKE_SYSTEM_PATH或将CMAKE_FIND_USE_CMAKE_SYSTEM_PATH设置成FALSE，则将跳过该步骤搜索

7. 搜索PATHS选项中定义的路径

CMake变量CMAKE_FIND_ROOT_PATH指定一个或多个目录作为所有其他搜索目录的前缀。该变量re-root了整个搜索过程到指定位置。默认情况下，CMAKE_FIND_ROOT_PATH为空。
CMAKE_SYSROOT变量也可以用来指定一个目录作为搜索目录前缀
上述两个变量在交叉编译时，用于指定搜索根路径很有用。
默认先搜索CMAKE_FIND_ROOT_PATH，之后搜索CMAKE_SYSROOT，最后搜索其他non-rooted路径
通过配置CMAKE_FIND_ROOT_PATH_MODE_INCLUDE变量修改上述搜索行为：
CMAKE_FIND_ROOT_PATH_BOTH：按上述顺序搜索
NO_CMAKE_FIND_ROOT_PATH：不搜索CMAKE_FIND_ROOT_PATH指定的路径
ONLY_CMAKE_FIND_ROOT_PATH：只搜索re-rooted目录和CMAKE_STAGING_PREFIX路径下的目录
默认的搜索顺序设计时考虑了最常用到最不常用的场景，实际工程中可以通过调用多次带有NO_*选项的命令来修改搜索顺序。一旦搜索成功，则结果将被缓存下来。
find_path (<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
find_path (<VAR> NAMES name)