Tutorial: Empaquetado de una biblioteca con vcpkg

Este tutorial le guía sobre cómo empaquetar una biblioteca para vcpkg mediante una superposición personalizada. Se recomienda leer el tutorial Instalación y uso de paquetes con CMake antes de continuar.

Requisitos previos

• Un terminal
• Un compilador de C++
• CMake
• Git

1 - Configurar vcpkg

1. Clonación del repositorio

   El primer paso es clonar el repositorio vcpkg desde GitHub. El repositorio contiene scripts para adquirir el ejecutable vcpkg y un registro de bibliotecas de código abierto mantenidas mantenidas por la comunidad de vcpkg. Para hacerlo, ejecute lo siguiente:

   git clone https://github.com/microsoft/vcpkg.git
   

   El registro mantenido de vcpkg es un conjunto de más de 2000 bibliotecas de código abierto. Las canalizaciones de integración continua de vcpkg han validado estas bibliotecas para trabajar conjuntamente. Aunque el repositorio vcpkg no contiene el código fuente de estas bibliotecas, contiene recetas y metadatos para compilarlos e instalarlos en el sistema.

2. Ejecución del script de arranque

   Ahora que ha clonado el repositorio vcpkg, vaya al vcpkg directorio y ejecute el script de arranque:

   cd vcpkg && bootstrap-vcpkg.bat
   

   cd vcpkg; .\bootstrap-vcpkg.bat
   

   cd vcpkg && ./bootstrap-vcpkg.sh
   

   El script de arranque realiza comprobaciones de requisitos previos y descarga el ejecutable vcpkg.

   Eso es todo. vcpkg está configurado y listo para usarse.

2- Configuración de la variable de VCPKG_ROOT entorno

Para establecer las variables de VCPKG_ROOT entorno, ejecute los siguientes comandos:

export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

set "VCPKG_ROOT=C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

$env:VCPKG_ROOT="C:\path\to\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"

La configuración VCPKG_ROOT indica a vcpkg dónde se encuentra la instancia de vcpkg. Agregarlo a PATH garantiza que puede ejecutar comandos vcpkg directamente desde el shell.

3 - Configuración de la superposición personalizada

1. Cree un directorio llamado junto al Hello World proyecto que creó en el tutorial Instalación y uso de paquetes con CMake.custom-overlay
2. En custom-overlay el directorio, cree una carpeta denominada vcpkg-sample-library.

4 - Configurar los archivos de puerto

En primer lugar, cree el vcpkg.json archivo dentro de la custom-overlay\vcpkg-sample-library carpeta con el siguiente contenido:

{
  "name": "vcpkg-sample-library",
  "version": "1.0.2",
  "homepage": "https://github.com/microsoft/vcpkg-docs/tree/cmake-sample-lib",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "license": "MIT",
  "dependencies": [
    {
      "name" : "vcpkg-cmake",
      "host" : true
    },
    {
      "name" : "vcpkg-cmake-config",
      "host" : true
    },
    "fmt"
  ]
}

El vcpkg.json archivo actúa como manifiesto que define metadatos y dependencias para una biblioteca de C++, lo que proporciona vcpkg con la información necesaria para compilar, instalar y administrar el paquete.

• name: especifica el nombre de la biblioteca. Se usa como identificador de paquete.
• version: indica el número de versión de la biblioteca.
• homepage: dirección URL a la página principal del proyecto, a menudo su repositorio. Útil para aquellos que quieren saber más o contribuir.
• description: texto breve que describe lo que hace la biblioteca. Esto es para la documentación y los usuarios.
• license: especifica la licencia con la que se distribuye la biblioteca.
• dependencies: matriz que contiene la lista de dependencias que necesita la biblioteca.
• name: vcpkg-cmakeespecifica una dependencia de vcpkg-cmake, que proporciona funciones y macros de CMake que se usan habitualmente en los puertos vcpkg.
• host: true: especifica que vcpkg-cmake es una dependencia de host, lo que significa que es necesario para compilar el paquete, pero no para usarlo.
• name: vcpkg-cmake-configespecifica una dependencia de vcpkg-cmake-config, que ayuda a usar scripts de configuración de CMake.
• fmt: especifica una dependencia en tiempo de ejecución en la fmt biblioteca. Esto significa que fmt es necesario para compilar y usar el paquete.

Para obtener más información sobre vcpkg.json, consulte la siguiente documentación sobre manifiestos.

Ahora, cree el usage archivo en el custom-overlay\vcpkg-sample-library directorio con el siguiente contenido:

vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

Proporcionar documentación de uso para los puertos permite a los usuarios adoptarlos fácilmente en sus proyectos. Se recomienda encarecidamente proporcionar un usage archivo dentro del directorio del puerto (ports/<port name>/usage) que describa los pasos mínimos necesarios para integrarse con un sistema de compilación. Para determinar las instrucciones de uso correctas, se recomienda seguir las instrucciones de la cadena ascendente. En caso de que la cadena ascendente no proporcione información de uso, puede ser necesario profundizar en su sistema de compilación para encontrar los destinos exportados.

Para obtener más instrucciones, consulte Control de archivos de uso.

Por último, cree el portfile.cmake archivo en el custom-overlay\vcpkg-sample-library directorio con el siguiente contenido:

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO Microsoft/vcpkg-docs
    REF "${VERSION}"
    SHA512 0  # This is a temporary value. We will modify this value in the next section.
    HEAD_REF cmake-sample-lib
)


vcpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

vcpkg_cmake_install()

vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

Esto portfile define cómo descargar, compilar, instalar y empaquetar una biblioteca específica de C++ desde GitHub mediante vcpkg.

• vcpkg_check_linkage(ONLY_STATIC_LIBRARY): especifica que solo se admite la vinculación estática para este paquete.
• vcpkg_from_github: inicia la función para descargar el código fuente de un repositorio de GitHub.
  • OUT_SOURCE_PATH SOURCE_PATH: establece el directorio donde se extraerá el código fuente.
  • REPO Microsoft/vcpkg-docs: repositorio de GitHub que contiene el código fuente.
  • REF "${VERSION}": la versión del código fuente que se va a descargar.
  • SHA512 0: marcador de posición para el hash SHA-512 del código fuente para la comprobación de integridad.
  • HEAD_REF main: especifica la rama predeterminada para el repositorio.
• vcpkg_cmake_configure: configura el proyecto mediante CMake y configura la compilación.
  • SOURCE_PATH "${SOURCE_PATH}": ruta de acceso al código fuente descargado anteriormente.
• vcpkg_cmake_install(): compila e instala el paquete mediante CMake.
• vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): corrige los archivos de configuración del paquete de CMake para que sean compatibles con vcpkg.
• file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): elimina el directorio include de la instalación de depuración para evitar la superposición.
• file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): instala el archivo LICENSE en el directorio de recursos compartidos del paquete y lo cambia a copyright.
• configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): copia un archivo de instrucciones de uso en el directorio de recursos compartidos del paquete.

Para obtener más información, consulte la guía del mantenedor.

5 - Actualizar SHA512 para portfile.cmake

Ejecute:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Recibirá un mensaje de error largo. Examine la salida hasta que encuentre:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Copie el valor "Hash real" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417y reemplace el SHA512 valor de portfile.cmake por su valor.

Vuelva a ejecutar el comando install:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Computing installation plan...
The following packages will be built and installed:
    vcpkg-sample-library:x64-windows -> 1.0.2 -- C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
Detecting compiler hash for triplet x64-windows...
Restored 0 package(s) from C:\Users\dev\AppData\Local\vcpkg\archives in 174 us. Use --debug to see more details.
Installing 1/1 vcpkg-sample-library:x64-windows...
Building vcpkg-sample-library:x64-windows...
-- Installing port from location: C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
-- Note: vcpkg-sample-library only supports static library linkage. Building static library.
-- Using cached Microsoft-vcpkg-docs-1.0.2.tar.gz.
-- Cleaning sources at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source C:/Users/dev/demo/vcpkg/downloads/Microsoft-vcpkg-docs-1.0.2.tar.gz
-- Using source at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/copyright
-- Performing post-build validation
Stored binaries in 1 destinations in 94 ms.
Elapsed time to handle vcpkg-sample-library:x64-windows: 6.1 s
Total install time: 6.1 s
vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

6- Comprobación de la compilación del puerto

Para comprobar que la biblioteca se compila y vincula correctamente, agregue una nueva dependencia al helloworld proyecto creado en el tutorial de instalación de paquetes. Realice los siguientes cambios en el manifiesto y los archivos de configuración del proyecto.

Modifique helloworld/vcpkg.json para agregar una dependencia en vcpkg-sample-library:

{
    "dependencies": [
        "fmt",
        "vcpkg-sample-library"
    ]
}

Modifique helloworld/vcpkg-configuration.json para incluir la overlay-ports carpeta que contiene el puerto nuevo:

{
  "default-registry": {
    "kind": "git",
    "baseline": "45f6e57d3e10ad96b7db206cf7888f736ba5aa61",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "overlay-ports": [
    "../custom-overlay"
  ]
}

A continuación, modifique helloworld/CMakeLists.txt y helloworld/main.cpp use la nueva dependencia.

Modifique con helloworld/CMakeLists.txt el siguiente contenido:

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)
find_package(my_sample_lib CONFIG REQUIRED)  # Add this line

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
target_link_libraries(HelloWorld PRIVATE my_sample_lib::my_sample_lib)  # Add this line

Modifique con main.cpp el siguiente contenido:

#include "my_sample_lib.h"  // Replace #include <fmt/core.h> with "my_sample_lib.h"

int main()
{
    greet("vcpkg!");  // Replace fmt::print("Hello World!\n) with this line
    return 0;
}

Configure, compile y ejecute la aplicación.

1. Configure la compilación mediante CMake:

cmake --preset=default

2. Compile el proyecto:

cmake --build build

3. Ejecute la aplicación:

./build/HelloWorld

La ruta de acceso al archivo ejecutable del proyecto puede ser diferente, por ejemplo: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Pasos siguientes

Ahora que se vcpkg-sample-library ha empaquetado como puerto, el siguiente paso es agregarlo al registro mantenido de vcpkg. Consulte Adición de puertos al registro vcpkg.

Para más información, vea:

• Puertos
• Guía del mantenedor