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

Ten samouczek pokazuje, jak spakować bibliotekę dla programu vcpkg, używając 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

1 — Konfigurowanie programu vcpkg

1. 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:

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

   Rejestr wyselekcjonowanych vcpkg to zbiór ponad 2000 bibliotek open source. Te biblioteki zostały zweryfikowane przez potoki ciągłej integracji vcpkg, aby współpracować razem. Chociaż repozytorium vcpkg nie zawiera kodu źródłowego dla tych bibliotek, przechowuje przepisy i metadane do kompilowania i instalowania ich w systemie.

2. 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

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"

Ustawienie VCPKG_ROOT informuje vcpkg, gdzie zlokalizowana jest jego instancja. Dodanie go w celu PATH zapewnia, że można uruchamiać polecenia vcpkg bezpośrednio z poziomu powłoki.

3 — Skonfiguruj niestandardową nakładkę

1. 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 .
2. 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",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "homepage": "https://github.com/MicrosoftDocs/vcpkg-docs/tree/cmake-sample-lib",
  "license": "MIT",
  "dependencies": [
    "fmt",
    {
      "name": "vcpkg-cmake",
      "host": true
    },
    {
      "name": "vcpkg-cmake-config",
      "host": true
    }
  ]
}

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-cmake: Określa zależność od vcpkg-cmake, który udostępnia funkcje i makra CMake często używane 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-config: określa zależność od programu vcpkg-cmake-config, 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.json, zobacz następujące dokumentacje dotyczące 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ę zastosowanie się do wskazówek źródłowych. W przypadku, gdy system źródłowy nie dostarcza informacji o użyciu, może być konieczne dokładne przeszukanie ich systemu kompilacji w celu zlokalizowania wyeksportowanych celów.

Aby uzyskać więcej wskazówek, zobacz obsługiwanie 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 MicrosoftDocs/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 "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

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 MicrosoftDocs/vcpkg-docs: 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 "${CMAKE_CURRENT_LIST_DIR}/usage" ...): kopiuje plik instrukcji użycia do katalogu udziału pakietu.
• vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): Instaluje plik LICENSE w katalogu współdzielonego pakietu i zmienia jego nazwę na copyright.

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:

Downloading https://github.com/MicrosoftDocs/vcpkg-docs/archive/1.0.2.tar.gz -> MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
Successfully downloaded MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: 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/usage
-- 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ść budowania i łączenia biblioteki, dodaj nową zależność do projektu helloworld 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, aby zawierał folder overlay-ports z nowym portem.

{
  "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, aby używały nowej zależności.

Zmodyfikuj helloworld/CMakeLists.txt następującą 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 main.cpp następującą 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ę.

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

cmake --preset=default

2. Skompiluj projekt:

cmake --build build

3. 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 został zapakowany jako port, następnym krokiem jest dodanie go do zarządzanego repozytorium vcpkg. Zobacz Dodawanie portów do rejestru vcpkg.

Aby uzyskać więcej informacji, zobacz:

• Porty
• Przewodnik obsługi