教程：使用 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 特选注册表是一组数量超过 2000 个的开源库。这些库已通过 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 命令设置环境变量只会影响当前 shell 会话。要使此更改在整个会话中永久存在，需要将 export 命令添加到 shell 的配置文件脚本（例如，~/.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 vcpkg 实例所在的位置。将它添加到 PATH 确保可以直接从 shell 运行 vcpkg 命令。

3 - 设置自定义覆盖

在使用 CMake 安装和使用包教程中创建的 Hello World 项目旁创建名为 custom-overlay 的新目录。
在 custom-overlay 目录中，创建名为 vcpkg-sample-library 的文件夹。

4 - 设置端口文件

首先，在 vcpkg.json 文件夹中创建 custom-overlay\vcpkg-sample-library 的文件，其中包含以下内容：

{
  "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)

为端口提供使用文档可让用户在项目中轻松采用这些文档。强烈建议在端口的目录 (ports/<port name>/usage) 中提供 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 - 更新 `portfile.cmake` 的 SHA512

运行：

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

你将收到一条长错误消息。扫描输出，直到找到：

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

复制“实际哈希”4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417，并将 portfile.cmake 中的 SHA512 值替换为其值。

重新运行安装命令：

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 注册表。

有关详细信息，请参阅：

通过