Esercitazione: Creare un pacchetto di una libreria con vcpkg

Questa esercitazione illustra come creare un pacchetto di una libreria per vcpkg usando una sovrimpressione personalizzata. È consigliabile leggere l'esercitazione Installare e usare pacchetti con CMake prima di procedere.

Prerequisiti

• Un terminale
• Compilatore C++
• CMake
• Git

1 - Configurare vcpkg

1. Clonare il repository

   Il primo passaggio consiste nel clonare il repository vcpkg da GitHub. Il repository contiene script per acquisire l'eseguibile vcpkg e un registro di librerie open source curate gestite dalla community vcpkg. A tale scopo, eseguire:

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

   Il registro curato vcpkg è un set di oltre 2.000 librerie open source. Queste librerie sono state convalidate dalle pipeline di integrazione continua di vcpkg per collaborare. Anche se il repository vcpkg non contiene il codice sorgente per queste librerie, contiene ricette e metadati per compilarli e installarli nel sistema.

2. Eseguire lo script bootstrap

   Dopo aver clonato il repository vcpkg, passare alla vcpkg directory ed eseguire lo script bootstrap:

   cd vcpkg && bootstrap-vcpkg.bat
   

   cd vcpkg; .\bootstrap-vcpkg.bat
   

   cd vcpkg && ./bootstrap-vcpkg.sh
   

   Lo script bootstrap esegue i controlli dei prerequisiti e scarica il file eseguibile vcpkg.

   Ecco fatto! vcpkg è configurato e pronto per l'uso.

2 - Configurare la VCPKG_ROOT variabile di ambiente

Per impostare le VCPKG_ROOT variabili di ambiente, eseguire i comandi seguenti:

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"

L'impostazione VCPKG_ROOT indica a vcpkg dove si trova l'istanza vcpkg. Aggiungendolo per PATH assicurarsi di poter eseguire comandi vcpkg direttamente dalla shell.

3 - Configurare la sovrimpressione personalizzata

1. Creare una nuova directory denominata custom-overlay accanto al Hello World progetto creato nell'esercitazione Installare e usare pacchetti con CMake .
2. All'interno della custom-overlay directory creare una cartella denominata vcpkg-sample-library.

4 - Configurare i file di porta

Creare prima di tutto il vcpkg.json file all'interno della custom-overlay\vcpkg-sample-library cartella con il contenuto seguente:

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

Il vcpkg.json file funge da manifesto che definisce metadati e dipendenze per una libreria C++, fornendo a vcpkg le informazioni necessarie per compilare, installare e gestire il pacchetto.

• name: specifica il nome della libreria. Viene usato come identificatore del pacchetto.
• version: indica il numero di versione della libreria.
• homepage: URL della home page del progetto, spesso il relativo repository. Utile per coloro che vogliono saperne di più o contribuire.
• description: breve testo che descrive le operazioni della libreria. Questo vale per la documentazione e gli utenti.
• license: specifica la licenza con cui viene distribuita la libreria.
• dependencies: matrice contenente l'elenco delle dipendenze necessarie per la libreria.
• name: vcpkg-cmakespecifica una dipendenza da vcpkg-cmake, che fornisce funzioni e macro CMake comunemente usate nelle porte vcpkg.
• host: true: specifica che vcpkg-cmake è una dipendenza host, ovvero è necessaria per la compilazione del pacchetto ma non per l'uso.
• name: vcpkg-cmake-configspecifica una dipendenza da vcpkg-cmake-config, utile per l'uso degli script di configurazione di CMake.
• fmt: specifica una dipendenza di runtime dalla fmt libreria. Ciò significa che fmt è necessario sia per la compilazione che per l'uso del pacchetto.

Per altre informazioni su vcpkg.json, vedere la documentazione seguente sui manifesti.

Creare ora il usage file all'interno della custom-overlay\vcpkg-sample-library directory con il contenuto seguente:

vcpkg-sample-library provides CMake targets:

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

La documentazione sull'utilizzo per le porte consente agli utenti di adottarli facilmente nei progetti. È consigliabile fornire un usage file all'interno della directory della porta (ports/<port name>/usage) che descrive i passaggi minimi necessari per l'integrazione con un sistema di compilazione. Per determinare le istruzioni di utilizzo corrette, è consigliabile seguire le indicazioni di upstream. Nel caso in cui upstream non fornisca informazioni sull'utilizzo, potrebbe essere necessario esaminare il sistema di compilazione per trovare le destinazioni esportate.

Per altre indicazioni, vedere Gestione dei file di utilizzo

Infine, creare il portfile.cmake file all'interno della custom-overlay\vcpkg-sample-library directory con il contenuto seguente:

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)

Questo portfile definisce come scaricare, compilare, installare e creare un pacchetto di una libreria C++ specifica da GitHub usando vcpkg.

• vcpkg_check_linkage(ONLY_STATIC_LIBRARY): specifica che per questo pacchetto è supportato solo il collegamento statico.
• vcpkg_from_github: avvia la funzione per scaricare il codice sorgente da un repository GitHub.
  • OUT_SOURCE_PATH SOURCE_PATH: imposta la directory in cui verrà estratto il codice sorgente.
  • REPO Microsoft/vcpkg-docs: repository GitHub contenente il codice sorgente.
  • REF "${VERSION}": versione del codice sorgente da scaricare.
  • SHA512 0: segnaposto per l'hash SHA-512 del codice sorgente per la verifica dell'integrità.
  • HEAD_REF main: specifica il ramo predefinito per il repository.
• vcpkg_cmake_configure: configura il progetto usando CMake, configurando la compilazione.
  • SOURCE_PATH "${SOURCE_PATH}": percorso del codice sorgente scaricato in precedenza.
• vcpkg_cmake_install(): compila e installa il pacchetto usando CMake.
• vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): corregge i file di configurazione del pacchetto CMake in modo che siano compatibili con vcpkg.
• file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): elimina la directory di inclusione dall'installazione di debug per evitare sovrapposizioni.
• file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): installa il file LICENSE nella directory di condivisione del pacchetto e lo rinomina in copyright.
• configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): copia un file di istruzioni di utilizzo nella directory di condivisione del pacchetto.

Per altre informazioni, vedere la guida del responsabile della manutenzione.

5 - Aggiornare SHA512 per portfile.cmake

Eseguire:

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

Verrà visualizzato un messaggio di errore lungo. Analizza l'output finché non trovi:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Copiare "Hash effettivo" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417e sostituire il SHA512 valore in portfile.cmake con il relativo valore.

Eseguire nuovamente il comando di installazione:

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 - Verificare la compilazione della porta

Per verificare correttamente le compilazioni e i collegamenti della libreria, aggiungere una nuova dipendenza al helloworld progetto creato nell'esercitazione sui pacchetti di installazione. Apportare le modifiche seguenti ai file di configurazione e al manifesto del progetto.

Modificare helloworld/vcpkg.json per aggiungere una dipendenza da vcpkg-sample-library:

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

Modificare helloworld/vcpkg-configuration.json per includere la overlay-ports cartella che contiene la nuova porta:

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

Modificare helloworld/CMakeLists.txt quindi e helloworld/main.cpp per usare la nuova dipendenza.

helloworld/CMakeLists.txt Modificare con il contenuto seguente:

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

main.cpp Modificare con il contenuto seguente:

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

Configurare, compilare ed eseguire l'applicazione.

1. Configurare la compilazione con CMake:

cmake --preset=default

2. Compilare il progetto:

cmake --build build

3. Eseguire l'applicazione:

./build/HelloWorld

Il percorso dell'eseguibile del progetto può essere diverso, ad esempio: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Passaggi successivi

Ora che è vcpkg-sample-library stato creato un pacchetto come porta, il passaggio successivo consiste nell'aggiungerlo al Registro di sistema curato da vcpkg. Vedere Aggiunta di porte al registro vcpkg.

Per altre informazioni, vedi:

• Porte
• Guida del manutentore