vcpkg en proyectos de CMake

Artículo
01/10/2024

vcpkg ofrece una integración perfecta con CMake para que los paquetes instalados estén disponibles automáticamente en los proyectos. El mecanismo en el que se integra vcpkg es proporcionando un archivo de cadena de herramientas de CMake.

La primera vez que CMake configura un proyecto, ejecuta rutinas de búsqueda internas para buscar una cadena de herramientas viable (compilador, enlazador, etc.). Esta búsqueda se produce dentro de la project() función en CMakeLists.txt.

Para personalizar el proceso de selección de cadenas de herramientas, CMake admite el uso de scripts de lenguaje CMake personalizados, conocidos como archivos de cadena de herramientas. Se especifica un archivo de cadena de herramientas estableciendo la CMAKE_TOOLCHAIN_FILE variable . CMake evalúa el contenido del script de cadena de herramientas proporcionado y establece definiciones de variables, rutas de acceso a las herramientas de compilación necesarias y otros parámetros de compilación, como marcas de compilación cruzadas, en consecuencia.

Cuando se establece CMAKE_TOOLCHAIN_FILE para usar la cadena de herramientas vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), vcpkg aprovecha el mecanismo de archivo de cadena de herramientas para insertar código para integrar con funciones CMake integradas de forma transparente.

Todavía puede usar un archivo de cadena de herramientas para configurar sus propios conjuntos de herramientas mediante la VCPKG_CHAINLOAD_TOOLCHAIN_FILE variable triplet.

La integración de vcpkg funciona de forma diferente en función del modo de operación que use:

En el modo clásico, vcpkg establece las rutas de búsqueda de CMake adecuadamente para que los paquetes instalados estén disponibles a través de las find_package()funciones , find_library()y find_path() .

En el modo de manifiesto, además de lo anterior, la cadena de herramientas detecta archivos de manifiesto (vcpkg.json archivos) y se ejecuta vcpkg install para adquirir automáticamente las dependencias del proyecto.

Dado que el archivo de cadena de herramientas se evalúa durante la project() llamada, todas las variables de nivel de CMake que modifican una configuración de vcpkg deben establecerse antes de la primera llamada a project(). También puede ser necesario volver a configurar el proyecto de CMake si modifica cualquier configuración de vcpkg que produzca cambios hash de ABI .

Consulte Ejemplo de instalación y uso de paquetes: sqlite para ver un ejemplo totalmente trabajado con CMake.

`CMAKE_TOOLCHAIN_FILE`

Nota:

Si establece CMAKE_TOOLCHAIN_FILE en CMakeList.txt el archivo, asegúrese de que la variable está establecida antes de cualquier llamada a project().

Los proyectos configurados para usar el archivo de cadena de herramientas vcpkg (a través del valor CMAKE_TOOLCHAIN_FILEde CMake ) pueden encontrar bibliotecas de vcpkg mediante las funciones estándar de CMake: find_package(), find_path()y find_library().

Se recomienda usar valores preestablecidos de CMake para especificar el archivo de cadena de herramientas. Por ejemplo, si ha definido la variable VCPKG_ROOTde entorno , puede usar lo siguiente CMakePresets.json y pasar --preset debug la línea de configuración:

{
  "version": 2,

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

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

Si necesita usar una ruta de acceso absoluta para vcpkg específico de la máquina actual, puede usar CMakeUserPresets.json y agregarla al .gitignore archivo.

{
  "version": 2,

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

Las versiones de CMake anteriores a la 3.19 deben pasar el archivo de cadena de herramientas en la línea de comandos de configuración:

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

Uso de bibliotecas

vcpkg admite los mecanismos nativos de CMake para buscar bibliotecas: find_package(), find_library()y find_path(). Al instalar bibliotecas con compatibilidad específica con CMake, vcpkg mostrará información de uso sobre cómo consumir la biblioteca:

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

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

vcpkg no agrega automáticamente ninguna ruta de acceso de inclusión o vínculos al proyecto. Para usar una biblioteca de solo encabezado, puede usar find_path() la que funcionará correctamente en todas las plataformas:

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

Integración del IDE

Visual Studio/Visual Studio Code

Se recomienda usar valores preestablecidos de CMake en Visual Studio y Visual Studio Code.

Obtenga más información en Configuración y compilación con valores preestablecidos de CMake en Visual Studio y Configuración y compilación con valores preestablecidos de CMake en Visual Studio Code.

CLion

Abra la configuración de cadenas de herramientas (File > Settings en Windows y Linux, CLion > Preferences en macOS) y vaya a la configuración de CMake (Build, Execution, Deployment > CMake). En CMake options, agregue la siguiente línea:

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

Debe agregar esta línea a cada perfil por separado.

Uso de varios archivos de cadena de herramientas

Para combinar el archivo de cadena de herramientas de vcpkg con otro archivo de cadena de herramientas, puede establecer la variable VCPKG_CHAINLOAD_TOOLCHAIN_FILEde caché de CMake :

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

Como alternativa, puede incluir la cadena de herramientas vcpkg al final del archivo de cadena de herramientas principal:

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

Nota:

vcpkg no aplica automáticamente la configuración de la cadena de herramientas, como el compilador o las marcas de compilación, al compilar bibliotecas. Para cambiar la configuración de la biblioteca de vcpkg, debe crear un archivo triplet personalizado (que puede compartir la cadena de herramientas)**

Referencia de configuración

Todas las variables que afectan a vcpkg deben definirse antes de la primera project() directiva, como en un CMakePresets.jsonmapa de , a través de "cacheVariables" la línea de comandos o set() las instrucciones .

`VCPKG_TARGET_TRIPLET`

Esta configuración controla el vcpkg triplet desde el que se instalarán y consumirán bibliotecas.

Si no se establece, vcpkg detectará automáticamente un triplet predeterminado adecuado según la configuración actual del compilador. Si cambia esta variable de CMake, debe eliminar la memoria caché y volver a configurarla.

`VCPKG_HOST_TRIPLET`

Esta variable controla las dependencias de host triples para las que se instalarán.

Si no se establece, vcpkg detectará automáticamente un triplet nativo adecuado (x64-windows, x64-osx, x64-linux).

Consulte también Dependencias de host.

`VCPKG_INSTALLED_DIR`

Esta variable establece la ubicación desde la que se instalarán y consumirán las bibliotecas.

En el modo de manifiesto, el valor predeterminado es ${CMAKE_BINARY_DIR}/vcpkg_installed.

En el modo clásico, el valor predeterminado es ${VCPKG_ROOT}/installed.

`VCPKG_MANIFEST_MODE`

Esta variable fuerza a vcpkg a operar en modo de manifiesto o en modo clásico.

El valor predeterminado es ON cuando VCPKG_MANIFEST_DIR no está vacío o ${CMAKE_SOURCE_DIR}/vcpkg.json existe.

Para deshabilitar el modo de manifiesto mientras se detecta un vcpkg.json , establezca este valor en OFF.

`VCPKG_MANIFEST_DIR`

Esta variable especifica una carpeta alternativa que contiene un vcpkg.json manifiesto.

El valor predeterminado es ${CMAKE_SOURCE_DIR} si ${CMAKE_SOURCE_DIR}/vcpkg.json existe.

`VCPKG_MANIFEST_INSTALL`

Esta variable controla si vcpkg se ejecutará automáticamente para instalar las dependencias durante el paso de configuración.

El valor predeterminado es ON si VCPKG_MANIFEST_MODE es ON.

`VCPKG_BOOTSTRAP_OPTIONS`

Esta variable se puede establecer en parámetros de comando adicionales para pasar a ./bootstrap-vcpkg.

En el modo de manifiesto, vcpkg se arrancará automáticamente si el ejecutable no existe.

`VCPKG_OVERLAY_TRIPLETS`

Esta variable se puede establecer en una lista de rutas de acceso que se van a pasar en la línea de comandos como --overlay-triplets=...

`VCPKG_OVERLAY_PORTS`

Esta variable se puede establecer en una lista de rutas de acceso que se van a pasar en la línea de comandos como --overlay-ports=...

`VCPKG_MANIFEST_FEATURES`

Esta variable se puede establecer en una lista de características que se van a activar al instalar desde el manifiesto.

Por ejemplo, los proyectos pueden usar características para controlar la compilación con dependencias adicionales para habilitar pruebas o ejemplos:

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

Este valor se puede controlar directamente mediante valores preestablecidos de CMake con "cacheVariables" o indirectamente en función de otras configuraciones:

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

Esta variable controla la activación de características predeterminadas además de las enumeradas en VCPKG_MANIFEST_FEATURES. Si se establece en ON, las características predeterminadas no se activarán automáticamente.

Tiene como valor predeterminado OFF.

`VCPKG_INSTALL_OPTIONS`

Esta variable se puede establecer en una lista de parámetros de línea de comandos adicionales para pasar a la herramienta vcpkg durante la instalación automática.

`VCPKG_PREFER_SYSTEM_LIBS`

Advertencia

Esta característica ha quedado en desuso. En su lugar, use puertos de superposición vacíos.

Esta variable controla si vcpkg anexará en lugar de anteponer sus rutas de acceso a CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH de modo que las bibliotecas o CMAKE_FIND_ROOT_PATH paquetes de vcpkg se encuentren después de la cadena de herramientas,las bibliotecas o paquetes del sistema.