vcpkg v projektech CMake

Článek
01/10/2024

Vcpkg nabízí bezproblémovou integraci s CMake, aby byly nainstalované balíčky dostupné ve vašich projektech automaticky. Mechanismus, ve kterém se vcpkg integruje, spočívá v poskytnutí souboru sady nástrojů CMake.

Když CMake poprvé nakonfiguruje projekt, spustí interní rutiny vyhledávání, aby vyhledaly funkční sadu nástrojů (kompilátor, linker atd.). K tomuto hledání dochází v rámci project() funkce ve vaší CMakeLists.txtfunkci .

Aby bylo možné přizpůsobit proces výběru sady nástrojů, CMake podporuje použití vlastních skriptů jazyka CMake, označovaných jako soubory sady nástrojů. Soubor sady nástrojů je určen nastavením CMAKE_TOOLCHAIN_FILE proměnné. CMake vyhodnotí obsah poskytnutého skriptu sady nástrojů a nastaví definice proměnných, cesty k požadovaným nástrojům sestavení a další parametry sestavení, jako jsou příznaky křížové kompilace.

Když nastavíte CMAKE_TOOLCHAIN_FILE použití sady nástrojů vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmaketoolchain), vcpkg využívá mechanismus souboru toolchain k vložení kódu pro integraci s integrovanými funkcemi CMake transparentně za vás.

Soubor sady nástrojů můžete stále použít ke konfiguraci vlastních sad nástrojů pomocí VCPKG_CHAINLOAD_TOOLCHAIN_FILE trojité proměnné.

Integrace vcpkg funguje jinak v závislosti na používaném provozním režimu:

V klasickém režimu vcpkg nastaví cesty hledání CMake odpovídajícím způsobem, aby byly nainstalované balíčky dostupné prostřednictvím find_package(), find_library()a find_path() funkce.

Kromě výše uvedeného režimu nástroj zjistí soubory manifestu (vcpkg.json soubory) a spustí vcpkg install se, aby automaticky získal závislosti projektu.

Vzhledem k tomu, že se soubor sady nástrojů vyhodnocuje během project() volání, musí být před prvním voláním project()nastaveny všechny proměnné CMake, které upravují nastavení vcpkg . Pokud upravíte jakékoli nastavení vcpkg, které vede ke změnám hodnoty hash ABI, může být také nutné překonfigurovat projekt CMake.

Viz Příklad instalace a používání balíčků: sqlite pro plně funkční příklad pomocí CMake.

`CMAKE_TOOLCHAIN_FILE`

Poznámka:

Pokud jste v souboru nastaviliCMAKE_TOOLCHAIN_FILE, ujistěte se, že je proměnná nastavena před všemi voláními project().CMakeList.txt

Projekty nakonfigurované pro použití souboru toolchain vcpkg (prostřednictvím nastavení CMAKE_TOOLCHAIN_FILECMake) mohou najít knihovny z vcpkg pomocí standardních funkcí CMake: find_package(), find_path()a find_library().

K zadání souboru sady nástrojů doporučujeme použít předvolby CMake. Pokud jste například definovali proměnnou VCPKG_ROOTprostředí, můžete použít následující CMakePresets.json příkaz a předat --preset debug ho na řádek konfigurace:

{
  "version": 2,

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

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

Pokud potřebujete použít absolutní cestu pro vcpkg specifickou pro váš aktuální počítač, můžete ho použít CMakeUserPresets.json a přidat do .gitignore souboru.

{
  "version": 2,

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

Verze CMake starší než 3.19 musí předat soubor sady nástrojů na příkazovém řádku konfigurace:

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

Použití knihoven

vcpkg podporuje nativní mechanismy CMake pro hledání knihoven: find_package(), find_library()a find_path(). Při instalaci knihoven s konkrétní podporou CMake zobrazí nástroj vcpkg informace o využití knihovny:

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

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

Vcpkg nepřidává do projektu automaticky žádné cesty zahrnutí ani propojení. Pokud chcete použít knihovnu jen pro hlavičky, můžete použít find_path() , která bude správně fungovat na všech platformách:

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

Integrace integrovaného vývojového prostředí (IDE)

Visual Studio / Visual Studio Code

V sadě Visual Studio i v editoru Visual Studio Code doporučujeme používat předvolby CMake.

Další informace najdete v tématu Konfigurace a sestavení pomocí předvoleb CMake v sadě Visual Studio a konfigurace a sestavení pomocí předvoleb CMake v editoru Visual Studio Code.

CLion

Otevřete nastavení sady nástrojů (File > Settings ve Windows a Linuxu, CLion > Preferences v macOS) a přejděte do nastavení CMake (Build, Execution, Deployment > CMake). Do CMake optionspole přidejte následující řádek:

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

Tento řádek musíte přidat do každého profilu zvlášť.

Použití více souborů sady nástrojů

Pokud chcete zkombinovat soubor sady nástrojů vcpkg s jiným souborem sady nástrojů, můžete nastavit proměnnou VCPKG_CHAINLOAD_TOOLCHAIN_FILEmezipaměti CMake:

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

Alternativně můžete na konec primárního souboru sady nástrojů zahrnout sadu nástrojů vcpkg:

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

Poznámka:

Vcpkg při sestavování knihoven automaticky nepoužije nastavení sady nástrojů, jako je kompilátor nebo příznaky kompilace. Pokud chcete změnit nastavení knihovny vcpkg, musíte vytvořit vlastní trojitý soubor (který může sdílet sadu nástrojů)**

Referenční informace k nastavení

Všechny proměnné ovlivňující vcpkg musí být definovány před první project() direktivou, například v mapěCMakePresets.json"cacheVariables", přes příkazový řádek nebo set() příkazy.

`VCPKG_TARGET_TRIPLET`

Toto nastavení řídí, že triplet vcpkg nainstaluje a bude využívat knihovny.

Pokud se nenasadí, nástroj vcpkg automaticky zjistí odpovídající výchozí trojitou hodnotu vzhledem k aktuálnímu nastavení kompilátoru. Pokud tuto proměnnou CMake změníte, musíte mezipaměť odstranit a znovu nakonfigurovat.

`VCPKG_HOST_TRIPLET`

Tato proměnná řídí, pro které budou nainstalovány závislosti trojitých hostitelů.

Pokud zrušíte nastavení, vcpkg automaticky rozpozná odpovídající nativní triplet (x64-windows, x64-osx, x64-linux).

Viz také závislosti hostitele.

`VCPKG_INSTALLED_DIR`

Tato proměnná nastaví umístění, odkud se knihovny nainstalují a spotřebují.

V režimu manifestu je ${CMAKE_BINARY_DIR}/vcpkg_installedvýchozí hodnota .

V klasickém režimu je ${VCPKG_ROOT}/installedvýchozí hodnota .

`VCPKG_MANIFEST_MODE`

Tato proměnná vynutí, aby vcpkg fungovala v režimu manifestu nebo v klasickém režimu.

Výchozí hodnota je ON , když VCPKG_MANIFEST_DIR je neprázdná nebo ${CMAKE_SOURCE_DIR}/vcpkg.json existuje.

Chcete-li zakázat režim manifestu vcpkg.json při zjištění, nastavte na OFFhodnotu .

`VCPKG_MANIFEST_DIR`

Tato proměnná určuje alternativní složku obsahující vcpkg.json manifest.

Výchozí hodnota je ${CMAKE_SOURCE_DIR} , pokud ${CMAKE_SOURCE_DIR}/vcpkg.json existuje.

`VCPKG_MANIFEST_INSTALL`

Tato proměnná určuje, jestli se vcpkg automaticky spustí, aby se během kroku konfigurace nainstalovaly vaše závislosti.

Výchozí hodnota ON je , pokud VCPKG_MANIFEST_MODE je ON.

`VCPKG_BOOTSTRAP_OPTIONS`

Tuto proměnnou lze nastavit na další parametry příkazu, které ./bootstrap-vcpkgse mají předat .

V režimu manifestu se vcpkg automaticky spustí, pokud spustitelný soubor neexistuje.

`VCPKG_OVERLAY_TRIPLETS`

Tuto proměnnou lze nastavit na seznam cest, které se mají předat na příkazovém řádku jako --overlay-triplets=...

`VCPKG_OVERLAY_PORTS`

Tuto proměnnou lze nastavit na seznam cest, které se mají předat na příkazovém řádku jako --overlay-ports=...

`VCPKG_MANIFEST_FEATURES`

Tuto proměnnou lze nastavit na seznam funkcí, které se mají aktivovat při instalaci z manifestu.

Například funkce můžou projekty použít k řízení sestavování s dalšími závislostmi pro povolení testů nebo ukázek:

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

Toto nastavení lze řídit přímo předvolbami CMake nebo "cacheVariables" nepřímo na základě jiných nastavení:

# 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`

Tato proměnná řídí aktivaci výchozích funkcí kromě těch, které jsou uvedeny v VCPKG_MANIFEST_FEATURES. Pokud je nastavená hodnota ON, výchozí funkce se neaktivují automaticky.

Výchozí hodnota OFFje .

`VCPKG_INSTALL_OPTIONS`

Tuto proměnnou lze nastavit na seznam dalších parametrů příkazového řádku, které se předávají nástroji vcpkg během automatické instalace.

`VCPKG_PREFER_SYSTEM_LIBS`

Upozorňující

Tato funkce je zastaralá. Místo toho použijte prázdné překryvné porty.

Tato proměnná určuje, jestli bude vcpkg přidávat místo předpřipravených cest k CMAKE_PREFIX_PATHCMAKE_LIBRARY_PATH knihovnám a balíčkům vcpkg a CMAKE_FIND_ROOT_PATH aby byly nalezeny po toolchain/systémových knihovnách/balíčcích.