vcpkg.json Referência

Artigo
07/22/2024

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. Os IDEs com suporte ao 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" vcpkg.json seu para este 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, libxml2e yajl. O exemplo também inclui uma $schema referência para permitir uma melhor validação e preenchimento automático 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: Característica}	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 de porta	Não	Número inteiro	Revisão de arquivos de porta
Suporta	Não	Expressão da plataforma	Configurações de plataforma e build compatíveis
version version-semver data da versão cadeia de caracteres de versão	Bibliotecas	string	Informações da versão upstream

`"builtin-baseline"`

Um atalho para especificar a "baseline" resolução de versão no registro padrão. Uma cadeia de caracteres. Opcional, usado apenas por projetos de nível superior.

Esse campo indica o commit que fornece informações de https://github.com/microsoft/vcpkg versão mínima global para o manifesto. Ele é necessário para arquivos de manifesto de nível superior usando controle de versão sem um arquivo ."default-registry" Ele tem a mesma semântica que define seu registro padrão como sendo:

{
  "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 sã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. Os ports usados por outros devem quase sempre ser usados "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 os 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 or find e aprender o que a biblioteca faz.

`"dependencies"`

A lista de dependências exigidas pelo projeto. Uma matriz de objetos Dependency. Opcional.

Esse 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.

Os 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 os recursos.

`"homepage"`

O URI para a página inicial do projeto. Uma cadeia de caracteres. Opcional.

`"license"`

A expressão de licença abreviada SPDX do projeto. Uma cadeia de caracteres ou nula. Opcional.

Deve "license" 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.

Observação

As informações de licenciamento fornecidas para cada pacote no registro vcpkg representam a melhor compreensão da Microsoft sobre os requisitos de licenciamento. No entanto, essas informações podem não ser definitivas. Os usuários são aconselhados a verificar os requisitos exatos de licenciamento para cada pacote que pretendem usar, pois é sua responsabilidade garantir a conformidade com as licenças aplicáveis.

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 "E-mail> do nome e sobrenome<".

`"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 um hífen. As bibliotecas são incentivadas a incluir o nome da organização ou da 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 as substituições definidas pelo projeto de nível superior são usadas.

Nome	Obrigatória	Type	Descrição
name	Sim	string	O nome da porta
version	Sim	string	Informações da versão upstream a serem fixadas.
version-semver data da versão cadeia de caracteres de versão	Sim	string	Alternativas obsoletas para `version` nomear esquemas específicos.
versão de porta	Não	Número inteiro	Revisão de arquivos de porta para pino. Obsoleto em favor de ser colocado na própria versão.

"port-version" deve ser especificado como um #N sufixo em "version". Por exemplo, "version": "1.2.3#7" nomeia a versão 1.2.3, port-version 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 que distingue as revisões dos arquivos de empacotamento. Um inteiro. Assume o padrão de 0.

O "port-version" deve ser incrementado sempre que uma nova versão do port for publicada que não altere a versão de origem do upstream. Quando a versão de origem upstream é alterada, o campo version deve ser alterado e deve "port-version" ser redefinido para 0 (ou removido).

Consulte o controle de versão para obter mais detalhes.

`"supports"`

Configurações de plataforma e build 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".

`"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 in definido ao vcpkg.json mesmo tempo em que tem um vcpkg-configuration.json arquivo não é permitido e resultará no encerramento do comando vcpkg com uma mensagem de erro.

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

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" - Semântica Relaxada Versão 2.0.0, permitindo mais ou menos de 3 números primários. Exemplo: 1.2.3.4.10-alpha1
"version-semver" - Semântica estrita versão 2.0.0. Exemplo: 2.0.1-rc5
"version-date" - Uma data formatada com YYYY-MM-DD uma sequência numérica separada por 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 string arbitrária. Usado para pacotes que não têm versões que podem ser encomendadas. Isso deve ser raramente usado, no entanto, todos os ports criados antes dos outros campos de versão serem introduzidos usam esse esquema.

Consulte o controle de versão para obter mais detalhes.

Campos de dependência

Cada dependência é uma string 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 necessários
host	Não	bool	Exigir a dependência para a máquina host em vez do destino
name	Sim	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 o nome definido para o valor da cadeia de caracteres.

Dependência: `"default-features"`

Um booleano que indica que o projeto depende dos recursos "ativados por padrão" 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 necessários. 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 em que o recurso é necessário. Opcional.

Uma string 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 ffmpeg biblioteca com suporte à codificação mp3. Somente no Windows, avisynthplus o suporte também está ativado.

Dependência: `"host"`

Um booleano que indica que a dependência deve ser criada para o trio de host em vez do trio 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 sistemas de compilação, 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.

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 propriedade de "name" um projeto.

Dependência: `"platform"`

Uma expressão que limita as plataformas em que 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 ao direcionar sistemas não 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 especificar também uma versão mínima da porta, se desejado.

Para obter mais informações sobre a semântica de controle de versão, consulte Controle de versão.

Campos de recursos

Cada feição é 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 dá suporte
license	Não	cadeia de caracteres ou nulo	Expressão de licença SPDX

Confira a documentação do modo de 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.

Esse 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 or find e aprender o que o recurso faz.

Característica: `"supports"`

A plataforma com suporte e as configurações de build para o recurso. Uma expressão de plataforma. Opcional.

Este campo documenta as configurações da plataforma em que o recurso será compilado e executado com êxito.

Característica: `"license"`

A expressão de licença abreviada SPDX do recurso. Uma cadeia de caracteres ou nula. Opcional. Se não for fornecida, a licença será a mesma especificada no campo de licença de nível superior.

Observação

Expressão da plataforma

Uma expressão de plataforma é uma string 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>, - OR lógico (a palavra-chave or é reservada, <expr>,<expr> mas não válida em expressões de plataforma)
<expr>&<expr>, <expr> and <expr> - lógico E
(<expr>) - agrupamento/precedência

Os seguintes identificadores são definidos com base nas configurações de trigêmeos e na configuração de build:

Identificador	Condição de trigêmeo
`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 `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` ou `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
`mingw`	`VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
`uwp`	`VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
`xbox`	`VCPKG_CMAKE_SYSTEM_NAME` == `""` e `XBOX_CONSOLE_TARGET` é 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"`
`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`

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

Compartilhar via

vcpkg.json Referência

Exemplo

Campos de nível superior

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

Exemplo de dependências de porta

`"documentation"`

`"features"`

`"homepage"`

`"license"`

Exemplo de cadeias de caracteres de licença

EBNF

`"maintainers"`

`"name"`

`"overrides"`

Exemplo de substituições de versão

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Exemplo inserido `vcpkg-configuration`

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

Campos de dependência

Dependência: `"default-features"`

Dependência: `"features"`

Dependência: `"host"`

Dependência: `"name"`

Dependência: `"platform"`

Dependência: `"version>="`

Campos de recursos

Exemplo de porta com recursos

Característica: `"dependencies"`

Característica: `"description"`

Característica: `"supports"`

Característica: `"license"`

Expressão da plataforma

Exemplo de expressão de plataforma

Recursos adicionais

Compartilhar via

vcpkg.json Referência

Exemplo

Campos de nível superior

"builtin-baseline"

"default-features"

"description"

"dependencies"

Exemplo de dependências de porta

"documentation"

"features"

"homepage"

"license"

Exemplo de cadeias de caracteres de licença

EBNF

"maintainers"

"name"

"overrides"

Exemplo de substituições de versão

"port-version"

"supports"

"vcpkg-configuration"

Exemplo inserido vcpkg-configuration

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

Campos de dependência

Dependência: "default-features"

Dependência: "features"

Dependência: "host"

Dependência: "name"

Dependência: "platform"

Dependência: "version>="

Campos de recursos

Exemplo de porta com recursos

Característica: "dependencies"

Característica: "description"

Característica: "supports"

Característica: "license"

Expressão da plataforma

Exemplo de expressão de plataforma

Recursos adicionais

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

`"documentation"`

`"features"`

`"homepage"`

`"license"`

`"maintainers"`

`"name"`

`"overrides"`

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Exemplo inserido `vcpkg-configuration`

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

Dependência: `"default-features"`

Dependência: `"features"`

Dependência: `"host"`

Dependência: `"name"`

Dependência: `"platform"`

Dependência: `"version>="`

Característica: `"dependencies"`

Característica: `"description"`

Característica: `"supports"`

Característica: `"license"`