vcpkg і CMake: toolchain-файл, manifest vcpkg.json, IDE

Лекція про основи vcpkg завершилась двома режимами роботи. Тепер ці режими підключаються до CMake: спершу з'ясовується, як CMake взагалі дізнається про vcpkg, а потім розглядається повний сценарій manifest-режиму.

Як CMake дізнається про vcpkg

CMake сам про vcpkg нічого не знає. Зв'язок створює toolchain-файл vcpkg.cmake, який лежить усередині каталогу vcpkg:

$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

Файл виконується на самому початку конфігурації. Він налаштовує пошук пакетів так, щоб find_package(fmt CONFIG REQUIRED) знаходив бібліотеки, встановлені через vcpkg, а в manifest-режимі ще й сам запускає vcpkg install для залежностей проєкту. Перед викликом find_package у вашому CMakeLists.txt нічого змінювати не потрібно.

Способи підключити toolchain

Спосіб 1: параметр командного рядка (рекомендовано)

# Windows
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build

# Linux / macOS
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build

Це найбільш явний і надійний спосіб. Шлях до vcpkg зберігається поза CMakeLists.txt, тому проєкт можна збирати й на комп'ютері, де vcpkg лежить в іншій папці.

Спосіб 2: змінна середовища

CMake починаючи з версії 3.21 бере значення параметра зі змінної середовища CMAKE_TOOLCHAIN_FILE, якщо в командному рядку його не вказано:

# Додайте в ~/.bashrc або ~/.zshrc
export VCPKG_ROOT=$HOME/vcpkg
export CMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake

[Environment]::SetEnvironmentVariable("VCPKG_ROOT", "C:\vcpkg", "User")
[Environment]::SetEnvironmentVariable("CMAKE_TOOLCHAIN_FILE", "C:\vcpkg\scripts\buildsystems\vcpkg.cmake", "User")

Після цього достатньо cmake -B build: toolchain підхоплюється автоматично. Недолік такого підходу: усі CMake-проєкти на комп'ютері починають використовувати vcpkg, навіть ті, яким він не потрібен. Користувачеві на іншому комп'ютері теж доведеться задати змінну.

Спосіб 3: встановити змінну в CMakeLists.txt (до project)

Якщо хочеться, щоб проєкт сам знаходив vcpkg, змінну можна встановити у файлі. Критично важливий порядок: toolchain-файл читається під час виконання project(), тому змінна має бути встановлена раніше.

cmake_minimum_required(VERSION 3.15)

# Toolchain потрібно задати ДО project()
if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
    set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
        CACHE STRING "")
endif()

project(MyProject)

set(CMAKE_CXX_STANDARD 17)

find_package(fmt CONFIG REQUIRED)
add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE fmt::fmt)

cmake_minimum_required(VERSION 3.15)
project(MyProject)

# Занадто пізно: toolchain уже не підхопиться
if(DEFINED ENV{VCPKG_ROOT} AND NOT DEFINED CMAKE_TOOLCHAIN_FILE)
    set(CMAKE_TOOLCHAIN_FILE "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
        CACHE STRING "")
endif()

set(CMAKE_CXX_STANDARD 17)

find_package(fmt CONFIG REQUIRED)
add_executable(MyApp main.cpp)
target_link_libraries(MyApp PRIVATE fmt::fmt)

Різницю підтверджує реальний запуск обох варіантів (змінна CMAKE_TOOLCHAIN_FILE середовища прибрана, а vcpkg.json однаковий):

У першому випадку vcpkg навіть не запускався: CMake не знав про нього, і find_package не знайшов нічого. У другому vcpkg встановив залежності з vcpkg.json і find_package пройшов.

Спосіб 4: пресети CMake

У командній роботі найзручніше записати toolchain у CMakePresets.json:

{
  "version": 6,
  "configurePresets": [
    {
      "name": "default",
      "binaryDir": "${sourceDir}/build",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    },
    {
      "name": "release",
      "inherits": "default",
      "binaryDir": "${sourceDir}/build-release",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Release"
      }
    }
  ],
  "buildPresets": [
    { "name": "default", "configurePreset": "default" },
    { "name": "release", "configurePreset": "release" }
  ]
}

Вираз $env{VCPKG_ROOT} береться зі змінної середовища кожного розробника, тому файл однаковий для всієї команди і не містить особистих шляхів. Використання: cmake --preset default && cmake --build --preset default.

Manifest-режим

У manifest-режимі залежності проєкту описані у файлі vcpkg.json, який лежить поруч із кореневим CMakeLists.txt. Виконувати vcpkg install <пакет> вручну не потрібно: toolchain сам запускає установку під час конфігурації.

Мінімальний vcpkg.json

{
  "name": "my-application",
  "version": "1.0.0",
  "dependencies": [
    "fmt",
    "nlohmann-json",
    "spdlog"
  ]
}

Поля файлу:

Правильне значення зручно отримати так:

vcpkg x-update-baseline --add-initial-baseline

Команда vcpkg add port <ім'я> додає залежність, не вимагаючи редагувати JSON вручну.

Повний приклад: застосунок із чотирма бібліотеками

Проєкт використовує cxxopts для аргументів командного рядка, spdlog для логування, fmt для форматованого виводу та nlohmann-json для JSON.

Що відбувається під час конфігурації

Одна команда робить усе: бачить vcpkg.json, збирає бібліотеки та підготовляє find_package.

cmake -B build -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
cmake --build build

Вміст списку показує: vcpkg взяв зі vcpkg.json чотири пакети, а ще два службових (позначені *) додав сам. Зверніть увагу на Restored 0 package(s): бінарного кешу ще не було, і всі пакети збиралися з джерел. Повторна конфігурація на цьому ж комп'ютері відновить їх із кешу за мілісекунди.

Після конфігурації залежності лежать усередині папки збірки:

Тобто залежності проєкту ізольовані від решти системи: видалення build/ прибирає і їх. Зібрані пакети при цьому зберігаються в бінарному кеші, тому повторна збірка не буде довгою.

Запуск

Допомога, яку згенерував cxxopts:

Як дізнатися, що писати у find_package

Назва порту й назва CMake-пакета не завжди збігаються. Наприклад, порт називається nlohmann-json, а в find_package пишуть nlohmann_json. Після встановлення vcpkg друкує підказку (як було видно у лекції про основи), а також зберігає її у файлі share/<порт>/usage.

Змінні vcpkg для CMake

Toolchain vcpkg.cmake реагує на ряд змінних. Їх задають через -D або у пресеті:

Приклад: збірка зі статичними бібліотеками на Windows та докладним виводом:

cmake -B build -S . ^
  -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ^
  -DVCPKG_TARGET_TRIPLET=x64-windows-static

Налаштування IDE

VS Code

Розширення «CMake Tools» використовує пресети або налаштування конфігурації. Найпростіший варіант:

{
    "cmake.configureSettings": {
        "CMAKE_TOOLCHAIN_FILE": "${env:VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
    }
}

Файл зберігається як .vscode/settings.json. Запис ${env:VCPKG_ROOT} береться із змінної середовища, тому не залежить від ОС і особистих шляхів. Якщо в проєкті вже є CMakePresets.json, CMake Tools використовує його, і додатково нічого налаштовувати не потрібно.

Visual Studio

Visual Studio 2022 розпізнає vcpkg у двох варіантах:

• Для CMake-проєктів (відкриття папки з CMakeLists.txt): достатньо CMakePresets.json з CMAKE_TOOLCHAIN_FILE, як у способі 4. Крім того, у складі Visual Studio поставляється власна копія vcpkg, і якщо в корені проєкту є vcpkg.json, середовище може саме встановлювати залежності.
• Для проєктів MSBuild (.sln/.vcxproj): виконайте vcpkg integrate install. Після цього пакети vcpkg доступні в усіх таких проєктах, а в manifest-режимі залежності беруться з vcpkg.json.

CLion

У CLion відкрийте Settings → Build, Execution, Deployment → CMake і додайте в поле «CMake options»:

-DCMAKE_TOOLCHAIN_FILE=/шлях/до/vcpkg/scripts/buildsystems/vcpkg.cmake

Також у Settings → Build, Execution, Deployment → Vcpkg можна додати каталог vcpkg, після чого CLion сам підставляє toolchain у налаштування CMake.

Типові помилки

Практичне завдання

Резюме