Öğ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

• Terminal
• C++ derleyicisi
• CMake
• Git

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 dizine vcpkg gidin ve bootstrap betiğini yürütebilirsiniz:

   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

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"

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

3 - Özel katman ayarlama

1. CMake ile paketleri yükleme ve kullanma öğreticisinde oluşturduğunuz projenin yanında Hello World adlı custom-overlay 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, aşağıdaki içeriğe sahip klasörde dosyayı custom-overlay\vcpkg-sample-library oluşturunvcpkg.json:

{
  "name": "vcpkg-sample-library",
  "version": "1.0.2",
  "homepage": "https://github.com/microsoft/vcpkg-docs/tree/cmake-sample-lib",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "license": "MIT",
  "dependencies": [
    {
      "name" : "vcpkg-cmake",
      "host" : true
    },
    {
      "name" : "vcpkg-cmake-config",
      "host" : true
    },
    "fmt"
  ]
}

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 altında dağıtıldığı lisansı belirtir.
• dependencies: Kitaplığın ihtiyaç duyduğu bağımlılıkların listesini içeren bir dizi.
• name: vcpkg-cmakeVcpkg bağlantı noktalarında yaygın olarak kullanılan CMake işlevlerini ve makrolarını sağlayan bir vcpkg-cmakebağımlılığı belirtir.
• 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-configCMake yapılandırma betiklerinin kullanılmasına yardımcı olan bağımlılığını vcpkg-cmake-configbelirtir.
• fmt: Kitaplıkta fmt bir çalışma zamanı bağımlılığı belirtir. Bu, paketi derlemek ve kullanmak için gerekli olduğu anlamına gelir fmt .

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 (ports/<port name>/usage) bir derleme sistemiyle tümleştirmek için gereken en düşük adımları açıklayan bir 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, dosyayı aşağıdaki içeriğe sahip dizin içinde custom-overlay\vcpkg-sample-library oluşturunportfile.cmake:

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO Microsoft/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 "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

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 Microsoft/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 karması 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 "${SOURCE_PATH}/LICENSE" DESTINATION ...): LİSANS dosyasını paketin paylaşım dizinine yükler ve telif hakkı olarak yeniden adlandırır.
• configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): Kullanım yönerge dosyasını paketin paylaşım dizinine kopyalar.

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

5 - SHA512 güncelleştirme portfile.cmake

Ç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:

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

"Gerçek karma" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417değerini kopyalayın ve içindeki portfile.cmake değerini değeriyle değiştirinSHA512.

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/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ı derlemesini doğrulama

Kitaplık derlemelerini ve bağlantılarını doğru doğrulamak için helloworld yükleme paketleri öğreticisinde 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 vcpkg-sample-librarybağımlılık eklemek için değiştirinhelloworld/vcpkg.json:

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

Yeni bağlantı noktasını içeren klasörü içerecek overlay-ports şekilde değiştirinhelloworld/vcpkg-configuration.json:

{
  "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 ve helloworld/main.cpp öğesini değiştirinhelloworld/CMakeLists.txt.

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

2. Projeyi oluşturun:

cmake --build build

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

• Bağlantı noktaları
• Bakımcı kılavuzu