dokumentacja vcpkg.json

Artykuł
03/01/2024

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, libxml2i 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
Dokumentacji	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
Licencji	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": falseprogramem .

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.

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-configurationvcpkg-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": "dacf4de488094a384ca2c202b923ccc097956e0c",
        "repository": "https://github.com/northwindtraders/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 jako YYYY-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
Platformy	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>" }.

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

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><expr>,<expr> — logiczny OR (słowo kluczowe or jest zastrzeżone, ale nieprawidłowe w wyrażeniach platformy)
<expr>&<expr>, <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"` Lub `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`arm32`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"`
`arm64`	`VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`wasm32`	`VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
`windows`	`VCPKG_CMAKE_SYSTEM_NAME` == `""`lub lub `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` == `""` i `XBOX_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"`
`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)"
}

Udostępnij za pośrednictwem

dokumentacja vcpkg.json

Przykład

Pola najwyższego poziomu

"builtin-baseline"

"default-features"

"description"

"dependencies"

Przykładowe zależności portów

"documentation"

"features"

"homepage"

"license"

Przykładowe ciągi licencji

EBNF

"maintainers"

"name"

"overrides"

Przykład przesłonięć wersji

"port-version"

"supports"

"vcpkg-configuration"

Przykład osadzony vcpkg-configuration

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