教學課程:使用 vcpkg 封裝連結庫

本教學課程會引導您使用自定義重迭封裝 vcpkg 的連結庫。 建議您先閱讀 安裝和使用套件搭配 CMake 教學課程,再繼續進行。

必要條件

注意

在 Windows 上,本教學課程使用 Visual Studio 的 MSVC 作為 C++ 開發的編譯程式。

1 - 設定 vcpkg

  1. 複製存放庫

    第一個步驟是從 GitHub 複製 vcpkg 存放庫。 存放庫包含可取得 vcpkg 可執行文件的腳本,以及 vcpkg 社群所維護之策劃開放原始碼連結庫的登錄。 若要這樣做,請執行:

    git clone https://github.com/microsoft/vcpkg.git
    

    vcpkg 策展登錄是一組超過 2,000 個開放原始碼連結庫。 這些連結庫已由 vcpkg 的持續整合管線進行驗證,以共同運作。 雖然 vcpkg 存放庫不包含這些連結庫的原始程式碼,但它會保存配方和元數據,以在您的系統中建置並安裝它們。

  2. 執行啟動程式腳本

    既然您已複製 vcpkg 存放庫,請瀏覽至 vcpkg 目錄並執行啟動程式腳本:

    cd vcpkg && bootstrap-vcpkg.bat
    
    cd vcpkg; .\bootstrap-vcpkg.bat
    
    cd vcpkg && ./bootstrap-vcpkg.sh
    

    啟動程式腳本會執行必要條件檢查,並下載 vcpkg 可執行檔。

    介紹完畢 vcpkg 已設定且可供使用。

2 - 設定 VCPKG_ROOT 環境變數

若要設定 VCPKG_ROOT 環境變數,請執行下列命令:

export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

注意

使用 export 命令設定VCPKG_ROOT環境變數只會影響目前的殼層會話。 若要讓此變更在會話之間永久完成,您必須將命令新增 export 至殼層的配置檔腳本(例如 ~/.bashrc~/.zshrc)。

set "VCPKG_ROOT=C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

注意

使用 set 命令設定VCPKG_ROOT環境變數只會影響目前的殼層會話。 若要讓此變更在會話之間永久完成,您可以使用 setx 命令並重新啟動殼層會話。

$env:VCPKG_ROOT="C:\path\to\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"

注意

VCPKG_ROOT以這種方式設定及更新PATH環境變數只會影響目前的PowerShell會話。 若要在所有工作階段中永久進行這些變更,您應該將它們新增至PowerShell配置檔,或透過 [Windows 系統環境變數] 面板加以設定。

設定 VCPKG_ROOT 會告知 vcpkg 實例所在的位置。 新增它以確保 PATH 您可以直接從殼層執行 vcpkg 命令。

3 - 設定自定義重疊

  1. 在安裝並使用套件搭配 CMake 教學課程中建立的專案旁Hello World,建立名為 custom-overlay 的新目錄。
  2. custom-overlay 目錄中,建立名為 vcpkg-sample-library的資料夾。

4 - 設定埠檔案

首先,使用下列內容在custom-overlay\vcpkg-sample-library資料夾內建立vcpkg.json檔案:

{
  "name": "vcpkg-sample-library",
  "version": "1.0.2",
  "homepage": "https://github.com/microsoft/vcpkg-docs/tree/cmake-sample-lib",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "license": "MIT",
  "dependencies": [
    {
      "name" : "vcpkg-cmake",
      "host" : true
    },
    {
      "name" : "vcpkg-cmake-config",
      "host" : true
    },
    "fmt"
  ]
}

vcpkg.json 檔案可作為定義 C++ 連結庫元數據和相依性的指令清單,為 vcpkg 提供建置、安裝及管理套件的必要資訊。

  • name:指定連結庫的名稱。 這會當做封裝標識碼使用。
  • version:表示連結庫的版本號碼。
  • homepage:專案首頁的 URL,通常是其存放庫。 適合想要深入瞭解或參與的人。
  • description:描述連結庫用途的簡短文字。 這適用於檔和使用者。
  • license:指定發佈連結庫的授權。
  • dependencies:陣列,包含連結庫所需的相依性清單。
  • namevcpkg-cmake指定 相依性, vcpkg-cmake其提供在 vcpkg 埠中常用的 CMake 函式和宏。
  • host:true:指定這是 vcpkg-cmake 主機相依性,這表示建置套件需要它,但不需要使用它。
  • namevcpkg-cmake-config指定 相依性, vcpkg-cmake-config以協助使用 CMake 組態腳本。
  • fmt:指定連結庫的 fmt 運行時間相依性。 這表示建置和使用套件都需要這個方法 fmt

如需 的詳細資訊vcpkg.json,請參閱下列指令清單

現在,使用 usage 下列內容在 custom-overlay\vcpkg-sample-library 目錄中建立檔案:

vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

提供埠的使用檔可讓用戶在專案中輕鬆採用它們。 我們強烈建議在埠目錄內提供檔案 usageports/<port name>/usage以描述與建置系統整合所需的最少步驟。 若要判斷正確的使用指示,建議您遵循上游的指引。 如果上游未提供使用資訊,可能需要深入探索其建置系統來尋找導出的目標。

如需詳細資訊,請參閱 處理使用檔案

最後,使用下列內容在custom-overlay\vcpkg-sample-library目錄中建立portfile.cmake檔案:

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO Microsoft/vcpkg-docs
    REF "${VERSION}"
    SHA512 0  # This is a temporary value. We will modify this value in the next section.
    HEAD_REF cmake-sample-lib
)


vcpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

vcpkg_cmake_install()

vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

這會 portfile 定義如何使用 vcpkg 從 GitHub 下載、建置、安裝及封裝特定的 C++ 連結庫。

  • vcpkg_check_linkage(ONLY_STATIC_LIBRARY):指定此套件僅支持靜態連結。
  • vcpkg_from_github:啟動 函式以從 GitHub 存放庫下載原始程式碼。
    • OUT_SOURCE_PATH SOURCE_PATH:設定將擷取原始程式碼的目錄。
    • REPO JavierMatosD/vcpkg-sample-library:包含原始程式碼的 GitHub 存放庫。
    • REF "${VERSION}":要下載的原始程式碼版本。
    • SHA512 0:原始碼 SHA-512 哈希的佔位元,以進行完整性驗證。
    • HEAD_REF main:指定存放庫的預設分支。
  • vcpkg_cmake_configure:使用 CMake 設定專案,並設定組建。
    • SOURCE_PATH "${SOURCE_PATH}":稍早下載之原始程式碼的路徑。
  • vcpkg_cmake_install():使用 CMake 建置並安裝套件。
  • vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"):修正 CMake 套件組態檔以與 vcpkg 相容。
  • file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"):從偵錯安裝中刪除 include 目錄,以防止重疊。
  • file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...):將 LICENSE 檔案安裝至套件的共享目錄,並將它重新命名為著作權。
  • configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...):將使用指示檔案複製到套件的共享目錄。

如需詳細資訊,請參閱 維護員指南

5 - 更新 的 SHA512 portfile.cmake

請執行:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

您會收到很長的錯誤訊息。 掃描輸出,直到您找到:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

複製 「Actual hash」 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417,並將 中的portfile.cmake值取代SHA512為其值。

重新執行 install 命令:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay
Computing installation plan...
The following packages will be built and installed:
    vcpkg-sample-library:x64-windows -> 1.0.2 -- C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
Detecting compiler hash for triplet x64-windows...
Restored 0 package(s) from C:\Users\dev\AppData\Local\vcpkg\archives in 174 us. Use --debug to see more details.
Installing 1/1 vcpkg-sample-library:x64-windows...
Building vcpkg-sample-library:x64-windows...
-- Installing port from location: C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
-- Note: vcpkg-sample-library only supports static library linkage. Building static library.
-- Using cached Microsoft-vcpkg-docs-1.0.2.tar.gz.
-- Cleaning sources at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source C:/Users/dev/demo/vcpkg/downloads/Microsoft-vcpkg-docs-1.0.2.tar.gz
-- Using source at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/copyright
-- Performing post-build validation
Stored binaries in 1 destinations in 94 ms.
Elapsed time to handle vcpkg-sample-library:x64-windows: 6.1 s
Total install time: 6.1 s
vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

6 - 驗證埠組建

若要確認連結庫建置並正確連結,請將新的相依性新增至helloworld安裝套件教學課程中建立的專案。 對專案的指令清單和組態檔進行下列變更。

修改 helloworld/vcpkg.json 以在 上 vcpkg-sample-library新增相依性:

{
    "dependencies": [
        "fmt",
        "vcpkg-sample-library"
    ]
}

變更 helloworld/vcpkg-configuration.json 以包含 overlay-ports 包含新連接埠的資料夾:

{
  "default-registry": {
    "kind": "git",
    "baseline": "45f6e57d3e10ad96b7db206cf7888f736ba5aa61",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "overlay-ports": [
    "../custom-overlay"
  ]
}

接下來,修改 helloworld/CMakeLists.txthelloworld/main.cpp 以使用新的相依性。

helloworld/CMakeLists.txt使用下列內容修改 :

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)
find_package(my_sample_lib CONFIG REQUIRED)  # Add this line

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
target_link_libraries(HelloWorld PRIVATE my_sample_lib::my_sample_lib)  # Add this line

main.cpp使用下列內容修改 :

#include "my_sample_lib.h"  // Replace #include <fmt/core.h> with "my_sample_lib.h"

int main()
{
    greet("vcpkg!");  // Replace fmt::print("Hello World!\n) with this line
    return 0;
}

設定、建置和執行應用程式。

  1. 使用 CMake 設定組建:
cmake --preset=default
  1. 建置專案:
cmake --build build
  1. 執行應用程式:
./build/HelloWorld

項目可執行文件的路徑可能不同,例如: ./build/Debug/HelloWorld.exe

Hello vcpkg!

下一步

vcpkg-sample-library現在已封裝為埠,下一個步驟是將其新增至 vcpkg 策展登錄。 請參閱將 埠新增至 vcpkg 登錄

如需詳細資訊,請參閱