vcpkg v projektech CMake
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.txt
funkci .
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.cmake
toolchain), 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_FILE
CMake) 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_ROOT
prostř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 options
pole 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_FILE
mezipamě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_installed
výchozí hodnota .
V klasickém režimu je ${VCPKG_ROOT}/installed
vý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 OFF
hodnotu .
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-vcpkg
se 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 OFF
je .
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_PATH
CMAKE_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.
Výchozí hodnota OFF
je .
VCPKG_FEATURE_FLAGS
Tuto proměnnou lze nastavit na seznam příznaků funkcí, které se mají předat nástroji vcpkg během automatické instalace a přihlásit se k experimentálnímu chování.
Další informace najdete v možnosti příkazového --feature-flags=
řádku.
VCPKG_TRACE_FIND_PACKAGE
Pokud je nastavena možnost ON
, tiskněte každý hovor na find_package
. Vnořená volání (např. přes find_dependency
) se odsadí podle hloubky vnoření.