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 rigorosos. 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" o seu vcpkg.json para este URL.

Example

{
  "$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 referência para permitir uma $schema melhor validação e preenchimento automático do IDE.

Campos de nível superior

"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 o seu manifesto. Ele é necessário para arquivos de manifesto de nível superior usando versionamento sem um arquivo "default-registry". 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 são selecionados automaticamente se:

1. Uma dependência de porta a porta para a porta tem "default-features": true -- o valor padrão.
2. 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 outros 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 do porto. 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 a montante. 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 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 ser null para indicar que os usuários devem ler o arquivo implantado /share/<port>/copyright . DocumentRefs não são suportados.

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ífenes (-). 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 encontrar 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. Apenas substituições definidas pelo projeto de nível superior são usadas.

"port-version" deve ser especificado como um #N sufixo em "version". Por exemplo, "version": "1.2.3#7" nomeia versão 1.2.3, porta-versão 7.

Consulte também o 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 revisões para os arquivos de empacotamento. Um inteiro. O padrão é 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 versionamento para obter mais detalhes.

"supports"

Plataforma suportada e configurações de compilação. 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 suporta a compilação para Linux, você usaria "supports": "!linux"o .

"configuration"

Permite incorporar propriedades de configuração vcpkg dentro do vcpkg.json arquivo. Tudo dentro da configuration propriedade é tratado como se estivesse definido em um vcpkg-configuration.json arquivo. Para obter mais detalhes, consulte a vcpkg-configuration.json documentação.

vcpkg-configuration é uma grafia mais antiga deste campo, mas é idêntica.

Ter um configuration ou vcpkg-configuration definido em vcpkg.json enquanto também tem um vcpkg-configuration.json arquivo não é permitido e resultará no comando vcpkg terminando com uma mensagem de erro.

Exemplo incorporado configuration

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
        "repository": "https://github.com/MicrosoftDocs/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 a montante. 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" - Versão semântica relaxada 2.0.0, permitindo mais ou menos de 3 números primários. Exemplo: 1.2.3.4.10-alpha1
• "version-semver"- Versão Semântica Estrita 2.0.0. Exemplo: 2.0.1-rc5
• "version-date" - Uma data formatada como YYYY-MM-DD com 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 cadeia de caracteres arbitrária. Usado para pacotes que não têm versões ordenáveis. Isso raramente deve ser usado, no entanto, todas as portas criadas antes dos outros campos de versão foram introduzidos usam esse esquema.

Consulte versionamento para obter mais detalhes.

Campos de dependência

Cada dependência é uma cadeia de caracteres ou um objeto com os seguintes campos:

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 das características 'on-by-default' da dependência. O padrão é true.

Na maioria dos casos, isso deve ser definido e false quaisquer recursos necessários devem ser explicitamente dependidos.

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. Required.
• 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. Apenas no Windows, avisynthplus o suporte também está habilitado.

Dependência: "host"

Um booleano indicando que a dependência deve ser construída para o trio host em vez do triplete da porta atual. O padrão é 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.

Consulte Dependências de host para obter mais informações.

Dependência: "name"

O nome da dependência. Uma cadeia de caracteres. Required.

Isso segue as mesmas restrições que a "name" propriedade para 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 ao direcionar 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 especificar também 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 recursos

Cada recurso é um objeto com os seguintes campos:

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

Caraterí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.

Caraterística: "description"

A descrição do recurso. Uma cadeia de caracteres ou matriz de cadeias de caracteres. Required.

Isso é usado para ajudar os usuários a descobrir o recurso como parte de um search comando ou find e saber o que o recurso faz.

Caraterí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á construído e executado com êxito.

Caraterí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 é 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 se espera que uma biblioteca ou recurso seja compilado.

As expressões são construídas a partir de identificadores primitivos, operadores lógicos e agrupamento:

• !<expr>, not <expr> - negação
• <expr>|<expr>, - lógico OU (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 do triplete e na configuração de compilação:

Exemplo de expressão de plataforma

• Precisa picosha2 de sha256 em não-Windows, mas obtê-lo a partir 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)"
}