Referensi vcpkg.json

Untuk gambaran umum penggunaan manifes dengan vcpkg, lihat Mode manifes.

Manifes adalah dokumen JSON yang ketat. Mereka tidak boleh berisi komentar gaya C++(//) atau koma berikutnya. Namun Anda dapat menggunakan nama bidang yang dimulai dengan $ untuk menulis komentar Anda di objek apa pun yang memiliki sekumpulan kunci yang ditentukan dengan baik. Bidang komentar ini tidak diizinkan dalam objek apa pun yang mengizinkan kunci yang ditentukan pengguna (seperti "features").

Skema JSON terbaru tersedia di https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. ID dengan dukungan Skema JSON seperti Visual Studio dan Visual Studio Code dapat menggunakan file ini untuk menyediakan pelengkapan otomatis dan pemeriksaan sintaksis. Untuk sebagian besar IDE, Anda harus mengatur "$schema" ke vcpkg.json URL ini.

Example

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "boost-system",
    {
      "name": "cpprestsdk",
      "default-features": false
    },
    "libxml2",
    "yajl"
  ]
}

Contoh ini menunjukkan manifes untuk aplikasi menggunakan boost-system, , cpprestsdklibxml2, dan yajl. Contohnya juga mencakup referensi untuk mengaktifkan validasi IDE dan pelengkapan otomatis yang $schema lebih baik.

Bidang tingkat atas

Nama	Diperlukan	Tipe	Description
garis besar bawaan	Tidak.	string	Pin versi yang akan digunakan saat membangun sebagai tingkat atas
fitur default	Tidak.	Objek Fitur[]	Memerlukan fitur yang tercantum sebagai on-by-default
Dependensi	Tidak.	Dependensi[]	Daftar dependensi yang diperlukan untuk membangun dan menggunakan proyek ini
deskripsi	Perpustakaan	string atau string[]	Deskripsi proyek
dokumentasi	Tidak.	string	URI ke dokumentasi proyek upstram
fitur	Tidak.	{string: Feature}	Fitur opsional yang tersedia untuk pengguna proyek
beranda	Tidak.	string	URI ke beranda proyek hulu
lisensi	Tidak.	string atau null	Ekspresi lisensi SPDX
Pengelola	Tidak.	string atau string[]	Pengelola file paket
Nama	Perpustakaan	string	Nama proyek
Mengabaikan	Tidak.	Ambil alih[]	Pin versi yang akan digunakan saat membangun sebagai tingkat atas
versi port	Tidak.	bilangan bulat	Revisi file port
Mendukung	Tidak.	Ekspresi Platform	Platform dan konfigurasi build yang didukung
versi semver versi tanggal versi string versi	Perpustakaan	string	Informasi versi upstram

"builtin-baseline"

Pintasan untuk menentukan "baseline" resolusi versi di registri default. String. Opsional, hanya digunakan oleh proyek tingkat atas.

Bidang ini menunjukkan penerapan https://github.com/microsoft/vcpkg yang menyediakan informasi versi minimum global untuk manifes Anda. Ini diperlukan untuk file manifes tingkat atas menggunakan penerapan versi tanpa yang ditentukan "default-registry". Ini memiliki semantik yang sama dengan menentukan registri default Anda menjadi:

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<value>"
  }
}

Lihat penerapan versi dan Menggunakan registri untuk detail semantik selengkapnya.

"default-features"

Serangkaian fitur yang diperlukan untuk perilaku yang wajar tanpa penyesuaian tambahan.

Fitur default secara otomatis dipilih jika:

1. Dependensi port-ke-port untuk port memiliki "default-features": true -- nilai default.
2. Manifes tingkat atas tidak memiliki dependensi untuk port dengan "default-features": false.

Fitur default menangani kasus tertentu untuk menyediakan konfigurasi "default" untuk dependensi transitif yang mungkin tidak diketahui oleh proyek tingkat atas. Port yang digunakan oleh orang lain harus hampir selalu digunakan "default-features": false untuk dependensinya.

Anda dapat menentukan fitur default khusus platform dengan menggunakan Objek Fitur:

{
  "name": "my-port",
  "default-features": [
    "png",
    {
      "name": "winssl",
      "platform": "windows"
    }
  ]
}

Lihat "features" untuk informasi selengkapnya tentang fitur.

"description"

Penjabaran dari port. String atau array string. Diperlukan untuk pustaka, opsional untuk proyek tingkat atas.

Ini digunakan untuk membantu pengguna menemukan pustaka sebagai bagian search dari perintah atau find dan mempelajari apa yang dilakukan pustaka.

"dependencies"

Daftar dependensi yang diperlukan oleh proyek. Array objek Dependensi. Optional.

Bidang ini mencantumkan semua dependensi yang diperlukan untuk membangun dan menggunakan pustaka atau aplikasi Anda.

Contoh dependensi port

"dependencies": [
  {
    "name": "arrow",
    "default-features": false,
    "features": [
      "json",
      {
        "name": "mimalloc",
        "platform": "windows"
      }
    ]
  },
  "boost-asio",
  "openssl",
  {
    "name": "picosha2",
    "platform": "!windows"
  }
]

"documentation"

URI ke dokumentasi proyek upstram. String. Optional.

"features"

Fitur yang tersedia untuk pengguna proyek. Peta nama ke objek Fitur. Optional.

Fitur adalah bendera boolean yang menambahkan perilaku dan dependensi tambahan ke build. Lihat Dokumentasi Konsep Manifes untuk informasi selengkapnya tentang fitur.

"homepage"

URI ke beranda proyek. String. Optional.

"license"

Ekspresi lisensi singkat SPDX dari proyek. String atau null. Optional.

"license" harus berupa ekspresi lisensi SPDX 3.19 atau harus null menunjukkan bahwa pengguna harus membaca file yang disebarkan/share/<port>/copyright. DocumentRefs tidak didukung.

Nota

Informasi lisensi yang disediakan untuk setiap paket dalam registri vcpkg mewakili pemahaman terbaik Microsoft tentang persyaratan lisensi. Namun, informasi ini mungkin tidak definitif. Pengguna disarankan untuk memverifikasi persyaratan lisensi yang tepat untuk setiap paket yang ingin mereka gunakan, karena pada akhirnya merupakan tanggung jawab mereka untuk memastikan kepatuhan terhadap lisensi yang berlaku.

Contoh string lisensi

• MIT
• LGPL-2.1-only AND BSD-2-Clause
• GPL-2.0-or-later WITH Bison-exception-2.2

EBNF

vcpkg menggunakan EBNF berikut untuk mengurai bidang lisensi:

idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;

(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;

with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;

simple-expression = [ whitespace ], (
  | license-id
  | license-id, "+"
  | license-ref
  ), [ whitespace ] ;

(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
  | simple-expression
  | [ whitespace ], "(", or-expression, ")", [ whitespace ] ;

with-expression =
  | parenthesized-expression
  | simple-expression, with, license-exception-id, [ whitespace ] ;

(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;

license-expression = or-expression ;

"maintainers"

Daftar pengelola paket. String atau array string. Optional.

Sebaiknya gunakan formulir "GivennameSurname<email>".

"name"

Nama proyek. String. Diperlukan untuk pustaka, opsional untuk proyek tingkat atas.

Nama harus huruf kecil ASCII, digit, atau tanda hubung (-). Ini tidak boleh dimulai atau diakhir dengan tanda hubung. Pustaka didorong untuk menyertakan organisasi atau nama kerangka kerja mereka sebagai awalan, seperti msft- atau boost- untuk membantu pengguna menemukan dan menjelaskan pustaka terkait.

Misalnya, pustaka dengan nama Boost.Asio resmi mungkin diberi nama boost-asio.

"overrides"

Pin versi yang tepat untuk digunakan untuk dependensi tertentu. Larik Ambil alih objek. Optional.

"overrides" dari manifes transitif (yaitu dari dependensi) diabaikan. Hanya penimpaan yang ditentukan oleh proyek tingkat atas yang digunakan.

Nama	Diperlukan	Tipe	Description
Nama	Yes	string	Nama port
version	Yes	string	Informasi versi upstream untuk disematkan.
semver versi tanggal versi string versi	Yes	string	Alternatif yang tidak digunakan lagi untuk version penamaan skema tertentu.
versi port	Tidak.	bilangan bulat	Revisi file port untuk disematkan. Tidak digunakan lagi demi ditempatkan ke dalam versi itu sendiri.

"port-version" harus ditentukan sebagai #N akhiran dalam "version". Misalnya, "version": "1.2.3#7" nama versi 1.2.3, port-versi 7.

Lihat juga penerapan versi untuk detail semantik lainnya.

Contoh penimpaan versi

  "overrides": [
    {
      "name": "arrow", "version": "1.2.3#7"
    },
    {
      "name": "openssl", "version": "1.1.1h#3"
    }
  ]

"port-version"

Akhiran versi yang membedakan revisi ke file kemasan. Bilangan bulat. Secara default menjadi 0.

"port-version" harus ditingkatkan setiap kali versi baru port diterbitkan yang tidak mengubah versi sumber upstream. Ketika versi sumber upstream diubah, bidang versi harus berubah dan "port-version" harus diatur ulang ke 0 (atau dihapus).

Lihat penerapan versi untuk detail selengkapnya.

"supports"

Platform yang didukung dan konfigurasi build. Ekspresi platform. Optional.

Bidang ini men dokumen bahwa proyek tidak diharapkan untuk membangun atau berjalan dengan sukses pada konfigurasi platform tertentu.

Misalnya, jika pustaka Anda tidak mendukung pembangunan untuk Linux, Anda akan menggunakan "supports": "!linux".

"configuration"

Memungkinkan untuk menyematkan properti konfigurasi vcpkg di vcpkg.json dalam file. Semua yang ada di configuration dalam properti diperlakukan seolah-olah didefinisikan dalam vcpkg-configuration.json file. Untuk detail selengkapnya, lihat vcpkg-configuration.json dokumentasi.

vcpkg-configuration adalah ejaan lama dari bidang ini tetapi identik.

configuration Memiliki atau vcpkg-configuration didefinisikan dalam vcpkg.json sementara juga memiliki vcpkg-configuration.json file tidak diizinkan dan akan mengakibatkan perintah vcpkg berakhir dengan pesan kesalahan.

Contoh yang disematkan configuration

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
        "repository": "https://github.com/MicrosoftDocs/vcpkg-docs",
        "reference": "vcpkg-registry",
        "packages": [ "beicode", "beison" ]
      }
    ],
    "overlay-ports": [ "./my-ports/fmt", 
                       "./team-ports"
    ]
  }

"version","version-semver","version-date","version-string"

Versi proyek upstream. String. Diperlukan untuk pustaka, opsional untuk proyek tingkat atas.

Manifes harus berisi paling banyak satu bidang versi. Setiap bidang versi sesuai dengan skema penerapan versi yang berbeda:

• "version" - Relaxed Semantic Versi 2.0.0, memungkinkan lebih atau kurang dari 3 angka primer. Contoh: 1.2.3.4.10-alpha1
• "version-semver" - Semantik Ketat Versi 2.0.0. Contoh: 2.0.1-rc5
• "version-date" - Tanggal yang diformat sebagai YYYY-MM-DD dengan urutan numerik terpisah titik opsional. Digunakan untuk paket yang tidak memiliki rilis numerik (misalnya, Live-at-HEAD). Contoh: 2022-12-09.314562
• "version-string" - String arbitrer. Digunakan untuk paket yang tidak memiliki versi yang dapat dipesan. Ini harus jarang digunakan, namun semua port yang dibuat sebelum bidang versi lain diperkenalkan menggunakan skema ini.

Lihat penerapan versi untuk detail selengkapnya.

Bidang Dependensi

Setiap dependensi adalah string atau objek dengan bidang berikut:

Nama	Diperlukan	Tipe	Description
fitur default	Tidak.	bool	Memerlukan fitur yang tercantum sebagai on-by-default
fitur	Tidak.	Objek Fitur[]	Daftar fitur tambahan yang diperlukan
tuan rumah	Tidak.	bool	Memerlukan dependensi untuk komputer host alih-alih target
Nama	Yes	string	Nama dependensi
balei-balei	Tidak.	Ekspresi Platform	Kualifikasi platform mana yang akan menggunakan dependensi
version>=	Tidak.	string	Versi minimum yang diperlukan. Versi port diidentifikasi dengan #N akhiran, misalnya, 1.2.3#7 nama port-versi 7.

String ditafsirkan sebagai objek dengan nama yang didefinisikan ke nilai string.

Dependensi: "default-features"

Boolean yang menunjukkan bahwa proyek bergantung pada fitur 'on-by-default' dependensi. Secara default menjadi true.

Dalam kebanyakan kasus, ini harus didefinisikan ke false dan fitur yang diperlukan harus secara eksplisit bergantung pada.

Dependensi: "features"

Daftar fitur tambahan yang diperlukan. Array objek Fitur. Optional.

Objek Fitur adalah objek dengan bidang berikut:

• name - Nama fitur. String. Dibutuhkan.
• platform - Ekspresi Platform yang membatasi platform tempat fitur diperlukan. Optional.

String sederhana juga Feature Object valid { "name": "<feature-name>" }setara dengan .

Contohnya,

{
  "name": "ffmpeg",
  "default-features": false,
  "features": [
    "mp3lame",
    {
      "name": "avisynthplus",
      "platform": "windows"
    }  
  ]
}

ffmpeg Menggunakan pustaka dengan dukungan pengodean mp3. Hanya pada Windows, avisynthplus dukungan juga diaktifkan.

Dependensi: "host"

Boolean yang menunjukkan bahwa dependensi harus dibangun untuk triplet host alih-alih kembar tiga port saat ini. Secara default menjadi false.

Dependensi apa pun yang menyediakan alat atau skrip yang harus "dijalankan" selama build (seperti buildsystem, generator kode, atau pembantu) harus ditandai sebagai "host": true. Ini memungkinkan kompilasi silang yang benar dalam kasus bahwa target tidak dapat dieksekusi -- seperti saat mengkompilasi untuk arm64-android.

Lihat Dependensi host untuk informasi selengkapnya.

Dependensi: "name"

Nama dependensi. String. Dibutuhkan.

Ini mengikuti pembatasan yang sama dengan "name" properti untuk proyek.

Dependensi: "platform"

Ekspresi yang membatasi platform tempat dependensi diperlukan. Ekspresi platform. Optional.

Jika ekspresi tidak cocok dengan konfigurasi saat ini, dependensi tidak akan digunakan. Misalnya, jika dependensi memiliki "platform": "!windows", itu hanya diperlukan saat menargetkan sistem non-Windows.

Dependensi: "version>="

Batasan versi minimum pada dependensi.

Bidang ini menentukan versi minimum dependensi, secara opsional menggunakan #N akhiran untuk juga menentukan versi port minimum jika diinginkan.

Untuk informasi selengkapnya tentang penerapan versi semantik, lihat Penerapan versi.

Bidang Fitur

Setiap fitur adalah objek dengan bidang berikut:

Nama	Diperlukan	Tipe	Description
deskripsi	Yes	string	Deskripsi fitur
Dependensi	Tidak.	Dependensi[]	Daftar dependensi
Mendukung	Tidak.	Ekspresi Platform	Kualifikasi yang didukung oleh platform dan konfigurasi fitur
lisensi	Tidak.	string atau null	Ekspresi lisensi SPDX

Lihat dokumentasi Mode manifes untuk gambaran umum konseptual fitur.

Contoh port dengan fitur

{
  "features": {
    "cbor": {
      "description": "The CBOR backend",
      "dependencies": [
        {
          "$explanation": [
            "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
          ],
          "name": "libdb",
          "default-features": false,
          "features": [ "json" ]
        }
      ]
    },
    "csv": {
      "description": "The CSV backend",
      "dependencies": [
        "fast-cpp-csv-parser"
      ]
    },
    "json": {
      "description": "The JSON backend",
      "dependencies": [
        "jsoncons"
      ]
    }
  }
}

Fitur: "dependencies"

Daftar dependensi yang diperlukan oleh fitur . Array objek Dependensi. Optional.

Bidang ini mencantumkan dependensi tambahan yang diperlukan untuk membangun dan menggunakan fitur tersebut.

Fitur: "description"

Deskripsi fitur. String atau array string. Dibutuhkan.

Ini digunakan untuk membantu pengguna menemukan fitur sebagai bagian search dari perintah atau find dan mempelajari apa yang dilakukan fitur tersebut.

Fitur: "supports"

Platform yang didukung dan konfigurasi build untuk fitur tersebut. Ekspresi platform. Optional.

Bidang ini mendanai konfigurasi platform tempat fitur akan dibuat dan berjalan dengan sukses.

Fitur: "license"

Ekspresi lisensi singkat SPDX dari fitur ini. String atau null. Optional. Jika tidak disediakan, lisensinya sama dengan yang ditentukan di bidang lisensi tingkat atas.

Nota

Informasi lisensi yang disediakan untuk setiap paket dalam registri vcpkg mewakili pemahaman terbaik Microsoft tentang persyaratan lisensi. Namun, informasi ini mungkin tidak definitif. Pengguna disarankan untuk memverifikasi persyaratan lisensi yang tepat untuk setiap paket yang ingin mereka gunakan, karena pada akhirnya merupakan tanggung jawab mereka untuk memastikan kepatuhan terhadap lisensi yang berlaku.

Ekspresi Platform

Ekspresi Platform adalah string JSON yang menjelaskan kapan dependensi diperlukan atau saat pustaka atau fitur diharapkan dibuat.

Ekspresi dibangun dari pengidentifikasi primitif, operator logis, dan pengelompokan:

• !<expr>, not <expr> - negasi
• <expr>|<expr>, <expr>,<expr> - logis OR (kata kunci or dicadangkan tetapi tidak valid dalam ekspresi platform)
• <expr>&<expr>, <expr> and <expr> - LOGIS AND
• (<expr>) - pengelompokan/prioritas

Pengidentifikasi berikut didefinisikan berdasarkan pengaturan triplet dan konfigurasi build:

Pengidentifikasi	Kondisi Triplet
x64	VCPKG_TARGET_ARCHITECTURE == "x64"
x86	VCPKG_TARGET_ARCHITECTURE == "x86"
arm	VCPKG_TARGET_ARCHITECTURE == "arm" atau VCPKG_TARGET_ARCHITECTURE == "arm64"
arm32	VCPKG_TARGET_ARCHITECTURE == "arm"
arm64	VCPKG_TARGET_ARCHITECTURE == "arm64"
arm64ec	VCPKG_TARGET_ARCHITECTURE == "arm64ec"
wasm32	VCPKG_TARGET_ARCHITECTURE == "wasm32"
mips64	VCPKG_TARGET_ARCHITECTURE == "mips64"
windows	VCPKG_CMAKE_SYSTEM_NAME == ""atau atau VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" VCPKG_CMAKE_SYSTEM_NAME == "MinGW"
mingw	VCPKG_CMAKE_SYSTEM_NAME == "MinGW"
uwp	VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore"
xbox	VCPKG_CMAKE_SYSTEM_NAME == "" dan XBOX_CONSOLE_TARGET didefinisikan.
linux	VCPKG_CMAKE_SYSTEM_NAME == "Linux"
osx	VCPKG_CMAKE_SYSTEM_NAME == "Darwin"
ios	VCPKG_CMAKE_SYSTEM_NAME == "iOS"
freebsd	VCPKG_CMAKE_SYSTEM_NAME == "FreeBSD"
openbsd	VCPKG_CMAKE_SYSTEM_NAME == "OpenBSD"
android	VCPKG_CMAKE_SYSTEM_NAME == "Android"
emscripten	VCPKG_CMAKE_SYSTEM_NAME == "Emscripten"
qnx	VCPKG_CMAKE_SYSTEM_NAME == "QNX"
vxworks	VCPKG_CMAKE_SYSTEM_NAME == "VxWorks"
static	VCPKG_LIBRARY_LINKAGE == "static"
staticcrt	VCPKG_CRT_LINKAGE == "static"
native	TARGET_TRIPLET == HOST_TRIPLET

Contoh ekspresi platform

• Kebutuhan picosha2 untuk sha256 di non-Windows, tetapi dapatkan dari OS di Windows (BCrypt)

{
  "name": "picosha2",
  "platform": "!windows"
}

• Memerlukan zlib pada arm64 Windows dan amd64 Linux

{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}