Tutoriel : Empaqueter une bibliothèque avec vcpkg

Article
07/22/2024

Ce tutoriel vous guide sur la façon de empaqueter une bibliothèque pour vcpkg à l’aide d’une superposition personnalisée. Nous vous recommandons de lire le didacticiel Installer et utiliser des packages avec CMake avant de continuer.

Prérequis

Un terminal
Compilateur C++
CMake
Git

Remarque

Sur Windows, ce didacticiel utilise MSVC de Visual Studio comme compilateur pour le développement C++.

1 - Configurer vcpkg

Cloner le référentiel

La première étape consiste à cloner le référentiel vcpkg à partir de GitHub. Le référentiel contient des scripts pour acquérir l’exécutable vcpkg et un registre de bibliothèques open source organisées gérées par la communauté vcpkg. Pour ce faire, exécutez :
```
git clone https://github.com/microsoft/vcpkg.git
```
Le registre organisé vcpkg est un ensemble de plus de 2 000 bibliothèques open source. Ces bibliothèques ont été validées par les pipelines d’intégration continue de vcpkg pour fonctionner ensemble. Bien que le référentiel vcpkg ne contienne pas le code source de ces bibliothèques, il contient des recettes et des métadonnées pour les générer et les installer dans votre système.
Exécuter le script bootstrap

Maintenant que vous avez cloné le référentiel vcpkg, accédez au vcpkg répertoire et exécutez le script de démarrage :
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
Le script d’amorçage effectue des vérifications des prérequis et télécharge l’exécutable vcpkg.

Et voilà ! vcpkg est configuré et prêt à être utilisé.

2 - Configurer la variable d’environnement `VCPKG_ROOT`

Pour définir les variables d’environnement VCPKG_ROOT , exécutez les commandes suivantes :

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

Remarque

La définition de variables d’environnement à l’aide de la export commande affecte uniquement la session shell active. Pour rendre cette modification permanente entre les sessions, ajoutez la export commande au script de profil de votre interpréteur de commandes (par exemple, ~/.bashrc ou ~/.zshrc).

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

Remarque

La définition de variables d’environnement de cette façon affecte uniquement la session de terminal active. Pour rendre ces modifications permanentes dans toutes les sessions, définissez-les via le panneau Variables d’environnement système Windows.

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

Remarque

Le paramètre VCPKG_ROOT indique à vcpkg où se trouve votre instance vcpkg. L’ajout de ces commandes vous PATH permet d’exécuter des commandes vcpkg directement à partir de l’interpréteur de commandes.

3 - Configurer la superposition personnalisée

Créez un répertoire appelé en regard du Hello World projet que custom-overlay vous avez créé dans le didacticiel Installer et utiliser des packages avec le didacticiel CMake.
Dans custom-overlay le répertoire, créez un dossier nommé vcpkg-sample-library.

4 - Configurer les fichiers de port

Tout d’abord, créez le vcpkg.json fichier dans le custom-overlay\vcpkg-sample-library dossier avec le contenu suivant :

{
  "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"
  ]
}

Le vcpkg.json fichier sert de manifeste qui définit les métadonnées et les dépendances d’une bibliothèque C++, fournissant à vcpkg les informations nécessaires pour générer, installer et gérer le package.

name: spécifie le nom de la bibliothèque. Il s’agit de l’identificateur du package.
version: indique le numéro de version de la bibliothèque.
homepage: URL de la page d’accueil du projet, souvent son référentiel. Utile pour ceux qui veulent en savoir plus ou contribuer.
description: texte bref décrivant ce que fait la bibliothèque. Il s’agit de la documentation et des utilisateurs.
license: spécifie la licence sous laquelle la bibliothèque est distribuée.
dependencies: tableau contenant la liste des dépendances dont la bibliothèque a besoin.
name: vcpkg-cmakespécifie une dépendance sur vcpkg-cmake, qui fournit des fonctions CMake et des macros couramment utilisées dans les ports vcpkg.
host: true : spécifie qu’il vcpkg-cmake s’agit d’une dépendance hôte, ce qui signifie qu’elle est requise pour générer le package, mais pas pour l’utiliser.
name: vcpkg-cmake-config: spécifie une dépendance sur vcpkg-cmake-configlaquelle il est utile d’utiliser des scripts de configuration CMake.
fmt: spécifie une dépendance au moment de l’exécution sur la fmt bibliothèque. Cela signifie qu’il fmt est nécessaire de créer et d’utiliser le package.

Pour plus d’informations sur vcpkg.json, consultez la documentation suivante sur les manifestes.

À présent, créez le usage fichier dans le custom-overlay\vcpkg-sample-library répertoire avec le contenu suivant :

vcpkg-sample-library provides CMake targets:

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

Fournir la documentation d’utilisation pour les ports permet aux utilisateurs de les adopter facilement dans leurs projets. Nous encourageons vivement à fournir un usage fichier dans le répertoire du port (ports/<port name>/usage) qui décrit les étapes minimales nécessaires à l’intégration à un système de génération. Pour déterminer les instructions d’utilisation correctes, il est recommandé de suivre les instructions en amont. Dans le cas où l’amont ne fournit pas d’informations d’utilisation, il peut être nécessaire d’explorer leur système de build pour rechercher les cibles exportées.

Pour plus d’informations, consultez la gestion des fichiers d’utilisation

Enfin, créez le portfile.cmake fichier dans le custom-overlay\vcpkg-sample-library répertoire avec le contenu suivant :

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)

Cela portfile définit comment télécharger, générer, installer et empaqueter une bibliothèque C++ spécifique à partir de GitHub à l’aide de vcpkg.

vcpkg_check_linkage(ONLY_STATIC_LIBRARY): spécifie que seule la liaison statique est prise en charge pour ce package.
vcpkg_from_github: démarre la fonction pour télécharger le code source à partir d’un dépôt GitHub.
- OUT_SOURCE_PATH SOURCE_PATH: définit le répertoire dans lequel le code source sera extrait.
- REPO Microsoft/vcpkg-docs: référentiel GitHub contenant le code source.
- REF "${VERSION}": version du code source à télécharger.
- SHA512 0: espace réservé pour le hachage SHA-512 du code source pour la vérification de l’intégrité.
- HEAD_REF main: spécifie la branche par défaut du référentiel.
vcpkg_cmake_configure: configure le projet à l’aide de CMake, en configurant la build.
- SOURCE_PATH "${SOURCE_PATH}": chemin d’accès au code source téléchargé précédemment.
vcpkg_cmake_install(): génère et installe le package à l’aide de CMake.
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): corrige les fichiers de configuration du package CMake pour qu’ils soient compatibles avec vcpkg.
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): supprime le répertoire include de l’installation de débogage pour empêcher le chevauchement.
file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): installe le fichier LICENSE dans le répertoire de partage du package et le renomme en droits d’auteur.
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): copie un fichier d’instructions d’utilisation dans le répertoire de partage du package.

Pour plus d’informations, reportez-vous au guide de maintenance.

5 - Mettre à jour SHA512 pour `portfile.cmake`

Run :

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

Vous obtiendrez un message d’erreur long. Analysez la sortie jusqu’à ce que vous trouviez :

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Copiez le « hachage réel » 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417et remplacez la SHA512 valeur dans la portfile.cmake valeur par sa valeur.

Réexécutez la commande d’installation :

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 - Vérifier la build du port

Pour vérifier correctement les builds et liens de la bibliothèque, ajoutez une nouvelle dépendance au helloworld projet créé dans le didacticiel sur les packages d’installation. Apportez les modifications suivantes au manifeste et aux fichiers de configuration du projet.

Modifiez helloworld/vcpkg.json pour ajouter une dépendance sur vcpkg-sample-library:

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

Modifiez helloworld/vcpkg-configuration.json pour inclure le overlay-ports dossier qui contient le nouveau port :

{
  "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"
  ]
}

Ensuite, modifiez helloworld/CMakeLists.txt et helloworld/main.cpp utilisez la nouvelle dépendance.

Modifiez le helloworld/CMakeLists.txt contenu suivant :

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

Modifiez le main.cpp contenu suivant :

#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;
}

Configurez, générez et exécutez l’application.

Configurez la build à l’aide de CMake :

cmake --preset=default

Générez le projet :

cmake --build build

Exécutez l’application :

./build/HelloWorld

Le chemin d’accès à l’exécutable de votre projet peut être différent, par exemple : ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Étapes suivantes

Maintenant que le vcpkg-sample-library port a été empaqueté, l’étape suivante consiste à l’ajouter au registre organisé vcpkg. Consultez l’article Ajout de ports au registre vcpkg.

Pour plus d’informations, consultez l’article suivant :

Partager via

Tutoriel : Empaqueter une bibliothèque avec vcpkg

Prérequis

1 - Configurer vcpkg

2 - Configurer la variable d’environnement `VCPKG_ROOT`

3 - Configurer la superposition personnalisée

4 - Configurer les fichiers de port

5 - Mettre à jour SHA512 pour `portfile.cmake`

6 - Vérifier la build du port

Étapes suivantes

Ressources supplémentaires

Partager via

Tutoriel : Empaqueter une bibliothèque avec vcpkg

Prérequis

1 - Configurer vcpkg

2 - Configurer la variable d’environnement VCPKG_ROOT

3 - Configurer la superposition personnalisée

4 - Configurer les fichiers de port

5 - Mettre à jour SHA512 pour portfile.cmake

6 - Vérifier la build du port

Étapes suivantes

Ressources supplémentaires

2 - Configurer la variable d’environnement `VCPKG_ROOT`

5 - Mettre à jour SHA512 pour `portfile.cmake`