cmake：指定find_package的搜索路径

find_package

找到外部项目，并加载其设置。
https://blog.csdn.net/zhizhengguan/article/details/111714160

全签名和配置模式

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)
/.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()