dokumentacja vcpkg.json
Aby zapoznać się z omówieniem używania manifestów z narzędziem vcpkg, zobacz Tryb manifestu.
Manifesty są rygorystycznymi dokumentami JSON . Nie mogą zawierać komentarzy w stylu C++(//
) ani przecinków końcowych. Można jednak użyć nazw pól rozpoczynających się od $
, aby zapisać komentarze w dowolnym obiekcie, który ma dobrze zdefiniowany zestaw kluczy. Te pola komentarzy nie są dozwolone w żadnych obiektach, które zezwalają na klucze zdefiniowane przez użytkownika (takie jak "features"
).
Najnowszy schemat JSON jest dostępny pod adresem https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. Środowiska IDE z obsługą schematu JSON, takie jak Visual Studio i Visual Studio Code, mogą używać tego pliku do automatycznego uzupełniania i sprawdzania składni. W przypadku większości identyfikatorów IDE należy ustawić "$schema"
ten vcpkg.json
adres URL.
Przykład
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
"dependencies": [
"boost-system",
{
"name": "cpprestsdk",
"default-features": false
},
"libxml2",
"yajl"
]
}
W tym przykładzie pokazano manifest dla aplikacji przy użyciu poleceń boost-system
, cpprestsdk
, libxml2
i yajl
. Przykład zawiera również odwołanie umożliwiające lepszą walidację $schema
środowiska IDE i autouzupełnianie.
Pola najwyższego poziomu
Nazwisko | Wymagania | Type | Opis |
---|---|---|---|
wbudowany punkt odniesienia | Nie. | string | Przypinania wersji do użycia podczas kompilowania jako najwyższego poziomu |
funkcje domyślne | Nie. | Obiekt funkcji[] | Wymagaj funkcji wymienionych jako domyślne |
Zależności | Nie. | Zależność[] | Lista zależności wymaganych do kompilowania i używania tego projektu |
opis | Biblioteki | ciąg lub ciąg[] | Opis projektu |
dokumentacja | Nie. | string | Identyfikator URI do dokumentacji nadrzędnego projektu |
features | Nie. | {ciąg: Funkcja} | Opcjonalne funkcje dostępne dla użytkowników projektu |
strona główna | Nie. | string | Identyfikator URI strony głównej projektu nadrzędnego |
licencja | Nie. | ciąg lub wartość null | Wyrażenie licencji SPDX |
Opiekunów | Nie. | ciąg lub ciąg[] | Osoby odpowiedzialne za pliki pakietu |
name | Biblioteki | string | Nazwa projektu |
Zastępuje | Nie. | Przesłonięcia[] | Przypinania wersji do użycia podczas kompilowania jako najwyższego poziomu |
wersja portu | Nie. | integer | Wersja plików portów |
Obsługuje | Nie. | Wyrażenie platformy | Obsługiwane konfiguracje platformy i kompilacji |
Wersja version-semver data wersji ciąg wersji |
Biblioteki | string | Informacje o wersji nadrzędnej |
"builtin-baseline"
Skrót do określania "baseline"
rozpoznawania wersji w rejestrze domyślnym. Ciąg. Opcjonalne, używane tylko przez projekty najwyższego poziomu.
To pole wskazuje zatwierdzenie https://github.com/microsoft/vcpkg , z którego zapewnia globalne informacje o minimalnej wersji manifestu. Jest to wymagane w przypadku plików manifestu najwyższego poziomu przy użyciu przechowywania wersji bez określonego "default-registry"
elementu . Ma ona taką samą semantyczną, jak zdefiniowanie domyślnego rejestru jako:
{
"default-registry": {
"kind": "builtin",
"baseline": "<value>"
}
}
Aby uzyskać więcej informacji semantycznych, zobacz przechowywanie wersji i używanie rejestrów.
"default-features"
Zestaw funkcji potrzebnych do rozsądnego zachowania bez dodatkowego dostosowania.
Funkcje domyślne są wybierane automatycznie, jeśli:
- Zależność port-port dla portu ma
"default-features": true
wartość domyślną. - Manifest najwyższego poziomu nie ma zależności dla portu z
"default-features": false
programem .
Funkcje domyślne obsługują konkretny przypadek udostępniania konfiguracji "domyślnej" dla przejściowych zależności, o których projekt najwyższego poziomu może nie wiedzieć. Porty używane przez inne osoby powinny prawie zawsze używać "default-features": false
ich zależności.
Funkcje domyślne specyficzne dla platformy można zdefiniować przy użyciu obiektu funkcji:
{
"name": "my-port",
"default-features": [
"png",
{
"name": "winssl",
"platform": "windows"
}
]
}
Zobacz "features"
, aby uzyskać więcej informacji na temat funkcji.
"description"
Opis portu. Ciąg lub tablica ciągów. Wymagane dla bibliotek, opcjonalne dla projektów najwyższego poziomu.
Służy to do ułatwiania użytkownikom odnajdywania biblioteki w ramach search
polecenia lub find
i poznawania tego, co robi biblioteka.
"dependencies"
Lista zależności wymaganych przez projekt. Tablica obiektów Zależności. Opcjonalny.
To pole zawiera listę wszystkich zależności potrzebnych do skompilowania biblioteki lub aplikacji i korzystania z nich.
Przykładowe zależności portów
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [
"json",
{
"name": "mimalloc",
"platform": "windows"
}
]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
"documentation"
Identyfikator URI do dokumentacji nadrzędnego projektu. Ciąg. Opcjonalny.
"features"
Funkcje dostępne dla użytkowników projektu. Mapa nazw obiektów funkcji. Opcjonalny.
Funkcje to flagi logiczne, które dodają dodatkowe zachowania i zależności do kompilacji. Aby uzyskać więcej informacji na temat funkcji, zobacz dokumentację koncepcji manifestu.
"homepage"
Identyfikator URI strony głównej projektu. Ciąg. Opcjonalny.
"license"
Krótkie wyrażenie licencji SPDX projektu. Ciąg lub wartość null. Opcjonalny.
Element "license"
powinien być wyrażeniem licencji SPDX 3.19 lub powinien wskazywaćnull
, że użytkownicy muszą odczytać wdrożony /share/<port>/copyright
plik. Elementy DocumentRef nie są obsługiwane.
Uwaga
Informacje o licencjonowaniu podane dla każdego pakietu w rejestrze vcpkg reprezentują najlepsze zrozumienie wymagań licencyjnych firmy Microsoft. Jednak te informacje mogą nie być ostateczne. Zaleca się sprawdzenie dokładnych wymagań dotyczących licencjonowania dla każdego pakietu, którego zamierza użyć, ponieważ ostatecznie jest to ich odpowiedzialność za zapewnienie zgodności z odpowiednimi licencjami.
Przykładowe ciągi licencji
MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2
EBNF
Narzędzie vcpkg analizuje pole licencji przy użyciu następującego systemu plików EBNF :
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"
Lista osób obsługujących pakiety. Ciąg lub tablica ciągów. Opcjonalny.
Zalecamy użycie formularza "Imię i nazwisko<e-mail>".
"name"
Nazwa projektu. Ciąg. Wymagane dla bibliotek, opcjonalne dla projektów najwyższego poziomu.
Nazwa musi mieć małe litery ASCII, cyfry lub łączniki (-
). Nie może zaczynać ani kończyć się łącznikiem. Biblioteki są zachęcane do uwzględnienia ich nazwy organizacji lub struktury jako prefiksu, takiego jak msft-
lub boost-
ułatwienia użytkownikom znajdowania i opisywania skojarzonych bibliotek.
Na przykład biblioteka o oficjalnej nazwie Boost.Asio
może mieć nazwę boost-asio
.
"overrides"
Dokładne numery PIN wersji do użycia dla określonych zależności. Tablica obiektów przesłaniania. Opcjonalny.
"overrides"
z manifestów przechodnich (tj. z zależności) są ignorowane. Używane są tylko przesłonięcia zdefiniowane przez projekt najwyższego poziomu.
Nazwisko | Wymagania | Type | opis |
---|---|---|---|
name | Tak | string | Nazwa portu |
version | Tak | string | Nadrzędne informacje o wersji do przypinania. |
version-semver data wersji ciąg wersji |
Tak | string | Przestarzałe alternatywy dla version nazewnictwa określonych schematów. |
wersja portu | Nie. | integer | Przesuń poprawkę plików do przypinania. Przestarzałe na rzecz umieszczenia w samej wersji. |
"port-version"
należy określić jako sufiks w pliku #N
"version"
. Na przykład "version": "1.2.3#7"
nazwy w wersji 1.2.3, port-version 7.
Zobacz również przechowywanie wersji, aby uzyskać więcej szczegółów semantycznych.
Przykład przesłonięć wersji
"overrides": [
{
"name": "arrow", "version": "1.2.3#7"
},
{
"name": "openssl", "version": "1.1.1h#3"
}
]
"port-version"
Sufiks wersji wyróżniający poprawki do plików pakietów. Całkowitą. Wartość domyślna to 0
.
"port-version"
Element powinien być zwiększany za każdym razem, gdy zostanie opublikowana nowa wersja portu, która nie zmienia nadrzędnej wersji źródłowej. Po zmianie nadrzędnej wersji źródłowej pole wersji powinno ulec zmianie i "port-version"
powinno zostać zresetowane do 0
(lub usunięte).
Aby uzyskać więcej informacji, zobacz przechowywanie wersji.
"supports"
Obsługiwane konfiguracje platformy i kompilacji. Wyrażenie platformy. Opcjonalny.
To pole dokumentuje, że projekt nie ma kompilować ani działać pomyślnie w niektórych konfiguracjach platformy.
Jeśli na przykład biblioteka nie obsługuje kompilowania dla systemu Linux, użyj polecenia "supports": "!linux"
.
"vcpkg-configuration"
Umożliwia osadzanie właściwości konfiguracji vcpkg wewnątrz vcpkg.json
pliku. Wszystkie elementy wewnątrz vcpkg-configuration
właściwości są traktowane tak, jakby zostały zdefiniowane w vcpkg-configuration.json
pliku. Aby uzyskać więcej informacji, zobacz dokumentację vcpkg-configuration.json
.
Posiadanie zdefiniowanego vcpkg-configuration
vcpkg-configuration.json
elementu , vcpkg.json
a także posiadanie pliku jest niedozwolone i spowoduje zakończenie polecenia vcpkg z komunikatem o błędzie.
Przykład osadzony vcpkg-configuration
{
"name": "test",
"version": "1.0.0",
"dependencies": [ "beison", "zlib" ],
"vcpkg-configuration": {
"registries": [
{
"kind": "git",
"baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
"repository": "https://github.com/microsoft/vcpkg-docs",
"reference": "vcpkg-registry",
"packages": [ "beicode", "beison" ]
}
],
"overlay-ports": [ "./my-ports/fmt",
"./team-ports"
]
}
"version"
, , "version-semver"
, , "version-date"
"version-string"
Wersja nadrzędnego projektu. Ciąg. Wymagane dla bibliotek, opcjonalne dla projektów najwyższego poziomu.
Manifest musi zawierać co najwyżej jedno pole wersji. Każde pole wersji odpowiada innego schematu przechowywania wersji:
"version"
— Zrelaksowana semantyczna wersja 2.0.0, umożliwiająca więcej lub mniej niż 3 numery podstawowe. Przykład:1.2.3.4.10-alpha1
"version-semver"
— Ścisła semantyczna wersja 2.0.0. Przykład:2.0.1-rc5
"version-date"
- Data sformatowana jakoYYYY-MM-DD
opcjonalna sekwencja kropkowa oddzielona kropką. Używany w przypadku pakietów, które nie mają wersji liczbowych (na przykład Live-at-HEAD). Przykład:2022-12-09.314562
"version-string"
- Dowolny ciąg. Używany w przypadku pakietów, które nie mają możliwych do zamówienia wersji. Powinno to być rzadko używane, jednak wszystkie porty utworzone przed wprowadzeniem innych pól wersji używają tego schematu.
Aby uzyskać więcej informacji, zobacz przechowywanie wersji.
Pola zależności
Każda zależność jest ciągiem lub obiektem z następującymi polami:
Nazwisko | Wymagania | Type | Opis |
---|---|---|---|
funkcje domyślne | Nie. | bool | Wymagaj funkcji wymienionych jako domyślne |
features | Nie. | Obiekt funkcji[] | Lista dodatkowych funkcji, które mają być wymagane |
host | Nie. | bool | Wymagaj zależności dla maszyny hosta zamiast docelowej |
name | Tak | string | Nazwa zależności |
podest | Nie. | Wyrażenie platformy | Kwalifikator, dla którego platformy mają być używane zależności |
version>= | Nie. | string | Minimalna wymagana wersja. Port-version jest identyfikowany z sufiksem #N , na przykład nazwy 1.2.3#7 port-version 7. |
Ciągi są interpretowane jako obiekt o nazwie zdefiniowanej dla wartości ciągu.
Zależność: "default-features"
Wartość logiczna wskazująca, że projekt zależy od funkcji "domyślnie" zależności. Wartość domyślna to true
.
W większości przypadków należy to zdefiniować, a false
wszelkie potrzebne funkcje powinny być jawnie zależne od.
Zależność: "features"
Lista dodatkowych funkcji, które mają być wymagane. Tablica obiektów funkcji. Opcjonalny.
Obiekt funkcji jest obiektem z następującymi polami:
name
— nazwa funkcji. Ciąg. Wymagany.platform
— Wyrażenie platformy, które ogranicza platformy, na których jest wymagana funkcja. Opcjonalny.
Prosty ciąg jest również prawidłowym Feature Object
odpowiednikiem { "name": "<feature-name>" }
.
Na przykład:
{
"name": "ffmpeg",
"default-features": false,
"features": [
"mp3lame",
{
"name": "avisynthplus",
"platform": "windows"
}
]
}
Używa biblioteki ffmpeg
z obsługą kodowania mp3. Tylko avisynthplus
w systemie Windows jest włączona obsługa.
Zależność: "host"
Wartość logiczna wskazująca, że zależność musi być zbudowana dla triplet hosta zamiast triplet bieżącego portu. Wartość domyślna to false
.
Każda zależność udostępniająca narzędzia lub skrypty, które powinny być "wykonywane" podczas kompilacji (takich jak systemy kompilacji, generatory kodu lub pomocniki) powinny być oznaczone jako "host": true
. Umożliwia to prawidłową kompilację krzyżową w przypadkach, gdy element docelowy nie jest wykonywalny — na przykład podczas kompilowania elementu .arm64-android
Aby uzyskać więcej informacji, zobacz Zależności hosta.
Zależność: "name"
Nazwa zależności. Ciąg. Wymagany.
Jest to zgodne z tymi samymi ograniczeniami co "name"
właściwość projektu.
Zależność: "platform"
Wyrażenie, które ogranicza platformy, na których jest wymagana zależność. Wyrażenie platformy. Opcjonalny.
Jeśli wyrażenie nie jest zgodne z bieżącą konfiguracją, zależność nie zostanie użyta. Jeśli na przykład zależność ma "platform": "!windows"
wartość , wymagana jest tylko w przypadku określania wartości docelowych systemów innych niż Windows.
Zależność: "version>="
Ograniczenie minimalnej wersji zależności.
To pole określa minimalną wersję zależności, opcjonalnie przy użyciu #N
sufiksu, aby również określić minimalną wersję portu w razie potrzeby.
Aby uzyskać więcej informacji na temat semantyki przechowywania wersji, zobacz Przechowywanie wersji.
Pola funkcji
Każda funkcja jest obiektem z następującymi polami:
Nazwisko | Wymagania | Type | Opis |
---|---|---|---|
opis | Tak | string | Opis funkcji |
Zależności | Nie. | Zależność[] | Lista zależności |
Obsługuje | Nie. | Wyrażenie platformy | Kwalifikator, dla których platform i konfiguracji obsługuje funkcja |
licencja | Nie. | ciąg lub wartość null | Wyrażenie licencji SPDX |
Zapoznaj się z dokumentacją trybu manifestu, aby zapoznać się z koncepcyjnym omówieniem funkcji.
Przykładowy port z funkcjami
{
"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"
]
}
}
}
Funkcja: "dependencies"
Lista zależności wymaganych przez tę funkcję. Tablica obiektów Zależności. Opcjonalny.
To pole zawiera listę wszelkich dodatkowych zależności potrzebnych do skompilowania funkcji i korzystania z tej funkcji.
Funkcja: "description"
Opis funkcji. Ciąg lub tablica ciągów. Wymagany.
Służy to do ułatwiania użytkownikom odnajdywania funkcji w ramach search
polecenia lub find
i poznawania funkcji.
Funkcja: "supports"
Obsługiwana platforma i konfiguracje kompilacji dla tej funkcji. Wyrażenie platformy. Opcjonalny.
To pole dokumentuje konfiguracje platformy, w których funkcja zostanie skompilowa i uruchomiona pomyślnie.
Funkcja: "license"
Krótkie wyrażenie licencji SPDX funkcji. Ciąg lub wartość null. Opcjonalny. Jeśli nie zostanie podana, licencja jest taka sama jak określona w polu licencji najwyższego poziomu.
Uwaga
Informacje o licencjonowaniu podane dla każdego pakietu w rejestrze vcpkg reprezentują najlepsze zrozumienie wymagań licencyjnych firmy Microsoft. Jednak te informacje mogą nie być ostateczne. Zaleca się sprawdzenie dokładnych wymagań dotyczących licencjonowania dla każdego pakietu, którego zamierza użyć, ponieważ ostatecznie jest to ich odpowiedzialność za zapewnienie zgodności z odpowiednimi licencjami.
Wyrażenie platformy
Wyrażenie platformy to ciąg JSON, który opisuje, kiedy zależność jest wymagana lub gdy biblioteka lub funkcja ma zostać skompilowaną.
Wyrażenia są tworzone na podstawie identyfikatorów pierwotnych, operatorów logicznych i grupowania:
!<expr>
,not <expr>
— negacja<expr>|<expr>
,<expr>,<expr>
— logiczny OR (słowo kluczoweor
jest zastrzeżone, ale nieprawidłowe w wyrażeniach platformy)<expr>&<expr>
,<expr> and <expr>
— logiczne AND(<expr>)
- grupowanie/pierwszeństwo
Następujące identyfikatory są definiowane na podstawie ustawień potrójnych i konfiguracji kompilacji:
Identyfikator | Warunek potrójny |
---|---|
x64 |
VCPKG_TARGET_ARCHITECTURE == "x64" |
x86 |
VCPKG_TARGET_ARCHITECTURE == "x86" |
arm |
VCPKG_TARGET_ARCHITECTURE == "arm" lubVCPKG_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 == "" lub lubVCPKG_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 == "" iXBOX_CONSOLE_TARGET jest definiowany. |
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 |
Przykładowe wyrażenie platformy
- Wymaga
picosha2
sha256 w systemie innych niż Windows, ale pobiera go z systemu operacyjnego w systemie Windows (BCrypt)
{
"name": "picosha2",
"platform": "!windows"
}
- Wymagaj biblioteki zlib w systemach Arm64 Windows i amd64 Linux
{
"name": "zlib",
"platform": "(windows & arm64) | (linux & x64)"
}