Kurz: Zabalení knihovny pomocí vcpkg

V tomto kurzu se dozvíte, jak připravit knihovnu k balíčkování pro vcpkg pomocí vlastního rozšíření. Před dalším postupem doporučujeme přečíst si tutoriál Instalace a používání balíčků s CMake.

Požadavky

Terminál
Kompilátor C++
CMake
Lotr

Poznámka:

V tomto kurzu ve Windows se jako kompilátor pro vývoj jazyka C++ používá MSVC sady Visual Studio.

1. Nastavení vcpkg

Klonování úložiště

Prvním krokem je klonování úložiště vcpkg z GitHubu. Úložiště obsahuje skripty pro získání spustitelného souboru vcpkg a registru kurátorovaných opensourcových knihoven spravovaných komunitou vcpkg. Provedete to spuštěním tohoto příkazu:
```
git clone https://github.com/microsoft/vcpkg.git
```
Kurátorovaný registr vcpkg je sada více než 2 000 opensourcových knihoven. Tyto knihovny byly ověřeny kontinuálními integračními kanály vcpkg, aby spolu správně fungovaly. I když úložiště vcpkg neobsahuje zdrojový kód pro tyto knihovny, obsahuje recepty a metadata pro sestavení a instalaci v systému.
Spuštění skriptu bootstrap

Teď, když jste naklonovali úložiště vcpkg, přejděte do vcpkg adresáře a spusťte spouštěcí skript:
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
Skript bootstrap provádí kontroly požadovaných součástí a stáhne spustitelný soubor vcpkg.

A je to! Vcpkg je nastavena a připravena k použití.

2. Konfigurace proměnné prostředí `VCPKG_ROOT`

Pokud chcete nastavit VCPKG_ROOT proměnné prostředí, spusťte následující příkazy:

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

Poznámka:

Nastavení proměnných prostředí příkazem export ovlivní pouze aktuální relaci shellu. Pokud chcete tuto změnu provést trvale napříč relacemi, přidejte příkaz export do skriptu profilu vašeho shellu (např. ~/.bashrc nebo ~/.zshrc).

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

Poznámka:

Nastavení proměnných prostředí tímto způsobem ovlivní pouze aktuální relaci terminálu. Abyste tyto změny provedli trvale ve všech relacích, nastavte je prostřednictvím panelu systémových proměnných prostředí Windows.

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

Poznámka:

Nastavení VCPKG_ROOT říká vcpkg, kde se nachází vaše instance vcpkg. Přidáním PATH zajistíte, že můžete přímo z příkazového řádku spouštět příkazy vcpkg.

3. Nastavení vlastního překryvu

Vytvořte nový adresář s názvem custom-overlay vedle Hello World projektu, který jste vytvořili v kurzu Instalace, a použijte balíčky s CMake .
V custom-overlay adresáři vytvořte složku s názvem vcpkg-sample-library.

4. Nastavení souborů portů

Nejprve ve složce vytvořte vcpkg.json soubor custom-overlay/vcpkg-sample-library s následujícím obsahem:

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

Soubor vcpkg.json slouží jako manifest, který definuje metadata a závislosti pro knihovnu C++ a poskytuje vcpkg potřebné informace k sestavení, instalaci a správě balíčku.

name: Určuje název knihovny. Používá se jako identifikátor balíčku.
version: Označuje číslo verze knihovny.
homepage: Adresa URL domovské stránky projektu, často jeho úložiště. Užitečné pro ty, kteří chtějí vědět více nebo přispívat.
description: Stručný text popisující, co knihovna dělá. Toto je pro dokumentaci a uživatele.
license: Určuje licenci, pod kterou se knihovna distribuuje.
dependencies: Pole obsahující seznam závislostí, které knihovna potřebuje.
name: vcpkg-cmake: Určuje závislost na vcpkg-cmake, která poskytuje funkce CMake a makra běžně používané v portech vcpkg.
host: true: Určuje, že jde o závislost hostitele, což znamená, že vcpkg-cmake se vyžaduje pro sestavení balíčku, ale ne pro jeho použití.
name: vcpkg-cmake-config: Určuje závislost na vcpkg-cmake-config, který pomáhá při používání konfiguračních skriptů CMake.
fmt: Určuje běhovou závislost na knihovně fmt. To znamená, že fmt se vyžaduje pro sestavení i použití balíčku.

Další informace o vcpkg.json najdete v následující dokumentaci o manifestech.

Teď v usage adresáři vytvořte soubor custom-overlay\vcpkg-sample-library s následujícím obsahem:

vcpkg-sample-library provides CMake targets:

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

Poskytnutí dokumentace k používání portů umožňuje uživatelům snadno je přijmout ve svých projektech. Důrazně doporučujeme poskytnout usage soubor v adresáři portu (ports/<port name>/usage), který popisuje minimální kroky potřebné k integraci se sestavovacím systémem. Pokud chcete určit správné pokyny k použití, doporučujeme postupovat podle pokynů upstreamu. V případě, že upstream neposkytuje informace o využití, může být nutné projít jejich systém sestavení a najít exportované cíle.

Další pokyny můžete nalézt v části zpracování souborů pro využití.

Nakonec vytvořte soubor portfile.cmake v adresáři custom-overlay\vcpkg-sample-library s následujícím obsahem:

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")

Definuje portfile , jak stáhnout, sestavit, nainstalovat a zabalit konkrétní knihovnu C++ z GitHubu pomocí vcpkg.

vcpkg_check_linkage(ONLY_STATIC_LIBRARY): Určuje, že pro tento balíček je podporováno pouze statické propojení.
vcpkg_from_github: Spustí funkci pro stažení zdrojového kódu z úložiště GitHub.
- OUT_SOURCE_PATH SOURCE_PATH: Nastaví adresář, ve kterém se bude extrahovat zdrojový kód.
- REPO MicrosoftDocs/vcpkg-docs: Úložiště GitHub obsahující zdrojový kód.
- REF "${VERSION}": Verze zdrojového kódu ke stažení.
- SHA512 0: Zástupný symbol pro SHA-512 hash zdrojového kódu k ověření jeho integrity.
- HEAD_REF main: Určuje výchozí větev úložiště.
vcpkg_cmake_configure: Nakonfiguruje projekt pomocí CMake a nastaví sestavení.
- SOURCE_PATH "${SOURCE_PATH}": Cesta ke zdrojovému kódu staženého dříve.
vcpkg_cmake_install(): Sestaví a nainstaluje balíček pomocí CMake.
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): Opravuje konfigurační soubory balíčku CMake, aby byly kompatibilní s vcpkg.
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Odstraní adresář include z instalace ladění, aby se zabránilo překrývání.
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): Zkopíruje soubor s pokyny k použití do adresáře sdílené složky balíčku.
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): Nainstaluje soubor LICENSE do adresáře sdílené složky balíčku a přejmenuje ho na autorská práva.

Další informace najdete v průvodci údržbou.

5. Aktualizace SHA512 pro `portfile.cmake`

Spustit:

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

Zobrazí se dlouhá chybová zpráva. Naskenujte výstup, dokud nenajdete:

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

Zkopírujte "aktuální hash" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417 a nahraďte SHA512 hodnotu v portfile.cmake její hodnotou.

Znovu spusťte příkaz 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/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. Ověření sestavení portu

Pokud chcete ověřit správné sestavení knihovny a odkazy, přidejte do helloworld projektu vytvořeného v kurzu instalace balíčků novou závislost. Proveďte následující změny manifestu a konfiguračních souborů projektu.

Upravte helloworld/vcpkg.json tak, aby se přidala závislost na vcpkg-sample-library.

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

Upravte helloworld/vcpkg-configuration.json tak, aby zahrnovala overlay-ports složku, která obsahuje nový 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"
  ]
}

Dále upravte helloworld/CMakeLists.txt a helloworld/main.cpp tak, aby používaly novou závislost.

Upravte helloworld/CMakeLists.txt pomocí následujícího obsahu:

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

Upravte main.cpp pomocí následujícího obsahu:

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

Nakonfigurujte, sestavte a spusťte aplikaci.

Konfigurace sestavení pomocí CMake:

cmake --preset=default

Sestavení projektu:

cmake --build build

Spusťte aplikaci:

./build/HelloWorld

Cesta ke spustitelnému souboru projektu se může lišit, například: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Další kroky

Teď, když je balíček vcpkg-sample-library jako port, je dalším krokem jeho přidání do kurátorovaného registru vcpkg. Viz přidání portů do registru vcpkg.

Další informace naleznete v tématu:

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-04-17

Kurz: Zabalení knihovny pomocí vcpkg

Požadavky

1. Nastavení vcpkg

2. Konfigurace proměnné prostředí VCPKG_ROOT

3. Nastavení vlastního překryvu

4. Nastavení souborů portů

5. Aktualizace SHA512 pro portfile.cmake

6. Ověření sestavení portu

Další kroky

Váš názor

Další materiály

2. Konfigurace proměnné prostředí `VCPKG_ROOT`

5. Aktualizace SHA512 pro `portfile.cmake`