Compartir a través de

vcpkg en proyectos de CMake

vcpkg ofrece una integración perfecta con CMake para que los paquetes instalados estén disponibles automáticamente en los proyectos. El mecanismo mediante el cual vcpkg se integra es mediante la provisión de un archivo de toolchain 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 función project() 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 configura CMAKE_TOOLCHAIN_FILE para usar la cadena de herramientas de vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), vcpkg aprovecha el mecanismo de archivos de la cadena de herramientas para inyectar código e integrarlo con las funciones incorporadas de CMake de forma transparente para usted.

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 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 funciones find_package(), find_library(), y find_path().

En modo manifiesto, además de lo anterior, el conjunto de herramientas detecta archivos de manifiesto (vcpkg.json) y 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 es posible que sea necesario reconfigurar su proyecto de CMake si modifica cualquier ajuste de vcpkg que resulte en cambios en el 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 de entorno VCPKG_ROOT, puede usar lo siguiente CMakePresets.json y pasar --preset debug en 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 absoluta para vcpkg que es específico para su máquina actual, puede usar CMakeUserPresets.json y agregarla al archivo .gitignore.

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "debug",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

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 inclusión o enlace en su 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.

CLión

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 las configuraciones de la cadena de herramientas, como el compilador o las opciones de compilación, mientras se construyen bibliotecas. Para cambiar la configuración de bibliotecas de vcpkg, debe crear un archivo de triplet personalizado (que puede compartir su cadena de herramientas)**

Referencia de configuración

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

VCPKG_TARGET_TRIPLET

Esta configuración controla el triplet desde el cual vcpkg instalará y utilizará 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 para qué triplet se instalarán las dependencias del host.

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

Consulte también Dependencias del huésped.

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.

Por defecto 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 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 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 :

# 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 añadirá en lugar de anteponer sus rutas a CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH y CMAKE_FIND_ROOT_PATH para que las bibliotecas/paquetes de vcpkg se encuentren después de las bibliotecas/paquetes de toolchain/system.

Tiene como valor predeterminado OFF.

VCPKG_FEATURE_FLAGS

Esta variable se puede establecer en una lista de 'feature flags' para pasar a la herramienta vcpkg durante la instalación automática para optar por el comportamiento experimental.

Consulte la opción de --feature-flags= línea de comandos para obtener más información.

VCPKG_TRACE_FIND_PACKAGE

Cuando se establece en ON, imprima cada llamada a find_package. Las llamadas anidadas (por ejemplo, a través de find_dependency) se sangrarán según la profundidad de anidamiento.

VCPKG_LOCK_FIND_PACKAGE_<Pkg>

Cuando esta opción está activada, las llamadas no anidadas a find_package son obligatorias (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=ON) o no (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=OFF).

Esta variable es una herramienta para controlar las dependencias directas y las características relacionadas en los puertos vcpkg que usan el sistema de compilación de CMake. Se puede usar con vcpkg_check_features y evita efectos no deseados en dependencias transitivas.