Informazioni di riferimento su vcpkg.json

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

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

1. Una dipendenza da porta a porta per la porta ha "default-features": true il valore predefinito.
2. 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.

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.

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

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:

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.

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:

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