CMake 專案中的 vcpkg

發行項
01/10/2024

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

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

若要自定義工具鏈選取程式，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`

注意

如果您在檔案CMakeList.txt中設定 CMAKE_TOOLCHAIN_FILE ，請確定變數是在呼叫 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": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

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 Code

建議您在 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`

此變數會控制要安裝的三重主機相依性。

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

另請參閱主機相依性。

`VCPKG_INSTALLED_DIR`

此變數會設定要安裝及取用連結庫的位置。

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

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

`VCPKG_MANIFEST_MODE`

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

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

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

`VCPKG_MANIFEST_DIR`

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

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

`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 連結庫/套件在工具鏈/系統連結庫/套件之後找到。