Självstudie: Paketera ett bibliotek med vcpkg

2025-04-22

Den här självstudien beskriver hur du paketar ett bibliotek för vcpkg med hjälp av ett anpassat överlägg. Vi rekommenderar att du läser självstudien Installera och använda paket med CMake innan du fortsätter.

Förutsättningar

En terminal
En C++-kompilator
CMake
Git

Anmärkning

I Windows använder den här självstudien Visual Studios MSVC som kompilator för C++-utveckling.

1 – Konfigurera vcpkg

Klona lagringsplatsen

Det första steget är att klona vcpkg-lagringsplatsen från GitHub. Lagringsplatsen innehåller skript för att hämta den körbara filen vcpkg och ett register över kuraterade bibliotek med öppen källkod som underhålls av vcpkg-communityn. Det gör du genom att köra:
```
git clone https://github.com/microsoft/vcpkg.git
```
Det vcpkg-kurerade registret är en uppsättning med över 2 000 bibliotek med öppen källkod. Dessa bibliotek har verifierats av vcpkgs kontinuerlig integrationspipelines för att fungera tillsammans. Även om vcpkg-lagringsplatsen inte innehåller källkoden för dessa bibliotek, innehåller den recept och metadata för att skapa och installera dem i systemet.
Kör bootstrap-skriptet

Nu när du har klonat vcpkg-lagringsplatsen går du till vcpkg katalogen och kör bootstrap-skriptet:
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
Bootstrap-skriptet utför nödvändiga kontroller och laddar ned den körbara filen vcpkg.

Det var allt! vcpkg är konfigurerat och redo att användas.

2 – Konfigurera `VCPKG_ROOT` miljövariabeln

Om du vill ange VCPKG_ROOT miljövariablerna kör du följande kommandon:

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

Anmärkning

Om du anger miljövariabler med kommandot export påverkas endast den aktuella shell-sessionen. Om du vill göra den här ändringen permanent mellan sessioner lägger du till kommandot i export gränssnittets profilskript (t.ex. ~/.bashrc eller ~/.zshrc).

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

Anmärkning

Inställningen av miljövariabler på det här sättet påverkar bara den aktuella terminalsessionen. För att göra dessa ändringar permanenta för alla sessioner, ställ in dem via panelen Windows systemmiljövariabler.

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

Anmärkning

Inställningen VCPKG_ROOT talar om för vcpkg var din vcpkg-instans finns. Genom att lägga till det till PATH säkerställer du att du kan köra vcpkg-kommandon direkt från skalet.

3 – Konfigurera det anpassade överlägget

Skapa en ny katalog med namnet custom-overlay bredvid det Hello World projekt som du skapade i självstudiekursen Installera och använda paket med CMake .
Inom custom-overlay katalogen, skapa en mapp med namnet vcpkg-sample-library.

4 – Konfigurera portfilerna

vcpkg.json Skapa först filen i custom-overlay/vcpkg-sample-library mappen med följande innehåll:

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

Filen vcpkg.json fungerar som ett manifest som definierar metadata och beroenden för ett C++-bibliotek, vilket ger vcpkg den information som krävs för att skapa, installera och hantera paketet.

name: Anger namnet på biblioteket. Detta används som paketidentifierare.
version: Anger bibliotekets versionsnummer.
homepage: URL till projektets startsida, ofta dess lagringsplats. Användbart för dem som vill veta mer eller bidra.
description: Kort text som beskriver vad biblioteket gör. Detta gäller för dokumentation och användare.
license: Anger den licens under vilken biblioteket distribueras.
dependencies: En matris som innehåller listan över beroenden som biblioteket behöver.
name: vcpkg-cmake: Anger ett beroende av vcpkg-cmake, som tillhandahåller CMake-funktioner och makron som ofta används i vcpkg-portar.
host: true: Anger att är ett värdberoende, vilket innebär att vcpkg-cmake det krävs för att skapa paketet men inte för att använda det.
name: vcpkg-cmake-config: Anger ett beroende av vcpkg-cmake-config, som hjälper dig att använda CMake-konfigurationsskript.
fmt: Anger ett körningsberoende för fmt biblioteket. Det innebär att fmt krävs både för att bygga och använda paketet.

Mer information om vcpkg.json finns i den följande dokumentationen om manifest.

usage Skapa nu filen i custom-overlay\vcpkg-sample-library katalogen med följande innehåll:

vcpkg-sample-library provides CMake targets:

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

Genom att tillhandahålla användningsdokumentation för portar kan användarna enkelt använda dem i sina projekt. Vi rekommenderar starkt att du tillhandahåller en usage fil i portens katalog (ports/<port name>/usage) som beskriver de minimala steg som krävs för att integrera med ett byggsystem. För att fastställa rätt användningsinstruktioner rekommenderar vi att du följer uppströms vägledning. Om uppströms inte tillhandahåller användningsinformation kan det vara nödvändigt att gå igenom deras byggsystem för att hitta de exporterade målen.

Mer vägledning finns i Hantera användningsfiler

portfile.cmake Skapa slutligen filen i custom-overlay\vcpkg-sample-library katalogen med följande innehåll:

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

Detta portfile definierar hur du laddar ned, skapar, installerar och paketar ett specifikt C++-bibliotek från GitHub med vcpkg.

vcpkg_check_linkage(ONLY_STATIC_LIBRARY): Anger att endast statisk länkning stöds för det här paketet.
vcpkg_from_github: Startar funktionen för att ladda ned källkoden från en GitHub-lagringsplats.
- OUT_SOURCE_PATH SOURCE_PATH: Anger den katalog där källkoden ska extraheras.
- REPO MicrosoftDocs/vcpkg-docs: GitHub-lagringsplatsen som innehåller källkoden.
- REF "${VERSION}": Den version av källkoden som ska laddas ned.
- SHA512 0: Platshållare för SHA-512-hashen för källkoden för integritetsverifiering.
- HEAD_REF main: Anger standardgrenen för lagringsplatsen.
vcpkg_cmake_configure: Konfigurerar projektet med hjälp av CMake och konfigurerar bygget.
- SOURCE_PATH "${SOURCE_PATH}": Sökvägen till källkoden som laddades ned tidigare.
vcpkg_cmake_install(): Skapar och installerar paketet med hjälp av CMake.
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): Åtgärdar CMake-paketkonfigurationsfilerna så att de är kompatibla med vcpkg.
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Tar bort inkluderingskatalogen från felsökningsinstallationen för att förhindra överlappning.
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): Kopierar en användningsinstruktionsfil till paketets resurskatalog.
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): Installerar LICENSfilen i paketets resurskatalog och byter namn på den till upphovsrätt.

Mer information finns i underhållsguiden.

5 – Uppdatera SHA512 för `portfile.cmake`

Springa:

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

Du får ett långt felmeddelande. Skanna utdata tills du hittar:

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

Kopiera "Faktisk hash" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417och ersätt SHA512 värdet i portfile.cmake med dess värde.

Kör installationskommandot igen:

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 – Verifiera portbygget

För att korrekt verifiera att biblioteket bygger och länkar, lägg till ett nytt beroende till helloworld projektet som skapades i guiden för installationspaket. Gör följande ändringar i projektets manifest- och konfigurationsfiler.

Ändra helloworld/vcpkg.json för att lägga till ett beroende av vcpkg-sample-library:

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

Ändra helloworld/vcpkg-configuration.json för att inkludera mappen overlay-ports som innehåller den nya porten:

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

Ändra först helloworld/CMakeLists.txt och helloworld/main.cpp för att använda det nya beroendet.

helloworld/CMakeLists.txt Ändra med följande innehåll:

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 Ändra med följande innehåll:

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

Konfigurera, skapa och kör programmet.

Konfigurera bygget med CMake:

cmake --preset=default

Bygg projektet:

cmake --build build

Kör programmet:

./build/HelloWorld

Sökvägen till projektets körbara fil kan vara annorlunda, till exempel: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Nästa steg

Nu när vcpkg-sample-library har paketerats som port är nästa steg att lägga till den i det vcpkg-kurerade registret. Se Lägga till portar i vcpkg-registret.

Mer information finns i:

Dela via

Självstudie: Paketera ett bibliotek med vcpkg

Förutsättningar

1 – Konfigurera vcpkg

2 – Konfigurera VCPKG_ROOT miljövariabeln

3 – Konfigurera det anpassade överlägget

4 – Konfigurera portfilerna

5 – Uppdatera SHA512 för portfile.cmake

6 – Verifiera portbygget

Nästa steg

Feedback

Ytterligare resurser

2 – Konfigurera `VCPKG_ROOT` miljövariabeln

5 – Uppdatera SHA512 för `portfile.cmake`