vcpkg.json Referência
Para obter uma visão geral do uso de manifestos com vcpkg, consulte Modo de manifesto.
Os manifestos são documentos JSON estritos. Eles não podem conter comentários no estilo C++ (//
) nem vírgulas à direita. No entanto, você pode usar nomes de campo que começam com $
para escrever seus comentários em qualquer objeto que tenha um conjunto bem definido de chaves. Esses campos de comentário não são permitidos em nenhum objeto que permita chaves definidas pelo usuário (como "features"
).
O esquema JSON mais recente está disponível em https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. IDEs com suporte a esquema JSON, como Visual Studio e Visual Studio Code, podem usar esse arquivo para fornecer preenchimento automático e verificação de sintaxe. Para a maioria dos IDEs, você deve definir "$schema"
em seu vcpkg.json
para esta URL.
Exemplo
{
"$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
"dependencies": [
"boost-system",
{
"name": "cpprestsdk",
"default-features": false
},
"libxml2",
"yajl"
]
}
Este exemplo demonstra um manifesto para um aplicativo usando boost-system
, cpprestsdk
, libxml2
e yajl
. O exemplo também inclui uma $schema
referência para permitir uma melhor validação e autoconclusão do IDE.
Campos de nível superior
Nome | Obrigatória | Type | Descrição |
---|---|---|---|
linha de base integrada | Não | string | Pinos de versão a serem usados ao criar como nível superior |
recursos padrão | Não | Objeto de recurso[] | Exigir os recursos listados como ativados por padrão |
dependencies | Não | Dependência[] | Lista de dependências necessárias para criar e usar este projeto |
descrição | Bibliotecas | string ou string[] | A descrição do projeto |
documentação | Não | string | URI para a documentação do projeto upstream |
features | Não | {cadeia de caracteres: Recurso} | Recursos opcionais disponíveis para usuários do projeto |
página inicial | Não | string | URI para a página inicial do projeto upstream |
license | Não | cadeia de caracteres ou nulo | Expressão de licença SPDX |
Mantenedores | Não | string ou string[] | Mantenedores dos arquivos de pacote |
name | Bibliotecas | string | O nome do projeto |
substitui | Não | Substituir[] | Pinos de versão a serem usados ao criar como nível superior |
versão da porta | Não | Número inteiro | Revisão de arquivos de porta |
Suporta | Não | Expressão da plataforma | Configurações de plataforma e compilação suportadas |
version version-semver data-versão versão-string |
Bibliotecas | string | Informações de versão upstream |
"builtin-baseline"
Um atalho para especificar a resolução de "baseline"
versão no registro padrão. Uma cadeia de caracteres. Opcional, usado apenas por projetos de nível superior.
Este campo indica a confirmação da qual fornece informações de https://github.com/microsoft/vcpkg versão mínima global para seu manifesto. Ele é necessário para arquivos de manifesto de nível superior usando controle de versão sem um "default-registry"
arquivo . Ele tem a mesma semântica que definir seu registro padrão para ser:
{
"default-registry": {
"kind": "builtin",
"baseline": "<value>"
}
}
Consulte controle de versão e Usando registros para obter mais detalhes semânticos.
"default-features"
O conjunto de recursos necessários para um comportamento razoável sem personalização adicional.
Os recursos padrão serão selecionados automaticamente se:
- Uma dependência de porta para porta para a porta tem
"default-features": true
-- o valor padrão. - O manifesto de nível superior não tem uma dependência para a porta com
"default-features": false
.
Os recursos padrão lidam com o caso específico de fornecer uma configuração "padrão" para dependências transitivas que o projeto de nível superior pode não conhecer. As portas usadas por outras pessoas quase sempre devem ser usadas "default-features": false
para suas dependências.
Você pode definir recursos padrão específicos da plataforma usando um objeto de recurso:
{
"name": "my-port",
"default-features": [
"png",
{
"name": "winssl",
"platform": "windows"
}
]
}
Consulte "features"
para obter mais informações sobre recursos.
"description"
A descrição da porta. Uma cadeia de caracteres ou matriz de cadeias de caracteres. Obrigatório para bibliotecas, opcional para projetos de nível superior.
Isso é usado para ajudar os usuários a descobrir a biblioteca como parte de um search
comando ou find
e aprender o que a biblioteca faz.
"dependencies"
A lista de dependências exigidas pelo projeto. Uma matriz de objetos Dependency. Opcional.
Este campo lista todas as dependências necessárias para criar e usar sua biblioteca ou aplicativo.
Exemplo de dependências de porta
"dependencies": [
{
"name": "arrow",
"default-features": false,
"features": [
"json",
{
"name": "mimalloc",
"platform": "windows"
}
]
},
"boost-asio",
"openssl",
{
"name": "picosha2",
"platform": "!windows"
}
]
"documentation"
O URI para a documentação do projeto upstream. Uma cadeia de caracteres. Opcional.
"features"
Os recursos disponíveis para os usuários do projeto. Um mapa de nomes para objetos Feature. Opcional.
Recursos são sinalizadores booleanos que adicionam comportamentos e dependências adicionais a uma compilação. Consulte a Documentação do Conceito de Manifesto para obter mais informações sobre recursos.
"homepage"
O URI para a página inicial do projeto. Uma cadeia de caracteres. Opcional.
"license"
A expressão de licença curta SPDX do projeto. Uma cadeia de caracteres ou null. Opcional.
O "license"
deve ser uma expressão de licença SPDX 3.19 ou deve indicar null
que os usuários devem ler o arquivo implantado/share/<port>/copyright
. Não há suporte para DocumentRefs.
Exemplo de cadeias de caracteres de licença
MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2
EBNF
vcpkg usa o seguinte EBNF para analisar o campo de licença:
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"
A lista de mantenedores de pacotes. Uma cadeia de caracteres ou matriz de cadeias de caracteres. Opcional.
Recomendamos o uso do formulário "GivennameSurname<email".>
"name"
O nome do projeto. Uma cadeia de caracteres. Obrigatório para bibliotecas, opcional para projetos de nível superior.
O nome deve ser letras ASCII minúsculas, dígitos ou hífens (-
). Não deve começar nem terminar com hífen. As bibliotecas são incentivadas a incluir seu nome de organização ou estrutura como um prefixo, como msft-
ou boost-
para ajudar os usuários a localizar e descrever bibliotecas associadas.
Por exemplo, uma biblioteca com um nome oficial de Boost.Asio
pode receber o nome boost-asio
.
"overrides"
Pinos de versão exatos a serem usados para dependências específicas. Uma matriz de objetos Override. Opcional.
"overrides"
de manifestos transitivos (ou seja, de dependências) são ignorados. Somente substituições definidas pelo projeto de nível superior são usadas.
Nome | Obrigatória | Type | Descrição |
---|---|---|---|
name | Yes | string | O nome da porta |
version | Yes | string | Informações de versão upstream para fixar. |
version-semver data-versão versão-string |
Yes | string | Alternativas preteridas para version nomear esquemas específicos. |
versão da porta | Não | Número inteiro | Revisão de arquivos de porta para fixar. Preterido em favor de ser colocado na própria versão. |
"port-version"
deve ser especificado como um sufixo #N
em "version"
. Por exemplo, "version": "1.2.3#7"
nomeia a versão 1.2.3, a versão de porta 7.
Consulte também controle de versão para obter mais detalhes semânticos.
Exemplo de substituições de versão
"overrides": [
{
"name": "arrow", "version": "1.2.3#7"
},
{
"name": "openssl", "version": "1.1.1h#3"
}
]
"port-version"
Um sufixo de versão distinguindo revisões para os arquivos de empacotamento. Um inteiro. Assume o padrão de 0
.
O "port-version"
deve ser incrementado sempre que uma nova versão da porta é publicada que não altera a versão de origem upstream. Quando a versão de origem upstream é alterada, o campo de versão deve ser alterado e o "port-version"
deve ser redefinido para 0
(ou removido).
Consulte o controle de versão para obter mais detalhes.
"supports"
Configurações de plataforma e compilação suportadas. Uma expressão de plataforma. Opcional.
Este campo documenta que não se espera que um projeto seja compilado ou executado com êxito em determinadas configurações de plataforma.
Por exemplo, se sua biblioteca não oferecer suporte à compilação para Linux, você usaria "supports": "!linux"
o .
"vcpkg-configuration"
Permite incorporar propriedades de configuração vcpkg dentro do vcpkg.json
arquivo. Tudo dentro da vcpkg-configuration
propriedade é tratado como se estivesse definido em um vcpkg-configuration.json
arquivo. Para obter mais detalhes, consulte a vcpkg-configuration.json
documentação.
Ter um vcpkg-configuration
definido enquanto vcpkg.json
também tem um vcpkg-configuration.json
arquivo não é permitido e resultará no comando vcpkg terminando com uma mensagem de erro.
Exemplo incorporado 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"
A versão do projeto upstream. Uma cadeia de caracteres. Obrigatório para bibliotecas, opcional para projetos de nível superior.
Um manifesto deve conter, no máximo, um campo de versão. Cada campo de versão corresponde a um esquema de controle de versão diferente:
"version"
- Relaxado semântico versão 2.0.0, permitindo mais ou menos de 3 números primários. Exemplo:1.2.3.4.10-alpha1
"version-semver"
- Estrita Semântica Versão 2.0.0. Exemplo:2.0.1-rc5
"version-date"
- Uma data formatada comoYYYY-MM-DD
com uma sequência numérica separada de pontos à direita opcional. Usado para pacotes que não têm versões numéricas (por exemplo, Live-at-HEAD). Exemplo:2022-12-09.314562
"version-string"
- Uma cadeia de caracteres arbitrária. Usado para pacotes que não têm versões que podem ser solicitadas. Isso deve ser raramente usado, no entanto, todas as portas criadas antes dos outros campos de versão foram introduzidos usam esse esquema.
Consulte o controle de versão para obter mais detalhes.
Campos de dependência
Cada dependência é uma cadeia de caracteres ou um objeto com os seguintes campos:
Nome | Obrigatória | Type | Descrição |
---|---|---|---|
recursos padrão | Não | bool | Exigir os recursos listados como ativados por padrão |
features | Não | Objeto de recurso[] | A lista de recursos adicionais a serem exigidos |
host | Não | bool | Exigir a dependência para a máquina host em vez do destino |
name | Yes | string | O nome da dependência |
platform | Não | Expressão da plataforma | Qualificador para quais plataformas usar a dependência |
versão>= | Não | string | Versão mínima necessária. Port-version é identificado com um #N sufixo, por exemplo, 1.2.3#7 nomes port-version 7. |
As cadeias de caracteres são interpretadas como um objeto com nome definido para o valor da cadeia de caracteres.
Dependência: "default-features"
Um booleano indicando que o projeto depende dos recursos 'on-by-default' da dependência. Assume o padrão de true
.
Na maioria dos casos, isso deve ser definido e false
quaisquer recursos necessários devem ser explicitamente dependentes.
Dependência: "features"
A lista de recursos adicionais a serem exigidos. Uma matriz de objetos Feature. Opcional.
Um objeto de recurso é um objeto com os seguintes campos:
name
- O nome do recurso. Uma cadeia de caracteres. Obrigatória.platform
- Uma expressão de plataforma que limita as plataformas onde o recurso é necessário. Opcional.
Uma cadeia de caracteres simples também é um equivalente válido Feature Object
a { "name": "<feature-name>" }
.
Por exemplo,
{
"name": "ffmpeg",
"default-features": false,
"features": [
"mp3lame",
{
"name": "avisynthplus",
"platform": "windows"
}
]
}
Usa a biblioteca com suporte a ffmpeg
codificação mp3. Somente no Windows, avisynthplus
o suporte também está habilitado.
Dependência: "host"
Um booleano indicando que a dependência deve ser criada para o triplete do host em vez do triplete da porta atual. Assume o padrão de false
.
Qualquer dependência que forneça ferramentas ou scripts que devem ser "executados" durante uma compilação (como buildsystems, geradores de código ou auxiliares) deve ser marcada como "host": true
. Isso permite a compilação cruzada correta nos casos em que o destino não é executável -- como ao compilar para arm64-android
o .
Consulte Dependências do host para obter mais informações.
Dependência: "name"
O nome da dependência. Uma cadeia de caracteres. Obrigatória.
Isso segue as mesmas restrições que a "name"
propriedade de um projeto.
Dependência: "platform"
Uma expressão que limita as plataformas onde a dependência é necessária. Uma expressão de plataforma. Opcional.
Se a expressão não corresponder à configuração atual, a dependência não será usada. Por exemplo, se uma dependência tiver "platform": "!windows"
, ela só será necessária quando estiver direcionada a sistemas que não sejam Windows.
Dependência: "version>="
Uma restrição de versão mínima na dependência.
Este campo especifica a versão mínima da dependência, opcionalmente usando um #N
sufixo para também especificar uma versão mínima da porta, se desejado.
Para obter mais informações sobre semântica de controle de versão, consulte Controle de versão.
Campos de recurso
Cada recurso é um objeto com os seguintes campos:
Nome | Obrigatória | Type | Descrição |
---|---|---|---|
descrição | Sim | string | A descrição do recurso |
dependencies | Não | Dependência[] | Uma lista de dependências |
Suporta | Não | Expressão da plataforma | Qualificador para quais plataformas e configurações o recurso oferece suporte |
license | Não | cadeia de caracteres ou nulo | Expressão de licença SPDX |
Confira a documentação do modo Manifesto para obter uma visão geral conceitual dos recursos.
Exemplo de porta com recursos
{
"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"
A lista de dependências exigidas pelo recurso. Uma matriz de objetos Dependency. Opcional.
Este campo lista todas as dependências adicionais necessárias para criar e usar o recurso.
Característica: "description"
A descrição do recurso. Uma cadeia de caracteres ou matriz de cadeias de caracteres. Obrigatória.
Isso é usado para ajudar os usuários a descobrir o recurso como parte de um search
comando ou find
e aprender o que o recurso faz.
Característica: "supports"
A plataforma suportada e as configurações de compilação para o recurso. Uma expressão de plataforma. Opcional.
Este campo documenta as configurações da plataforma onde o recurso será compilado e executado com êxito.
Característica: "license"
A expressão de licença curta SPDX do recurso. Uma cadeia de caracteres ou null. Opcional. Se não for fornecida, a licença será a mesma especificada no campo de licença de nível superior.
Expressão da plataforma
Uma expressão de plataforma é uma cadeia de caracteres JSON que descreve quando uma dependência é necessária ou quando uma biblioteca ou recurso deve ser criado.
As expressões são criadas a partir de identificadores primitivos, operadores lógicos e agrupamento:
!<expr>
,not <expr>
- negação<expr>|<expr>
, ,<expr>,<expr>
- OR lógico (a palavra-chaveor
é reservada,<expr>||<expr>
mas não é válida em expressões de plataforma)<expr>&<expr>
,<expr>&&<expr>
,<expr> and <expr>
- lógico E(<expr>)
- agrupamento/precedência
Os seguintes identificadores são definidos com base nas configurações triplete e configuração de compilação:
Identificador | Condição de trigêmeos |
---|---|
x64 |
VCPKG_TARGET_ARCHITECTURE == "x64" |
x86 |
VCPKG_TARGET_ARCHITECTURE == "x86" |
arm |
VCPKG_TARGET_ARCHITECTURE == "arm" ouVCPKG_TARGET_ARCHITECTURE == "arm64" |
arm32 |
VCPKG_TARGET_ARCHITECTURE == "arm" |
arm64 |
VCPKG_TARGET_ARCHITECTURE == "arm64" |
wasm32 |
VCPKG_TARGET_ARCHITECTURE == "wasm32" |
windows |
VCPKG_CMAKE_SYSTEM_NAME == "" ouVCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" ouVCPKG_CMAKE_SYSTEM_NAME == "MinGW" |
mingw |
VCPKG_CMAKE_SYSTEM_NAME == "MinGW" |
uwp |
VCPKG_CMAKE_SYSTEM_NAME == "WindowsStore" |
xbox |
VCPKG_CMAKE_SYSTEM_NAME == "" eXBOX_CONSOLE_TARGET está definido. |
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 |
Exemplo de expressão de plataforma
- Precisa
picosha2
de sha256 em não-Windows, mas obtê-lo do sistema operacional no Windows (BCrypt)
{
"name": "picosha2",
"platform": "!windows"
}
- Requer zlib no arm64 Windows e amd64 Linux
{
"name": "zlib",
"platform": "(windows & arm64) | (linux & x64)"
}
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de