vcpkg в проектах CMake

vcpkg предлагает простую интеграцию с CMake, чтобы сделать установленные пакеты доступными в проектах автоматически. Механизм интеграции vcpkg заключается в предоставлении файла цепочки инструментов CMake.

При первом настройке проекта CMake выполняет внутренние процедуры поиска, чтобы найти жизнеспособную цепочку инструментов (компилятор, компоновщик и т. д.). Этот поиск выполняется в функции в вашей системе project() CMakeLists.txt.

Чтобы настроить процесс выбора цепочки инструментов, CMake поддерживает использование пользовательских скриптов CMake-language, известных как файлы цепочки инструментов. Файл цепочки инструментов указывается путем задания переменной CMAKE_TOOLCHAIN_FILE . CMake вычисляет содержимое предоставленного скрипта цепочки инструментов и задает определения переменных, пути к необходимым средствам сборки и другим параметрам сборки, таким как флаги кросс-компиляции, соответственно.

При использовании CMAKE_TOOLCHAIN_FILE цепочки инструментов vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake) vcpkg использует механизм цепочки инструментов для внедрения кода для интеграции со встроенными функциями CMake прозрачно.

Вы по-прежнему можете использовать файл цепочки инструментов для настройки собственных наборов инструментов с помощью тройной переменной VCPKG_CHAINLOAD_TOOLCHAIN_FILE .

Интеграция vcpkg работает по-разному в зависимости от используемого режима работы:

В классическом режиме vcpkg устанавливает пути поиска CMake соответствующим образом, чтобы сделать установленные пакеты доступными через find_package()функции find_library()и find_path() функции.

В режиме манифеста, помимо приведенного выше, цепочка инструментов обнаруживает файлы манифеста (vcpkg.json файлы) и запускается vcpkg install для автоматического получения зависимостей проекта.

Так как файл цепочки инструментов вычисляется во время project() вызова, все переменные уровня CMake, изменяющие параметр vcpkg, должны быть заданы перед первым вызовом project(). Также может потребоваться перенастроить проект CMake, если изменить любой параметр vcpkg, который приводит к изменениям хэша ABI.

См. пример установки и использования пакетов: sqlite для полного примера с помощью CMake.

Проекты, настроенные для использования цепочки инструментов vcpkg (с помощью параметра CMAKE_TOOLCHAIN_FILECMake), могут находить библиотеки из vcpkg с помощью стандартных функций CMake: find_package(), find_path()и find_library().

Рекомендуется использовать предустановки CMake, чтобы указать файл цепочки инструментов. Например, если вы определили переменную VCPKG_ROOTсреды, можно использовать следующее CMakePresets.json и передать --preset debug строку настройки:

{
  "version": 2,
  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

cmake -B build -S /my/project --preset debug

Если вам нужно использовать абсолютный путь для vcpkg, характерный для текущего компьютера, можно использовать CMakeUserPresets.json и добавить его в .gitignore файл.

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "debug",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

Версии CMake старше 3.19 должны передавать файл цепочки инструментов в настраиваемой командной строке:

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

vcpkg поддерживает собственные механизмы CMake для поиска библиотек: find_package(), find_library()и find_path(). При установке библиотек с определенной поддержкой CMake vcpkg отобразит сведения об использовании библиотеки:

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

vcpkg не добавляет в проект пути включения или ссылок автоматически. Чтобы использовать библиотеку только заголовков, можно использовать find_path() , которая будет правильно работать на всех платформах:

# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

Рекомендуется использовать предустановки CMake как в Visual Studio, так и в Visual Studio Code.

Дополнительные сведения о настройке и сборке с помощью предустановок CMake в Visual Studio и настройке и сборке с помощью предустановок CMake в Visual Studio Code.

Откройте параметры цепочки инструментов (File > Settings в Windows и Linux, CLion > Preferences в macOS) и перейдите к параметрам CMake (Build, Execution, Deployment > CMake). Добавьте CMake optionsследующую строку:

-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

Эту строку необходимо добавить в каждый профиль отдельно.

Чтобы объединить файл цепочки инструментов vcpkg с другим файлом цепочки инструментов, можно задать переменную VCPKG_CHAINLOAD_TOOLCHAIN_FILEкэша CMake:

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake

Кроме того, можно включить цепочку инструментов vcpkg в конце основного файла цепочки инструментов:

# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)

Все переменные, влияющие на vcpkg, должны быть определены перед первой project() директивой, например в CMakePresets.json"cacheVariables" карте, с помощью командной строки или set() инструкций.

Этот параметр управляет триплетом vcpkg, из который будут устанавливаться и потреблять библиотеки.

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

Эта переменная определяет, для каких зависимостей узлов будут установлены триплетные зависимости узла.

Если не задано, vcpkg автоматически обнаружит соответствующий собственный триплет (x64-windows, x64-osx, x64-linux).

См. также зависимости узлов.

Эта переменная задает расположение, из которого будут установлены и использованы библиотеки.

В режиме манифеста используется ${CMAKE_BINARY_DIR}/vcpkg_installedзначение по умолчанию.

В классическом режиме используется ${VCPKG_ROOT}/installedзначение по умолчанию.

Эта переменная заставляет vcpkg работать в режиме манифеста или классическом режиме.

По умолчанию используется ON значение, когда VCPKG_MANIFEST_DIR не пусто или ${CMAKE_SOURCE_DIR}/vcpkg.json существует.

Чтобы отключить режим манифеста vcpkg.json во время обнаружения, установите для этого значение OFF.

Эта переменная указывает альтернативную папку, vcpkg.json содержащую манифест.

Значение ${CMAKE_SOURCE_DIR} по умолчанию, если ${CMAKE_SOURCE_DIR}/vcpkg.json существует.

Эта переменная определяет, будет ли vcpkg автоматически запускаться для установки зависимостей во время настройки.

По умолчанию используется ON VCPKG_MANIFEST_MODE ONзначение if .

Для передачи ./bootstrap-vcpkgэтой переменной можно задать дополнительные параметры команды.

В режиме манифеста vcpkg автоматически загрузится, если исполняемый файл не существует.

Эту переменную можно задать в списке путей, передаваемых в командной строке как --overlay-triplets=...

Эту переменную можно задать в списке путей, передаваемых в командной строке как --overlay-ports=...

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

Например, функции можно использовать проектами для управления сборкой с дополнительными зависимостями, чтобы включить тесты или примеры:

{
  "name": "mylibrary",
  "version": "1.0",
  "dependencies": [ "curl" ],
  "features": {
    "samples": {
      "description": "Build Samples",
      "dependencies": [ "fltk" ]
    },
    "tests": {
      "description": "Build Tests",
      "dependencies": [ "gtest" ]
    }
  }
}

Этот параметр можно контролировать напрямую с помощью предустановок CMake или "cacheVariables" косвенно на основе других параметров:

# CMakeLists.txt

option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
  list(APPEND VCPKG_MANIFEST_FEATURES "samples")
endif()

project(myapp)

# ...

Эта переменная управляет активацией функций по умолчанию в дополнение к перечисленным в VCPKG_MANIFEST_FEATURES. Если задано значение ON, функции по умолчанию не будут автоматически активированы.

По умолчанию — OFF.

Эту переменную можно задать в списке дополнительных параметров командной строки для передачи средству vcpkg во время автоматической установки.

Эта переменная определяет, будет ли vcpkg добавляться вместо предустановки путей CMAKE_PREFIX_PATHк и CMAKE_LIBRARY_PATH CMAKE_FIND_ROOT_PATH поэтому библиотеки и пакеты vcpkg будут найдены после цепочки инструментов, системных библиотек и пакетов.

По умолчанию — OFF.

Эта переменная может быть задана в список флагов компонентов, которые передаются средству vcpkg во время автоматической установки, чтобы принять участие в экспериментальном поведении.

Дополнительные сведения см. в параметре командной --feature-flags= строки.

Если задано значение ON, печать каждого вызова find_package. Вложенные вызовы (например, через find_dependency) отступируются в соответствии с глубиной вложения.