vcpkg w projektach CMake

Artykuł
01/10/2024

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 ustawień

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`

Ostrzeżenie

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.