FindBoost

3.30 版中更改： 当策略 CMP0167 未设置为 NEW 时，此模块才可用。将项目移植为上游 Boost 的 BoostConfig.cmake 软件包配置文件， find_package(Boost) 现在用来对此配置文件进行搜索。

查找 Boost include 目录和库

通过使用 find_package() 调用此模块，采用以下形式

find_package(Boost
  [version] [EXACT]      # Minimum or EXACT version e.g. 1.67.0
  [REQUIRED]             # Fail with error if Boost is not found
  [COMPONENTS <libs>...] # Boost libraries by their canonical name
                         # e.g. "date_time" for "libboost_date_time"
  [OPTIONAL_COMPONENTS <libs>...]
                         # Optional Boost libraries by their canonical name)
  )                      # e.g. "date_time" for "libboost_date_time"

此模块查找头文件和要求的组件库或由“Boost CMake”构建提供的 CMake 软件包配置文件。对于后一种情况，跳过以下 Boost CMake 部分。

3.7 版本中新增： bzip2 和 zlib 组件（仅 Windows）。

3.11 版本中新增： OPTIONAL_COMPONENTS 选项。

3.13 版本中新增： stacktrace_* 组件。

3.19 版本中新增： bzip2 和 zlib 组件（所有平台）。

结果变量

此模块定义以下变量

Boost_FOUND

如果找到了头文件和要求的库，则为 True。

Boost_INCLUDE_DIRS

Boost include 目录。

Boost_LIBRARY_DIRS

Boost 库的链接目录。

Boost_LIBRARIES

要链接的 Boost 组件库。

Boost_<COMPONENT>_FOUND

如果找到了组件 <COMPONENT>，则为 True（<COMPONENT> 名称是大写的）。

Boost_<COMPONENT>_LIBRARY

要链接到组件 <COMPONENT> 的库（可能包含 target_link_libraries() 调试/优化的关键字）。

Boost_VERSION_MACRO

BOOST_VERSION 来自 boost/version.hpp 的值。

Boost_VERSION_STRING

以 X.Y.Z 格式表示的 Boost 版本号。

Boost_VERSION

以 X.Y.Z 格式表示的 Boost 版本号（与 Boost_VERSION_STRING 相同）。

在 3.15 版本中更改： 在之前的 CMake 版本中，此变量使用了 Boost header（与 Boost_VERSION_MACRO 相同）中的原始版本字符串。参见策略 CMP0093。

Boost_LIB_VERSION

追加到库文件名的版本字符串。

Boost_VERSION_MAJOR, Boost_MAJOR_VERSION

Boost 主版本号（X.Y.Z 中的 X）。

Boost_VERSION_MINOR, Boost_MINOR_VERSION

Boost 次版本号（X.Y.Z 中的 Y）。

Boost_VERSION_PATCH, Boost_SUBMINOR_VERSION

Boost 子次版本号（X.Y.Z 中的 Z）。

Boost_VERSION_COUNT

版本组件数量 (3)。

Boost_LIB_DIAGNOSTIC_DEFINITIONS（特定于 Windows）

传递给 add_definitions() 在编译期间显示关于 Boost 自动链接的诊断信息

在 3.15 版本中添加： Boost_VERSION_<PART> 变量。

缓存变量

搜索结果会以 CMake 缓存项的形式永久保存

Boost_INCLUDE_DIR

包含 Boost 头文件的目录。

Boost_LIBRARY_DIR_RELEASE

包含发布版 Boost 库的目录。

Boost_LIBRARY_DIR_DEBUG

包含调试版 Boost 库的目录。

Boost_<COMPONENT>_LIBRARY_DEBUG

组件 <COMPONENT> 库调试变体。

Boost_<COMPONENT>_LIBRARY_RELEASE

组件 <COMPONENT> 库发布变体。

在 3.3 版本中添加： 针对每个配置的变量 Boost_LIBRARY_DIR_RELEASE 和 Boost_LIBRARY_DIR_DEBUG。

提示

该模块从变量中读取关于搜索位置的提示

BOOST_ROOT, BOOSTROOT

首选安装前缀。

BOOST_INCLUDEDIR

首选包含目录，例如 <prefix>/include。

BOOST_LIBRARYDIR

首选库目录，例如 <prefix>/lib。

Boost_NO_SYSTEM_PATHS

设置为 ON 以禁用在这些提示变量未指定的位置进行搜索。默认值为 OFF。

Boost_ADDITIONAL_VERSIONS

此模块不知道的 Boost 版本列表。（Boost 安装位置可能包含版本）。

用户可以将这些提示或结果设置为 CACHE 条目。项目不应该直接读取这些条目，而是应该使用上述结果变量。请注意，某些提示名称以大写 BOOST 开头。如果未指定为 CMake 变量或缓存条目，则可以在这些提示中指定为环境变量。

此模块首先使用上述提示变量（不包括 BOOST_LIBRARYDIR）搜索 Boost 头文件，并将结果保存在 Boost_INCLUDE_DIR 中。然后，它使用上述提示（不包括 BOOST_INCLUDEDIR 和 Boost_ADDITIONAL_VERSIONS）、Boost_INCLUDE_DIR 附近的“lib”目录以及以下库名称配置设置来搜索请求的组件库。它将库目录保存在 Boost_LIBRARY_DIR_DEBUG 和 Boost_LIBRARY_DIR_RELEASE 中，并将各个库位置保存在 Boost_<COMPONENT>_LIBRARY_DEBUG 和 Boost_<COMPONENT>_LIBRARY_RELEASE 中。当有人更改同一构建树中先前搜索使用的设置（不包括环境变量）时，此模块将放弃受更改影响的先前搜索结果，然后重新搜索。

导入的目标

在 3.5 版本中添加。

此模块定义以下 IMPORTED 目标

Boost::boost

目标，仅适用于头文件依赖项。（Boost 包含目录）。

Boost::headers

在 3.15 版本中添加： Boost::boost 的别名。

Boost::<component>

特定组件依赖项（共享库或静态库）的目标； <component> 名称是 “小写” 的。

Boost::diagnostic_definitions

接口目标，用于在编译期间启用有关 Boost 自动链接的诊断信息（添加 -DBOOST_LIB_DIAGNOSTIC）。

Boost::disable_autolinking

接口目标，用于禁用与 MSVC 的自动链接（添加 -DBOOST_ALL_NO_LIB）。

Boost::dynamic_linking

接口目标，用于启用与 MSVC 的动态链接（添加 -DBOOST_ALL_DYN_LINK）。

将自动检测并满足隐式依赖项，例如需要 Boost::system 的 Boost::filesystem，即使在使用 find_package() 时未指定 system，并且未将 Boost::system 添加到 target_link_libraries() 中。如果使用 Boost::thread，那么也将自动添加 Threads::Threads。

请务必注意，导入的目标与该模块创建的变量的表现不同：在同一目录或子目录中使用不同的选项（例如静态或共享）多次调用 find_package(Boost) 不会覆盖第一次调用创建的目标值。

其他变量

Boost 库有许多变体，以其文件名进行编码。用户或项目可以通过设置变量来告知模块找到哪个变体

Boost_USE_DEBUG_LIBS

添加到 3.10 版本。

设置为 ON 或 OFF 以指定是否搜索和使用调试库。默认值为 ON。

Boost_USE_RELEASE_LIBS

添加到 3.10 版本。

设置为 ON 或 OFF 以指定是否搜索和使用发布库。默认值为 ON。

Boost_USE_MULTITHREADED

设置为 OFF 以使用非多线程库（“mt”标记）。默认设置为 ON。

Boost_USE_STATIC_LIBS

设置为 ON 以强制使用静态库。默认值为 OFF。

Boost_USE_STATIC_RUNTIME

设置为 ON 或 OFF 以指定是否使用以静态方式链接到 C++ 运行时的库（“s”标记）。默认值取决于平台。

Boost_USE_DEBUG_RUNTIME

设置为 ON 或 OFF 以指定是否使用链接到 MS 调试 C++ 运行时的库（“g”标记）。默认设置为 ON。

Boost_USE_DEBUG_PYTHON

设置为 ON 以使用通过调试 Python 构建编译的库（“y”标记）。默认值为 OFF。

Boost_USE_STLPORT

设置为 ON 以使用通过 STLPort（“p”标记）编译的库。默认值为 OFF。

Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS

设置为 ON 以使用通过 STLPort 弃用的“本地 iostreams”（“n”标记）编译的库。默认值为 OFF。

Boost_COMPILER

设置为特定于编译器的库后缀（例如 -gcc43）。默认值为自动计算正在使用的 C++ 编译器。

在 3.9 版本中更改：如果需要测试多个兼容的后缀，则可以使用一个列表，按偏好程度递减。

Boost_LIB_PREFIX

添加到 3.18 版本。

设置为 Boost 静态文件使用的平台特定库名称前缀（例如 lib）。仅在 CMake 默认情况下不知道前缀的平台上需要这样做。

Boost_ARCHITECTURE

添加到 3.13 版本。

设置为特定于架构的库后缀（例如 -x64）。默认值为自动计算正在使用的 C++ 编译器。

Boost_THREADAPI

用于 thread 组件库名称的后缀，例如 pthread 或 win32。将同时尝试带和不带此后缀的名称。

Boost_NAMESPACE

用于构建 boost 的备用名称空间，例如，如果设置为 myboost，将搜索 myboost_thread 而非 boost_thread。

可以用来控制此模块的其他变量有

Boost_DEBUG

设置为 ON 以启用 FindBoost 的调试输出。请在此之前启用在提交任何故障报告。

Boost_REALPATH

设置为 ON 以解决已发现库的符号链接，以协助打包。例如，“系统”组件库可能会解析为 /usr/lib/libboost_system.so.1.67.0 而不是 /usr/lib/libboost_system.so。这不会影响链接，且在用户不需要这些信息的情况下不应启用它。

Boost_LIBRARY_DIR

为 Boost_LIBRARY_DIR_RELEASE 和 Boost_LIBRARY_DIR_DEBUG 的默认值。

Boost_NO_WARN_NEW_VERSIONS

在版本 3.20 中添加。

设置为 ON 以禁止有关未知依赖项的警告，这些警告针对的是 Boost 新版本。

在 Visual Studio 和 Borland 编译器上，Boost 头文件请求与对应库进行自动链接。这需要明确地链接匹配的库，或在链接库搜索路径中提供匹配的库。在此情况下，将 Boost_USE_STATIC_LIBS 设置为 OFF 可能无法实现动态链接。Boost 自动链接通常请求静态库，但有若干例外（例如 Boost.Python）。使用

add_definitions(${Boost_LIB_DIAGNOSTIC_DEFINITIONS})

请求 Boost 报告有关自动链接请求的信息。

示例

仅查找 Boost 头文件

find_package(Boost 1.36.0)
if(Boost_FOUND)
  include_directories(${Boost_INCLUDE_DIRS})
  add_executable(foo foo.cc)
endif()

查找 Boost 库并使用导入的目标

find_package(Boost 1.56 REQUIRED COMPONENTS
             date_time filesystem iostreams)
add_executable(foo foo.cc)
target_link_libraries(foo Boost::date_time Boost::filesystem
                          Boost::iostreams)

查找 Boost Python 3.6 库并使用导入的目标

find_package(Boost 1.67 REQUIRED COMPONENTS
             python36 numpy36)
add_executable(foo foo.cc)
target_link_libraries(foo Boost::python36 Boost::numpy36)

查找 Boost 头文件和一些静态（仅发行版）库

set(Boost_USE_STATIC_LIBS        ON)  # only find static libs
set(Boost_USE_DEBUG_LIBS        OFF)  # ignore debug libs and
set(Boost_USE_RELEASE_LIBS       ON)  # only find release libs
set(Boost_USE_MULTITHREADED      ON)
set(Boost_USE_STATIC_RUNTIME    OFF)
find_package(Boost 1.66.0 COMPONENTS date_time filesystem system ...)
if(Boost_FOUND)
  include_directories(${Boost_INCLUDE_DIRS})
  add_executable(foo foo.cc)
  target_link_libraries(foo ${Boost_LIBRARIES})
endif()

Boost CMake

如果使用 boost-cmake 项目或从 Boost 1.70.0 构建 Boost，则它会提供一个包配置文件以与 find_package 的配置模式一起使用。此模块会寻找称为 BoostConfig.cmake 或 boost-config.cmake 的包配置文件，并将结果存储在 CACHE 条目 Boost_DIR 中。找到后，将加载包配置文件，此模块将返回且不执行进一步的操作。有关它提供的详细信息，请查看 Boost CMake 包配置的文档。

将 Boost_NO_BOOST_CMAKE 设置为 ON，禁用对 boost-cmake 的搜索。