Informazioni di riferimento su vcpkg.json

Articolo
07/16/2024

Per una panoramica dell'uso dei manifesti con vcpkg, vedere Modalità manifesto.

I manifesti sono documenti JSON rigorosi. Non possono contenere commenti in stile C++(//) né virgole finali. È tuttavia possibile usare nomi di campo che iniziano con $ per scrivere i commenti in qualsiasi oggetto con un set ben definito di chiavi. Questi campi di commento non sono consentiti in alcun oggetto che consenta chiavi definite dall'utente , ad esempio "features".

Lo schema JSON più recente è disponibile all'indirizzo https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. Gli IDE con supporto dello schema JSON, ad esempio Visual Studio e Visual Studio Code, possono usare questo file per fornire il completamento automatico e il controllo della sintassi. Per la maggior parte degli IDE, è necessario impostare "$schema" su vcpkg.json questo URL.

Esempio

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "boost-system",
    {
      "name": "cpprestsdk",
      "default-features": false
    },
    "libxml2",
    "yajl"
  ]
}

In questo esempio viene illustrato un manifesto per un'applicazione che usa boost-system, cpprestsdklibxml2, e yajl. L'esempio include anche un $schema riferimento per abilitare una migliore convalida dell'IDE e il completamento automatico.

Campi di primo livello

Nome	Obbligatorio	Type	Descrizione
baseline predefinita	No	string	Pin di versione da usare per la compilazione come primo livello
funzionalità predefinite	No	Oggetto Feature[]	Richiedi le funzionalità elencate come on-by-default
dependencies	No	Dipendenza[]	Elenco delle dipendenze necessarie per compilare e usare questo progetto
description	Librerie	string o string[]	Descrizione del progetto
documentazione.	No	string	URI alla documentazione del progetto upstream
features	No	{string: Funzionalità}	Funzionalità facoltative disponibili per gli utenti del progetto
home page	No	string	URI alla home page del progetto upstream
license	No	stringa o null	Espressione di licenza SPDX
Manutentori	No	string o string[]	Gestori dei file del pacchetto
name	Librerie	string	Nome del progetto
override	No	Override[]	Pin di versione da usare per la compilazione come primo livello
port-version	No	integer	Revisione dei file di porta
Supporta	No	Espressione piattaforma	Configurazioni di piattaforma e compilazione supportate
version version-semver data della versione version-string	Librerie	string	Informazioni sulla versione upstream

`"builtin-baseline"`

Collegamento per specificare per la risoluzione della "baseline" versione nel Registro di sistema predefinito. Stringa . Facoltativo, usato solo da progetti di primo livello.

Questo campo indica il commit di https://github.com/microsoft/vcpkg che fornisce informazioni sulla versione minima globale per il manifesto. È necessario per i file manifesto di primo livello usando il controllo delle versioni senza un oggetto specificato "default-registry". Ha la stessa semantica della definizione del registro predefinito in modo che sia:

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<value>"
  }
}

Per altri dettagli semantici, vedere Controllo delle versioni e Uso dei registri.

`"default-features"`

Set di funzionalità necessarie per un comportamento ragionevole senza personalizzazioni aggiuntive.

Le funzionalità predefinite vengono selezionate automaticamente se:

Una dipendenza da porta a porta per la porta ha "default-features": true il valore predefinito.
Il manifesto di primo livello non ha una dipendenza per la porta con "default-features": false.

Le funzionalità predefinite gestiscono il caso specifico di fornire una configurazione "predefinita" per le dipendenze transitive che il progetto di primo livello potrebbe non conoscere. Le porte usate da altri utenti devono quasi sempre usare "default-features": false per le relative dipendenze.

È possibile definire funzionalità predefinite specifiche della piattaforma usando un oggetto Feature:

{
  "name": "my-port",
  "default-features": [
    "png",
    {
      "name": "winssl",
      "platform": "windows"
    }
  ]
}

Per altre informazioni sulle funzionalità, vedere "features" .

`"description"`

Descrizione della porta. Stringa o matrice di stringhe. Obbligatorio per le librerie, facoltativo per i progetti di primo livello.

Questa operazione viene usata per consentire agli utenti di individuare la libreria come parte di un search comando o find e di apprendere le operazioni della libreria.

`"dependencies"`

Elenco delle dipendenze richieste dal progetto. Matrice di oggetti Dependency. Facoltativo.

Questo campo elenca tutte le dipendenze necessarie per compilare e usare la libreria o l'applicazione.

Dipendenze delle porte di esempio

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

`"documentation"`

URI della documentazione del progetto upstream. Stringa . Facoltativo.

`"features"`

Funzionalità disponibili per gli utenti del progetto. Mappa dei nomi agli oggetti Feature. Facoltativo.

Le funzionalità sono flag booleani che aggiungono comportamenti e dipendenze aggiuntivi a una compilazione. Per altre informazioni sulle funzionalità, vedere la documentazione sul concetto di manifesto.

`"homepage"`

URI della home page del progetto. Stringa . Facoltativo.

`"license"`

Espressione di licenza breve SPDX del progetto. Stringa o null. Facoltativo.

"license" deve essere un'espressione di licenza SPDX 3.19 oppure deve essere null per indicare che gli utenti devono leggere il file distribuito/share/<port>/copyright. DocumentRefs non è supportato.

Nota

Le informazioni sulle licenze fornite per ogni pacchetto nel registro vcpkg rappresentano la migliore comprensione dei requisiti di licenza di Microsoft. Tuttavia, queste informazioni potrebbero non essere definitive. Gli utenti sono invitati a verificare i requisiti di licenza esatti per ogni pacchetto che intende utilizzare, in quanto è in definitiva responsabilità di garantire la conformità alle licenze applicabili.

Stringhe di licenza di esempio

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

EBNF

vcpkg usa il codice EBNF seguente per analizzare il campo della licenza:

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"`

Elenco dei gestori di pacchetti. Stringa o matrice di stringhe. Facoltativo.

È consigliabile usare il formato "Givenname Surname<email".>

`"name"`

Nome del progetto. Stringa . Obbligatorio per le librerie, facoltativo per i progetti di primo livello.

Il nome deve essere lettere ASCII minuscole, cifre o trattini (-). Non deve iniziare né terminare con un trattino. Le librerie sono incoraggiate a includere il nome dell'organizzazione o del framework come prefisso, ad esempio msft- o boost- per aiutare gli utenti a trovare e descrivere le librerie associate.

Ad esempio, a una libreria con un nome ufficiale di Boost.Asio potrebbe essere assegnato il nome boost-asio.

`"overrides"`

Pin di versione esatti da usare per dipendenze specifiche. Matrice di oggetti Override. Facoltativo.

"overrides" dai manifesti transitivi (ad esempio dalle dipendenze) vengono ignorati. Vengono usate solo le sostituzioni definite dal progetto di primo livello.

Nome	Obbligatorio	Type	Descrizione
name	Sì	string	Nome porta
version	Sì	string	Informazioni sulla versione upstream da aggiungere.
version-semver data della versione version-string	Sì	string	Alternative deprecate per `version` la denominazione di schemi specifici.
port-version	No	integer	Revisione dei file di porta da aggiungere. Deprecato a favore dell'inserimento nella versione stessa.

"port-version" deve essere specificato come #N suffisso in "version". Ad esempio, "version": "1.2.3#7" nomi versione 1.2.3, porta-versione 7.

Per altri dettagli semantici, vedere anche controllo delle versioni.

Esempio di override della versione

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

`"port-version"`

Suffisso di versione che distingue le revisioni ai file di creazione del pacchetto. Valore intero. Il valore predefinito è 0.

Deve "port-version" essere incrementato ogni volta che viene pubblicata una nuova versione della porta che non modifica la versione di origine upstream. Quando viene modificata la versione di origine upstream, il campo della versione deve cambiare e deve "port-version" essere reimpostato 0 (o rimosso).

Per altri dettagli, vedere Controllo delle versioni.

`"supports"`

Configurazioni di piattaforma e compilazione supportate. Espressione di piattaforma. Facoltativo.

Questo campo documenta che non è previsto che un progetto venga compilato o eseguito correttamente in determinate configurazioni della piattaforma.

Ad esempio, se la libreria non supporta la compilazione per Linux, usare "supports": "!linux".

`"vcpkg-configuration"`

Consente di incorporare le proprietà di configurazione di vcpkg all'interno del vcpkg.json file. Tutti gli elementi all'interno della vcpkg-configuration proprietà vengono considerati come se fossero definiti in un vcpkg-configuration.json file. Per altri dettagli, vedere la vcpkg-configuration.json documentazione.

La presenza di un vcpkg-configuration file definito in vcpkg.json non vcpkg-configuration.json è consentita e comporterà la terminazione del comando vcpkg con un messaggio di errore.

Esempio incorporato `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"`

Versione del progetto upstream. Stringa . Obbligatorio per le librerie, facoltativo per i progetti di primo livello.

Un manifesto deve contenere al massimo un campo di versione. Ogni campo della versione corrisponde a uno schema di controllo delle versioni diverso:

"version" - Versione semantica rilassata 2.0.0, consentendo più o meno di 3 numeri primari. Esempio: 1.2.3.4.10-alpha1
"version-semver" - Versione semantica strict 2.0.0. Esempio: 2.0.1-rc5
"version-date" - Data formattata come YYYY-MM-DD con una sequenza numerica finale a punti finale. Usato per i pacchetti che non dispongono di versioni numeriche, ad esempio Live-at-HEAD. Esempio: 2022-12-09.314562
"version-string" - Stringa arbitraria. Usato per i pacchetti che non dispongono di versioni ordinabili. Questa operazione deve essere usata raramente, tuttavia tutte le porte create prima dell'introduzione degli altri campi della versione usano questo schema.

Per altri dettagli, vedere Controllo delle versioni.

Campi di dipendenza

Ogni dipendenza è una stringa o un oggetto con i campi seguenti:

Nome	Obbligatorio	Type	Descrizione
funzionalità predefinite	No	bool	Richiedi le funzionalità elencate come on-by-default
features	No	Oggetto Feature[]	Elenco di funzionalità aggiuntive da richiedere
host	No	bool	Richiedere la dipendenza per il computer host invece della destinazione
name	Sì	string	Nome della dipendenza
platform	No	Espressione piattaforma	Qualificatore per le piattaforme per cui usare la dipendenza
version>=	No	string	Versione minima richiesta. La versione della porta viene identificata con un `#N` suffisso, ad esempio i `1.2.3#7` nomi port-version 7.

Le stringhe vengono interpretate come un oggetto con nome definito per il valore stringa.

Dipendenza:`"default-features"`

Valore booleano che indica che il progetto dipende dalle funzionalità "on-by-default" della dipendenza. Il valore predefinito è true.

Nella maggior parte dei casi, questa deve essere definita in false e tutte le funzionalità necessarie devono essere dipendenti in modo esplicito.

Dipendenza:`"features"`

Elenco di funzionalità aggiuntive da richiedere. Matrice di oggetti Feature. Facoltativo.

Un oggetto Feature è un oggetto con i campi seguenti:

name - Nome della funzionalità. Stringa . Obbligatorio.
platform- Espressione piattaforma che limita le piattaforme in cui è necessaria la funzionalità. Facoltativo.

Una stringa semplice è anche un equivalente valido Feature Object a { "name": "<feature-name>" }.

ad esempio:

{
  "name": "ffmpeg",
  "default-features": false,
  "features": [
    "mp3lame",
    {
      "name": "avisynthplus",
      "platform": "windows"
    }  
  ]
}

Usa la libreria con supporto per la ffmpeg codifica mp3. Solo in Windows, avisynthplus il supporto è abilitato.

Dipendenza:`"host"`

Valore booleano che indica che la dipendenza deve essere compilata per il tripletto host anziché per il tripletto della porta corrente. Il valore predefinito è false.

Qualsiasi dipendenza che fornisce strumenti o script che devono essere "eseguiti" durante una compilazione (ad esempio buildsystems, generatori di codice o helper) deve essere contrassegnato come "host": true. Ciò consente la compilazione incrociata corretta nei casi in cui la destinazione non è eseguibile, ad esempio durante la compilazione per arm64-android.

Per altre informazioni, vedere Dipendenze host.

Dipendenza:`"name"`

Nome della dipendenza. Stringa . Obbligatorio.

Ciò segue le stesse restrizioni della "name" proprietà per un progetto.

Dipendenza:`"platform"`

Espressione che limita le piattaforme in cui è necessaria la dipendenza. Espressione di piattaforma. Facoltativo.

Se l'espressione non corrisponde alla configurazione corrente, la dipendenza non verrà usata. Ad esempio, se una dipendenza ha "platform": "!windows", è necessario solo quando è destinata a sistemi non Windows.

Dipendenza:`"version>="`

Vincolo di versione minima per la dipendenza.

Questo campo specifica la versione minima della dipendenza, facoltativamente usando un #N suffisso per specificare anche una versione minima della porta, se necessario.

Per altre informazioni sulla semantica del controllo delle versioni, vedere Controllo delle versioni.

Campi delle funzionalità

Ogni funzionalità è un oggetto con i campi seguenti:

Nome	Obbligatorio	Type	Descrizione
description	Sì	string	Descrizione della funzionalità
dependencies	No	Dipendenza[]	Elenco di dipendenze
Supporta	No	Espressione piattaforma	Qualificatore per le piattaforme e le configurazioni supportate dalla funzionalità
license	No	stringa o null	Espressione di licenza SPDX

Per una panoramica concettuale delle funzionalità, vedere la documentazione relativa alla modalità manifesto.

Porta di esempio con funzionalità

{
  "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"
      ]
    }
  }
}

Funzionalità: `"dependencies"`

Elenco delle dipendenze richieste dalla funzionalità. Matrice di oggetti Dependency. Facoltativo.

Questo campo elenca eventuali dipendenze aggiuntive necessarie per compilare e usare la funzionalità.

Funzionalità: `"description"`

Descrizione della funzionalità. Stringa o matrice di stringhe. Obbligatorio.

Viene usato per consentire agli utenti di individuare la funzionalità come parte di un search comando o find e di apprendere le operazioni che la funzionalità esegue.

Funzionalità: `"supports"`

La piattaforma supportata e le configurazioni di compilazione per la funzionalità. Espressione di piattaforma. Facoltativo.

Questo campo documenta le configurazioni della piattaforma in cui la funzionalità verrà compilata ed eseguita correttamente.

Funzionalità: `"license"`

Espressione di licenza breve SPDX della funzionalità. Stringa o null. Facoltativo. Se non viene specificato, la licenza è uguale a quella specificata nel campo della licenza di primo livello.

Nota

Espressione piattaforma

Un'espressione platform è una stringa JSON che descrive quando è necessaria una dipendenza o quando è prevista la compilazione di una libreria o di una funzionalità.

Le espressioni vengono compilate da identificatori primitivi, operatori logici e raggruppamento:

!<expr>, - not <expr> negazione
<expr>|<expr>, <expr>,<expr> - OR logico (la parola chiave or è riservata ma non valida nelle espressioni della piattaforma)
<expr>&<expr>, - <expr> and <expr> AND logico
(<expr>) - raggruppamento/precedenza

Gli identificatori seguenti vengono definiti in base alle impostazioni triplet e alla configurazione della compilazione:

Identifier	Triplet Condition
`x64`	`VCPKG_TARGET_ARCHITECTURE` == `"x64"`
`x86`	`VCPKG_TARGET_ARCHITECTURE` == `"x86"`
`arm`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"` o `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` == `""`o o `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` == `""` e `XBOX_CONSOLE_TARGET` viene definito.
`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`

Espressione di piattaforma di esempio

È necessario picosha2 per sha256 in non Windows, ma ottenerlo dal sistema operativo in Windows (BCrypt)

{
  "name": "picosha2",
  "platform": "!windows"
}

Richiedere zlib in arm64 Windows e amd64 Linux

{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}

Condividi tramite

Informazioni di riferimento su vcpkg.json

Esempio

Campi di primo livello

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

Dipendenze delle porte di esempio

`"documentation"`

`"features"`

`"homepage"`

`"license"`

Stringhe di licenza di esempio

EBNF

`"maintainers"`

`"name"`

`"overrides"`

Esempio di override della versione

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Esempio incorporato `vcpkg-configuration`

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

Campi di dipendenza

Dipendenza:`"default-features"`

Dipendenza:`"features"`

Dipendenza:`"host"`

Dipendenza:`"name"`

Dipendenza:`"platform"`

Dipendenza:`"version>="`

Campi delle funzionalità

Porta di esempio con funzionalità

Funzionalità: `"dependencies"`

Funzionalità: `"description"`

Funzionalità: `"supports"`

Funzionalità: `"license"`

Espressione piattaforma

Espressione di piattaforma di esempio

Risorse aggiuntive

Condividi tramite

Informazioni di riferimento su vcpkg.json

Esempio

Campi di primo livello

"builtin-baseline"

"default-features"

"description"

"dependencies"

Dipendenze delle porte di esempio

"documentation"

"features"

"homepage"

"license"

Stringhe di licenza di esempio

EBNF

"maintainers"

"name"

"overrides"

Esempio di override della versione

"port-version"

"supports"

"vcpkg-configuration"

Esempio incorporato vcpkg-configuration

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

Campi di dipendenza

Dipendenza:"default-features"

Dipendenza:"features"

Dipendenza:"host"

Dipendenza:"name"

Dipendenza:"platform"

Dipendenza:"version>="

Campi delle funzionalità

Porta di esempio con funzionalità

Funzionalità: "dependencies"

Funzionalità: "description"

Funzionalità: "supports"

Funzionalità: "license"

Espressione piattaforma

Espressione di piattaforma di esempio

Risorse aggiuntive

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

`"documentation"`

`"features"`

`"homepage"`

`"license"`

`"maintainers"`

`"name"`

`"overrides"`

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Esempio incorporato `vcpkg-configuration`

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

Dipendenza:`"default-features"`

Dipendenza:`"features"`

Dipendenza:`"host"`

Dipendenza:`"name"`

Dipendenza:`"platform"`

Dipendenza:`"version>="`

Funzionalità: `"dependencies"`

Funzionalità: `"description"`

Funzionalità: `"supports"`

Funzionalità: `"license"`