Tutorial: Mengemas pustaka dengan vcpkg

Tutorial ini memandu Anda tentang cara mengemas pustaka untuk vcpkg menggunakan overlay kustom. Sebaiknya Anda membaca tutorial Instal dan gunakan paket dengan CMake sebelum melanjutkan.

Prasyarat

Sebuah terminal
Pengkompilasi C++
CMake
Git

Nota

Di Windows, tutorial ini menggunakan MSVC Visual Studio sebagai pengkompilasi untuk pengembangan C++.

1 - Menyiapkan vcpkg

Mengkloning repositori

Langkah pertama adalah mengkloning repositori vcpkg dari GitHub. Repositori berisi skrip untuk memperoleh vcpkg yang dapat dieksekusi dan registri pustaka sumber terbuka yang dikumpulkan yang dikelola oleh komunitas vcpkg. Untuk melakukan ini, jalankan:
```
git clone https://github.com/microsoft/vcpkg.git
```
Registri terkurasi vcpkg adalah kumpulan lebih dari 2.000 pustaka open-source. Pustaka ini telah divalidasi oleh alur integrasi berkelanjutan vcpkg untuk bekerja sama. Meskipun repositori vcpkg tidak berisi kode sumber untuk pustaka ini, repositori ini menyimpan resep dan metadata untuk membangun dan menginstalnya di sistem Anda.
Jalankan skrip bootstrap

Sekarang setelah Anda mengkloning repositori vcpkg, navigasikan ke vcpkg direktori dan jalankan skrip bootstrap:
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
Skrip pemasangan awal melakukan pemeriksaan prasyarat dan mengunduh berkas vcpkg yang dapat dieksekusi.

Itu saja! vcpkg disiapkan dan siap digunakan.

2 - Mengonfigurasi variabel lingkungan `VCPKG_ROOT`

Untuk mengatur VCPKG_ROOT variabel lingkungan, jalankan perintah berikut:

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

Nota

Mengatur variabel lingkungan menggunakan export perintah hanya memengaruhi sesi shell saat ini. Untuk membuat perubahan ini permanen di seluruh sesi, tambahkan export perintah ke skrip profil shell Anda (misalnya, ~/.bashrc atau ~/.zshrc).

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

Nota

Mengatur variabel lingkungan dengan cara ini hanya memengaruhi sesi terminal saat ini. Untuk membuat perubahan ini permanen di semua sesi, atur melalui panel Variabel Lingkungan Sistem Windows.

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

Nota

Mengatur variabel lingkungan dengan cara ini hanya memengaruhi sesi terminal saat ini. Untuk membuat perubahan ini permanen di semua sesi, atur melalui panel Variabel Lingkungan Sistem Windows.

Pengaturan VCPKG_ROOT memberi tahu vcpkg tempat instans vcpkg Anda berada. Menambahkannya untuk PATH memastikan Anda dapat menjalankan perintah vcpkg langsung dari shell.

3 - Menyiapkan overlay kustom

Buat direktori baru yang disebut custom-overlay di samping proyek yang Hello World Anda buat di tutorial Instal dan gunakan paket dengan CMake .
Dalam custom-overlay direktori, buat folder bernama vcpkg-sample-library.

4 - Menyiapkan file port

Pertama, buat file vcpkg.json di dalam folder custom-overlay/vcpkg-sample-library dengan konten berikut:

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

File vcpkg.json berfungsi sebagai manifes yang menentukan metadata dan dependensi untuk perpustakaan C++, menyediakan vcpkg dengan informasi yang diperlukan untuk membangun, menginstal, dan mengelola paket tersebut.

name: Menentukan nama pustaka. Ini digunakan sebagai pengidentifikasi paket.
version: Menunjukkan nomor versi pustaka.
homepage: URL ke beranda proyek, sering kali repositorinya. Berguna bagi mereka yang ingin tahu lebih banyak atau berkontribusi.
description: Teks singkat yang menjelaskan apa yang dilakukan pustaka. Ini untuk dokumentasi dan pengguna.
license: Menentukan lisensi tempat pustaka didistribusikan.
dependencies: Array yang berisi daftar dependensi yang dibutuhkan pustaka.
name: vcpkg-cmake: Menentukan dependensi pada vcpkg-cmake, yang menyediakan fungsi dan makro CMake yang umumnya digunakan dalam port vcpkg.
host: true: Menentukan bahwa vcpkg-cmake itu adalah dependensi host, yang berarti diperlukan untuk membangun paket tetapi tidak untuk menggunakannya.
name: vcpkg-cmake-configMenentukan dependensi pada vcpkg-cmake-config, yang membantu dalam menggunakan skrip konfigurasi CMake.
fmt: Menentukan dependensi run-time pada pustaka fmt. Ini berarti fmt diperlukan untuk membangun dan menggunakan paket.

Untuk informasi selengkapnya tentang vcpkg.json, silakan merujuk ke dokumentasi berikut tentang manifesto.

Sekarang, buat file dalam usagecustom-overlay\vcpkg-sample-library direktori dengan konten berikut:

vcpkg-sample-library provides CMake targets:

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

Menyediakan dokumentasi penggunaan untuk port memungkinkan pengguna untuk dengan mudah mengadopsinya dalam proyek mereka. Kami sangat mendorong penyediaan usage file dalam direktori port (ports/<port name>/usage) yang menjelaskan langkah-langkah minimal yang diperlukan untuk diintegrasikan dengan sistem build. Untuk menentukan instruksi penggunaan yang benar, disarankan untuk mengikuti panduan hulu. Jika upstream tidak memberikan informasi penggunaan, mungkin perlu untuk menggali melalui sistem build mereka untuk menemukan target yang diekspor.

Untuk panduan selengkapnya, lihat menangani file penggunaan

Terakhir, buat file dalam portfile.cmakecustom-overlay\vcpkg-sample-library direktori dengan konten berikut:

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

Ini portfile menentukan cara mengunduh, membangun, menginstal, dan mengemas pustaka C++ tertentu dari GitHub menggunakan vcpkg.

vcpkg_check_linkage(ONLY_STATIC_LIBRARY): Menentukan bahwa hanya penautan statis yang didukung untuk paket ini.
vcpkg_from_github: Memulai fungsi untuk mengunduh kode sumber dari repositori GitHub.
- OUT_SOURCE_PATH SOURCE_PATH: Mengatur direktori tempat kode sumber akan diekstrak.
- REPO MicrosoftDocs/vcpkg-docs: Repositori GitHub yang berisi kode sumber.
- REF "${VERSION}": Versi kode sumber yang akan diunduh.
- SHA512 0: Tempat penampung untuk hash SHA-512 dari kode sumber untuk verifikasi integritas.
- HEAD_REF main: Menentukan cabang default untuk repositori.
vcpkg_cmake_configure: Mengonfigurasi proyek menggunakan CMake, menyiapkan build.
- SOURCE_PATH "${SOURCE_PATH}": Jalur ke kode sumber yang diunduh sebelumnya.
vcpkg_cmake_install(): Membangun dan menginstal paket menggunakan CMake.
vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): Memperbaiki file konfigurasi paket CMake agar kompatibel dengan vcpkg.
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Menghapus direktori include dari penginstalan debug untuk mencegah tumpang tindih.
file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): Menyalin file instruksi penggunaan ke direktori berbagi paket.
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): Menginstal file LISENSI ke direktori berbagi paket dan mengganti namanya menjadi hak cipta.

Untuk informasi selengkapnya, lihat panduan pemeliharaan.

5 - Memperbarui SHA512 untuk `portfile.cmake`

Jalankan:

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

Anda akan mendapatkan pesan kesalahan panjang. Pindai output hingga Anda menemukan:

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

Salin "hash sebenarnya" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417, dan ganti nilai SHA512 dalam portfile.cmake dengan nilainya.

Jalankan kembali perintah instal:

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 - Memverifikasi build port

Untuk memverifikasi build dan tautan pustaka dengan benar, tambahkan dependensi baru ke proyek yang helloworld dibuat dalam tutorial paket penginstalan. Buat perubahan berikut pada file manifes dan konfigurasi proyek.

Ubah helloworld/vcpkg.json untuk menambahkan dependensi pada vcpkg-sample-library:

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

Ubah helloworld/vcpkg-configuration.json untuk menyertakan overlay-ports folder yang berisi port baru:

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

Selanjutnya, ubah helloworld/CMakeLists.txt dan helloworld/main.cpp untuk menggunakan dependensi baru.

Ubah helloworld/CMakeLists.txt dengan konten berikut:

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

Ubah main.cpp dengan konten berikut:

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

Mengonfigurasi, membangun, dan menjalankan aplikasi.

Konfigurasikan build menggunakan CMake:

cmake --preset=default

Bangun proyek tersebut:

cmake --build build

Jalankan aplikasi:

./build/HelloWorld

Jalur ke executable proyek Anda mungkin berbeda, misalnya: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Langkah selanjutnya

Sekarang setelah vcpkg-sample-library dikemas sebagai port, langkah selanjutnya adalah menambahkannya ke registri terkurasi vcpkg. Lihat, Menambahkan port ke registri vcpkg.

Untuk informasi selengkapnya, lihat:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-04-22

Bagikan melalui

Tutorial: Mengemas pustaka dengan vcpkg

Prasyarat

1 - Menyiapkan vcpkg

2 - Mengonfigurasi variabel lingkungan VCPKG_ROOT

3 - Menyiapkan overlay kustom

4 - Menyiapkan file port

5 - Memperbarui SHA512 untuk portfile.cmake

6 - Memverifikasi build port

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan:

2 - Mengonfigurasi variabel lingkungan `VCPKG_ROOT`

5 - Memperbarui SHA512 untuk `portfile.cmake`