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": 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": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

Версии 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.

CLion

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

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

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

VCPKG_TARGET_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_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 автоматически запускаться для установки зависимостей во время настройки.

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

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_PATHCMAKE_FIND_ROOT_PATH поэтому библиотеки и пакеты vcpkg будут найдены после цепочки инструментов, системных библиотек и пакетов.

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

VCPKG_FEATURE_FLAGS

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

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

VCPKG_TRACE_FIND_PACKAGE

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