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

發行項
07/16/2024

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

必要條件

終端機
C++ 編譯器
CMake
Git

注意

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

1 - 設定 vcpkg

複製存放庫

第一個步驟是從 GitHub 複製 vcpkg 存放庫。存放庫包含可取得 vcpkg 可執行文件的腳本，以及 vcpkg 社群所維護之策劃開放原始碼連結庫的登錄。若要這樣做，請執行：
```
git clone https://github.com/microsoft/vcpkg.git
```
vcpkg 策展登錄是一組超過 2,000 個開放原始碼連結庫。這些連結庫已由 vcpkg 的持續整合管線進行驗證，以共同運作。雖然 vcpkg 存放庫不包含這些連結庫的原始程式碼，但它會保存配方和元數據，以在您的系統中建置並安裝它們。
執行啟動程式腳本

既然您已複製 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 命令設定環境變數只會影響目前的殼層會話。若要讓此變更在會話之間永久完成，請將命令新增 export 至殼層的配置檔腳本（例如 ~/.bashrc 或 ~/.zshrc）。

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

注意

以這種方式設定環境變數只會影響目前的終端機會話。若要在所有工作階段中永久進行這些變更，請透過 [Windows 系統環境變數] 面板加以設定。

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

注意

以這種方式設定環境變數只會影響目前的終端機會話。若要在所有工作階段中永久進行這些變更，請透過 [Windows 系統環境變數] 面板加以設定。

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

3 - 設定自定義重疊

在安裝並使用套件搭配 CMake 教學課程中建立的專案旁Hello World，建立名為 custom-overlay 的新目錄。
在 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：陣列，包含連結庫所需的相依性清單。
name： vcpkg-cmake指定相依性， vcpkg-cmake其提供在 vcpkg 埠中常用的 CMake 函式和巨集。
host：true：指定這是 vcpkg-cmake 主機相依性，這表示建置套件需要它，但不需要使用它。
name： vcpkg-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)

提供埠的使用檔可讓用戶在專案中輕鬆採用它們。我們強烈建議在埠目錄內提供檔案 usage ，ports/<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 Microsoft/vcpkg-docs：包含原始程式碼的 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.txt 和 helloworld/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;
}

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

使用 CMake 設定組建：

cmake --preset=default

建置專案：

cmake --build build

執行應用程式：

./build/HelloWorld

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

Hello vcpkg!

下一步

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

如需詳細資訊，請參閱

共用方式為

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

必要條件

1 - 設定 vcpkg

2 - 設定 `VCPKG_ROOT` 環境變數

3 - 設定自定義重疊

4 - 設定埠檔案

5 - 更新的 SHA512 `portfile.cmake`

6 - 驗證埠組建

下一步

其他資源

共用方式為

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

必要條件

1 - 設定 vcpkg

2 - 設定 VCPKG_ROOT 環境變數

3 - 設定自定義重疊

4 - 設定埠檔案

5 - 更新 的 SHA512 portfile.cmake

6 - 驗證埠組建

下一步

其他資源

2 - 設定 `VCPKG_ROOT` 環境變數

5 - 更新的 SHA512 `portfile.cmake`