referenční dokumentace k vcpkg.json

Článek
07/22/2024

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.

Příklad

{
  "$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).

Pole nejvyšší úrovně

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

`"builtin-baseline"`

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

`"default-features"`

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.

`"description"`

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

`"dependencies"`

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.

Ukázkové závislosti portů

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

`"documentation"`

Identifikátor URI do dokumentace upstreamového projektu. Řetězec. Nepovinné.

`"features"`

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.

`"homepage"`

Identifikátor URI domovské stránky projektu. Řetězec. Nepovinné.

`"license"`

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

Příklady licenčních řetězců

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

EBNF

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 ;

`"maintainers"`

Seznam správců balíčků. Řetězec nebo pole řetězců. Nepovinné.

Doporučujeme použít formulář "Givenname Příjmení<e-mail>".

`"name"`

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.

`"overrides"`

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

Příklad přepsání verzí

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

`"port-version"`

Přípona verze rozlišující revize souborů balení. Celé číslo. Výchozí hodnota 0je .

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

`"supports"`

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 .

`"vcpkg-configuration"`

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.

Příklad vloženého `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"`

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é jako YYYY-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í.

Pole závislostí

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

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

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

Pole funkcí

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

Příklad portu s funkcemi

{
  "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:

Výraz platformy

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é slovo or 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"` nebo `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` == `""`nebo `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` == `""` a `XBOX_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`

Příklad výrazu platformy

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)"
}

Sdílet prostřednictvím

referenční dokumentace k vcpkg.json

Příklad

Pole nejvyšší úrovně

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

Ukázkové závislosti portů

`"documentation"`

`"features"`

`"homepage"`

`"license"`

Příklady licenčních řetězců

EBNF

`"maintainers"`

`"name"`

`"overrides"`

Příklad přepsání verzí

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Příklad vloženého `vcpkg-configuration`

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

Pole závislostí

Závislost: `"default-features"`

Závislost: `"features"`

Závislost: `"host"`

Závislost: `"name"`

Závislost: `"platform"`

Závislost: `"version>="`

Pole funkcí

Příklad portu s funkcemi

Funkce: `"dependencies"`

Funkce: `"description"`

Funkce: `"supports"`

Funkce: `"license"`

Výraz platformy

Příklad výrazu platformy

Další materiály

Sdílet prostřednictvím

referenční dokumentace k vcpkg.json

Příklad

Pole nejvyšší úrovně

"builtin-baseline"

"default-features"

"description"

"dependencies"

Ukázkové závislosti portů

"documentation"

"features"

"homepage"

"license"

Příklady licenčních řetězců

EBNF

"maintainers"

"name"

"overrides"

Příklad přepsání verzí

"port-version"

"supports"

"vcpkg-configuration"

Příklad vloženého vcpkg-configuration

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

Pole závislostí

Závislost: "default-features"

Závislost: "features"

Závislost: "host"

Závislost: "name"

Závislost: "platform"

Závislost: "version>="

Pole funkcí

Příklad portu s funkcemi

Funkce: "dependencies"

Funkce: "description"

Funkce: "supports"

Funkce: "license"

Výraz platformy

Příklad výrazu platformy

Další materiály

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

`"documentation"`

`"features"`

`"homepage"`

`"license"`

`"maintainers"`

`"name"`

`"overrides"`

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Příklad vloženého `vcpkg-configuration`

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

Závislost: `"default-features"`

Závislost: `"features"`

Závislost: `"host"`

Závislost: `"name"`

Závislost: `"platform"`

Závislost: `"version>="`

Funkce: `"dependencies"`

Funkce: `"description"`

Funkce: `"supports"`

Funkce: `"license"`