Руководство. Упаковка библиотеки с помощью vcpkg

Статья
07/16/2024

В этом руководстве описано, как упаковать библиотеку для vcpkg с помощью пользовательского наложения. Прежде чем продолжить, рекомендуется ознакомиться с руководством по установке и использованию пакетов с CMake .

Необходимые компоненты

Терминал
Компилятора C++
CMake.
Git

Примечание.

В Windows в этом руководстве в качестве компилятора для разработки C++ используется MSVC Visual Studio.

1. Настройка vcpkg

Клонирование репозитория

Первым шагом является клонирование репозитория vcpkg из GitHub. Репозиторий содержит скрипты для получения исполняемого файла 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 команды влияет только на текущий сеанс оболочки. Чтобы сделать это изменение постоянным в сеансах, добавьте 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"

Примечание.

Параметр VCPKG_ROOT указывает vcpkg, где расположен экземпляр vcpkg. Добавьте его, чтобы PATH вы могли выполнять команды vcpkg непосредственно из оболочки.

3. Настройка настраиваемого наложения

Создайте новый каталог custom-overlay рядом с проектом, Hello World созданным в руководстве по установке и использованию пакетов с помощью CMake .
В 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функций и макросов CMake, часто используемых в портах vcpkg.
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), который описывает минимальные шаги, необходимые для интеграции с системой сборки. Чтобы определить правильные инструкции по использованию, рекомендуется следовать инструкциям вышестоящего руководства. В случае, если вышестоящее приложение не предоставляет сведения об использовании, возможно, потребуется выполнить поиск экспортированных целевых объектов в системе сборки.

Дополнительные рекомендации см. в разделе об обработке файлов использования

Наконец, создайте portfile.cmake файл в custom-overlay\vcpkg-sample-library каталоге со следующим содержимым:

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 определяет, как скачать, собрать, установить и упаковать определенную библиотеку C++ из GitHub с помощью vcpkg.

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

Скопируйте "Фактический хэш" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417и замените SHA512 значение в его значении portfile.cmake .

Повторно выполните команду установки:

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`