Öğretici: Kitaplığı vcpkg ile paketleme

Bu öğretici, özel katman kullanarak vcpkg kitaplığını paketleme konusunda size yol gösterir. Devam etmeden önce CMake ile paketleri yükleme ve kullanma öğreticisini okumanızı öneririz.

Önkoşullar

Not

Windows'da bu öğreticide, C++ geliştirme derleyicisi olarak Visual Studio'nun MSVC'si kullanılır.

1 - vcpkg ayarlama

  1. Depoyu kopyalama

    İlk adım, vcpkg deposunu GitHub'dan kopyalamaktır. Depo, vcpkg yürütülebilir dosyasını ve vcpkg topluluğu tarafından tutulan seçilmiş açık kaynak kitaplıklarının kayıt defterini almaya yönelik betikler içerir. Bunu yapmak için şunu çalıştırın:

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

    Vcpkg tarafından seçilen kayıt defteri, 2.000'den fazla açık kaynak kitaplık kümesidir. Bu kitaplıklar vcpkg'nin sürekli tümleştirme işlem hatları tarafından birlikte çalışacak şekilde doğrulanmıştır. vcpkg deposu bu kitaplıkların kaynak kodunu içermese de, bunları derlemek ve sisteminize yüklemek için tarifler ve meta veriler içerir.

  2. Bootstrap betiğini çalıştırma

    Artık vcpkg deposunu kopyaladığınıza göre vcpkg dizinine gidin ve bootstrap betiğini çalıştırın.

    cd vcpkg && bootstrap-vcpkg.bat

    cd vcpkg; .\bootstrap-vcpkg.bat

    cd vcpkg && ./bootstrap-vcpkg.sh

    Bootstrap betiği önkoşul denetimleri gerçekleştirir ve vcpkg yürütülebilir dosyasını indirir.

    İşte hepsi bu! vcpkg ayarlandı ve kullanıma hazır.

2 - Ortam değişkenini VCPKG_ROOT yapılandırma

Ortam değişkenlerini ayarlamak VCPKG_ROOT için aşağıdaki komutları çalıştırın:

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

Not

komutunu kullanarak export ortam değişkenlerini ayarlamak yalnızca geçerli kabuk oturumunu etkiler. Bu değişikliği oturumlar arasında kalıcı hale getirmek için export komutunu kabuk dosyanızın profil betiğine (ör. ~/.bashrc veya ~/.zshrc) ekleyin.

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

Not

Ortam değişkenlerini bu şekilde ayarlamak yalnızca geçerli terminal oturumunu etkiler. Bu değişiklikleri tüm oturumlarda kalıcı hale getirmek için Bunları Windows Sistem Ortamı Değişkenleri paneli aracılığıyla ayarlayın.

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

Not

Ortam değişkenlerini bu şekilde ayarlamak yalnızca geçerli terminal oturumunu etkiler. Bu değişiklikleri tüm oturumlarda kalıcı hale getirmek için Bunları Windows Sistem Ortamı Değişkenleri paneli aracılığıyla ayarlayın.

Ayar VCPKG_ROOT , vcpkg'ye vcpkg örneğinizin nerede olduğunu bildirir. Bunu PATH eklemek, vcpkg komutlarını doğrudan kabuktan çalıştırabilmenizi sağlar.

3 - Özel katman ayarlama

  1. CMakecustom-overlayoluşturduğunuz projenin yanında Hello World adlı yeni bir dizin oluşturun.
  2. dizininde custom-overlay adlı vcpkg-sample-librarybir klasör oluşturun.

4 - Bağlantı noktası dosyalarını ayarlama

İlk olarak, vcpkg.json klasörünün içine aşağıdaki içeriğe sahip custom-overlay/vcpkg-sample-library dosyasını oluşturun.

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

Dosya, vcpkg.json bir C++ kitaplığı için meta verileri ve bağımlılıkları tanımlayan bir bildirim görevi görür ve vcpkg'ye paketi derlemek, yüklemek ve yönetmek için gerekli bilgileri sağlar.

  • name: Kitaplığın adını belirtir. Bu, paket tanımlayıcısı olarak kullanılır.
  • version: Kitaplığın sürüm numarasını gösterir.
  • homepage: Projenin giriş sayfasının URL'si, genellikle deposu. Daha fazla bilgi edinmek veya katkıda bulunmak isteyenler için kullanışlıdır.
  • description: Kitaplığın ne yaptığını açıklayan kısa metin. Bu, belgelere ve kullanıcılara yöneliktir.
  • license: Kitaplığın hangi lisansla dağıtıldığını belirtir.
  • dependencies: Kitaplığın ihtiyaç duyduğu bağımlılıkların listesini içeren bir dizi.
  • name: vcpkg-cmake: vcpkg-cmake bağımlılığını belirtir, bu da vcpkg bağlantı noktalarında yaygın olarak kullanılan CMake işlevlerini ve makrolarını sağlar.
  • host: true: Bunun bir konak bağımlılığı olduğunu vcpkg-cmake belirtir, yani paketi oluşturmak için gereklidir, ancak kullanmak için gerekli değildir.
  • name: vcpkg-cmake-config: CMake yapılandırma betiklerinin kullanılmasına yardımcı olan vcpkg-cmake-config üzerinde bir bağımlılığı belirtir.
  • fmt: fmt kitaplığına bir çalışma zamanı bağımlılığı belirtir. Bu, paketi derlemek ve kullanmak için fmt'in gerekli olduğu anlamına gelir.

hakkında vcpkg.jsondaha fazla bilgi için, bildirimlerle ilgili aşağıdaki belgelere bakın.

Şimdi, aşağıdaki içeriğe usage sahip dizin içinde custom-overlay\vcpkg-sample-library dosyayı oluşturun:

vcpkg-sample-library provides CMake targets:

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

Bağlantı noktaları için kullanım belgeleri sağlamak, kullanıcıların projelerinde bunları kolayca benimsemesini sağlar. Bağlantı noktasının dizininde (usage) bir derleme sistemiyle tümleştirmek için gereken en düşük adımları açıklayan bir ports/<port name>/usage dosya sağlamayı kesinlikle öneririz. Doğru kullanım yönergelerini belirlemek için akış yönergelerini izlemenizi öneririz. Yukarı akışın kullanım bilgilerini sağlamaması durumunda, dışarı aktarılan hedefleri bulmak için derleme sistemleri arasında gezinmek gerekebilir.

Daha fazla kılavuz için bkz. kullanım dosyalarını işleme

Son olarak, portfile.cmake dosyasını custom-overlay\vcpkg-sample-library dizini içinde aşağıdaki içeriğe sahip olacak şekilde oluşturun.

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

Bu portfile , vcpkg kullanarak GitHub'dan belirli bir C++ kitaplığını indirmeyi, derlemeyi, yüklemeyi ve paketlemeyi tanımlar.

  • vcpkg_check_linkage(ONLY_STATIC_LIBRARY): Bu paket için yalnızca statik bağlamanın desteklendiğini belirtir.
  • vcpkg_from_github: GitHub deposundan kaynak kodu indirmek için işlevini başlatır.
    • OUT_SOURCE_PATH SOURCE_PATH: Kaynak kodun ayıklanacağı dizini ayarlar.
    • REPO MicrosoftDocs/vcpkg-docs: Kaynak kodu içeren GitHub deposu.
    • REF "${VERSION}": İndirilmesi gereken kaynak kodun sürümü.
    • SHA512 0: Bütünlük doğrulaması için kaynak kodun SHA-512 hash'i için yer tutucu.
    • HEAD_REF main: Depo için varsayılan dalı belirtir.
  • vcpkg_cmake_configure: CMake kullanarak projeyi yapılandırarak derlemeyi ayarlar.
    • SOURCE_PATH "${SOURCE_PATH}": Daha önce indirilen kaynak kodun yolu.
  • vcpkg_cmake_install(): CMake kullanarak paketi derler ve yükler.
  • vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): CMake paketi yapılandırma dosyalarını vcpkg ile uyumlu olacak şekilde düzeltir.
  • file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Çakışmayı önlemek için ekleme dizinini hata ayıklama yüklemesinden siler.
  • file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): Kullanım yönerge dosyasını paketin paylaşım dizinine kopyalar.
  • vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): LİSANS dosyasını paketin paylaşım dizinine yükler ve telif hakkı olarak yeniden adlandırır.

Daha fazla bilgi için bakımcı kılavuzuna bakın.

5 - portfile.cmake için SHA512'yi güncelleştir

Çalıştır:

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

Uzun bir hata iletisi alırsınız. Şunları bulana kadar çıkışı tarayın:

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

"Gerçek karma 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417 değerini kopyalayın, ardından SHA512 içindeki portfile.cmake'i yeni değeriyle değiştirin."

Yükleme komutunu yeniden çalıştırın:

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 - Bağlantı noktası yapısını doğrulama

Kütüphanenin doğru bir şekilde derlendiğini ve bağlandığını doğrulamak için paket yükleme öğreticisinde helloworld oluşturulan projeye yeni bir bağımlılık ekleyin. Projenin bildirim ve yapılandırma dosyalarında aşağıdaki değişiklikleri yapın.

üzerinde helloworld/vcpkg.jsonbağımlılık eklemek için değiştirinvcpkg-sample-library:

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

helloworld/vcpkg-configuration.json etiketini, yeni bağlantı noktasını içeren overlay-ports klasörü içerecek şekilde değiştirin:

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

Ardından, yeni bağımlılığı kullanmak için helloworld/CMakeLists.txt ve helloworld/main.cpp öğelerini değiştirin.

dosyasını helloworld/CMakeLists.txt aşağıdaki içerikle değiştirin:

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

dosyasını main.cpp aşağıdaki içerikle değiştirin:

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

Uygulamayı yapılandırın, derleyin ve çalıştırın.

  1. CMake kullanarak derlemeyi yapılandırın:
cmake --preset=default
  1. Projeyi oluşturun:
cmake --build build
  1. Uygulamayı çalıştırın:
./build/HelloWorld

Projenizin yürütülebilir dosyasının yolu farklı olabilir, örneğin: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Sonraki adımlar

vcpkg-sample-library artık bağlantı noktası olarak paketlendiğine göre, sonraki adım bunu vcpkg tarafından seçilmiş kayıt defterine eklemektir. Bkz. vcpkg kayıt defterine bağlantı noktaları ekleme.

Daha fazla bilgi için bkz.

  • Last updated on