FindBoost¶

變更於版本 3.30: 只有在策略 CMP0167 未設定為 NEW 時，此模組才可用。將專案移植到上游 Boost 的 BoostConfig.cmake 套件組態檔，find_package(Boost) 現在會搜尋該檔案。

尋找 Boost 包含目錄和函式庫

透過調用 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 包含目錄。
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: X.Y.Z 格式的 Boost 版本號碼。
Boost_VERSION: X.Y.Z 格式的 Boost 版本號碼（與 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: 包含發行版本 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）。

即使在使用 find_package() 時未指定 system，且 Boost::system 未新增到 target_link_libraries()，也會自動偵測並滿足隱含相依性，例如需要 Boost::system 的 Boost::filesystem。如果使用 Boost::thread，則也會自動新增 Threads::Threads。

重要的是要注意，匯入的目標的行為與此模組建立的變數不同：在相同目錄或子目錄中使用不同選項（例如 static 或 shared）多次調用 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 棄用的 "native iostreams" 編譯的函式庫（"n" 標籤）。預設值為 OFF。
Boost_COMPILER: 設定為編譯器特定的函式庫後綴（例如 -gcc43）。預設值會針對使用的 C++ 編譯器自動計算。

變更於版本 3.9: 如果應測試多個相容後綴，可以使用列表，優先順序遞減。
Boost_LIB_PREFIX: 新增於版本 3.18。

設定為平台特定的函式庫名稱前綴（例如 lib），Boost 靜態函式庫使用該前綴。這僅在 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 以解析已發現函式庫的符號連結，以協助封裝。例如，"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 標頭和一些靜態（僅發行版本）函式庫

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。