vcpkg.json Referência

Artigo
03/01/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. 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, libxml2e 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 como YYYY-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-androido .

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-chave or é 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"` ou `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`arm32`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"`
`arm64`	`VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`wasm32`	`VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
`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` 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)"
}

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 incorporado vcpkg-configuration

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