vcpkg.json-referentie

Zie de manifestmodus voor een overzicht van het gebruik van manifesten met vcpkg.

Manifesten zijn strikte JSON-documenten . Ze kunnen geen C++-stijlopmerkingen (//) of volgkomma's bevatten. U kunt echter veldnamen gebruiken die beginnen met $ het schrijven van uw opmerkingen in elk object met een goed gedefinieerde set sleutels. Deze opmerkingvelden zijn niet toegestaan in objecten die door de gebruiker gedefinieerde sleutels toestaan (zoals "features").

Het nieuwste JSON-schema is beschikbaar op https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. IDE's met ondersteuning voor JSON-schema's, zoals Visual Studio en Visual Studio Code, kunnen dit bestand gebruiken om automatisch aanvullen en syntaxiscontrole te bieden. Voor de meeste IDE's moet u deze vcpkg.json URL instellen"$schema".

Example

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

In dit voorbeeld ziet u een manifest voor een toepassing die gebruikmaakt van boost-system, cpprestsdken libxml2yajl. Het voorbeeld bevat ook een $schema verwijzing om betere IDE-validatie en automatische aanvulling mogelijk te maken.

Velden op het hoogste niveau

"builtin-baseline"

Een snelkoppeling voor het opgeven van de "baseline" voor versieomzetting in het standaardregister. Een tekenreeks. Optioneel, alleen gebruikt door projecten op het hoogste niveau.

Dit veld geeft aan dat de doorvoering https://github.com/microsoft/vcpkg globale minimale versie-informatie voor uw manifest biedt. Het is vereist voor manifestbestanden op het hoogste niveau met versiebeheer zonder een opgegeven "default-registry". Het heeft dezelfde semantische als het definiëren van uw standaardregister:

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

Zie versiebeheer en registers gebruiken voor meer semantische details.

"default-features"

De set functies die nodig zijn voor redelijk gedrag zonder extra aanpassingen.

De standaardfuncties worden automatisch geselecteerd als een van de volgende opties:

1. Een poort-naar-poort-afhankelijkheid voor de poort heeft "default-features": true de standaardwaarde.
2. Het manifest op het hoogste niveau heeft geen afhankelijkheid voor de poort met "default-features": false.

Standaardfuncties verwerken het specifieke geval van het instellen van een standaardconfiguratie voor transitieve afhankelijkheden waarover het project op het hoogste niveau mogelijk niet weet. Poorten die door anderen worden gebruikt, moeten bijna altijd worden gebruikt "default-features": false voor hun afhankelijkheden.

U kunt platformspecifieke standaardfuncties definiëren met behulp van een functieobject:

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

Zie "features" voor meer informatie over functies.

"description"

De beschrijving van de poort. Een tekenreeks of matrix met tekenreeksen. Vereist voor bibliotheken, optioneel voor projecten op het hoogste niveau.

Dit wordt gebruikt om gebruikers te helpen de bibliotheek te ontdekken als onderdeel van een search of find opdracht en te leren wat de bibliotheek doet.

"dependencies"

De lijst met afhankelijkheden die vereist zijn voor het project. Een matrix van afhankelijkheidsobjecten. Optional.

Dit veld bevat alle afhankelijkheden die nodig zijn om uw bibliotheek of toepassing te bouwen en te gebruiken.

Voorbeeld van poortafhankelijkheden

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

"documentation"

De URI naar de documentatie van het upstream-project. Een tekenreeks. Optional.

"features"

De functies die beschikbaar zijn voor gebruikers van het project. Een kaart met namen voor functieobjecten. Optional.

Functies zijn Booleaanse vlaggen die extra gedrag en afhankelijkheden toevoegen aan een build. Zie de manifestconceptdocumentatie voor meer informatie over functies.

"homepage"

De URI naar de startpagina van het project. Een tekenreeks. Optional.

"license"

De SPDX-korte licentie-expressie van het project. Een tekenreeks of null. Optional.

Het "license" moet een SPDX 3.19-licentieexpressie zijn of moet null aangeven dat gebruikers het geïmplementeerde /share/<port>/copyright bestand moeten lezen. DocumentRefs wordt niet ondersteund.

Voorbeeld van licentiereeksen

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

EBNF

vcpkg gebruikt het volgende EBNF om het licentieveld te parseren:

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"

De lijst met pakketonderhouders. Een tekenreeks of matrix met tekenreeksen. Optional.

U wordt aangeraden het formulier 'E-mailadres>Voornaam achternaam<' te gebruiken.

"name"

De naam van het project. Een tekenreeks. Vereist voor bibliotheken, optioneel voor projecten op het hoogste niveau.

De naam moet kleine letters, cijfers of afbreekstreepjes (-) zijn. Het mag niet beginnen of eindigen met een afbreekstreepje. Bibliotheken worden aangemoedigd om hun organisatie- of frameworknaam op te nemen als voorvoegsel, zoals msft- of boost- om gebruikers te helpen gekoppelde bibliotheken te vinden en te beschrijven.

Een bibliotheek met een officiële naam kan Boost.Asio bijvoorbeeld de naam boost-asiokrijgen.

"overrides"

Exacte versiepinnen die moeten worden gebruikt voor specifieke afhankelijkheden. Een matrix van onderdrukkingsobjecten. Optional.

"overrides" van transitieve manifesten (d.w.w.v. afhankelijkheden) worden genegeerd. Alleen onderdrukkingen die zijn gedefinieerd door het project op het hoogste niveau, worden gebruikt.

"port-version" moet worden opgegeven als achtervoegsel #N in "version". Namen van versie "version": "1.2.3#7" 1.2.3, poortversie 7.

Zie ook versiebeheer voor meer semantische details.

Voorbeeld van versie-onderdrukkingen

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

"port-version"

Een versieachtervoegsel dat revisies onderscheidt van de verpakkingsbestanden. Een geheel getal. Standaardwaarde is 0.

De "port-version" waarde moet worden verhoogd wanneer een nieuwe versie van de poort wordt gepubliceerd die de upstream-bronversie niet wijzigt. Wanneer de upstream-bronversie wordt gewijzigd, moet het versieveld worden gewijzigd en moet het "port-version" opnieuw worden ingesteld 0 op (of verwijderd).

Zie versiebeheer voor meer informatie.

"supports"

Ondersteunde platform- en buildconfiguraties. Een platformexpressie. Optional.

Dit veld documenteert dat een project naar verwachting niet met succes wordt gebouwd of uitgevoerd op bepaalde platformconfiguraties.

Als uw bibliotheek bijvoorbeeld geen ondersteuning biedt voor bouwen voor Linux, gebruikt "supports": "!linux"u .

"configuration"

Hiermee kunnen vcpkg-configuratie-eigenschappen in het vcpkg.json bestand worden ingesloten. Alles in de configuration eigenschap wordt behandeld alsof deze in een vcpkg-configuration.json bestand is gedefinieerd. Zie de vcpkg-configuration.json documentatie voor meer informatie.

vcpkg-configuration is een oudere spelling van dit veld, maar is anders identiek.

Als u een configurationvcpkg-configuration.json of vcpkg-configuration meer bestanden hebt gedefinieerdvcpkg.json, is het niet toegestaan en resulteert dit in het beëindigen van de vcpkg-opdracht met een foutbericht.

Voorbeeld van ingesloten configuration

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
        "repository": "https://github.com/MicrosoftDocs/vcpkg-docs",
        "reference": "vcpkg-registry",
        "packages": [ "beicode", "beison" ]
      }
    ],
    "overlay-ports": [ "./my-ports/fmt", 
                       "./team-ports"
    ]
  }

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

De versie van het upstream-project. Een tekenreeks. Vereist voor bibliotheken, optioneel voor projecten op het hoogste niveau.

Een manifest moet maximaal één versieveld bevatten. Elk versieveld komt overeen met een ander versiebeheerschema:

• "version" - Ontspannen Semantische versie 2.0.0, waardoor meer of minder dan 3 primaire nummers zijn toegestaan. Voorbeeld: 1.2.3.4.10-alpha1
• "version-semver" - Strikte Semantische versie 2.0.0. Voorbeeld: 2.0.1-rc5
• "version-date" - Een datum die is opgemaakt als YYYY-MM-DD met een optionele volgpunt-afzonderlijke numerieke reeks. Wordt gebruikt voor pakketten die geen numerieke releases hebben (bijvoorbeeld Live-at-HEAD). Voorbeeld: 2022-12-09.314562
• "version-string" - Een willekeurige tekenreeks. Wordt gebruikt voor pakketten die geen bestelbare versies hebben. Dit moet zelden worden gebruikt, maar alle poorten die zijn gemaakt voordat de andere versievelden werden geïntroduceerd, gebruiken dit schema.

Zie versiebeheer voor meer informatie.

Afhankelijkheidsvelden

Elke afhankelijkheid is een tekenreeks of een object met de volgende velden:

Tekenreeksen worden geïnterpreteerd als een object met de naam die is gedefinieerd voor de tekenreekswaarde.

Afhankelijkheid: "default-features"

Een Booleaanse waarde die aangeeft dat het project afhankelijk is van de 'on-by-default'-functies van de afhankelijkheid. Standaardwaarde is true.

In de meeste gevallen moet dit worden gedefinieerd en false moeten eventuele benodigde functies expliciet worden bepaald.

Afhankelijkheid: "features"

De lijst met aanvullende functies die u moet vereisen. Een matrix met functieobjecten. Optional.

Een functieobject is een object met de volgende velden:

• name - De naam van de functie. Een tekenreeks. Verplicht.
• platform - Een platformexpressie die de platformen beperkt waarvoor de functie is vereist. Optional.

Een eenvoudige tekenreeks is ook een geldig Feature Object equivalent van { "name": "<feature-name>" }.

Bijvoorbeeld

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

Maakt gebruik van de ffmpeg bibliotheek met mp3-coderingsondersteuning. Alleen in Windows avisynthplus is ondersteuning ook ingeschakeld.

Afhankelijkheid: "host"

Een Booleaanse waarde die aangeeft dat de afhankelijkheid moet worden gebouwd voor de host triplet in plaats van de triplet van de huidige poort. Standaardwaarde is false.

Afhankelijkheid die hulpprogramma's of scripts biedt die 'moeten worden uitgevoerd' tijdens een build (zoals buildsystems, codegeneratoren of helpers) moeten worden gemarkeerd als "host": true. Dit maakt een juiste kruiscompilatie mogelijk in gevallen dat het doel niet uitvoerbaar is, zoals bij het compileren voor arm64-android.

Zie Hostafhankelijkheden voor meer informatie.

Afhankelijkheid: "name"

De naam van de afhankelijkheid. Een tekenreeks. Verplicht.

Dit volgt dezelfde beperkingen als de "name" eigenschap voor een project.

Afhankelijkheid: "platform"

Een expressie die de platforms beperkt waarvoor de afhankelijkheid is vereist. Een platformexpressie. Optional.

Als de expressie niet overeenkomt met de huidige configuratie, wordt de afhankelijkheid niet gebruikt. Als een afhankelijkheid bijvoorbeeld is, "platform": "!windows"is deze alleen vereist bij het instellen van niet-Windows-systemen.

Afhankelijkheid: "version>="

Een minimale versiebeperking voor de afhankelijkheid.

In dit veld wordt de minimale versie van de afhankelijkheid opgegeven, eventueel met behulp van een #N achtervoegsel om desgewenst ook een minimale poortversie op te geven.

Zie Versiebeheer voor meer informatie over versiebeheersemantiek.

Functievelden

Elke functie is een object met de volgende velden:

Bekijk de documentatie over de manifestmodus voor een conceptueel overzicht van functies.

Voorbeeldpoort met functies

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

Functie: "dependencies"

De lijst met afhankelijkheden die vereist zijn voor de functie. Een matrix van afhankelijkheidsobjecten. Optional.

Dit veld bevat eventuele extra afhankelijkheden die nodig zijn om de functie te bouwen en te gebruiken.

Functie: "description"

De beschrijving van de functie. Een tekenreeks of matrix met tekenreeksen. Verplicht.

Dit wordt gebruikt om gebruikers te helpen de functie te ontdekken als onderdeel van een search of find opdracht en te leren wat de functie doet.

Functie: "supports"

Het ondersteunde platform en de buildconfiguraties voor de functie. Een platformexpressie. Optional.

Dit veld documenteert de platformconfiguraties waar de functie wordt gebouwd en uitgevoerd.

Functie: "license"

De SPDX-korte licentie-expressie van de functie. Een tekenreeks of null. Optional. Als deze niet is opgegeven, is de licentie hetzelfde als die is opgegeven in het veld Licentie op het hoogste niveau.

Platformexpressie

Een platformexpressie is een JSON-tekenreeks die beschrijft wanneer een afhankelijkheid vereist is of wanneer een bibliotheek of functie naar verwachting wordt gebouwd.

Expressies zijn gebouwd op basis van primitieve id's, logische operators en groepering:

• !<expr>, not <expr> - negatie
• <expr>|<expr>, <expr>,<expr> - logische OR (het trefwoord or is gereserveerd, maar niet geldig in platformexpressies)
• <expr>&<expr>, <expr> and <expr> - logische AND
• (<expr>) - groepering/prioriteit

De volgende id's worden gedefinieerd op basis van de drievoudige instellingen en de buildconfiguratie:

Voorbeeld van platformexpressie

• Vereist picosha2 voor sha256 op niet-Windows, maar haal het uit het besturingssysteem op Windows (BCrypt)

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

• Zlib vereisen in arm64 Windows en amd64 Linux

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