CMake 專案中的 vcpkg

vcpkg 提供與 CMake 的無縫整合，以自動在您的專案中提供已安裝的套件。 vcpkg 整合的機制是藉由提供 CMake 工具鏈檔案。

CMake 第一次設定專案時，它會執行內部搜尋例程來尋找可行的 工具鏈 （編譯程式、鏈接器等）。 此搜尋會在您的project()函數的CMakeLists.txt內發生。

若要自定義工具鏈選取程式，CMake 支援使用自定義 CMake 語言腳本，稱為工具鏈檔案。 藉由設定 CMAKE_TOOLCHAIN_FILE 變數來指定工具鏈檔案。 CMake 會評估所提供工具鏈腳本的內容，並設定變數定義、必要建置工具的路徑，以及其他建置參數，例如交叉編譯旗標。

當您設定 CMAKE_TOOLCHAIN_FILE 為使用 vcpkg 工具鏈 （<vcpkg-root>/scripts/buildsystems/vcpkg.cmake）， vcpkg 會利用工具鏈檔案機制來插入程式代碼，以透明方式與內建 CMake 函式整合。

您仍然可以使用工具鏈檔案來設定自己的工具組，方法是使用 VCPKG_CHAINLOAD_TOOLCHAIN_FILE triplet 變數。

vcpkg 整合的運作方式會根據您使用的作業模式而有所不同：

在 傳統模式中，vcpkg 會適當地設定 CMake 搜尋路徑，使已安裝的套件可以透過find_package()、find_library()和find_path()等函式使用。

在 指令清單模式中，除了上述專案之外，工具鏈也會偵測指令清單檔（vcpkg.json 檔案）並執行 vcpkg install ，以自動取得專案的相依性。

由於工具鏈檔案在 project() 呼叫時會被評估，因此所有會修改 vcpkg 設定的 CMake 層級變數必須在第一次呼叫 project() 之前設定。 如果您修改任何導致 ABI 哈希變更的 vcpkg 設定，可能也需要重新設定 CMake 專案。

如需使用 CMake 的完整範例，請參閱 安裝和使用套件範例：sqlite 。

CMAKE_TOOLCHAIN_FILE

注意

如果您在檔案CMAKE_TOOLCHAIN_FILE中設定 CMakeList.txt ，請確定變數是在呼叫 project()之前設定的。

設定為使用 vcpkg 工具鏈檔案的項目（透過 CMake 設定 CMAKE_TOOLCHAIN_FILE）可以使用標準 CMake 函式從 vcpkg 尋找連結庫： find_package()、 find_path()和 find_library()。

建議您使用 CMake 預設值 來指定您的工具鏈檔案。 例如，如果您已定義環境變數 VCPKG_ROOT，您可以使用下列 CMakePresets.json 命令，並在設定行上傳遞 --preset debug ：

{
  "version": 2,
  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

cmake -B build -S /my/project --preset debug

如果您需要使用目前電腦專屬 vcpkg 的絕對路徑，您可以使用 CMakeUserPresets.json 並將它新增至檔案 .gitignore 。

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "debug",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

3.19 之前的 CMake 版本必須在設定命令行上傳遞工具鏈檔案：

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

使用函式庫

vcpkg 支援 CMake 的原生機制來尋找連結庫： find_package()、 find_library()和 find_path()。 安裝具有特定 CMake 支援的連結庫時，vcpkg 會顯示如何使用連結庫的使用資訊：

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

vcpkg 不會自動將任何 include 或 links 路徑新增至您的專案。 若要使用僅限標頭的連結庫，您可以使用可在所有平台上正確運作 find_path() 的連結庫：

# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

IDE 整合

Visual Studio/Visual Studio 代碼

建議您在 Visual Studio 和 Visual Studio Code 中使用 CMake 預設值 。

若要深入瞭解，請參閱在Visual Studio中使用 CMake 預設值進行設定和建置，以及在Visual Studio Code 中使用 CMake 預設值進行設定和建置。

CLion

開啟工具鏈設定 （File > Settings 在 Windows 和 Linux 上， CLion > Preferences 在 macOS 上），然後移至 CMake 設定 （Build, Execution, Deployment > CMake）。 在 中 CMake options，新增下列這一行：

-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

您必須將這一行分別新增至每個配置檔。

使用多個工具鏈檔案

若要將 vcpkg 的工具鏈檔案與其他工具鏈檔案結合，您可以設定 CMake 快取變數 VCPKG_CHAINLOAD_TOOLCHAIN_FILE：

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake

或者，您可以在主要工具鏈檔案的結尾包含 vcpkg 工具鏈：

# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)

注意

vcpkg 不會在建置程式庫時自動套用您的工具鏈設定，例如編譯器或編譯標誌。 若要變更 vcpkg 的連結庫設定，您必須建立 自定義三重檔案 （可以 共用您的工具鏈）**

設置參考指南

所有影響 vcpkg 的變數都必須在首次出現的 project() 指示詞之前被定義，例如在 CMakePresets.json 的 "cacheVariables" 對應中，透過命令列或 set() 語句。

VCPKG_TARGET_TRIPLET

此設定控制 vcpkg 將從哪個三元組安裝和使用程式庫。

如果未設定，vcpkg 會自動偵測適當的預設三重項，因為目前的編譯程序設定。 如果您變更此 CMake 變數，則必須刪除快取並重新設定。

VCPKG_HOST_TRIPLET

此變數控制將安裝哪些 triplet（三联体） 主機依賴項。

如果未設定，vcpkg 會自動偵測適當的原生三重項（x64-windows、x64-osx、x64-linux）。

另 請參閱主機相依性。

VCPKG_INSTALLED_DIR

此變數會設定函式庫要安裝與被取用的位置。

在指令清單模式中，預設值為 ${CMAKE_BINARY_DIR}/vcpkg_installed。

在傳統模式中，預設值為 ${VCPKG_ROOT}/installed。

VCPKG_MANIFEST_MODE

此變數會強制 vcpkg 在指令清單模式或傳統模式中運作。

ON 預設為當 VCPKG_MANIFEST_DIR 非空或 ${CMAKE_SOURCE_DIR}/vcpkg.json 存在的時候。

若要在偵測到 vcpkg.json 時停用清單模式，請將此設定為 OFF。

VCPKG_MANIFEST_DIR

此變數會指定包含 vcpkg.json 配置清單的替代資料夾。

如果${CMAKE_SOURCE_DIR}存在，則預設為 ${CMAKE_SOURCE_DIR}/vcpkg.json 。

VCPKG_MANIFEST_INSTALL

此變數可控制 vcpkg 是否會在設定步驟期間自動執行以安裝相依性。

如果 ON 為 VCPKG_MANIFEST_MODE，則預設為 ON。

VCPKG_BOOTSTRAP_OPTIONS

這個變數可以設定為要傳遞至 ./bootstrap-vcpkg的其他命令參數。

在指令清單模式中，如果可執行檔不存在，vcpkg 會自動啟動。

VCPKG_OVERLAY_TRIPLETS

此變數可以設定為要在命令行上傳遞的路徑清單， --overlay-triplets=...

VCPKG_OVERLAY_PORTS

此變數可以設定為要在命令行上傳遞的路徑清單， --overlay-ports=...

VCPKG_MANIFEST_FEATURES

此變數可以設定為從指令清單安裝時要啟動的功能清單。

例如，專案可以使用特性來控制建置，搭配其他相依性來啟動測試或範例：

{
  "name": "mylibrary",
  "version": "1.0",
  "dependencies": [ "curl" ],
  "features": {
    "samples": {
      "description": "Build Samples",
      "dependencies": [ "fltk" ]
    },
    "tests": {
      "description": "Build Tests",
      "dependencies": [ "gtest" ]
    }
  }
}

此設定可以直接由 CMake 預設值"cacheVariables"控制，也可以根據其他設定間接控制：

# CMakeLists.txt

option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
  list(APPEND VCPKG_MANIFEST_FEATURES "samples")
endif()

project(myapp)

# ...

VCPKG_MANIFEST_NO_DEFAULT_FEATURES

此變數會控制預設功能的啟用，除了 列出的 VCPKG_MANIFEST_FEATURES功能之外。 如果設定為 ON，預設功能將不會自動啟用。

預設為 OFF。

VCPKG_INSTALL_OPTIONS

此變數可以設定為額外的命令行參數清單，以在自動安裝期間傳遞至 vcpkg 工具。

VCPKG_PREFER_SYSTEM_LIBS

警告

這個功能已被取代。 請改用空的覆蓋埠。

此變數控制 vcpkg 是否會將其路徑附加到 CMAKE_PREFIX_PATH、CMAKE_LIBRARY_PATH 和 CMAKE_FIND_ROOT_PATH 之後，而不是在前面加上，這樣 vcpkg 的庫/套件會在工具鏈/系統庫/套件之後被找到。

預設為 OFF。

VCPKG_FEATURE_FLAGS

此變數可以設定為功能旗標清單，以在自動安裝期間傳遞至 vcpkg 工具，以選擇加入實驗行為。

如需詳細資訊，請參閱 --feature-flags= 命令行選項。

VCPKG_TRACE_FIND_PACKAGE

當設定為 ON 時，列印 find_package 的每個呼叫。 巢狀呼叫（例如透過 find_dependency）會根據巢狀深度縮排。

VCPKG_LOCK_FIND_PACKAGE_<Pkg>

當此選項設定時，對 find_package 的非巢狀呼叫要麼是必需的（VCPKG_LOCK_FIND_PACKAGE_<Pkg>=ON），要麼是禁用的（VCPKG_LOCK_FIND_PACKAGE_<Pkg>=OFF）。

此變數是一種工具，可用來控制使用 CMake 建置系統之 vcpkg 埠中的直接相依性和相關功能。 它可與 搭配 vcpkg_check_features 使用，並避免對可轉移相依性產生非預期的影響。