informations de référence sur vcpkg.json

Article
03/01/2024

Pour obtenir une vue d’ensemble de l’utilisation de manifestes avec vcpkg, consultez le mode manifeste.

Les manifestes sont des documents JSON stricts. Ils ne peuvent pas contenir de commentaires de style C++(//) ni de virgules de fin. Toutefois, vous pouvez utiliser des noms de champs qui commencent $ par écrire vos commentaires dans n’importe quel objet qui a un ensemble de clés bien défini. Ces champs de commentaire ne sont pas autorisés dans les objets qui autorisent les clés définies par l’utilisateur (par "features"exemple).

Le dernier schéma JSON est disponible à l’adresse https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. Les IDEs avec prise en charge du schéma JSON, telles que Visual Studio et Visual Studio Code, peuvent utiliser ce fichier pour fournir la saisie semi-automatique et la syntaxe case activée ing. Pour la plupart des IDE, vous devez définir "$schema" dans votre vcpkg.json URL.

Exemple

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

Cet exemple illustre un manifeste pour une application à l’aide boost-systemde , cpprestsdk, libxml2et yajl. L’exemple inclut également une $schema référence pour améliorer la validation et la saisie automatique de l’IDE.

Champs de niveau supérieur

Nom	Requise	Type	Description
base de référence intégrée	Non	string	Épingles de version à utiliser lors de la génération en tant que niveau supérieur
fonctionnalités par défaut	Non	Feature, objet[]	Exiger les fonctionnalités répertoriées comme activées par défaut
dependencies	Non	Dépendance[]	Liste des dépendances requises pour générer et utiliser ce projet
description	Bibliothèques	chaîne ou chaîne[]	Description du projet
documentation	Non	string	URI de la documentation du projet amont
features	Non	{string : Fonctionnalité}	Fonctionnalités facultatives disponibles pour les utilisateurs du projet
Page d’accueil	Non	string	URI vers la page d’accueil du projet amont
licence	Non	chaîne ou null	Expression de licence SPDX
Maintainers	Non	chaîne ou chaîne[]	Mainteneurs des fichiers de package
name	Bibliothèques	string	Nom du projet
remplace	Non	Remplacer[]	Épingles de version à utiliser lors de la génération en tant que niveau supérieur
version du port	Non	entier	Révision des fichiers de port
Soutient	Non	Expression de plateforme	Configurations de plateforme et de build prises en charge
version version-semver date de version version-string	Bibliothèques	string	Informations sur la version en amont

`"builtin-baseline"`

Raccourci permettant de spécifier la "baseline" résolution de version dans le Registre par défaut. Chaîne. Facultatif, utilisé uniquement par les projets de niveau supérieur.

Ce champ indique la validation qui https://github.com/microsoft/vcpkg fournit des informations de version minimale globales pour votre manifeste. Il est nécessaire pour les fichiers manifestes de niveau supérieur à l’aide du contrôle de version sans spécification."default-registry" Il a la même sémantique que la définition de votre registre par défaut comme suit :

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

Pour plus d’informations sémantiques, consultez gestion des versions et utilisation des registres.

`"default-features"`

Ensemble de fonctionnalités nécessaires pour un comportement raisonnable sans personnalisation supplémentaire.

Les fonctionnalités par défaut sont automatiquement sélectionnées si :

Une dépendance de port à port pour le port a "default-features": true la valeur par défaut.
Le manifeste de niveau supérieur n’a pas de dépendance pour le port avec "default-features": false.

Les fonctionnalités par défaut gèrent le cas spécifique de fournir une configuration « par défaut » pour les dépendances transitives que le projet de niveau supérieur peut ne pas connaître. Les ports utilisés par d’autres utilisateurs doivent presque toujours être utilisés "default-features": false pour leurs dépendances.

Vous pouvez définir des fonctionnalités par défaut spécifiques à la plateforme à l’aide d’un objet de fonctionnalité :

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

Pour plus d’informations sur les fonctionnalités, consultez "features" cette rubrique.

`"description"`

Description du port. Chaîne ou tableau de chaînes. Obligatoire pour les bibliothèques, facultatif pour les projets de niveau supérieur.

Cela permet aux utilisateurs de découvrir la bibliothèque dans le cadre d’une ou find d’une search commande et d’apprendre ce que fait la bibliothèque.

`"dependencies"`

Liste des dépendances requises par le projet. Tableau d’objets De dépendance. facultatif.

Ce champ répertorie toutes les dépendances nécessaires pour générer et utiliser votre bibliothèque ou votre application.

Exemples de dépendances de port

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

`"documentation"`

URI de la documentation du projet amont. Chaîne. facultatif.

`"features"`

Fonctionnalités disponibles pour les utilisateurs du projet. Mappage de noms aux objets Feature. facultatif.

Les fonctionnalités sont des indicateurs booléens qui ajoutent des comportements et des dépendances supplémentaires à une build. Pour plus d’informations sur les fonctionnalités, consultez la documentation sur le concept de manifeste.

`"homepage"`

URI de la page d’accueil du projet. Chaîne. facultatif.

`"license"`

Expression de licence courte SPDX du projet. Chaîne ou null. facultatif.

Il "license" doit s’agir d’une expression de licence SPDX 3.19 ou d’indiquer null que les utilisateurs doivent lire le fichier déployé /share/<port>/copyright . DocumentRefs n’est pas pris en charge.

Exemples de chaînes de licence

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

EBNF

vcpkg utilise l’EBNF suivant pour analyser le champ de licence :

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

Liste des maintenances de package. Chaîne ou tableau de chaînes. facultatif.

Nous vous recommandons d’utiliser le formulaire « Nom de famille<donnée-mail ».>

`"name"`

Nom du projet. Chaîne. Obligatoire pour les bibliothèques, facultatif pour les projets de niveau supérieur.

Le nom doit être des lettres ASCII minuscules, des chiffres ou des traits d’union (-). Il ne doit pas commencer ni se terminer par un trait d’union. Les bibliothèques sont encouragées à inclure leur nom d’organisation ou d’infrastructure comme préfixe, comme msft- ou boost- pour aider les utilisateurs à trouver et décrire les bibliothèques associées.

Par exemple, une bibliothèque portant un nom Boost.Asio officiel peut être donnée au nom boost-asio.

`"overrides"`

Épingles de version exactes à utiliser pour des dépendances spécifiques. Tableau d’objets Override. facultatif.

"overrides" des manifestes transitifs (c’est-à-dire des dépendances) sont ignorés. Seules les substitutions définies par le projet de niveau supérieur sont utilisées.

Nom	Requise	Type	Description
name	Oui	string	Nom du port
version	Oui	string	Informations de version en amont à épingler.
version-semver date de version version-string	Oui	string	Alternatives déconseillées à l’affectation de noms à `version` des schémas particuliers.
version du port	Non	entier	Révision des fichiers de port à épingler. Déconseillé en faveur d’être placé dans la version elle-même.

"port-version" doit être spécifié en tant que #N suffixe dans "version". Par exemple, "version": "1.2.3#7" les noms version 1.2.3, port-version 7.

Pour plus d’informations sur la sémantique, consultez également la gestion des versions.

Exemple de remplacements de version

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

`"port-version"`

Suffixe de version qui distingue les révisions des fichiers d’empaquetage. Entier. La valeur par défaut est 0.

Il "port-version" doit être incrémenté chaque fois qu’une nouvelle version du port est publiée qui ne modifie pas la version source amont. Lorsque la amont version source est modifiée, le champ de version doit changer et le "port-version" champ doit être réinitialisé (0ou supprimé).

Pour plus d’informations, consultez la gestion des versions.

`"supports"`

Configurations de plateforme et de génération prises en charge. Expression de plateforme. facultatif.

Ce champ indique qu’un projet n’est pas censé générer ou s’exécuter correctement sur certaines configurations de plateforme.

Par exemple, si votre bibliothèque ne prend pas en charge la génération pour Linux, vous devez utiliser "supports": "!linux".

`"vcpkg-configuration"`

Permet d’incorporer des propriétés de configuration vcpkg à l’intérieur du vcpkg.json fichier. Tout à l’intérieur de la vcpkg-configuration propriété est traité comme s’il était défini dans un vcpkg-configuration.json fichier. Pour plus d’informations, consultez la vcpkg-configuration.json documentation.

L’utilisation d’un vcpkg-configuration fichier défini vcpkg.json pendant qu’un vcpkg-configuration.json fichier n’est pas autorisé et entraîne la fin de la commande vcpkg avec un message d’erreur.

Exemple incorporé `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"`

Version du projet amont. Chaîne. Obligatoire pour les bibliothèques, facultatif pour les projets de niveau supérieur.

Un manifeste doit contenir au plus un champ de version. Chaque champ de version correspond à un schéma de contrôle de version différent :

"version" - Sémantique détendue version 2.0.0, autorisant plus ou moins de 3 nombres principaux. Exemple : 1.2.3.4.10-alpha1
"version-semver" - Sémantique stricte version 2.0.0. Exemple : 2.0.1-rc5
"version-date" - Date mise en forme comme YYYY-MM-DD avec une séquence numérique séparée par des points de fin facultative. Utilisé pour les packages qui n’ont pas de versions numériques (par exemple, Live-at-HEAD). Exemple : 2022-12-09.314562
"version-string" - Chaîne arbitraire. Utilisé pour les packages qui n’ont pas de versions triables. Cela doit être rarement utilisé, mais tous les ports créés avant que les autres champs de version n’aient été introduits utilisent ce schéma.

Pour plus d’informations, consultez la gestion des versions.

Champs de dépendance

Chaque dépendance est une chaîne ou un objet avec les champs suivants :

Nom	Requise	Type	Description
fonctionnalités par défaut	Non	bool	Exiger les fonctionnalités répertoriées comme activées par défaut
features	Non	Feature, objet[]	Liste des fonctionnalités supplémentaires à exiger
host	Non	bool	Exiger la dépendance pour l’ordinateur hôte au lieu de la cible
name	Oui	string	Nom de la dépendance
platform	Non	Expression de plateforme	Qualificateur pour quelles plateformes utiliser la dépendance
version>=	Non	string	Version minimale requise. La version de port est identifiée avec un `#N` suffixe, par exemple, `1.2.3#7` les noms port-version 7.

Les chaînes sont interprétées comme un objet portant le nom défini sur la valeur de chaîne.

Dépendance : `"default-features"`

Valeur booléenne indiquant que le projet dépend des fonctionnalités « on-by-default » de la dépendance. La valeur par défaut est true.

Dans la plupart des cas, cela doit être défini false et toutes les fonctionnalités nécessaires doivent être explicitement dépendantes.

Dépendance : `"features"`

Liste des fonctionnalités supplémentaires à exiger. Tableau d’objets Feature. facultatif.

Un objet Feature Object est un objet avec les champs suivants :

name - Nom de la fonctionnalité. Chaîne. Obligatoire.
platform- Expression de plateforme qui limite les plateformes où la fonctionnalité est requise. facultatif.

Une chaîne simple est également un équivalent valide Feature Object à { "name": "<feature-name>" }.

Par exemple,

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

Utilise la bibliothèque avec prise en charge de l’encodage ffmpeg mp3. Sur Windows uniquement, la avisynthplus prise en charge est également activée.

Dépendance : `"host"`

Valeur booléenne indiquant que la dépendance doit être générée pour le triplet hôte au lieu du triplet du port actuel. La valeur par défaut est false.

Toute dépendance qui fournit des outils ou des scripts qui doivent être « exécutés » pendant une build (par exemple, des générateurs de code, des générateurs de code ou des helpers) doit être marquée comme "host": true. Cela permet une compilation croisée correcte dans les cas où la cible n’est pas exécutable, par exemple lors de la compilation pour arm64-android.

Pour plus d’informations, consultez les dépendances de l’hôte.

Dépendance : `"name"`

Nom de la dépendance. Chaîne. Obligatoire.

Cela suit les mêmes restrictions que la "name" propriété d’un projet.

Dépendance : `"platform"`

Expression qui limite les plateformes où la dépendance est requise. Expression de plateforme. facultatif.

Si l’expression ne correspond pas à la configuration actuelle, la dépendance n’est pas utilisée. Par exemple, si une dépendance a "platform": "!windows", elle ne doit être requise que lorsque vous ciblez des systèmes non-Windows.

Dépendance : `"version>="`

Contrainte de version minimale sur la dépendance.

Ce champ spécifie la version minimale de la dépendance, éventuellement à l’aide d’un #N suffixe pour spécifier une version minimale du port si vous le souhaitez.

Pour plus d’informations sur la sémantique de contrôle de version, consultez Contrôle de version.

Champs de fonctionnalité

Chaque fonctionnalité est un objet avec les champs suivants :

Nom	Requise	Type	Description
description	Oui	string	Description de la fonctionnalité
dependencies	Non	Dépendance[]	Liste des dépendances
Soutient	Non	Expression de plateforme	Qualificateur pour quelles plateformes et configurations la fonctionnalité prend en charge
licence	Non	chaîne ou null	Expression de licence SPDX

Consultez la documentation du mode manifeste pour obtenir une vue d’ensemble conceptuelle des fonctionnalités.

Exemple de port avec des fonctionnalités

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

Fonctionnalité : `"dependencies"`

Liste des dépendances requises par la fonctionnalité. Tableau d’objets De dépendance. facultatif.

Ce champ répertorie les dépendances supplémentaires nécessaires à la génération et à l’utilisation de la fonctionnalité.

Fonctionnalité : `"description"`

Description de la fonctionnalité. Chaîne ou tableau de chaînes. Obligatoire.

Cela permet aux utilisateurs de découvrir la fonctionnalité dans le cadre d’une search ou find de commande et d’apprendre ce que fait la fonctionnalité.

Fonctionnalité : `"supports"`

La plateforme et les configurations de build prises en charge pour la fonctionnalité. Expression de plateforme. facultatif.

Ce champ documente les configurations de plateforme dans lesquelles la fonctionnalité va générer et s’exécuter correctement.

Fonctionnalité : `"license"`

Expression de licence courte SPDX de la fonctionnalité. Chaîne ou null. facultatif. Si elle n’est pas fournie, la licence est la même que celle spécifiée dans le champ de licence de niveau supérieur.

Expression de plateforme

Une expression de plateforme est une chaîne JSON qui décrit quand une dépendance est requise ou lorsqu’une bibliothèque ou une fonctionnalité est censée être générée.

Les expressions sont générées à partir d’identificateurs primitifs, d’opérateurs logiques et de regroupement :

!<expr>, - not <expr> négation
<expr>|<expr>, - <expr>||<expr><expr>,<expr> or logique (le mot clé or est réservé mais non valide dans les expressions de plateforme)
<expr>&<expr>, , <expr>&&<expr><expr> and <expr> - logique AND
(<expr>) - regroupement/précédence

Les identificateurs suivants sont définis en fonction des paramètres de triplet et de la configuration de build :

Identificateur	Triplet Condition
`x64`	`VCPKG_TARGET_ARCHITECTURE` == `"x64"`
`x86`	`VCPKG_TARGET_ARCHITECTURE` == `"x86"`
`arm`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"` ou `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`arm32`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"`
`arm64`	`VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`wasm32`	`VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
`windows`	`VCPKG_CMAKE_SYSTEM_NAME` == `""`ou ou `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` == `""` et `XBOX_CONSOLE_TARGET` est défini.
`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`

Exemple d’expression de plateforme

Besoins picosha2 pour sha256 sur non-Windows, mais obtenez-le à partir du système d’exploitation sur Windows (BCrypt)

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

Exiger zlib sur arm64 Windows et amd64 Linux

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

Partage via

informations de référence sur vcpkg.json

Exemple

Champs de niveau supérieur

"builtin-baseline"

"default-features"

"description"

"dependencies"

Exemples de dépendances de port

"documentation"

"features"

"homepage"

"license"

Exemples de chaînes de licence

EBNF

"maintainers"

"name"

"overrides"

Exemple de remplacements de version

"port-version"

"supports"

"vcpkg-configuration"

Exemple incorporé vcpkg-configuration

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