Konfigurasi penembolokan biner

Sintaks Konfigurasi

Penembolokan biner dikonfigurasi dengan variabel lingkungan VCPKG_BINARY_SOURCES (diatur ke <source>;<source>;...) dan opsi baris perintah --binarysource=<source>. Opsi dievaluasi terlebih dahulu dari lingkungan, lalu dari baris perintah. Penembolokan biner dapat sepenuhnya dinonaktifkan dengan meneruskan --binarysource=clear sebagai opsi baris perintah terakhir.

Parameter opsional <rw> untuk sumber tertentu mengontrol apakah mereka akan dikonsultasikan untuk mengunduh biner (read)(default), apakah build sesuai permintaan akan diunggah ke remote tersebut (write), atau keduanya (readwrite).

Penyedia

Penyedia AWS S3

x-aws,<prefix>[,<rw>]

Tambahkan sumber AWS S3 menggunakan AWS CLI. <awalan> harus dimulai dengan s3:// dan diakhiri dengan /.

x-aws-config,no-sign-request

Teruskan --no-sign-request ke AWS CLI.

Penyedia Azure Blob Storage

x-azblob,<baseuri>,<sas>[,<rw>]

Menambahkan penyedia Azure Blob Storage menggunakan validasi Tanda Tangan Akses Bersama. <baseuri> harus menyertakan jalur kontainer.

Mulai cepat

Pertama, Anda perlu membuat Akun Azure Storage serta kontainer. Lihat Dokumentasi Mulai Cepat Azure Storage untuk mendapatkan instruksi.

Selanjutnya, Anda harus membuat Tanda Tangan Akses Bersama (SAS), yang dapat dilakukan dari akun penyimpanan di bawah Pengaturan ->Tanda Tangan Akses Bersama. SAS ini akan membutuhkan:

• Layanan yang diizinkan: Blob
• Jenis sumber daya yang diizinkan: Objek
• Izin yang diizinkan: Baca (jika menggunakan read) atau Baca , Buat (jika menggunakan write atau readwrite)

Titik akhir blob ditambah kontainer harus diteruskan sebagai <baseuri> dan SAS yang dihasilkan tanpa awalan ? harus diteruskan sebagai <sas>.

Contoh :

x-azblob,https://<storagename>.blob.core.windows.net/<containername>,sv=2019-12-12&ss=b&srt=o&sp=rcx&se=2020-12-31T06:20:36Z&st=2020-12-30T22:20:36Z&spr=https&sig=abcd,readwrite

vcpkg akan mencoba untuk menghindari mengungkapkan SAS selama operasi normal, namun:

1. Ini akan dicetak penuh jika --debug diteruskan
2. Ini akan diteruskan sebagai parameter baris perintah ke subproses, seperti curl.exe

Azure Blob Storage menyertakan fitur untuk menghapus entri cache yang belum diakses dalam jumlah hari tertentu yang dapat digunakan untuk mengelola ukuran cache biner Anda secara otomatis. Lihat Manajemen Siklus Hidup Data di Microsoft Docs untuk informasi selengkapnya, atau cari manajemen data -manajemen Siklus Hidup> di Portal Microsoft Azure untuk akun penyimpanan Anda.

Penyedia Tencent Cloud Object Storage

x-cos,<prefix>[,<rw>]

Menambahkan sumber COS. <prefix> harus dimulai dengan cos:// dan diakhir dengan /.

Penyedia file

files,<absolute path>[,<rw>]

Menyimpan arsip yang dikompresi zip di jalur berdasarkan ID penembolokan biner .

Penyedia Google Cloud Storage

x-gcs,<prefix>[,<rw>]

Menambahkan penyedia Google Cloud Storage. <prefix> harus dimulai dengan gs:// dan diakhir dengan /.

Mulai cepat

Pertama, Anda perlu membuat Akun Google Cloud Platform serta wadah penyimpanan (GCS Quick Start].

Sebagai bagian dari mulai cepat ini, Anda akan mengonfigurasi alat baris perintah gsutil untuk mengautentikasi dengan Google Cloud. vcpkg akan menggunakan alat baris perintah ini, jadi pastikan alat tersebut berada di jalur pencarian Anda untuk executable.

Contoh 1 (menggunakan wadah tanpa awalan umum untuk objek):

x-gcs,gs://<bucket-name>/,readwrite

Contoh 2 (menggunakan wadah dan awalan untuk objek):

x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with/many/slashes/,readwrite
x-gcs,gs://<bucket-name>/my-vcpkg-cache/maybe/with`,commas/too!/,readwrite

Koma (,) valid sebagai bagian dari awalan objek di GCS. Ingatlah untuk menghindarinya dalam konfigurasi vcpkg, seperti yang ditunjukkan pada contoh sebelumnya. GCS tidak memiliki folder (beberapa alat GCS mensimulasikan folder). Anda tidak perlu membuat atau memanipulasi prefiks yang digunakan oleh cache vcpkg Anda.

Cache GitHub Actions

x-gha[,<rw>]

Menambahkan cache GitHub Actions sebagai penyedia. Penyedia penembolokan biner ini hanya valid dalam konteks alur kerja GitHub Actions. Penyedia ini mengharuskan variabel lingkungan ACTIONS_CACHE_URL dan ACTIONS_RUNTIME_TOKEN diatur. Mengatur variabel lingkungan ini dengan benar tercakup di bagian Mulai Cepat berikut.

Mulai cepat

Agar vcpkg dapat menggunakan Cache Tindakan GitHub, dibutuhkan URL Actions Cache dan Token Runtime. Untuk melakukan ini, kedua nilai harus diekspor sebagai variabel lingkungan dalam langkah alur kerja yang mirip dengan yang berikut ini:

- uses: actions/github-script@v7
  with:
    script: |
      core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
      core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

Menentukan nilai-nilai ini sebagai variabel lingkungan alih-alih argumen baris perintah vcpkg dirancang karena penyedia penembolokan biner GitHub Actions Cache hanya dapat digunakan dari alur kerja GitHub Actions.

Setelah variabel lingkungan diekspor, vcpkg dapat dijalankan dengan penyedia penembolokan biner GitHub Actions seperti ini:

- name: Install dependencies via vcpkg
  run: vcpkg install zlib --binarysource="clear;x-gha,readwrite"

Paket Universal di Artefak Azure

x-az-universal,<organization>,<project>,<feed>[,<rw>]

Menambahkan Paket Universal di Azure Artifacts sebagai penyedia.

Mulai cepat

Pertama, Anda perlu membuat umpan Paket Universal. Lihat mulai cepat Paket Universal untuk mendapatkan petunjuk.

Selanjutnya, Anda harus menginstal dan mengautentikasi ke Azure CLI. Lihat panduan mengautentikasi ke Azure CLI untuk instruksi. vcpkg akan menggunakan alat baris perintah ini, jadi pastikan alat tersebut berada di jalur pencarian Anda untuk executable.

Contoh :

x-az-universal,organization_url,project_name,feed_name,readwrite

Berikan parameter project_name untuk membuat vcpkg mengunduh dan menerbitkan Paket Universal ke umpan Anda pada cakupan proyek.

x-az-universal,organization_url,,feed_name,readwrite

Biarkan parameter project_name kosong untuk membuat vcpkg mengunduh dan menerbitkan Paket Universal ke umpan Anda pada cakupan organisasi.

Penyedia HTTP

http,<url_template>[,<rw>[,<header>]]

Setiap operasi penembolokan biner dipetakan ke kata kerja HTTP:

• Unduh - GET
• Unggah - PUT
• Periksa Keberadaan - HEAD

Templat URL

Templat menggunakan kurung kurawal untuk ekspansi variabel. Anda dapat menggunakan variabel 'name', 'version', 'sha' dan 'triplet'. Misalnya:

https://cache.example.com/{name}/{version}/{sha}

Header

Autentikasi didukung dengan menentukan Header Otorisasi HTTP. Misalnya:

http,https://cache.example.com/{name}/{version}/{sha},readwrite,Authorization: Bearer BearerTokenValue

Penyedia NuGet

Tambahkan server NuGet dengan parameter CLI NuGet -Source:

nuget,<uri>[,<rw>]

Gunakan file konfigurasi NuGet dengan parameter CLI NuGet -Config:

nugetconfig,<path>[,<rw>]

Konfigurasikan batas waktu untuk sumber NuGet:

nugettimeout,<seconds>

File konfigurasi harus menentukan defaultPushSource untuk mendukung penulisan paket kembali ke umpan.

Kredensial

Banyak server NuGet memerlukan kredensial tambahan untuk diakses. Cara paling fleksibel untuk menyediakan kredensial adalah melalui sumber nugetconfig dengan file nuget.config kustom. Lihat Menggunakan paket dari umpan terautentikasi untuk informasi selengkapnya.

Namun, masih mungkin untuk mengautentikasi terhadap banyak server menggunakan penyedia kredensial bawaan NuGet atau melalui menyesuaikan nuget.configdefault lingkungan Anda. Konfigurasi default dapat diperluas melalui panggilan klien nuget seperti:

nuget sources add -Name MyRemote -Source https://... -Username $user -Password $pass

dan kemudian diteruskan ke vcpkg melalui nuget,MyRemote,readwrite. Anda bisa mendapatkan jalur ke salinan nuGet yang tepat yang digunakan oleh vcpkg dengan menjalankan vcpkg fetch nuget, yang akan melaporkan sesuatu seperti:

$ vcpkg fetch nuget
/vcpkg/downloads/tools/nuget-5.5.1-linux/nuget.exe

Pengguna non-Windows perlu memanggil ini melalui mono melalui mono /path/to/nuget.exe sources add ....

metadata.repository

Penyedia sumber nuget dan nugetconfig menghormati variabel lingkungan tertentu sambil menghasilkan paket nuget. Bidang metadata.repository dari paket apa pun akan dihasilkan sebagai:

    <repository type="git" url="${VCPKG_NUGET_REPOSITORY}"/>

atau

    <repository type="git"
                url="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}.git"
                branch="${GITHUB_REF}"
                commit="${GITHUB_SHA}"/>

jika variabel lingkungan yang sesuai ditentukan dan tidak kosong. Ini secara khusus digunakan untuk mengaitkan paket dalam Paket GitHub dengan proyek bangunan dan tidak dimaksudkan untuk mengaitkan dengan sumber paket asli.

Singgahan NuGet

Cache di seluruh pengguna NuGet tidak digunakan secara default. Untuk menggunakannya untuk setiap sumber berbasis nuget, atur variabel lingkungan VCPKG_USE_NUGET_CACHE ke true (tidak peka huruf besar/kecil) atau 1.

Contoh Penyedia

Jika sistem ci pilihan Anda tidak tercantum, Anda dipersilakan untuk mengirimkan PR untuk menambahkannya!

Paket GitHub

Untuk menggunakan vcpkg dengan Paket GitHub, disarankan untuk menggunakan penyedia NuGet .

# actions.yaml
#
# In this example, vcpkg has been added as a submodule (`git submodule add https://github.com/Microsoft/vcpkg`).
env:
  VCPKG_BINARY_SOURCES: 'clear;nuget,GitHub,readwrite'

matrix:
  os: ['windows-2019', 'ubuntu-20.04']
  include:
    - os: 'windows-2019'
      triplet: 'x86-windows'
      mono: ''
    - os: 'ubuntu-20.04'
      triplet: 'x64-linux'
      # To run `nuget.exe` on non-Windows platforms, `mono` must be used.
      mono: 'mono'

steps:
  # This step assumes `vcpkg` has been bootstrapped (run `./vcpkg/bootstrap-vcpkg`)
  - name: 'Setup NuGet Credentials'
    shell: 'bash'
    # Replace <OWNER> with your organization name
    run: |
      ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \
        sources add \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json" \
        -storepasswordincleartext \
        -name "GitHub" \
        -username "<OWNER>" \
        -password "${{ secrets.GITHUB_TOKEN }}"
      ${{ matrix.mono }} `./vcpkg/vcpkg fetch nuget | tail -n 1` \
        setapikey "${{ secrets.GITHUB_TOKEN }}" \
        -source "https://nuget.pkg.github.com/<OWNER>/index.json"

  # Omit this step if you're using manifests
  - name: 'vcpkg package restore'
    shell: 'bash'
    run: >
      ./vcpkg/vcpkg install sqlite3 cpprestsdk --triplet ${{ matrix.triplet }}

Jika Anda menggunakan manifes , Anda dapat menghilangkan langkah vcpkg package restore: manifes tersebut akan dijalankan secara otomatis sebagai bagian dari build Anda.

Lihat dokumentasi NuGet Paket GitHub untuk informasi selengkapnya.

Artefak Azure DevOps

Untuk menggunakan vcpkg dengan Artefak Azure DevOps, disarankan untuk menggunakan penyedia NuGet .

Pertama, pastikan Artefak telah diaktifkan di akun DevOps Anda. Administrator dapat mengaktifkan ini melalui Pengaturan Proyek -> Umum -Gambaran Umum> ->Artefak>Azure DevOps Services.

Selanjutnya, buat umpan untuk proyek Anda. URL umpan Anda akan menjadi tautan https:// yang berakhiran dengan /nuget/v3/index.json. Untuk informasi selengkapnya, lihat Dokumentasi Artefak Azure DevOps.

Menggunakan umpan dari alur

# azure-pipelines.yaml
variables:
- name: VCPKG_BINARY_SOURCES
  value: 'clear;nuget,<FEED_URL>,readwrite'

steps:
# Remember to add this task to allow vcpkg to upload archives via NuGet
- task: NuGetAuthenticate@0

Jika Anda menggunakan agen kustom dengan OS non-Windows, Anda harus menginstal Mono untuk menjalankan nuget.exe (apt install mono-complete, brew install mono, dll).

Menggunakan umpan secara lokal

# On Windows Powershell
PS> & $(vcpkg fetch nuget | select -last 1) sources add `
  -name ADO `
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json `
  -Username $USERNAME `
  -Password $PAT
PS> $env:VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"

# On Linux or OSX
$ mono `vcpkg fetch nuget | tail -n1` sources add \
  -name ADO \
  -Source https://pkgs.dev.azure.com/$ORG/_packaging/$FEEDNAME/nuget/v3/index.json \
  -Username $USERNAME \
  -Password $PAT
$ export VCPKG_BINARY_SOURCES="nuget,ADO,readwrite"

Gunakan Token Akses Pribadi (PAT) sebagai kata sandi untuk keamanan maksimum. Anda dapat membuat PAT di Pengaturan Pengguna ->Token Akses Pribadi atau https://dev.azure.com/<ORG>/_usersSettings/tokens.

ABI Hash

Untuk setiap build, vcpkg menghitung Hash ABI untuk menentukan kesetaraan. Jika dua build memiliki Hash ABI yang sama, vcpkg akan menganggapnya identik dan menggunakan kembali biner di seluruh proyek dan mesin.

Hash ABI mempertimbangkan:

• Setiap file dalam direktori port
• Isi dan nama file triplet
• File yang dapat dieksekusi pengkompilasi C++
• File yang dapat dieksekusi pengkompilasi C
• Kumpulan fitur dipilih
• Hash ABI dari setiap dependensi
• Semua fungsi pembantu yang dirujuk oleh portfile.cmake (heuristik)
• Versi CMake yang digunakan
• Versi PowerShell yang digunakan (Windows)
• Konten variabel lingkungan apa pun yang tercantum dalam VCPKG_ENV_PASSTHROUGH
• Konten tekstual file toolchain (VCPKG_CHAINLOAD_TOOLCHAIN_FILE)
• Toolkit GRDK (hanya saat menargetkan platform Xbox)

Terlepas dari daftar ekstensif ini, dimungkinkan untuk mengalahkan cache dan memperkenalkan nondeterminisme. Jika Anda memiliki detail tambahan yang perlu Anda lacak untuk lingkungan Anda, Anda dapat membuat file triplet dengan informasi tambahan Anda dalam komentar. Informasi tambahan itu akan disertakan dalam Hash ABI dan memastikan alam semesta biner yang unik.

File bernama .DS_Store tidak dipertimbangkan untuk hash ABI.

Hash ABI terhitung disimpan di setiap paket dan di direktori yang diinstal saat ini pada /share/<port>/vcpkg_abi_info.txt untuk diperiksa.

Contoh Hash ABI zlib

Aktifkan output debug untuk mencetak hash Application Binary Interface (ABI) lengkap dari pacakge. Untuk zlib:

[DEBUG] Trying to hash <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt
[DEBUG] <path>\buildtrees\zlib\x86-windows.vcpkg_abi_info.txt has hash bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87

hash ABI bb1c96759ac96102b4b18215db138daedd3eb16c2cd3302ae7bffab2b643eb87 untuk paket zlib dibangun dengan hash semua informasi yang mungkin relevan untuk membedakan paket biner.

Versi pengkompilasi Anda adalah bagian dari hash ABI, dan dihitung di bawah ini:

[DEBUG] -- The C compiler identification is MSVC 19.36.32538.0
[DEBUG] -- The CXX compiler identification is MSVC 19.36.32538.0
[DEBUG] #COMPILER_HASH#f5d02a6542664cfbd4a38db478133cbb1a18f315

File yang relevan, kompilator, dan informasi versi alat di-hash untuk menghitung hash ABI akhir:

[DEBUG] <abientries for zlib:x86-windows>
[DEBUG]   0001-Prevent-invalid-inclusions-when-HAVE_-is-set-to-0.patch|750b9542cb55e6328cca01d3ca997f1373b9530afa95e04213168676936e7bfa
[DEBUG]   0002-skip-building-examples.patch|835ddecfed752e0f49be9b0f8ff7ba76541cb0a150044327316e22ca84f8d0c2
[DEBUG]   0003-build-static-or-shared-not-both.patch|d6026271dcb3d8fc74b41e235620ae31576a798e77aa411c3af8cd9e948c02b1
[DEBUG]   0004-android-and-mingw-fixes.patch|37a43eddbcb1b7dde49e7659ae895dfd0ff1df66666c1371ba7d5bfc49d8b438
[DEBUG]   cmake|3.26.2
[DEBUG]   features|core
[DEBUG]   portfile.cmake|ac63047b644fa758860dd7ba48ff9a13b058c6f240b8e8d675b8fbba035976be
[DEBUG]   ports.cmake|5a8e00cedff0c898b1f90f7d129329d0288801bc9056562b039698caf31ff3f3
[DEBUG]   post_build_checks|2
[DEBUG]   powershell|7.3.6
[DEBUG]   triplet|x86-windows
[DEBUG]   triplet_abi|3e71dd1d4afa622894ae367adbbb1ecbd42c57c51428a86b675fa1c8cad3a581-36b818778ba6f2c16962495caedb9a7b221d5be4c60de1cd3060f549319a9931-f5d02a6542664cfbd4a38db478133cbb1a18f315
[DEBUG]   usage|be22662327df993eebc437495add75acb365ab18d37c7e5de735d4ea4f5d3083
[DEBUG]   vcpkg-cmake|1b3dac4b9b0bcbef227c954b495174863feebe3900b2a6bdef0cd1cf04ca1213
[DEBUG]   vcpkg-cmake-wrapper.cmake|5d49ef2ee6448479c2aad0e5f732e2676eaba0411860f9bebabe6002d66f57d1
[DEBUG]   vcpkg.json|bc94e2540efabe36130a806381a001c57194e7de67454ab7ff1e30aa15e6ce23
[DEBUG]   vcpkg_copy_pdbs|d57e4f196c82dc562a9968c6155073094513c31e2de475694143d3aa47954b1c
[DEBUG]   vcpkg_fixup_pkgconfig|588d833ff057d3ca99c14616c7ecfb5948b5e2a9e4fc02517dceb8b803473457
[DEBUG]   vcpkg_from_git|8f27bff0d01c6d15a3e691758df52bfbb0b1b929da45c4ebba02ef76b54b1881
[DEBUG]   vcpkg_from_github|b743742296a114ea1b18ae99672e02f142c4eb2bef7f57d36c038bedbfb0502f
[DEBUG]   vcpkg_replace_string|d43c8699ce27e25d47367c970d1c546f6bc36b6df8fb0be0c3986eb5830bd4f1
[DEBUG] </abientries>