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

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

Предварительные условия

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

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

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

   Первым шагом является клонирование репозитория vcpkg из GitHub. Репозиторий содержит скрипты для получения исполняемого файла vcpkg и реестра курируемых библиотек с открытым исходным кодом, поддерживаемых сообществом vcpkg. Для этого выполните следующую команду:

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

   Управляемый реестр vcpkg — это набор из более чем 2000 библиотек с открытым исходным кодом. Эти библиотеки были проверены конвейерами непрерывной интеграции 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

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

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

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

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

1. Создайте новый каталог custom-overlay рядом с проектом, Hello World созданным в руководстве по установке и использованию пакетов с помощью CMake .
2. В custom-overlay каталоге создайте папку с именем vcpkg-sample-library.

4. Настройка файлов портов

Сначала создайте vcpkg.json файл в папке custom-overlay/vcpkg-sample-library со следующим содержимым:

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

Файл 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 MicrosoftDocs/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 "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

Это portfile определяет, как скачать, собрать, установить и упаковать определенную библиотеку C++ из GitHub с помощью vcpkg.

• vcpkg_check_linkage(ONLY_STATIC_LIBRARY): указывает, что для этого пакета поддерживается только статическое связывание.
• vcpkg_from_github: запускает функцию для скачивания исходного кода из репозитория GitHub.
  • OUT_SOURCE_PATH SOURCE_PATH: задает каталог, в котором будет извлечен исходный код.
  • REPO MicrosoftDocs/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 "${CMAKE_CURRENT_LIST_DIR}/usage" ...): копирует файл инструкции по использованию в общий каталог пакета.
• vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): устанавливает файл LICENSE в общий каталог пакета и переименовывает его в авторские права.

Дополнительные сведения см. в руководстве по обслуживанию.

5. Обновление SHA512 для portfile.cmake

Запустить:

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

Появится длинное сообщение об ошибке. Сканируйте выходные данные, пока не найдете следующее:

Downloading https://github.com/MicrosoftDocs/vcpkg-docs/archive/1.0.2.tar.gz -> MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
Successfully downloaded MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: 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/usage
-- 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;
}

Настройте, создайте и запустите приложение.

1. Настройте сборку с помощью CMake:

cmake --preset=default

2. Скомпилируйте проект.

cmake --build build

3. Запустите приложение:

./build/HelloWorld

Путь к исполняемому файлу проекта может отличаться, например: ./build/Debug/HelloWorld.exe

Hello vcpkg!

Следующие шаги

Теперь, когда пакет vcpkg-sample-library был упакован в качестве порта, следующий шаг — добавить его в проверенный реестр vcpkg. См. раздел " Добавление портов в реестр vcpkg".

Дополнительные сведения см. в разделе:

• Порты
• Руководство по поддержке