cmake：指定find_package的搜索路径

柔光的暖阳◎ 2022-11-13 04:12 803阅读 0赞

# find\_package #

找到外部项目，并加载其设置。

## 基本签名和模块模式 ##

find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
                 [REQUIRED] [[COMPONENTS] [components...]]
                 [OPTIONAL_COMPONENTS components...]
                 [NO_POLICY_SCOPE])

从外部项目查找并加载设置。

*  < PackageName >\_FOUND将被设置为指示是否找到了包。当找到包时，特定于包的信息会通过包本身记录的变量和Imported Targets提供。
 *  QUIET选项禁用信息消息，包括那些表示如果包不是REQUIRED则无法找到它的消息。如果找不到包，REQUIRED选项将停止处理，并显示一条错误消息。
 *  QUIET选项禁用信息性消息
 *  如果设置了REQUIRED选项，那么找不到包时将退出并报错

特定于包的必需组件列表可以列在components选项之后(如果存在的话，也可以列在REQUIRED选项之后)。其他可选组件可以在OPTIONAL\_COMPONENTS之后列出

\[version\]参数请求一个与找到的包兼容的版本。有两种可能的规定形式:

*  一个格式为major\[.minor\[.patch\[.tweak\]\]的单一版本。
 *  格式为versionMin…\[<\]versionMax的版本范围，其中versionMin和versionMax的格式与单个版本相同。默认情况下，包括两个端点。通过指定<，将排除上端点。仅CMake 3.19或更高版本支持版本范围。

EXACT选项要求版本完全匹配。此选项与版本范围的规范不兼容。

有关NO\_POLICY\_SCOPE选项的讨论，请参阅cmake\_policy()命令文档。

命令有两种模式用于搜索包：“模块”模式和“配置”模式。以上签名选择模块模式。如果找不到模块，命令将返回到配置模式，如下所述。如果给定了模块选项，则此回退将被禁用。

在Module模式下，CMake搜索一个名为Find< PackageName >. CMake的文件。该文件首先在CMAKE\_MODULE\_PATH中搜索，然后在CMake安装提供的Find Modules中搜索。如果找到了该文件，则由CMake读取并处理它。它负责查找包，检查版本，并生成任何需要的消息。有些查找模块提供有限或不支持版本控制；检查模块文档。

如果MODULE选项没有在上面的签名中指定，那么CMake首先使用MODULE模式搜索包。然后，如果没有找到包，它将使用Config模式再次搜索。用户可以设置变量CMAKE\_FIND\_PACKAGE\_PREFER\_CONFIG为TRUE，以便在退回到Module模式之前先使用Config模式进行CMake搜索。

## 全签名和配置模式 ##

用户代码通常应该寻找使用上述基本签名的包。此命令文档的其余部分指定完整的命令签名和搜索过程的详细信息。希望通过此命令提供一个包的项目维护者可以继续阅读。

find_package(<PackageName> [version] [EXACT] [QUIET]
                 [REQUIRED] [[COMPONENTS] [components...]]
                 [OPTIONAL_COMPONENTS components...]
                 [CONFIG|NO_MODULE]
                 [NO_POLICY_SCOPE]
                 [NAMES name1 [name2 ...]]
                 [CONFIGS config1 [config2 ...]]
                 [HINTS path1 [path2 ... ]]
                 [PATHS path1 [path2 ... ]]
                 [PATH_SUFFIXES suffix1 [suffix2 ...]]
                 [NO_DEFAULT_PATH]
                 [NO_PACKAGE_ROOT_PATH]
                 [NO_CMAKE_PATH]
                 [NO_CMAKE_ENVIRONMENT_PATH]
                 [NO_SYSTEM_ENVIRONMENT_PATH]
                 [NO_CMAKE_PACKAGE_REGISTRY]
                 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
                 [NO_CMAKE_SYSTEM_PATH]
                 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
                 [CMAKE_FIND_ROOT_PATH_BOTH |
                  ONLY_CMAKE_FIND_ROOT_PATH |
                  NO_CMAKE_FIND_ROOT_PATH])

**CONFIG选项、同义词NO\_MODULE选项或基本签名中未指定的选项的使用都强制采用纯CONFIG模式**。在纯粹的Config模式下，命令会跳过模块模式搜索而立即执行Config模式搜索。

配置模式搜索尝试查找由要查找的包提供的配置文件。

*  创建一个名为< PackageName >\_DIR的缓存项来保存包含该文件的目录。
 *  默认情况下，该命令搜索名称为< PackageName >的包。如果给出NAMES选项，则使用其后的名称，而不是< PackageName >。
 *  该命令为指定的每个名称搜索名为< PackageName >Config.cmake或< lower case package name >-Config.cmake的文件。
 *  可以使用CONFIGS选项提供可能的配置文件名的替换集。搜索程序如下所述。找到配置文件后，CMake将读取并处理该文件。因为文件是由包提供的，所以它已经知道包内容的位置。
 *  配置文件的完整路径存储在cmake变量< PackageName >\_CONFIG中。

CMake在搜索具有适当版本的软件包安装时考虑的所有配置文件都存储在CMake变量< PackageName >\_CONSIDERED\_CONFIGS中，相关版本存储在< PackageName >\_CONSIDERED\_VERSIONS.中。

如果无法找到包配置文件，除非指定了QUIET参数，否则CMake将产生描述问题的错误。如果指定了REQUIRED且没有找到包，则会生成致命错误，配置步骤会停止执行。如果< PackageName >\_DIR已经被设置为一个不包含配置文件的目录，CMake将忽略它并从头开始搜索。

我们鼓励提供CMake包配置文件的包维护人员对它们进行命名和安装，这样下面列出的Search Procedure就可以在不需要使用其他选项的情况下找到它们。

## 版本选择 ##

*  当给出\[version\]参数时，配置模式将只找到声称与请求的版本兼容的包版本（请参阅格式规范）
 *  如果提供了EXACT选项，则只能找到声明与请求版本完全匹配的包版本。
 *  CMake没有为版本号的含义建立任何约定。包版本号由包本身提供的“版本”文件检查。对于候选包配置文件< config-file>.cmake，相应的版本文件位于其旁边，并命名为< config-file >-version.cmake或 < config-file>version.cmake。
 *  如果没有此类版本文件可用，则假定配置文件与任何请求的版本不兼容。可以使用CMakePackageConfigHelpers模块创建包含通用版本匹配代码的基本版本文件。
 *  找到版本文件后，将加载该文件以检查请求的版本号。版本文件加载到嵌套范围中，其中定义了以下变量：
    
     *  PACKAGE\_FIND\_NAME：即 < PackageName >
     *  PACKAGE\_FIND\_VERSION：完整请求的版本字符串
     *  PACKAGE\_FIND\_VERSION\_MAJOR：如果请求主版本，否则为0
     *  PACKAGE\_FIND\_VERSION\_MINOR：如果要求次要版本，否则为0
     *  PACKAGE\_FIND\_VERSION\_PATCH：如果请求补丁版本，则为0
     *  PACKAGE\_FIND\_VERSION\_TWEAK：如果请求调整版本，否则0
     *  PACKAGE\_FIND\_VERSION\_COUNT：版本组件个数，0 ~ 4
 *  当指定了版本范围时，上述版本变量将根据版本范围的低端保存值。这是为了保持与未实现的软件包的兼容性，以期望版本范围。此外，版本范围将用以下变量来描述:
    
     *  PACKAGE\_FIND\_VERSION\_RANGE：完整请求的版本范围字符串
     *  PACKAGE\_FIND\_VERSION\_RANGE\_MIN：它指定是应该包含还是排除版本范围的低端端点。目前，这个变量唯一支持的值是INCLUDE。
     *  PACKAGE\_FIND\_VERSION\_RANGE\_MAX：它指定是应该包含还是排除版本范围的上端点。这个变量支持的值是INCLUDE和EXCLUDE。

## 搜索过程 ##

CMake为包构造一组可能的安装前缀。在每个前缀下搜索配置文件的多个目录。下面的表显示了搜索的目录。每一项都适用于遵循Windows (W)、UNIX (U)或Apple (A)约定的安装树:

<prefix>/                                                       (W)
    <prefix>/(cmake|CMake)/                                         (W)
    <prefix>/<name>*/                                               (W)
    <prefix>/<name>*/(cmake|CMake)/                                 (W)
    <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/                 (U)
    <prefix>/(lib/<arch>|lib*|share)/<name>*/                       (U)
    <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/         (U)
    <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/         (W/U)
    <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
    <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)

在支持macOS框架和BUNDLE的系统上，会在以下目录中搜索包含配置文件的框架或应用包:

<prefix>/<name>.framework/Resources/                    (A)
    <prefix>/<name>.framework/Resources/CMake/              (A)
    <prefix>/<name>.framework/Versions/*/Resources/         (A)
    <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
    <prefix>/<name>.app/Contents/Resources/                 (A)
    <prefix>/<name>.app/Contents/Resources/CMake/           (A)

在所有情况下，< name >被视为不区分大小写，并对应于任何指定的名称(< PackageName >或NAMES 给出的名称)。

如果设置了CMAKE\_LIBRARY\_ARCHITECTURE变量，那么带有lib/< arch >的路径将被启用。lib\*包含一个或多个值lib64、lib32、libx32或Lib(按此顺序搜索)。

*  如果FIND\_LIBRARY\_USE\_LIB64\_PATHS属性设置为TRUE，则在64位平台上搜索具有lib64的路径。
 *  如果FIND\_LIBRARY\_USE\_LIB32\_PATHS属性设置为TRUE，则在32位平台上搜索具有lib32的路径。
 *  如果FIND\_LIBRARY\_USE\_LIBX32\_PATHS属性设置为TRUE，则使用x32 ABI在平台上搜索libx32的路径。
 *  总是搜索lib路径。

如果指定了PATH\_SUFFIXES ，则将后缀逐个附加到每个(W)或(U)目录条目。

这组目录旨在与在安装树中提供配置文件的项目协同工作。上面标有（W）的目录用于Windows上的安装，其中前缀可能指向应用程序安装目录的顶部。标记为（U）的用于UNIX平台上的安装，其中前缀由多个包共享。这只是一个约定，所以所有的（W）和（U）目录仍然在所有平台上搜索。标有（A）的目录用于在Apple平台上安装。CMAKE\_FIND\_FRAMEWORK和CMAKE\_FIND\_APPBUNDLE变量决定优先次序。

安装前缀集是通过以下步骤构造的。如果指定了NO\_DEFAULT\_PATH，则启用所有NO\_\*选项。

*  3.12新版功能:搜索< PackageName >\_ROOT CMake变量和< PackageName >\_ROOT环境变量中指定的路径，其中< PackageName >是要找到的包。包的根变量被维护为一个堆栈，因此如果从一个find模块中调用，来自父模块的find模块的根路径也将在当前包的路径之后进行搜索。如果传递了NO\_PACKAGE\_ROOT\_PATH，或者将CMAKE\_FIND\_USE\_PACKAGE\_ROOT\_PATH设置为FALSE，则可以跳过这个步骤。看到CMP0074政策。
 *  在cmake特定缓存变量中指定的搜索路径。这些将用于命令行中，且值为-DVAR=value。这些值被解释为分号分隔的列表。如果传入了NO\_CMAKE\_PATH，或者将CMAKE\_FIND\_USE\_CMAKE\_PATH设置为FALSE，则可以跳过这个步骤
 *  在cmake特定环境变量中指定的搜索路径。这些是在用户的shell配置中设置的，因此使用主机的本机路径分隔符（；在Windows和：在UNIX上）。如果传入了NO\_CMAKE\_ENVIRONMENT\_PATH，或者将CMAKE\_FIND\_USE\_CMAKE\_ENVIRONMENT\_PATH设置为FALSE，则可以跳过这个步骤
 *  由提示选项指定的搜索路径。这些路径应该是由系统自省计算出来的，比如已经找到的另一个项目的位置提供的提示。硬编码猜测应该用路径选项指定。
 *  搜索标准的系统环境变量。如果传递了NO\_SYSTEM\_ENVIRONMENT\_PATH，或者将CMAKE\_FIND\_USE\_SYSTEM\_ENVIRONMENT\_PATH设置为FALSE，则可以跳过此步骤。以/bin或/sbin结尾的路径条目会自动转换为它们的父目录
 *  搜索路径存储在CMake用户包注册表。如果传递了NO\_CMAKE\_PACKAGE\_REGISTRY变量，或者将变量CMAKE\_FIND\_USE\_PACKAGE\_REGISTRY设置为FALSE，或者将已弃用的变量CMAKE\_FIND\_PACKAGE\_NO\_PACKAGE\_REGISTRY设置为TRUE，则可以跳过这个变量。关于用户包注册表的详细信息，请参见cmake-packages(7)手册。
 *  搜索cmake变量在平台文件中定义的当前系统。如果传入了NO\_CMAKE\_SYSTEM\_PATH，或者将CMAKE\_FIND\_USE\_CMAKE\_SYSTEM\_PATH设置为FALSE，则可以跳过这个步骤
 *  检索路径存储在CMake系统包注册表。如果传递了NO\_CMAKE\_SYSTEM\_PACKAGE\_REGISTRY变量，或者将CMAKE\_FIND\_USE\_SYSTEM\_PACKAGE\_REGISTRY变量设置为FALSE，或者将CMAKE\_FIND\_PACKAGE\_NO\_SYSTEM\_PACKAGE\_REGISTRY变量设置为TRUE，则可以跳过这个变量。
 *  搜索由PATHS选项指定的路径。这些通常是硬编码的猜测。

3.16新版功能:添加了CMAKE\_FIND\_USE\_\_PATH变量来全局禁用各种搜索位置。

CMake变量CMAKE\_FIND\_ROOT\_PATH指定一个或多个要添加到所有其他搜索目录的目录。这有效地“重新根”了给定位置下的整个搜索。CMAKE\_STAGING\_PREFIX的后代路径将被排除在重新生根之外，因为该变量始终是主机系统上的路径。默认情况下，CMAKE\_FIND\_ROOT\_PATH为空。

CMAKE\_SYSROOT变量还可以用来指定一个目录作为前缀。设置CMAKE\_SYSROOT还有其他效果。有关该变量的更多信息，请参见文档。

当交叉编译指向目标环境的根目录时，这些变量特别有用，CMake也会在那里进行搜索。默认情况下，首先搜索CMAKE\_FIND\_ROOT\_PATH中列出的目录，然后搜索CMAKE\_SYSROOT目录，然后搜索非根目录。默认行为可以通过设置CMAKE\_FIND\_ROOT\_PATH\_MODE\_PACKAGE进行调整。这个行为可以在每次调用的基础上使用选项手动重写:

*  CMAKE\_FIND\_ROOT\_PATH\_BOTH：按上面描述的顺序进行搜索。
 *  NO\_CMAKE\_FIND\_ROOT\_PATH：不要使用CMAKE\_FIND\_ROOT\_PATH变量。
 *  ONLY\_CMAKE\_FIND\_ROOT\_PATH：只搜索重新根目录和CMAKE\_STAGING\_PREFIX下面的目录。

默认搜索顺序被设计为最特定于最不特定于常见用例。项目可以通过多次调用该命令并使用NO\_\*选项来覆盖该命令:

find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH)
    find_package (<PackageName>)

一旦其中一个调用成功，结果变量将被设置并存储在缓存中，以便不再进行调用搜索。

默认情况下，存储在结果变量中的值将是找到文件的路径。在调用find\_package之前，CMAKE\_FIND\_PACKAGE\_RESOLVE\_SYMLINKS变量可以设置为TRUE，以便解析符号链接并存储文件的真实路径。

每个非必需的find\_package调用都可以通过将CMAKE\_DISABLE\_FIND\_PACKAGE\_变量设置为TRUE来禁用。

# 使用示例 #

find_package(OpenCV
            PATHS /opt/opencv
            NO_DEFAULT_PATH
            REQUIRED)
    if (OpenCV_FOUND)
        include_directories(${
        OpenCV_INCLUDE_DIRS})
        message( ${
        OpenCV_LIBS})
    else()
        message("OpenCV not found, so we won't build the project.")
    endif()