Číst v angličtině

Sdílet prostřednictvím


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.

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:

  1. Závislost typu port-port pro port má "default-features": true výchozí hodnotu.
  2. 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

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

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