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）。

會自動偵測並滿足隱含的相依性，例如需要 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 版本中新增。

設定為平台特定的函式庫名稱前綴（例如 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 的組態模式。此模組會尋找名為 BoostConfig.cmake 或 boost-config.cmake 的套件組態檔案，並將結果儲存在 CACHE 項目 Boost_DIR 中。如果找到，則會載入套件組態檔案，且此模組會傳回而不執行其他動作。有關其提供的詳細資訊，請參閱 Boost CMake 套件組態的文件。

將 Boost_NO_BOOST_CMAKE 設定為 ON，以停用搜尋 boost-cmake。