referenční dokumentace k vcpkg.json
Přehled použití manifestů s vcpkg najdete v tématu Režim manifestu.
Manifesty jsou striktní dokumenty JSON . Nemohou obsahovat komentáře ve stylu C++(//
) ani koncové čárky. Můžete ale použít názvy polí, které začínají $
psát komentáře do libovolného objektu, který má dobře definovanou sadu klíčů. Tato pole komentářů nejsou povolena v žádném objektu, který povoluje uživatelsky definované klíče (například "features"
).
Nejnovější schéma JSON je k dispozici na adrese https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. Integrované vývojové prostředí s podporou schématu JSON, jako je Visual Studio a Visual Studio Code, můžou tento soubor použít k zajištění automatického dokončování a kontroly syntaxe. U většiny prostředí IDE byste měli nastavit "$schema"
tuto vcpkg.json
adresu URL.
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
"dependencies": [
"boost-system",
{
"name": "cpprestsdk",
"default-features": false
},
"libxml2",
"yajl"
]
}
Tento příklad ukazuje manifest pro aplikaci používající boost-system
, cpprestsdk
, libxml2
, a yajl
. Příklad obsahuje také odkaz na $schema
povolení lepšího ověřování a automatického dokončování integrovaného vývojového prostředí ( IDE).
Název | Požadováno | Type | Popis |
---|---|---|---|
builtin-baseline | No | string | Připnutí verzí, které se mají použít při sestavování jako nejvyšší úrovně |
default-features | No | Objekt funkce[] | Vyžadovat funkce uvedené ve výchozím nastavení jako zapnuté |
závislosti | No | Závislost[] | Seznam závislostí potřebných k sestavení a použití tohoto projektu |
popis | Knihovny | řetězec nebo řetězec[] | Popis projektu |
dokumentace | No | string | Identifikátor URI do dokumentace upstreamového projektu |
features | No | {řetězec: Feature} | Volitelné funkce dostupné pro uživatele projektu |
Domovská stránka | No | string | Identifikátor URI domovské stránky upstreamového projektu |
licence | No | řetězec nebo null | Výraz licence SPDX |
Správci | No | řetězec nebo řetězec[] | Správci souborů balíčků |
Jméno | Knihovny | string | Název projektu |
potlačuje | No | Přepsání[] | Připnutí verzí, které se mají použít při sestavování jako nejvyšší úrovně |
verze portu | No | integer | Revize souborů portů |
podporuje | No | Výraz platformy | Podporované konfigurace platformy a sestavení |
verze version-semver datum verze version-string |
Knihovny | string | Informace o nadřazené verzi |
Zástupce pro zadání "baseline"
rozlišení verze ve výchozím registru. Řetězec. Volitelné, pouze používané projekty nejvyšší úrovně.
Toto pole označuje potvrzení, jehož https://github.com/microsoft/vcpkg součástí jsou informace o globální minimální verzi manifestu. Je vyžadován pro soubory manifestu nejvyšší úrovně pomocí správy verzí bez zadaného "default-registry"
. Má stejný sémantický jako definování výchozího registru, který má být:
{
"default-registry": {
"kind": "builtin",
"baseline": "<value>"
}
}
Další sémantické podrobnosti najdete v tématu Správa verzí a Používání registrů .
Sada funkcí potřebných k přiměřenému chování bez dalšího přizpůsobení.
Výchozí funkce se automaticky vyberou v následujících případech:
- Závislost typu port-port pro port má
"default-features": true
výchozí hodnotu. - Manifest nejvyšší úrovně nemá závislost pro port s
"default-features": false
.
Výchozí funkce zpracovávají konkrétní případ poskytnutí "výchozí" konfigurace pro tranzitivní závislosti, o kterých projekt nejvyšší úrovně nemusí vědět. Porty používané jinými uživateli by měly téměř vždy používat "default-features": false
pro jejich závislosti.
Výchozí funkce specifické pro platformu můžete definovat pomocí objektu funkce:
{
"name": "my-port",
"default-features": [
"png",
{
"name": "winssl",
"platform": "windows"
}
]
}
Další "features"
informace o funkcích najdete.
Popis portu. Řetězec nebo pole řetězců. Povinné pro knihovny, volitelné pro projekty nejvyšší úrovně.
Slouží k tomu, aby uživatelé mohli knihovnu zjistit jako součást search
příkazu nebo find
příkazu a dozvěděli se, co knihovna dělá.
Seznam závislostí vyžadovaných projektem Pole závislostí objektů. Nepovinné.
Toto pole obsahuje seznam všech závislostí potřebných k sestavení a používání knihovny nebo aplikace.
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [
"json",
{
"name": "mimalloc",
"platform": "windows"
}
]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
Identifikátor URI do dokumentace upstreamového projektu. Řetězec. Nepovinné.
Funkce, které jsou k dispozici pro uživatele projektu. Mapa názvů na objekty Funkce Nepovinné.
Funkce jsou logické příznaky, které do sestavení přidávají další chování a závislosti. Další informace o funkcích najdete v dokumentaci ke konceptu manifestu.
Identifikátor URI domovské stránky projektu. Řetězec. Nepovinné.
Krátký licenční výraz SPDX projektu. Řetězec nebo null. Nepovinné.
Měl "license"
by to být buď výraz licence SPDX 3.19, nebo by měl být null
indikovaný, že uživatelé musí číst nasazený /share/<port>/copyright
soubor. DocumentRefs nejsou podporovány.
Poznámka
Informace o licencování poskytované pro každý balíček v registru vcpkg představují nejlepší pochopení licenčních požadavků Microsoftu. Tyto informace však nemusí být konečné. Uživatelům se doporučuje ověřit přesné licenční požadavky pro každý balíček, který mají v úmyslu používat, protože je nakonec jejich odpovědností zajistit dodržování příslušných licencí.
MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2
vcpkg používá k analýze pole licence následující 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 ;
Seznam správců balíčků. Řetězec nebo pole řetězců. Nepovinné.
Doporučujeme použít formulář "Givenname Příjmení<e-mail>".
Název projektu. Řetězec. Povinné pro knihovny, volitelné pro projekty nejvyšší úrovně.
Název musí být malá písmena ASCII, číslice nebo pomlčky (-
). Nesmí začínat ani končit pomlčkou. Knihovny se doporučuje, aby jako předponu zahrnuly název organizace nebo architektury, například msft-
aby boost-
uživatelům pomohly najít a popsat přidružené knihovny.
Například knihovnu s oficiálním názvem Boost.Asio
může být uveden název boost-asio
.
Přesné špendlíky verzí, které se mají použít pro konkrétní závislosti. Pole objektů Override. Nepovinné.
"overrides"
z tranzitivních manifestů (tj. ze závislostí) se ignorují. Používají se pouze přepsání definovaná projektem nejvyšší úrovně.
Název | Požadováno | Type | Popis |
---|---|---|---|
name | Ano | string | Název portu |
version | Ano | string | Upstreamové informace o verzi pro připnutí. |
version-semver datum verze version-string |
Ano | string | Zastaralé alternativy k version pojmenování konkrétních schémat. |
verze portu | No | integer | Revize souborů portů pro připnutí Zastaralé ve prospěch umístění do samotné verze. |
"port-version"
musí být zadána #N
jako přípona v "version"
. Například "version": "1.2.3#7"
názvy verze 1.2.3, port-verze 7.
Další sémantické podrobnosti najdete v tématu správa verzí.
"overrides": [
{
"name": "arrow", "version": "1.2.3#7"
},
{
"name": "openssl", "version": "1.1.1h#3"
}
]
Přípona verze rozlišující revize souborů balení. Celé číslo. Výchozí hodnota 0
je .
Při "port-version"
publikování nové verze portu, která nemění nadřazenou zdrojovou verzi, by se měla zvýšit. Při změně nadřazené zdrojové verze by se mělo změnit pole verze a "port-version"
mělo by se resetovat ( 0
nebo odebrat).
Další podrobnosti najdete v tématu Správa verzí.
Podporované konfigurace platformy a sestavení Výraz platformy. Nepovinné.
Toto pole dokumentuje, že projekt se neočekává, že se sestaví nebo úspěšně spustí v určitých konfiguracích platformy.
Pokud například vaše knihovna nepodporuje sestavování pro Linux, použili "supports": "!linux"
byste .
Umožňuje vložit vlastnosti konfigurace vcpkg do vcpkg.json
souboru. Všechno uvnitř vcpkg-configuration
vlastnosti je považováno za to, jako by bylo definováno v vcpkg-configuration.json
souboru. Další podrobnosti najdete v vcpkg-configuration.json
dokumentaci.
vcpkg-configuration
Když je definovaný vcpkg.json
i vcpkg-configuration.json
soubor, který nemá povolený soubor, a výsledkem bude ukončení příkazu vcpkg s chybovou zprávou.
{
"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"
]
}
Verze upstreamového projektu. Řetězec. Povinné pro knihovny, volitelné pro projekty nejvyšší úrovně.
Manifest musí obsahovat maximálně jedno pole verze. Každé pole verze odpovídá jinému schématu správy verzí:
"version"
- Uvolněná sémantická verze 2.0.0, což umožňuje více nebo méně než 3 primární čísla. Příklad:1.2.3.4.10-alpha1
"version-semver"
- Striktní sémantická verze 2.0.0. Příklad:2.0.1-rc5
"version-date"
– Datum naformátované jakoYYYY-MM-DD
volitelné koncové číselné sekvence oddělené tečkami. Používá se pro balíčky, které nemají číselné verze (například Live-at-HEAD). Příklad:2022-12-09.314562
"version-string"
- Libovolný řetězec. Používá se pro balíčky, které nemají seřazené verze. Tato možnost by se měla používat jen zřídka, ale všechny porty vytvořené před zavedením jiných polí verze toto schéma používají.
Další podrobnosti najdete v tématu Správa verzí.
Každá závislost je řetězec nebo objekt s následujícími poli:
Název | Požadováno | Type | Popis |
---|---|---|---|
default-features | No | bool | Vyžadovat funkce uvedené ve výchozím nastavení jako zapnuté |
features | No | Objekt funkce[] | Seznam dalších funkcí, které se mají vyžadovat |
host | No | bool | Vyžadovat závislost pro hostitelský počítač místo cíle |
Jméno | Ano | string | Název závislosti |
nástupiště | No | Výraz platformy | Kvalifikátor, pro které platformy mají závislost používat |
version>= | No | string | Minimální požadovaná verze. Verze portu je identifikována příponou #N , 1.2.3#7 například názvy port-version 7. |
Řetězce se interpretují jako objekt s názvem definovaným pro řetězcovou hodnotu.
Závislost: "default-features"
Logická hodnota označující, že projekt závisí na funkcích závislosti ve výchozím nastavení. Výchozí hodnota true
je .
Ve většině případů by to mělo být definováno false
a na všech potřebných funkcích by měly být explicitně závislé.
Závislost: "features"
Seznam dalších funkcí, které potřebujete. Pole objektů Feature. Nepovinné.
Objekt funkce je objekt s následujícími poli:
name
- Název funkce. Řetězec. Povinný:platform
– Výraz platformy, který omezuje platformy, ve kterých je funkce povinná. Nepovinné.
Jednoduchý řetězec je také platným Feature Object
ekvivalentem { "name": "<feature-name>" }
.
Příklad:
{
"name": "ffmpeg",
"default-features": false,
"features": [
"mp3lame",
{
"name": "avisynthplus",
"platform": "windows"
}
]
}
Používá knihovnu ffmpeg
s podporou kódování MP3. Podpora je povolená jenom avisynthplus
pro Windows.
Závislost: "host"
Logická hodnota označující, že závislost musí být vytvořena pro triplet hostitele místo triplet aktuálního portu. Výchozí hodnota false
je .
Všechny závislosti, které poskytují nástroje nebo skripty, které by se měly "spustit" během sestavení (jako jsou systémy sestavení, generátory kódu nebo pomocné rutiny), by měly být označeny jako "host": true
. To umožňuje správnou křížovou kompilaci v případech, že cíl není spustitelný – například při kompilaci pro arm64-android
.
Další informace najdete v tématu Závislosti hostitele.
Závislost: "name"
Název závislosti. Řetězec. Povinný:
To se řídí stejnými omezeními jako "name"
vlastnost projektu.
Závislost: "platform"
Výraz, který omezuje platformy, ve kterých je závislost povinná. Výraz platformy. Nepovinné.
Pokud výraz neodpovídá aktuální konfiguraci, závislost se nepoužije. Pokud například závislost obsahuje "platform": "!windows"
, bude se vyžadovat pouze při cílení na systémy mimo Systém Windows.
Závislost: "version>="
Omezení minimální verze závislosti.
Toto pole určuje minimální verzi závislosti, volitelně pomocí #N
přípony, která v případě potřeby také určuje minimální verzi portu.
Další informace o sémantice správy verzí najdete v tématu Správa verzí.
Každá funkce je objekt s následujícími poli:
Název | Požadováno | Type | Popis |
---|---|---|---|
popis | Ano | string | Popis funkce |
závislosti | No | Závislost[] | Seznam závislostí |
podporuje | No | Výraz platformy | Kvalifikátor, pro které platformy a konfigurace funkce podporuje |
licence | No | řetězec nebo null | Výraz licence SPDX |
V dokumentaci k režimu manifestu najdete koncepční přehled funkcí.
{
"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"
]
}
}
}
Funkce: "dependencies"
Seznam závislostí vyžadovaných funkcí Pole závislostí objektů. Nepovinné.
Toto pole obsahuje všechny další závislosti potřebné k sestavení a použití této funkce.
Funkce: "description"
Popis funkce. Řetězec nebo pole řetězců. Povinný:
Slouží k tomu, aby uživatelé tuto funkci objevili jako součást search
příkazu nebo příkazu find
a dozvěděli se, co tato funkce dělá.
Funkce: "supports"
Podporovaná platforma a konfigurace sestavení pro tuto funkci. Výraz platformy. Nepovinné.
Toto pole dokumentuje konfigurace platformy, ve kterých se funkce sestaví a úspěšně spustí.
Funkce: "license"
Krátký licenční výraz funkce SPDX. Řetězec nebo null. Nepovinné. Pokud není zadána, licence je stejná jako v poli licence nejvyšší úrovně.
Poznámka
Informace o licencování poskytované pro každý balíček v registru vcpkg představují nejlepší pochopení licenčních požadavků Microsoftu. Tyto informace však nemusí být konečné. Uživatelům se doporučuje ověřit přesné licenční požadavky pro každý balíček, který mají v úmyslu používat, protože je nakonec jejich odpovědností zajistit dodržování příslušných licencí.
Výraz platformy je řetězec JSON, který popisuje, kdy se vyžaduje závislost nebo kdy se očekává sestavení knihovny nebo funkce.
Výrazy jsou sestaveny z primitivních identifikátorů, logických operátorů a seskupení:
!<expr>
,not <expr>
- negace<expr>|<expr>
,<expr>,<expr>
– logický OPERÁTOR OR (klíčové slovoor
je vyhrazeno, ale není platné ve výrazech platformy)<expr>&<expr>
,<expr> and <expr>
– logický operátor AND(<expr>)
- seskupování/priorita
Následující identifikátory jsou definovány na základě nastavení triplet a konfigurace sestavení:
Identifikátor | Podmínka trojití |
---|---|
x64 |
VCPKG_TARGET_ARCHITECTURE == "x64" |
x86 |
VCPKG_TARGET_ARCHITECTURE == "x86" |
arm |
VCPKG_TARGET_ARCHITECTURE == "arm" neboVCPKG_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 == "" neboVCPKG_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 == "" aXBOX_CONSOLE_TARGET je definován. |
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 |
- Potřebuje
picosha2
sha256 v jiných systémech než Windows, ale získat ho z operačního systému ve Windows (BCrypt)
{
"name": "picosha2",
"platform": "!windows"
}
- Vyžadování knihovny zlib ve Windows arm64 a amd64 Linuxu
{
"name": "zlib",
"platform": "(windows & arm64) | (linux & x64)"
}
Zpětná vazba k produktu vcpkg
vcpkg je open source projekt. Vyberte odkaz pro poskytnutí zpětné vazby: