Freigeben über

vcpkg.json Referenz

  • Artikel

Eine Übersicht über die Verwendung von Manifesten mit vcpkg finden Sie im Manifestmodus.

Manifeste sind strenge JSON-Dokumente . Sie können keine C++-Formatkommentare (//) oder nachfolgende Kommas enthalten. Sie können jedoch Feldnamen verwenden, die mit $ dem Schreiben Ihrer Kommentare in jedem Objekt beginnen, das über einen gut definierten Satz von Schlüsseln verfügt. Diese Kommentarfelder sind in Objekten, die benutzerdefinierte Schlüssel zulassen (z "features". B. ) nicht zulässig.

Das neueste JSON-Schema ist unter https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. IDEs mit JSON-Schemaunterstützung wie Visual Studio und Visual Studio Code können diese Datei verwenden, um autoVervollständigen und Syntaxüberprüfung bereitzustellen. Für die meisten IDEs sollten Sie in Ihrer vcpkg.json URL festlegen"$schema".

Beispiel

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

In diesem Beispiel wird ein Manifest für eine Anwendung mit boost-system, , cpprestsdk, libxml2und yajl. Das Beispiel enthält auch einen Verweis, um eine $schema bessere IDE-Überprüfung und AutoVervollständigen zu ermöglichen.

Felder auf oberster Ebene

Name Erforderlich Type Beschreibung
builtin-baseline No Zeichenfolge Versions-Pins, die beim Erstellen als oberste Ebene verwendet werden sollen
Standardfeatures No Feature-Objekt[] Festlegen der standardmäßig aufgeführten Features
dependencies No Abhängigkeit[] Liste der zum Erstellen und Verwenden dieses Projekts erforderlichen Abhängigkeiten
Beschreibung Libraries Zeichenfolge oder Zeichenfolge[] Die Projektbeschreibung
Dokumentation No Zeichenfolge URI für die Dokumentation des Upstreamprojekts
features No {string: Feature} Optionale Features , die für Benutzer des Projekts verfügbar sind
Homepage No Zeichenfolge URI zur Homepage des Upstreamprojekts
license No Zeichenfolge oder null SPDX-Lizenzausdruck
Maintainers No Zeichenfolge oder Zeichenfolge[] Betreuer der Paketdateien
name Bibliotheken Zeichenfolge Der Projektname
overrides No Außerkraftsetzen[] Versions-Pins, die beim Erstellen als oberste Ebene verwendet werden sollen
Portversion No integer Überarbeitung von Portdateien
unterstützt No Plattformausdruck Unterstützte Plattform- und Buildkonfigurationen
Version
version-semver
Versionsdatum
Version-Zeichenfolge		 Libraries Zeichenfolge Informationen zur Upstreamversion

"builtin-baseline"

Eine Verknüpfung zum Angeben der "baseline" Versionsauflösung in der Standardregistrierung. Eine Zeichenfolge. Optional, nur von Projekten der obersten Ebene verwendet.

Dieses Feld gibt den Commit an, von https://github.com/microsoft/vcpkg dem globale Mindestversionsinformationen für Ihr Manifest bereitgestellt werden. Sie ist für Manifestdateien auf oberster Ebene mit Versionsverwaltung ohne angabe erforderlich "default-registry". Sie hat dieselbe Semantik wie das Definieren der Standardregistrierung für Folgendes:

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

Weitere semantische Details finden Sie unter Versionsverwaltung und Verwenden von Registrierungen .

"default-features"

Der Satz von Features, die für ein angemessenes Verhalten ohne zusätzliche Anpassung erforderlich sind.

Die Standardfeatures werden automatisch ausgewählt, wenn eine der folgenden:

  1. Eine Port-zu-Port-Abhängigkeit für den Port weist "default-features": true den Standardwert auf.
  2. Das Manifest der obersten Ebene verfügt nicht über eine Abhängigkeit für den Port mit "default-features": false.

Standardfeatures behandeln den spezifischen Fall der Bereitstellung einer "Standardkonfiguration" für transitive Abhängigkeiten, die das Projekt auf oberster Ebene möglicherweise nicht kennt. Von anderen benutzern verwendete Ports sollten fast immer für ihre Abhängigkeiten verwendet "default-features": false werden.

Sie können plattformspezifische Standardfeatures mithilfe eines Featureobjekts definieren:

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

Weitere Informationen zu Features finden Sie unter.See "features" for more information about features.

"description"

Die Beschreibung des Ports. Eine Zeichenfolge oder ein Array von Zeichenfolgen. Erforderlich für Bibliotheken, optional für Projekte auf oberster Ebene.

Dies wird verwendet, um Benutzern zu helfen, die Bibliothek als Teil eines search Oder find Befehls zu entdecken und zu erfahren, was die Bibliothek tut.

"dependencies"

Die Liste der Abhängigkeiten, die für das Projekt erforderlich sind. Ein Array von Abhängigkeitsobjekten. Optional.

In diesem Feld werden alle Abhängigkeiten aufgelistet, die zum Erstellen und Verwenden Ihrer Bibliothek oder Anwendung erforderlich sind.

Beispiel für Portabhängigkeiten

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

"documentation"

Der URI für die Dokumentation des Upstreamprojekts. Eine Zeichenfolge. Optional.

"features"

Die Für Benutzer des Projekts verfügbaren Features . Eine Zuordnung von Namen zu Featureobjekten. Optional.

Features sind boolesche Flags, die einem Build zusätzliche Verhaltensweisen und Abhängigkeiten hinzufügen. Weitere Informationen zu Features finden Sie in der Manifestkonzeptdokumentation .

"homepage"

Der URI für die Startseite des Projekts. Eine Zeichenfolge. Optional.

"license"

Der SPDX-Kurzlizenzausdruck des Projekts. Eine Zeichenfolge oder null. Optional.

Dies "license" sollte entweder ein SPDX 3.19-Lizenzausdruck sein oder darauf null hinweisen, dass Benutzer die bereitgestellte /share/<port>/copyright Datei lesen müssen. DocumentRefs werden nicht unterstützt.

Hinweis

Die Lizenzierungsinformationen für jedes Paket in der vcpkg-Registrierung stellen das beste Verständnis der Lizenzierungsanforderungen von Microsoft dar. Diese Informationen dürfen jedoch nicht endgültig sein. Benutzern wird empfohlen, die genauen Lizenzierungsanforderungen für jedes Paket zu überprüfen, das sie verwenden möchten, da es letztendlich ihre Verantwortung ist, die Einhaltung der anwendbaren Lizenzen sicherzustellen.

Beispiel für Lizenzzeichenfolgen

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

EBNF

vcpkg verwendet das folgende EBNF , um das Lizenzfeld zu analysieren:

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"

Die Liste der Paketbetreuer. Eine Zeichenfolge oder ein Array von Zeichenfolgen. Optional.

Wir empfehlen die Verwendung des Formulars "Nachname E-Mail<".>

"name"

Der Name des Projekts. Eine Zeichenfolge. Erforderlich für Bibliotheken, optional für Projekte auf oberster Ebene.

Der Name muss kleingeschriebene ASCII-Buchstaben, Ziffern oder Bindestriche (-) sein. Er darf nicht mit einem Bindestrich beginnen oder enden. Bibliotheken werden empfohlen, ihren Organisations- oder Frameworknamen als Präfix einzuschließen, z msft- . B. oder boost- um Benutzern bei der Suche und Beschreibung zugeordneter Bibliotheken zu helfen.

Beispielsweise kann eine Bibliothek mit einem offiziellen Namen Boost.Asio den Namen boost-asioerhalten.

"overrides"

Genaue Versionsheftungen, die für bestimmte Abhängigkeiten verwendet werden sollen. Ein Array von Override-Objekten. Optional.

"overrides" von transitiven Manifesten (d. h. von Abhängigkeiten) werden ignoriert. Es werden nur Außerkraftsetzungen verwendet, die vom Projekt auf oberster Ebene definiert werden.

Name Erforderlich Type BESCHREIBUNG
name Ja Zeichenfolge Der Portname
Version Ja Zeichenfolge Informationen zur Upstreamversion zum Anheften.
version-semver
Versionsdatum
Version-Zeichenfolge		 Ja Zeichenfolge Veraltete Alternativen zum version Benennen bestimmter Schemas.
Portversion No integer Portieren sie die Überarbeitung der Dateien, um sie anzuheften. Veraltet, da sie in die Version selbst versetzt werden.

"port-version" sollte als #N Suffix in "version". Nennen Sie z. B "version": "1.2.3#7" . Version 1.2.3, Port-Version 7.

Weitere semantische Details finden Sie auch in der Versionsverwaltung .

Beispiel für Versionsüberschreibungen

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

"port-version"

Ein Versionssuffix, das Überarbeitungen von Paketdateien unterscheidet. Eine ganze Zahl Wird standardmäßig auf 0 festgelegt.

Dies "port-version" sollte immer dann erhöht werden, wenn eine neue Version des Ports veröffentlicht wird, die die Upstream-Quellversion nicht ändert. Wenn die Upstream-Quellversion geändert wird, sollte sich das Versionsfeld ändern und auf "port-version" (oder entfernt) werden 0 .

Weitere Informationen finden Sie unter Versionsverwaltung .

"supports"

Unterstützte Plattform- und Buildkonfigurationen. Ein Plattformausdruck. Optional.

Dieses Feld dokumentiert, dass ein Projekt nicht für bestimmte Plattformkonfigurationen erstellt oder erfolgreich ausgeführt wird.

Wenn Ihre Bibliothek beispielsweise das Erstellen für Linux nicht unterstützt, würden Sie dies verwenden "supports": "!linux".

"vcpkg-configuration"

Ermöglicht das Einbetten von vcpkg-Konfigurationseigenschaften in die vcpkg.json Datei. Alles innerhalb der vcpkg-configuration Eigenschaft wird so behandelt, als wäre es in einer vcpkg-configuration.json Datei definiert. Weitere Informationen finden Sie in der vcpkg-configuration.json Dokumentation.

Wenn Sie eine vcpkg-configuration Datei auch definiert vcpkg.json haben vcpkg-configuration.json , ist sie nicht zulässig und führt dazu, dass der vcpkg-Befehl mit einer Fehlermeldung beendet wird.

Eingebettetes Beispiel 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"

Die Version des Upstreamprojekts. Eine Zeichenfolge. Erforderlich für Bibliotheken, optional für Projekte auf oberster Ebene.

Ein Manifest muss höchstens ein Versionsfeld enthalten. Jedes Versionsfeld entspricht einem anderen Versionsverwaltungsschema:

  • "version" - Entspannter semantischer Version 2.0.0, der mehr oder weniger als 3 Primärnummern zulässt. Beispiel: 1.2.3.4.10-alpha1
  • "version-semver" - Strict Semantic Version 2.0.0. Beispiel: 2.0.1-rc5
  • "version-date" - Ein Datum, das mit YYYY-MM-DD einer optionalen nachgestellten punkttrennten numerischen Sequenz formatiert ist. Wird für Pakete verwendet, die keine numerischen Versionen haben (z. B. Live-at-HEAD). Beispiel: 2022-12-09.314562
  • "version-string" - Eine beliebige Zeichenfolge. Wird für Pakete verwendet, für die keine geordneten Versionen verfügbar sind. Dies sollte selten verwendet werden, aber alle Ports, die erstellt wurden, bevor die anderen Versionsfelder eingeführt wurden, verwenden dieses Schema.

Weitere Informationen finden Sie unter Versionsverwaltung .

Abhängigkeitsfelder

Jede Abhängigkeit ist eine Zeichenfolge oder ein Objekt mit den folgenden Feldern:

Name Erforderlich Type Beschreibung
Standardfeatures No bool Festlegen der standardmäßig aufgeführten Features
features No Feature-Objekt[] Die Liste der zusätzlichen Features, die erforderlich sind
host No bool Anfordern der Abhängigkeit für den Hostcomputer anstelle des Ziels
name Ja Zeichenfolge Der Name der Abhängigkeit
platform No Plattformausdruck Qualifizierer, für welche Plattformen die Abhängigkeit verwendet werden soll
version>= No Zeichenfolge Mindestens erforderliche Version. Die Portversion wird mit einem #N Suffix identifiziert, 1.2.3#7 z. B. mit namen port-version 7.

Zeichenfolgen werden als Objekt mit dem Namen interpretiert, der für den Zeichenfolgenwert definiert ist.

Abhängigkeit: "default-features"

Ein boolescher Wert, der angibt, dass das Projekt von den "standardmäßigen" Features der Abhängigkeit abhängt. Wird standardmäßig auf true festgelegt.

In den meisten Fällen sollte dies definiert false werden, und alle erforderlichen Features sollten explizit abhängig sein.

Abhängigkeit: "features"

Die Liste der erforderlichen zusätzlichen Features. Ein Array von Featureobjekten. Optional.

Ein Featureobjekt ist ein Objekt mit den folgenden Feldern:

  • name - Der Name des Features. Eine Zeichenfolge. Erforderlich.
  • platform – Ein Plattformausdruck , der die Plattformen beschränkt, auf denen das Feature erforderlich ist. Optional.

Eine einfache Zeichenfolge ist auch ein gültiges Feature Object Äquivalent zu { "name": "<feature-name>" }.

Beispiel:

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

Verwendet die ffmpeg Bibliothek mit mp3-Codierungsunterstützung. Nur avisynthplus unter Windows ist der Support ebenfalls aktiviert.

Abhängigkeit: "host"

Ein boolescher Wert, der angibt, dass die Abhängigkeit für das Host-Triplet anstelle des Triplets des aktuellen Ports erstellt werden muss. Wird standardmäßig auf false festgelegt.

Jede Abhängigkeit, die Tools oder Skripts bereitstellt, die während eines Builds (z. B. Buildsysteme, Codegeneratoren oder Hilfsprogramme) "ausgeführt" werden sollen, sollten als "host": truegekennzeichnet werden. Dies ermöglicht die korrekte Kompilierung in Fällen, in denen das Ziel nicht ausführbar ist – z. B. beim Kompilieren für arm64-android.

Weitere Informationen finden Sie unter Hostabhängigkeiten .

Abhängigkeit: "name"

Der Name der Abhängigkeit. Eine Zeichenfolge. Erforderlich.

Dies folgt den gleichen Einschränkungen wie die "name" Eigenschaft für ein Projekt.

Abhängigkeit: "platform"

Ein Ausdruck, der die Plattformen begrenzt, auf denen die Abhängigkeit erforderlich ist. Ein Plattformausdruck. Optional.

Wenn der Ausdruck nicht mit der aktuellen Konfiguration übereinstimmt, wird die Abhängigkeit nicht verwendet. Wenn z. B. eine Abhängigkeit vorhanden ist "platform": "!windows", ist dies nur erforderlich, wenn sie nicht auf Windows-Systeme ausgerichtet ist.

Abhängigkeit: "version>="

Eine Mindestversionseinschränkung für die Abhängigkeit.

Dieses Feld gibt die Mindestversion der Abhängigkeit an, optional mithilfe eines #N Suffixes, um bei Bedarf auch eine Mindestportversion anzugeben.

Weitere Informationen zur Versionsverwaltungssemantik finden Sie unter Versionsverwaltung.

Featurefelder

Jedes Feature ist ein Objekt mit den folgenden Feldern:

Name Erforderlich Type BESCHREIBUNG
Beschreibung Ja Zeichenfolge Die Beschreibung des Features
dependencies No Abhängigkeit[] Eine Liste der Abhängigkeiten
unterstützt No Plattformausdruck Qualifizierer, für welche Plattformen und Konfigurationen das Feature unterstützt
license No Zeichenfolge oder null SPDX-Lizenzausdruck

Sehen Sie sich die Dokumentation zum Manifestmodus an, um eine konzeptionelle Übersicht über Features zu finden.

Beispielport mit Features

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

Feature: "dependencies"

Die Liste der Abhängigkeiten, die für das Feature erforderlich sind. Ein Array von Abhängigkeitsobjekten. Optional.

In diesem Feld werden alle zusätzlichen Abhängigkeiten aufgelistet, die zum Erstellen und Verwenden des Features erforderlich sind.

Feature: "description"

Die Beschreibung des Features. Eine Zeichenfolge oder ein Array von Zeichenfolgen. Erforderlich.

Dies wird verwendet, um Benutzern zu helfen, das Feature als Teil eines search oder find Befehls zu entdecken und zu erfahren, was das Feature tut.

Feature: "supports"

Die unterstützten Plattform- und Buildkonfigurationen für das Feature. Ein Plattformausdruck. Optional.

Dieses Feld dokumentiert die Plattformkonfigurationen, in denen das Feature erfolgreich erstellt und ausgeführt wird.

Feature: "license"

Der SPDX-Kurzlizenzausdruck des Features. Eine Zeichenfolge oder null. Optional. Wenn nicht angegeben, ist die Lizenz identisch mit dem im Feld "Lizenz auf oberster Ebene" angegeben.

Hinweis

Die Lizenzierungsinformationen für jedes Paket in der vcpkg-Registrierung stellen das beste Verständnis der Lizenzierungsanforderungen von Microsoft dar. Diese Informationen dürfen jedoch nicht endgültig sein. Benutzern wird empfohlen, die genauen Lizenzierungsanforderungen für jedes Paket zu überprüfen, das sie verwenden möchten, da es letztendlich ihre Verantwortung ist, die Einhaltung der anwendbaren Lizenzen sicherzustellen.

Plattformausdruck

Ein Plattformausdruck ist eine JSON-Zeichenfolge, die beschreibt, wann eine Abhängigkeit erforderlich ist oder wann eine Bibliothek oder ein Feature erstellt werden soll.

Ausdrücke basieren auf primitiven Bezeichnern, logischen Operatoren und Gruppierung:

  • !<expr>, not <expr> - Negation
  • <expr>|<expr>, <expr>,<expr> - logischeS ODER (das Schlüsselwort or ist reserviert, aber in Plattformausdrücken nicht gültig)
  • <expr>&<expr>, - <expr> and <expr> logischeS UND
  • (<expr>) - Gruppierung/Rangfolge

Die folgenden Bezeichner werden basierend auf den Tripleteinstellungen und der Buildkonfiguration definiert:

Identifier Dreifache Bedingung
x64 VCPKG_TARGET_ARCHITECTURE == "x64"
x86 VCPKG_TARGET_ARCHITECTURE == "x86"
arm VCPKG_TARGET_ARCHITECTURE == "arm" oder
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 == ""oder
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 == "" und
XBOX_CONSOLE_TARGET wird definiert.
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

Beispiel für einen Plattformausdruck

  • Bedarf picosha2 für Sha256 unter Nicht-Windows, aber holen Sie es vom Betriebssystem unter Windows (BCrypt)
{
  "name": "picosha2",
  "platform": "!windows"
}
  • Erfordern einer Zlib auf arm64 Windows und amd64 Linux
{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}