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()
的 debug/optimized 关键字)。Boost_VERSION_MACRO
来自
boost/version.hpp
的BOOST_VERSION
值。Boost_VERSION_STRING
Boost 版本号,格式为
X.Y.Z
。Boost_VERSION
Boost 版本号,格式为
X.Y.Z
(与Boost_VERSION_STRING
相同)。3.15 版本已更改: 在之前的 CMake 版本中,此变量使用 Boost 头文件中的原始版本字符串(与
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
包含 Release 版本 Boost 库的目录。
Boost_LIBRARY_DIR_DEBUG
包含 Debug 版本 Boost 库的目录。
Boost_<COMPONENT>_LIBRARY_DEBUG
组件
<COMPONENT>
的 Debug 版本库。Boost_<COMPONENT>_LIBRARY_RELEASE
组件
<COMPONENT>
的 Release 版本库。
3.3 版本已添加: 每个配置的变量 Boost_LIBRARY_DIR_RELEASE
和 Boost_LIBRARY_DIR_DEBUG
。
提示¶
此模块从以下变量读取搜索位置的提示。
BOOST_ROOT
,BOOSTROOT
首选安装前缀。
BOOST_INCLUDEDIR
首选 include 目录,例如
<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 include 目录)。
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::filesystem
需要 Boost::system
,即使在使用 find_package()
时未指定 system,并且 Boost::system
未添加到 target_link_libraries()
中,也会自动检测并满足。如果使用 Boost::thread
,则 Threads::Threads
也会被自动添加。
重要的是要注意,导入的目标的行为与此模块创建的变量不同:在同一目录或子目录中多次调用具有不同选项(例如静态或共享)的 find_package(Boost)
不会覆盖第一次调用创建的目标值。
其他变量¶
Boost 库在其文件名中有许多变体。用户或项目可以通过设置变量来告诉此模块查找哪个变体。
Boost_USE_DEBUG_LIBS
3.10 版本新增。
设置为
ON
或OFF
可指定是否搜索和使用 Debug 库。默认为ON
。Boost_USE_RELEASE_LIBS
3.10 版本新增。
设置为
ON
或OFF
可指定是否搜索和使用 Release 库。默认为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 Debug C++ 运行时链接的库(“g”标签)。默认为ON
。Boost_USE_DEBUG_PYTHON
设置为
ON
可使用与 Debug Python 构建一起编译的库(“y”标签)。默认为OFF
。Boost_USE_STLPORT
设置为
ON
可使用与 STLPort 一起编译的库(“p”标签)。默认为OFF
。Boost_USE_STLPORT_DEPRECATED_NATIVE_IOSTREAMS
设置为 ON 可使用与 STLPort 已弃用的“native 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
的调试输出。请在提交任何 bug 报告之前启用此选项。Boost_REALPATH
设置为
ON
以解析发现的库的符号链接,以协助打包。例如,“system”组件库可能会解析为/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 头文件和一些 *静态*(仅 Release)库
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 是使用 boost-cmake 项目或从 Boost 1.70.0 及更高版本构建的,它会提供一个包配置文件,供 find_package 的 config 模式使用。此模块查找名为 BoostConfig.cmake
或 boost-config.cmake
的包配置文件,并将结果存储在 CACHE
条目 Boost_DIR
中。如果找到,则加载包配置文件,此模块将不再执行任何操作。有关 Boost CMake 包配置文件提供的功能的详细信息,请参阅其文档。
将 Boost_NO_BOOST_CMAKE
设置为 ON
,以禁用对 boost-cmake 的搜索。