Referencia de vcpkg.json

Artículo
07/22/2024

Para obtener información general sobre el uso de manifiestos con vcpkg, consulte Modo de manifiesto.

Los manifiestos son documentos JSON estrictos. No pueden contener comentarios de estilo C++(//) ni comas finales. Sin embargo, puede usar nombres de campo que empiecen por $ escribir sus comentarios en cualquier objeto que tenga un conjunto bien definido de claves. Estos campos de comentario no se permiten en ningún objeto que permita claves definidas por el usuario (como "features").

El esquema JSON más reciente está disponible en https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. Los IDE con compatibilidad con esquemas JSON, como Visual Studio y Visual Studio Code, pueden usar este archivo para proporcionar comprobación de sintaxis y autocompletar. Para la mayoría de los IDE, debe establecer "$schema" en vcpkg.json la dirección URL.

Ejemplo

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

En este ejemplo se muestra un manifiesto para una aplicación mediante boost-system, cpprestsdk, libxml2y yajl. En el ejemplo también se incluye una $schema referencia para habilitar una mejor validación del IDE y autocompletar.

Campos de nivel superior

Nombre	Obligatorio	Type	Descripción
builtin-baseline	No	string	Patillas de versión que se usarán al compilar como de nivel superior
características predeterminadas	No	Feature Object[]	Requerir las características enumeradas como activadas de forma predeterminada
dependencies	No	Dependencia[]	Lista de dependencias necesarias para compilar y usar este proyecto
descripción	Bibliotecas	string o string[]	Descripción del proyecto
documentación	No	string	URI a la documentación del proyecto ascendente
features	No	{string: Feature}	Características opcionales disponibles para los usuarios del proyecto
Página principal	No	string	URI a la página principal del proyecto ascendente
license	No	cadena o null	Expresión de licencia de SPDX
Mantenedores	No	string o string[]	Mantenedores de los archivos de paquete
name	Bibliotecas	string	El nombre del proyecto
invalida	No	Invalidación[]	Patillas de versión que se usarán al compilar como de nivel superior
port-version	No	integer	Revisión de archivos de puerto
Soporta	No	Expresión de plataforma	Configuraciones de compilación y plataforma admitidas
versión version-semver version-date version-string	Bibliotecas	string	Información de la versión ascendente

`"builtin-baseline"`

Acceso directo para especificar la "baseline" resolución de versiones en el registro predeterminado. Una cadena. Opcional, solo se usa en proyectos de nivel superior.

Este campo indica la confirmación de https://github.com/microsoft/vcpkg que proporciona información de versión mínima global para el manifiesto. Es necesario para los archivos de manifiesto de nivel superior mediante el control de versiones sin un especificado "default-registry". Tiene la misma semántica que definir el registro predeterminado para que sea:

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

Consulte Control de versiones y Uso de registros para obtener más detalles semánticos.

`"default-features"`

Conjunto de características necesarias para un comportamiento razonable sin personalización adicional.

Las características predeterminadas se seleccionan automáticamente si:

Una dependencia de puerto a puerto para el puerto tiene "default-features": true el valor predeterminado.
El manifiesto de nivel superior no tiene una dependencia para el puerto con "default-features": false.

Las características predeterminadas controlan el caso específico de proporcionar una configuración "predeterminada" para las dependencias transitivas que es posible que el proyecto de nivel superior no conozca. Los puertos usados por otros usuarios casi siempre deben usarse "default-features": false para sus dependencias.

Puede definir características predeterminadas específicas de la plataforma mediante un objeto feature:

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

Consulte "features" para obtener más información sobre las características.

`"description"`

Descripción del puerto. Cadena o matriz de cadenas. Necesario para las bibliotecas, opcional para proyectos de nivel superior.

Esto se usa para ayudar a los usuarios a detectar la biblioteca como parte de un search comando o find y aprender lo que hace la biblioteca.

`"dependencies"`

Lista de dependencias requeridas por el proyecto. Matriz de objetos Dependency. Opcional.

En este campo se enumeran todas las dependencias necesarias para compilar y usar la biblioteca o la aplicación.

Dependencias de puerto de ejemplo

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

`"documentation"`

Identificador URI de la documentación del proyecto ascendente. Una cadena. Opcional.

`"features"`

Las características disponibles para los usuarios del proyecto. Asignación de nombres a objetos Feature. Opcional.

Las características son marcas booleanas que agregan comportamientos y dependencias adicionales a una compilación. Consulte la documentación del concepto de manifiesto para obtener más información sobre las características.

`"homepage"`

Identificador URI de la página principal del proyecto. Una cadena. Opcional.

`"license"`

Expresión de licencia corta de SPDX del proyecto. Cadena o null. Opcional.

"license" debe ser una expresión de licencia SPDX 3.19 o debe ser null para indicar que los usuarios deben leer el archivo implementado/share/<port>/copyright. No se admiten DocumentRefs.

Nota:

La información de licencia proporcionada para cada paquete del registro vcpkg representa el mejor conocimiento de Microsoft de los requisitos de licencia. Sin embargo, esta información puede no ser definitiva. Se recomienda a los usuarios comprobar los requisitos exactos de licencia de cada paquete que pretenden usar, ya que en última instancia es su responsabilidad garantizar el cumplimiento de las licencias aplicables.

Cadenas de licencia de ejemplo

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

EBNF

vcpkg usa el siguiente EBNF para analizar el campo de licencia:

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

Lista de mantenedores de paquetes. Cadena o matriz de cadenas. Opcional.

Se recomienda usar el formulario "Givenname Surname<email>".

`"name"`

Nombre del proyecto. Una cadena. Necesario para las bibliotecas, opcional para proyectos de nivel superior.

El nombre debe ser letras ASCII minúsculas, dígitos o guiones (-). No debe comenzar ni terminar con un guión. Se recomienda que las bibliotecas incluyan su organización o nombre de marco como prefijo, como msft- o boost- para ayudar a los usuarios a encontrar y describir bibliotecas asociadas.

Por ejemplo, una biblioteca con un nombre oficial de Boost.Asio podría tener el nombre boost-asio.

`"overrides"`

Anclajes de versión exactos que se usarán para dependencias específicas. Matriz de objetos Override. Opcional.

"overrides" desde manifiestos transitivos (es decir, desde dependencias) se omiten. Solo se usan invalidaciones definidas por el proyecto de nivel superior.

Nombre	Obligatorio	Type	Descripción
name	Sí	string	El nombre del puerto
version	Sí	string	Información de versión ascendente que se va a anclar.
version-semver version-date version-string	Sí	string	Alternativas en desuso para asignar nombres a `version` esquemas concretos.
port-version	No	integer	Revisión de archivos de puerto para anclar. En desuso en favor de colocarse en la propia versión.

"port-version" debe especificarse como sufijo #N en "version". Por ejemplo, "version": "1.2.3#7" nombres versión 1.2.3, port-version 7.

Consulte también control de versiones para obtener más detalles semánticos.

Ejemplo de invalidaciones de versión

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

`"port-version"`

Un sufijo de versión que distingue las revisiones de los archivos de empaquetado. Entero. Tiene como valor predeterminado 0.

"port-version" Se debe incrementar cada vez que se publica una nueva versión del puerto que no cambia la versión de origen ascendente. Cuando se cambia la versión de origen ascendente, el campo de versión debe cambiar y "port-version" se debe restablecer a 0 (o quitar).

Consulte control de versiones para obtener más información.

`"supports"`

Configuraciones de compilación y plataforma admitidas. Expresión de plataforma. Opcional.

Este campo documenta que un proyecto no se espera que compile o ejecute correctamente en determinadas configuraciones de plataforma.

Por ejemplo, si la biblioteca no admite la compilación para Linux, usaría "supports": "!linux".

`"vcpkg-configuration"`

Permite insertar propiedades de configuración de vcpkg dentro del vcpkg.json archivo. Todo lo que hay dentro de la vcpkg-configuration propiedad se trata como si se definiese en un vcpkg-configuration.json archivo. Para obtener más información, consulte la vcpkg-configuration.json documentación.

Tener un vcpkg-configuration elemento definido en vcpkg.json mientras también tiene un vcpkg-configuration.json archivo no está permitido y dará como resultado que el comando vcpkg termine con un mensaje de error.

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

Versión del proyecto ascendente. Una cadena. Necesario para las bibliotecas, opcional para proyectos de nivel superior.

Un manifiesto debe contener como máximo un campo de versión. Cada campo de versión corresponde a un esquema de control de versiones diferente:

"version" - Semántica relajada versión 2.0.0, lo que permite más o menos de 3 números principales. Ejemplo: 1.2.3.4.10-alpha1
"version-semver" - Versión semántica estricta 2.0.0. Ejemplo: 2.0.1-rc5
"version-date" - Una fecha con formato como YYYY-MM-DD con una secuencia numérica de puntos finales opcional independiente. Se usa para paquetes que no tienen versiones numéricas (por ejemplo, Live-at-HEAD). Ejemplo: 2022-12-09.314562
"version-string" : una cadena arbitraria. Se usa para paquetes que no tienen versiones ordenables. Esto rara vez se debe usar, pero todos los puertos creados antes de que se introdujeran los demás campos de versión usen este esquema.

Consulte control de versiones para obtener más información.

Campos de dependencia

Cada dependencia es una cadena o un objeto con los siguientes campos:

Nombre	Obligatorio	Type	Descripción
características predeterminadas	No	bool	Requerir las características enumeradas como activadas de forma predeterminada
features	No	Feature Object[]	Lista de características adicionales que se van a requerir
host	No	bool	Requerir la dependencia para la máquina host en lugar del destino
name	Sí	string	Nombre de la dependencia
platform	No	Expresión de plataforma	Calificador para qué plataformas usar la dependencia
version>=	No	string	Versión mínima requerida. Port-version se identifica con un `#N` sufijo, por ejemplo, `1.2.3#7` nombres port-version 7.

Las cadenas se interpretan como un objeto con el nombre definido en el valor de cadena.

Dependencia:`"default-features"`

Valor booleano que indica que el proyecto depende de las características "on-by-default" de la dependencia. Tiene como valor predeterminado true.

En la mayoría de los casos, esto debe definirse en false y las características necesarias deben depender explícitamente.

Dependencia:`"features"`

Lista de características adicionales que se van a requerir. Matriz de objetos Feature. Opcional.

Un objeto Feature es un objeto con los siguientes campos:

name : el nombre de la característica. Una cadena. Necesario.
platform- Expresión de plataforma que limita las plataformas donde se requiere la característica. Opcional.

Una cadena simple también es un equivalente válido Feature Object a { "name": "<feature-name>" }.

Por ejemplo,

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

Usa la ffmpeg biblioteca con compatibilidad con la codificación mp3. Solo en Windows, avisynthplus la compatibilidad también está habilitada.

Dependencia:`"host"`

Valor booleano que indica que la dependencia debe compilarse para el host triplet en lugar del triplete del puerto actual. Tiene como valor predeterminado false.

Cualquier dependencia que proporcione herramientas o scripts que se deben "ejecutar" durante una compilación (como sistemas de compilación, generadores de código o asistentes) debe marcarse como "host": true. Esto habilita la compilación cruzada correcta en los casos en los que el destino no es ejecutable, como al compilar para arm64-android.

Consulte Dependencias de host para obtener más información.

Dependencia:`"name"`

Nombre de la dependencia. Una cadena. Necesario.

Esto sigue las mismas restricciones que la "name" propiedad de un proyecto.

Dependencia:`"platform"`

Expresión que limita las plataformas donde se requiere la dependencia. Expresión de plataforma. Opcional.

Si la expresión no coincide con la configuración actual, no se usará la dependencia. Por ejemplo, si una dependencia tiene "platform": "!windows", solo se requiere al dirigirse a sistemas que no son windows.

Dependencia:`"version>="`

Restricción de versión mínima en la dependencia.

Este campo especifica la versión mínima de la dependencia, opcionalmente mediante un #N sufijo para especificar también una versión de puerto mínima si lo desea.

Para obtener más información sobre la semántica de control de versiones, consulte Control de versiones.

Campos de características

Cada característica es un objeto con los siguientes campos:

Nombre	Obligatorio	Type	Descripción
descripción	Sí	string	Descripción de la característica
dependencies	No	Dependencia[]	Lista de dependencias
Soporta	No	Expresión de plataforma	Calificador para qué plataformas y configuraciones admite la característica
license	No	cadena o null	Expresión de licencia de SPDX

Consulte la documentación del modo manifiesto para obtener información general conceptual de las características.

Puerto de ejemplo con características

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

Característica: `"dependencies"`

Lista de dependencias requeridas por la característica. Matriz de objetos Dependency. Opcional.

En este campo se enumeran las dependencias adicionales necesarias para compilar y usar la característica.

Característica: `"description"`

Descripción de la característica. Cadena o matriz de cadenas. Necesario.

Esto se usa para ayudar a los usuarios a detectar la característica como parte de un search comando o find y aprender lo que hace la característica.

Característica: `"supports"`

Las configuraciones de compilación y plataforma admitidas para la característica. Expresión de plataforma. Opcional.

Este campo documenta las configuraciones de la plataforma donde la característica se compilará y ejecutará correctamente.

Característica: `"license"`

Expresión de licencia corta de SPDX de la característica. Cadena o null. Opcional. Si no se proporciona, la licencia es la misma que se especifica en el campo de licencia de nivel superior.

Nota:

Expresión de plataforma

Una expresión de plataforma es una cadena JSON que describe cuándo se requiere una dependencia o cuando se espera que se compile una biblioteca o característica.

Las expresiones se compilan a partir de identificadores primitivos, operadores lógicos y agrupación:

!<expr>, not <expr> - negación
<expr>|<expr>, <expr>,<expr> : OR lógico (la palabra clave or está reservada pero no es válida en expresiones de plataforma)
<expr>&<expr>, : <expr> and <expr> AND lógico
(<expr>) - agrupación/precedencia

Los identificadores siguientes se definen en función de la configuración de triplet y de la configuración de compilación:

Identificador	Condición triplet
`x64`	`VCPKG_TARGET_ARCHITECTURE` == `"x64"`
`x86`	`VCPKG_TARGET_ARCHITECTURE` == `"x86"`
`arm`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"` o `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` == `""`o o `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` == `""` y `XBOX_CONSOLE_TARGET` se define.
`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`

Expresión de plataforma de ejemplo

Necesita picosha2 sha256 en no Windows, pero obtenerlo del sistema operativo en Windows (BCrypt)

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

Requerir zlib en Arm64 Windows y amd64 Linux

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

Compartir a través de

Referencia de vcpkg.json

Ejemplo

Campos de nivel superior

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

Dependencias de puerto de ejemplo

`"documentation"`

`"features"`

`"homepage"`

`"license"`

Cadenas de licencia de ejemplo

EBNF

`"maintainers"`

`"name"`

`"overrides"`

Ejemplo de invalidaciones de versión

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Ejemplo incrustado `vcpkg-configuration`

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

Campos de dependencia

Dependencia:`"default-features"`

Dependencia:`"features"`

Dependencia:`"host"`

Dependencia:`"name"`

Dependencia:`"platform"`

Dependencia:`"version>="`

Campos de características

Puerto de ejemplo con características

Característica: `"dependencies"`

Característica: `"description"`

Característica: `"supports"`

Característica: `"license"`

Expresión de plataforma

Expresión de plataforma de ejemplo

Recursos adicionales

Compartir a través de

Referencia de vcpkg.json

Ejemplo

Campos de nivel superior

"builtin-baseline"

"default-features"

"description"

"dependencies"

Dependencias de puerto de ejemplo

"documentation"

"features"

"homepage"

"license"

Cadenas de licencia de ejemplo

EBNF

"maintainers"

"name"

"overrides"

Ejemplo de invalidaciones de versión

"port-version"

"supports"

"vcpkg-configuration"

Ejemplo incrustado vcpkg-configuration

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

Campos de dependencia

Dependencia:"default-features"

Dependencia:"features"

Dependencia:"host"

Dependencia:"name"

Dependencia:"platform"

Dependencia:"version>="

Campos de características

Puerto de ejemplo con características

Característica: "dependencies"

Característica: "description"

Característica: "supports"

Característica: "license"

Expresión de plataforma

Expresión de plataforma de ejemplo

Recursos adicionales

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

`"documentation"`

`"features"`

`"homepage"`

`"license"`

`"maintainers"`

`"name"`

`"overrides"`

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Ejemplo incrustado `vcpkg-configuration`

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

Dependencia:`"default-features"`

Dependencia:`"features"`

Dependencia:`"host"`

Dependencia:`"name"`

Dependencia:`"platform"`

Dependencia:`"version>="`

Característica: `"dependencies"`

Característica: `"description"`

Característica: `"supports"`

Característica: `"license"`