Samouczek: pakowanie biblioteki przy użyciu narzędzia vcpkg

Artykuł
05/01/2024

Ten samouczek zawiera instrukcje dotyczące tworzenia pakietów biblioteki dla programu vcpkg przy użyciu niestandardowej nakładki. Zalecamy przeczytanie samouczka Instalowanie i używanie pakietów za pomocą narzędzia CMake przed kontynuowaniem.

Wymagania wstępne

Terminal
Kompilator języka C++
CMake
Usługa Git

Uwaga

W systemie Windows ten samouczek używa MSVC programu Visual Studio jako kompilatora do programowania w języku C++.

1 — Konfigurowanie programu vcpkg

Klonowanie repozytorium

Pierwszym krokiem jest sklonowanie repozytorium vcpkg z usługi GitHub. Repozytorium zawiera skrypty w celu uzyskania pliku wykonywalnego vcpkg i rejestru wyselekcjonowanych bibliotek open source obsługiwanych przez społeczność programu vcpkg. Aby to zrobić, uruchom polecenie:
```
git clone https://github.com/microsoft/vcpkg.git
```
Rejestr wyselekcjonowanych vcpkg to zestaw ponad 2000 bibliotek typu open source. Te biblioteki zostały zweryfikowane przez potoki ciągłej integracji vcpkg do współpracy. Chociaż repozytorium vcpkg nie zawiera kodu źródłowego dla tych bibliotek, przechowuje przepisy i metadane do kompilowania i instalowania ich w systemie.
Uruchamianie skryptu bootstrap

Po sklonowaniu repozytorium vcpkg przejdź do vcpkg katalogu i wykonaj skrypt bootstrap:
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
Skrypt bootstrap wykonuje testy wymagań wstępnych i pobiera plik wykonywalny vcpkg.

I już! Narzędzie vcpkg jest skonfigurowane i gotowe do użycia.

2 — Konfigurowanie zmiennej środowiskowej `VCPKG_ROOT`

Aby ustawić VCPKG_ROOT zmienne środowiskowe, uruchom następujące polecenia:

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

Uwaga

Ustawienie zmiennych środowiskowych przy użyciu export polecenia wpływa tylko na bieżącą sesję powłoki. Aby zmienić tę zmianę export na stałe między sesjami, dodaj polecenie do skryptu profilu powłoki (np. ~/.bashrc lub ~/.zshrc).

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

Uwaga

Ustawienie zmiennych środowiskowych w ten sposób wpływa tylko na bieżącą sesję terminalu. Aby wprowadzić te zmiany na stałe we wszystkich sesjach, ustaw je za pomocą panelu Zmienne środowiskowe systemu Windows.

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

Uwaga

Ustawienie VCPKG_ROOT informuje vcpkg, gdzie znajduje się wystąpienie vcpkg. Dodanie go w celu PATH zapewnia, że można uruchamiać polecenia vcpkg bezpośrednio z poziomu powłoki.

3 — Konfigurowanie niestandardowej nakładki

Utwórz nowy katalog o nazwie custom-overlay obok projektu utworzonego Hello World w samouczku Instalowanie i używanie pakietów za pomocą narzędzia CMake .
W custom-overlay katalogu utwórz folder o nazwie vcpkg-sample-library.

4 — Konfigurowanie plików portów

Najpierw utwórz vcpkg.json plik w folderze custom-overlay\vcpkg-sample-library z następującą zawartością:

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

Plik vcpkg.json służy jako manifest, który definiuje metadane i zależności dla biblioteki języka C++, udostępniając narzędzie vcpkg z informacjami niezbędnymi do kompilowania, instalowania i zarządzania pakietem.

name: określa nazwę biblioteki. Jest on używany jako identyfikator pakietu.
version: wskazuje numer wersji biblioteki.
homepage: adres URL strony głównej projektu, często jego repozytorium. Przydatne dla tych, którzy chcą wiedzieć więcej lub współtworzyć.
description: Krótki tekst opisujący, co robi biblioteka. Dotyczy to dokumentacji i użytkowników.
license: określa licencję, w ramach której biblioteka jest dystrybuowana.
dependencies: tablica zawierająca listę zależności, których potrzebuje biblioteka.
name: vcpkg-cmakeokreśla zależność od vcpkg-cmakeprogramu , która udostępnia funkcje i makra CMake używane często w portach vcpkg.
host: true: określa, że jest to zależność hosta, co oznacza, że vcpkg-cmake jest wymagane do kompilowania pakietu, ale nie do jego używania.
name: vcpkg-cmake-configokreśla zależność od vcpkg-cmake-configprogramu , która pomaga w korzystaniu ze skryptów konfiguracji narzędzia CMake.
fmt: określa zależność czasu wykonywania od fmt biblioteki. Oznacza to, że fmt jest to wymagane zarówno w przypadku kompilowania, jak i używania pakietu.

Aby uzyskać więcej informacji na temat vcpkg.jsonprogramu , zobacz następującą dokumentację dotyczącą manifestów.

Teraz utwórz usage plik w custom-overlay\vcpkg-sample-library katalogu z następującą zawartością:

vcpkg-sample-library provides CMake targets:

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

Udostępnianie dokumentacji użycia portów umożliwia użytkownikom łatwe wdrażanie ich w swoich projektach. Zdecydowanie zachęcamy do udostępnienia usage pliku w katalogu portu (ports/<port name>/usage), który opisuje minimalne kroki niezbędne do integracji z systemem kompilacji. Aby określić prawidłowe instrukcje dotyczące użycia, zaleca się wykonanie instrukcji nadrzędnych. W przypadku, gdy nadrzędny strumień nie dostarcza informacji o użyciu, może być konieczne przejrzenie ich systemu kompilacji w celu znalezienia wyeksportowanych obiektów docelowych.

Aby uzyskać więcej wskazówek, zobacz obsługa plików użycia

Na koniec utwórz portfile.cmake plik w custom-overlay\vcpkg-sample-library katalogu z następującą zawartością:

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)

Definiuje to portfile sposób pobierania, kompilowania, instalowania i tworzenia określonej biblioteki języka C++ z usługi GitHub przy użyciu narzędzia vcpkg.

vcpkg_check_linkage(ONLY_STATIC_LIBRARY): określa, że dla tego pakietu jest obsługiwane tylko łączenie statyczne.
vcpkg_from_github: uruchamia funkcję, aby pobrać kod źródłowy z repozytorium GitHub.
- OUT_SOURCE_PATH SOURCE_PATH: ustawia katalog, w którym zostanie wyodrębniony kod źródłowy.
- REPO JavierMatosD/vcpkg-sample-library: repozytorium GitHub zawierające kod źródłowy.
- REF "${VERSION}": wersja kodu źródłowego do pobrania.
- SHA512 0: Symbol zastępczy skrótu SHA-512 kodu źródłowego na potrzeby weryfikacji integralności.
- HEAD_REF main: określa gałąź domyślną dla repozytorium.
vcpkg_cmake_configure: Konfiguruje projekt przy użyciu narzędzia CMake, konfiguruje kompilację.
- SOURCE_PATH "${SOURCE_PATH}": ścieżka do pobranego wcześniej kodu źródłowego.
vcpkg_cmake_install(): kompiluje i instaluje pakiet przy użyciu narzędzia CMake.
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): naprawia pliki konfiguracji pakietu CMake tak, aby były zgodne z narzędziem vcpkg.
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): usuwa katalog include z instalacji debugowania, aby zapobiec nakładaniu się na siebie.
file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): instaluje plik LICENSE w katalogu udziału pakietu i zmienia jego nazwę na copyright.
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): kopiuje plik instrukcji użycia do katalogu udziału pakietu.

Aby uzyskać więcej informacji, zapoznaj się z przewodnikiem obsługi.

5 — Aktualizowanie algorytmu SHA512 dla `portfile.cmake`

Uruchom:

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

Zostanie wyświetlony długi komunikat o błędzie. Skanuj dane wyjściowe do momentu znalezienia:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Skopiuj wartość "Rzeczywista wartość skrótu" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417i zastąp SHA512 ją wartością portfile.cmake .

Uruchom ponownie polecenie instalacji:

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 — Weryfikowanie kompilacji portu

Aby zweryfikować poprawność kompilacji i łączy biblioteki, dodaj nową zależność do helloworld projektu utworzonego w samouczku dotyczącym pakietów instalacyjnych. Wprowadź następujące zmiany w plikach manifestu i konfiguracji projektu.

Zmodyfikuj helloworld/vcpkg.json , aby dodać zależność od vcpkg-sample-libraryelementu :

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

Zmodyfikuj helloworld/vcpkg-configuration.json tak overlay-ports , aby zawierał folder zawierający nowy 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"
  ]
}

Następnie zmodyfikuj helloworld/CMakeLists.txt i helloworld/main.cpp użyj nowej zależności.

Zmodyfikuj element przy helloworld/CMakeLists.txt użyciu następującej zawartości:

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

Zmodyfikuj element przy main.cpp użyciu następującej zawartości:

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

Skonfiguruj, skompiluj i uruchom aplikację.

Skonfiguruj kompilację przy użyciu narzędzia CMake:

cmake --preset=default

Skompiluj projekt:

cmake --build build

Uruchom aplikację:

./build/HelloWorld

Ścieżka do pliku wykonywalnego projektu może być inna, na przykład: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Następne kroki

Teraz, gdy vcpkg-sample-library element został spakowany jako port, następnym krokiem jest dodanie go do rejestru wyselekcjonowanego programu vcpkg. Zobacz Dodawanie portów do rejestru vcpkg.

Aby uzyskać więcej informacji, zobacz:

Share via

Samouczek: pakowanie biblioteki przy użyciu narzędzia vcpkg

Wymagania wstępne

1 — Konfigurowanie programu vcpkg

2 — Konfigurowanie zmiennej środowiskowej `VCPKG_ROOT`

3 — Konfigurowanie niestandardowej nakładki

4 — Konfigurowanie plików portów

5 — Aktualizowanie algorytmu SHA512 dla `portfile.cmake`

6 — Weryfikowanie kompilacji portu

Następne kroki

Opinia

Dodatkowe zasoby

Share via

Samouczek: pakowanie biblioteki przy użyciu narzędzia vcpkg

Wymagania wstępne

1 — Konfigurowanie programu vcpkg

2 — Konfigurowanie zmiennej środowiskowej VCPKG_ROOT

3 — Konfigurowanie niestandardowej nakładki

4 — Konfigurowanie plików portów

5 — Aktualizowanie algorytmu SHA512 dla portfile.cmake

6 — Weryfikowanie kompilacji portu

Następne kroki

Opinia

Dodatkowe zasoby

2 — Konfigurowanie zmiennej środowiskowej `VCPKG_ROOT`

5 — Aktualizowanie algorytmu SHA512 dla `portfile.cmake`