Partager via


informations de référence sur vcpkg.json

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 ID 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 vérification de la syntaxe. 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 en 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 en amont
licence Non chaîne ou null Expression de licence SPDX
Maintainers Non chaîne ou chaîne[] Mainteneurs des fichiers de package
nom 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 :

  1. Une dépendance de port à port pour le port a "default-features": true la valeur par défaut.
  2. 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 en 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.

Remarque

Les informations de licence fournies pour chaque package du registre vcpkg représentent la meilleure compréhension des exigences de licence de Microsoft. Toutefois, ces informations peuvent ne pas être définitives. Les utilisateurs sont invités à vérifier les exigences de licence exactes pour chaque package qu’ils ont l’intention d’utiliser, car c’est finalement leur responsabilité de garantir la conformité aux licences applicables.

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 en amont. Lorsque la version source en amont est modifiée, le champ de version doit changer et le "port-version" champ doit être réinitialisé 0 (ou 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": "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"

Version du projet en 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
nom 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.

Remarque

Les informations de licence fournies pour chaque package du registre vcpkg représentent la meilleure compréhension des exigences de licence de Microsoft. Toutefois, ces informations peuvent ne pas être définitives. Les utilisateurs sont invités à vérifier les exigences de licence exactes pour chaque package qu’ils ont l’intention d’utiliser, car c’est finalement leur responsabilité de garantir la conformité aux licences applicables.

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> or logique (le mot clé or est réservé mais non valide dans les expressions de plateforme)
  • <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"
arm64ec VCPKG_TARGET_ARCHITECTURE == "arm64ec"
wasm32 VCPKG_TARGET_ARCHITECTURE == "wasm32"
mips64 VCPKG_TARGET_ARCHITECTURE == "mips64"
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"
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

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