vcpkg w projektach CMake

Narzędzie vcpkg oferuje bezproblemową integrację z narzędziem CMake w celu automatycznego udostępniania zainstalowanych pakietów w projektach. Mechanizm, w którym integruje się narzędzie vcpkg, polega na udostępnieniu pliku łańcucha narzędzi CMake.

Przy pierwszym konfigurowaniu projektu narzędzie CMake uruchamia wewnętrzne procedury wyszukiwania w celu zlokalizowania realnego łańcucha narzędzi (kompilatora, konsolidatora itp.). To wyszukiwanie odbywa się w project() ramach funkcji w pliku CMakeLists.txt.

Aby dostosować proces wyboru łańcucha narzędzi, narzędzie CMake obsługuje używanie niestandardowych skryptów CMake-language, znanych jako pliki łańcucha narzędzi. Plik łańcucha narzędzi jest określany przez ustawienie zmiennej CMAKE_TOOLCHAIN_FILE . Narzędzie CMake ocenia zawartość dostarczonego skryptu łańcucha narzędzi i ustawia definicje zmiennych, ścieżki do wymaganych narzędzi kompilacji i inne parametry kompilacji, takie jak flagi kompilacji krzyżowej, odpowiednio.

Po ustawieniu CMAKE_TOOLCHAIN_FILE używania łańcucha narzędzi vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), narzędzie vcpkg korzysta z mechanizmu pliku łańcucha narzędzi do wstrzykiwania kodu w celu zintegrowania z wbudowanymi funkcjami CMake.

Nadal możesz użyć pliku łańcucha narzędzi, aby skonfigurować własne zestawy narzędzi przy użyciu zmiennej potrójnej VCPKG_CHAINLOAD_TOOLCHAIN_FILE .

Integracja z narzędziem vcpkg działa inaczej w zależności od używanego trybu działania:

W trybie klasycznym narzędzie vcpkg odpowiednio ustawia ścieżki wyszukiwania narzędzia CMake w celu udostępnienia zainstalowanych pakietów za pośrednictwem find_package()funkcji , find_library()i find_path() .

W trybie manifestu, oprócz powyższych, łańcuch narzędzi wykrywa pliki manifestu (vcpkg.json pliki) i uruchamia polecenie vcpkg install w celu automatycznego uzyskania zależności projektu.

Ponieważ plik łańcucha narzędzi jest obliczany podczas project() wywołania, wszystkie zmienne poziomu CMake modyfikujące ustawienie vcpkg muszą być ustawione przed pierwszym wywołaniem metody project(). Może być również konieczne ponowne skonfigurowanie projektu narzędzia CMake, jeśli zmodyfikujesz dowolne ustawienie vcpkg, które spowoduje zmianę skrótu usługi ABI.

Zobacz Przykład instalowania i używania pakietów: sqlite , aby zapoznać się z w pełni sprawnym przykładem użycia narzędzia CMake.

CMAKE_TOOLCHAIN_FILE

Uwaga

W przypadku ustawienia CMAKE_TOOLCHAIN_FILE w CMakeList.txt pliku upewnij się, że zmienna jest ustawiona przed wywołaniami metody project().

Projekty skonfigurowane do używania pliku łańcucha narzędzi vcpkg (za pomocą ustawienia CMAKE_TOOLCHAIN_FILECMake ) mogą znajdować biblioteki z narzędzia vcpkg przy użyciu standardowych funkcji CMake: find_package(), find_path()i find_library().

Zalecamy używanie ustawień wstępnych narzędzia CMake w celu określenia pliku łańcucha narzędzi. Jeśli na przykład zdefiniowano zmienną środowiskową , możesz użyć następującej CMakePresets.json metody VCPKG_ROOTi przekazać --preset debug w wierszu konfiguracji:

{
  "version": 2,

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

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

Jeśli musisz użyć ścieżki bezwzględnej dla narzędzia vcpkg specyficznego dla bieżącej maszyny, możesz użyć CMakeUserPresets.json polecenia i dodać ją do .gitignore pliku.

{
  "version": 2,

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

Wersje narzędzia CMake starsze niż 3.19 muszą przekazać plik łańcucha narzędzi w wierszu polecenia konfiguracji:

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

Korzystanie z bibliotek

Narzędzie vcpkg obsługuje natywne mechanizmy narzędzia CMake do znajdowania bibliotek: find_package(), find_library()i find_path(). Podczas instalowania bibliotek z określoną obsługą narzędzia CMake narzędzie vcpkg wyświetli informacje o użyciu dotyczące korzystania z biblioteki:

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

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

Narzędzie vcpkg nie dodaje automatycznie żadnych ścieżek dołączania ani łączy do projektu. Aby użyć biblioteki tylko do nagłówka, można użyć find_path() , która będzie działać poprawnie na wszystkich platformach:

# 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 Integration (Integracja środowiska IDE)

Visual Studio/Visual Studio Code

Zalecamy używanie ustawień wstępnych narzędzia CMake zarówno w programie Visual Studio, jak i programie Visual Studio Code.

Dowiedz się więcej na stronie Konfigurowanie i kompilowanie przy użyciu ustawień wstępnych narzędzia CMake w programie Visual Studio oraz Konfigurowanie i kompilowanie przy użyciu ustawień wstępnych narzędzia CMake w programie Visual Studio Code.

CLion

Otwórz ustawienia łańcuchów narzędzi (File > Settings w systemach Windows i Linux w CLion > Preferences systemie macOS) i przejdź do ustawień narzędzia CMake (Build, Execution, Deployment > CMake). W CMake optionspliku dodaj następujący wiersz:

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

Ten wiersz należy dodać do każdego profilu oddzielnie.

Używanie wielu plików łańcucha narzędzi

Aby połączyć plik łańcucha narzędzi vcpkg z innym plikiem łańcucha narzędzi, możesz ustawić zmienną VCPKG_CHAINLOAD_TOOLCHAIN_FILEpamięci podręcznej CMake :

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

Alternatywnie możesz dołączyć łańcuch narzędzi vcpkg na końcu podstawowego pliku łańcucha narzędzi:

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

Uwaga

Narzędzie vcpkg nie stosuje automatycznie ustawień łańcucha narzędzi, takich jak flagi kompilatora lub kompilacji, podczas kompilowania bibliotek. Aby zmienić ustawienia biblioteki programu vcpkg, musisz utworzyć niestandardowy plik potrójny (który może udostępniać łańcuch narzędzi)**

dokumentacja Ustawienia

Wszystkie zmienne wpływające na program vcpkg muszą być zdefiniowane przed pierwszą project() dyrektywą "cacheVariables"CMakePresets.json, taką jak na mapie , za pośrednictwem wiersza polecenia lub set() instrukcji.

VCPKG_TARGET_TRIPLET

To ustawienie steruje potrójnym vcpkg zainstaluje i zużyje biblioteki.

Jeśli ustawienie nie zostanie ustawione, narzędzie vcpkg automatycznie wykryje odpowiedni domyślny triplet, biorąc pod uwagę bieżące ustawienia kompilatora. Jeśli zmienisz tę zmienną CMake, musisz usunąć pamięć podręczną i ponownie skonfigurować.

VCPKG_HOST_TRIPLET

Ta zmienna steruje zależnościami potrójnego hosta, dla których zostaną zainstalowane.

Jeśli program vcpkg nie zostanie zdenerwowany, automatycznie wykryje odpowiedni natywny triplet (x64-windows, x64-osx, x64-linux).

Zobacz również Zależności hosta.

VCPKG_INSTALLED_DIR

Ta zmienna ustawia lokalizację, z której będą instalowane i używane biblioteki.

W trybie manifestu wartość domyślna to ${CMAKE_BINARY_DIR}/vcpkg_installed.

W trybie klasycznym wartość domyślna to ${VCPKG_ROOT}/installed.

VCPKG_MANIFEST_MODE

Ta zmienna wymusza działanie programu vcpkg w trybie manifestu lub w trybie klasycznym.

Wartość domyślna to ON , gdy VCPKG_MANIFEST_DIR nie jest pusta lub ${CMAKE_SOURCE_DIR}/vcpkg.json istnieje.

Aby wyłączyć tryb manifestu podczas wykrywania vcpkg.json elementu , ustaw wartość OFF.

VCPKG_MANIFEST_DIR

Ta zmienna określa folder alternatywny zawierający vcpkg.json manifest.

Wartość domyślna to ${CMAKE_SOURCE_DIR} , jeśli ${CMAKE_SOURCE_DIR}/vcpkg.json istnieje.

VCPKG_MANIFEST_INSTALL

Ta zmienna określa, czy narzędzie vcpkg zostanie automatycznie uruchomione w celu zainstalowania zależności podczas kroku konfigurowania.

Wartość domyślna to ON , jeśli VCPKG_MANIFEST_MODE ma wartość ON.

VCPKG_BOOTSTRAP_OPTIONS

Tę zmienną można ustawić na dodatkowe parametry polecenia, które mają zostać przekazane do ./bootstrap-vcpkg.

W trybie manifestu narzędzie vcpkg zostanie automatycznie uruchomione, jeśli plik wykonywalny nie istnieje.

VCPKG_OVERLAY_TRIPLETS

Tę zmienną można ustawić na listę ścieżek, które mają być przekazywane w wierszu polecenia jako --overlay-triplets=...

VCPKG_OVERLAY_PORTS

Tę zmienną można ustawić na listę ścieżek, które mają być przekazywane w wierszu polecenia jako --overlay-ports=...

VCPKG_MANIFEST_FEATURES

Tę zmienną można ustawić na listę funkcji, które mają zostać aktywowane podczas instalowania z manifestu.

Na przykład funkcje mogą być używane przez projekty do kontrolowania kompilowania z dodatkowymi zależnościami w celu włączenia testów lub przykładów:

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

To ustawienie może być kontrolowane bezpośrednio przez ustawienia wstępne narzędzia CMake z "cacheVariables" lub pośrednio w oparciu o inne ustawienia:

# 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

Ta zmienna kontroluje aktywację funkcji domyślnych oprócz tych wymienionych w pliku VCPKG_MANIFEST_FEATURES. Jeśli zostanie ustawiona ONwartość , funkcje domyślne nie zostaną automatycznie aktywowane.

Wartość domyślna to OFF.

VCPKG_INSTALL_OPTIONS

Tę zmienną można ustawić na listę dodatkowych parametrów wiersza polecenia, które mają zostać przekazane do narzędzia vcpkg podczas instalacji automatycznej.

VCPKG_PREFER_SYSTEM_LIBS

Ta funkcja jest przestarzała. Zamiast tego użyj pustych portów nakładki.

Ta zmienna określa, czy narzędzie vcpkg dołączy zamiast prepend jego ścieżek do CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH i CMAKE_FIND_ROOT_PATH tak, aby biblioteki/pakiety vcpkg zostały znalezione po bibliotece narzędzi/bibliotekach systemowych/pakietach.

Wartość domyślna to OFF.

VCPKG_FEATURE_FLAGS

Tę zmienną można ustawić na listę flag funkcji, które mają zostać przekazane do narzędzia vcpkg podczas automatycznej instalacji, aby wyrazić zgodę na zachowanie eksperymentalne.

--feature-flags= Aby uzyskać więcej informacji, zobacz opcję wiersza polecenia.

VCPKG_TRACE_FIND_PACKAGE

Gdy jest ustawiona wartość ON, wydrukuj każde wywołanie na find_package. Zagnieżdżone wywołania (np. za pośrednictwem find_dependency) są wcięte zgodnie z głębią zagnieżdżenia.