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.

CMAKE_TOOLCHAIN_FILE

Примечание.

Если вы установили CMAKE_TOOLCHAIN_FILE в CMakeList.txt файле, убедитесь, что переменная задана перед вызовами project().

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

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

{
  "version": 3,
  "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})

Интеграция с IDE

Visual Studio или Visual Studio Code

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

Справочник по переменным CMake

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

VCPKG_TARGET_TRIPLET

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

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

VCPKG_HOST_TRIPLET

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

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

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

VCPKG_INSTALLED_DIR

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

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

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

VCPKG_APPLOCAL_DEPS

Эта переменная определяет, автоматически ли vcpkg копирует зависимые библиотеки DLL в выходной каталог для исполняемых файлов и общих библиотек в целевых объектах Windows, UWP и Xbox. По умолчанию имеет значение ON.

VCPKG_USE_LEGACY_APPLOCAL

Эта переменная определяет, какую реализацию развертывания DLL, локальных для приложения, использует vcpkg. По умолчанию используется OFF, который использует встроенную реализацию vcpkg z-applocal. Установите значение ON, чтобы использовать устаревшую реализацию PowerShell applocal.ps1.

VCPKG_MANIFEST_MODE

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

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

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

VCPKG_MANIFEST_DIR

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

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

VCPKG_MANIFEST_INSTALL

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

По умолчанию ON, если VCPKG_MANIFEST_MODE является ON.

VCPKG_BOOTSTRAP_OPTIONS

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

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

VCPKG_OVERLAY_TRIPLETS

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

VCPKG_OVERLAY_PORTS

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

VCPKG_MANIFEST_FEATURES

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

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

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

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

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

VCPKG_INSTALL_OPTIONS

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

VCPKG_PREFER_SYSTEM_LIBS

Предупреждение

Эта функция является устаревшей. Вместо этого используйте пустые порты оверлейной сети.

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

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

VCPKG_FEATURE_FLAGS

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

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

VCPKG_TRACE_FIND_PACKAGE

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

VCPKG_LOCK_FIND_PACKAGE_<Pkg>

Если эта переменная задана, невложенные вызовы find_package либо обязательны (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=ON), либо отключены (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=OFF).

Эта переменная — это средство для управления прямыми зависимостями и связанными функциями в портах vcpkg, использующих систему сборки CMake. Его можно использовать с vcpkg_check_features и избегать непредвиденных эффектов на транзитивные зависимости.

  • Last updated on