Guia de solução de problemas de versionamento

Artigo
02/10/2025

Este guia destina-se a usuários que enfrentam problemas com controle de versão.

Inspecionando o arquivo de versão de uma porta

Nota

O processo descrito abaixo destina-se a funcionar para portas do registro do vcpkg. Consulte nossa documentação do registro para saber como o banco de dados de controle de versão é implementado em registros personalizados.

Para inspecionar o banco de dados de versões de uma porta específica:

Navegue até o diretório vcpkg/versions.
Localize a pasta da porta:
- Localize a pasta correspondente à primeira letra da porta. Por exemplo, para fmt abra a pasta chamada f-.
Abra o arquivo de versão das portas:
- Localize o arquivo JSON com o mesmo nome da porta. Por exemplo, o arquivo de versões fmt é nomeado fmt.json.

O arquivo de versão da porta contém uma lista de versões disponíveis com detalhes como marcas de versão e o hash de objeto de árvore do Git correspondente . Essas informações são necessárias pelo vcpkg para recuperar versões de porta específicas. Somente as versões contidas nesta lista estão disponíveis para uso em seus arquivos de manifesto.

Para obter mais detalhes sobre o controle de versão, consulte nossa documentação de referência:

Para obter mais detalhes sobre como usar um manifesto, consulte manifesto

Causa: solicitando uma versão inexistente de um pacote

Quando uma versão especificada no arquivo de manifesto não existe no banco de dados de versão vcpkg, o vcpkg falha ao resolver a dependência e produz uma mensagem de erro semelhante à seguinte:

error: no version database entry for fmt at 100.0.0
Available versions:
  10.1.1
  10.1.0
  10.0.0
  9.1.0#1
  9.1.0
  9.0.0
  8.1.1#2
  8.1.1#1
  ...
See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Para resolver o problema:

Atualize o banco de dados de versões:
- A versão desejada pode não estar na cópia local do banco de dados de versões. Nesse caso, execute o comando git pull para atualizar o registro do vcpkg para a confirmação mais recente.
Verifique as versões disponíveis:
- Escolha uma das versões disponíveis no banco de dados de versões.
Atualizar arquivo de manifesto:
- Edite seu arquivo de vcpkg.json.
- Altere a versão especificada para uma disponível no repositório vcpkg. Por exemplo, altere de "version>=": "100.0.0" para "version>=": "10.1.1".
Execute a instalação do vcpkg:
- Execute o comando vcpkg install novamente em seu terminal ou prompt de comando.

Causa: especificação da restrição de versão em esquemas diferentes

Um conflito de esquema de versão ocorre quando a versão especificada no arquivo vcpkg.json para uma dependência usa um esquema de controle de versão diferente do usado na versão de linha de base do repositório vcpkg. Isso resulta em um erro, pois vcpkg não pode comparar versões em diferentes esquemas.

Se uma restrição de version>= declarada usar um esquema de versão diferente do usado na versão de linha de base, o vcpkg não poderá determinar qual versão é maior ou igual à outra.

Por exemplo, se você especificar:

{
  "dependencies": [
    {
      "name": "boost-regex",
      "version>=": "1.75.0"
    }
  ]
}

vcpkg gera a seguinte mensagem de erro:

error: version conflict on boost-regex:x64-windows:  required 1.75.0, which cannot be compared with the baseline version 1.83.0.

The versions have incomparable schemes:
  boost-regex@1.83.0 has scheme relaxed
  boost-regex@1.75.0 has scheme string

This can be resolved by adding an explicit override to the preferred version. For example:

  "overrides": [
    { "name": "boost-regex", "version": "1.83.0" }
  ]

See `vcpkg help versioning` or https://learn.microsoft.com/vcpkg/users/versioning for more information.

Resoluções:

Use um esquema de versão compatível:
- Inspecione o banco de dados de versão no repositório vcpkg em versions/b-/boost-regex.json para localizar uma versão de boost-regex que usa o mesmo esquema de controle de versão que a linha de base.
- Atualize a restrição version>= em seu vcpkg.json para uma versão que usa um esquema compatível.
Substitua pela versão desejada:
- Se você precisar de uma versão específica do boost-regex que use um esquema de controle de versão diferente, poderá substituí-la em seu manifesto.
- Modifique o vcpkg.json para incluir uma seção de substituições especificando a versão desejada:
```
{
  "dependencies": [
    { "name": "boost-regex" }
  ],
  "overrides": [
    { "name": "boost-regex", "version": "1.75.0" }
  ]
}
```

Causa: histórico de confirmação inadequado no clone superficial

Quando vcpkg é clonado com um histórico de confirmação limitado (clone superficial), ele não tem o histórico de confirmação necessário para resolver restrições de versão ou linhas de base específicas. Os hashes de objeto de árvore do Git usados pelo vcpkg para recuperar versões específicas das portas só estão disponíveis quando o histórico de confirmação completo é verificado. O vcpkg detecta quando foi clonado em um repositório superficial e produz uma mensagem de erro quando não recupera uma versão da porta.

Por exemplo, usando um vcpkg.json com uma linha de base específica como a seguinte:

{
  "dependencies": [
    {
      "name": "fmt"
    }
  ],
  "overrides": [
    {
      "name": "fmt",
      "version": "7.1.3#1"
    }
  ],
  "builtin-baseline": "bb588985e37484d543fc849d0d79434e0d45bb3c"
}

Resultará no seguinte erro:

error: failed to execute: "C:\Program Files\Git\cmd\git.exe" "--git-dir=C:\dev\demo\vcpkg\.git" "--work-tree=C:\dev\demo\vcpkg\buildtrees\versioning_\versions\fmt\4f8427eb0bd40da1856d4e67bde39a4fda689d72_26648.tmp" -c core.autocrlf=false read-tree -m -u 4f8427eb0bd40da1856d4e67bde39a4fda689d72
vcpkg was cloned as a shallow repository in: C:\dev\demo\vcpkg\.git
Try again with a full vcpkg clone.
error: git failed with exit code: (128).
fatal: failed to unpack tree object 4f8427eb0bd40da1856d4e67bde39a4fda689d72
note: while checking out port fmt with git tree 4f8427eb0bd40da1856d4e67bde39a4fda689d72

Esse erro indica que a confirmação (4f8427eb0bd40da1856d4e67bde39a4fda689d72) necessária para a versão específica do pacote fmt não está disponível no clone superficial.

Resoluções:

Converter em um clone completo
- A solução mais fácil para esse problema é converter em clone completo:
```
git fetch --unshallow
```
Usando o GitHub Actions (clones rasos padrão)
- O GitHub Actions geralmente usa como padrão clones rasos. Para contornar isso, você pode modificar o fluxo de trabalho do GitHub Actions para executar um clone completo. Adicione a seguinte etapa antes de usar vcpkg:
```
- name: Convert to Full Clone
  run: git fetch --unshallow
```

Causa: inclusão inesperada de recursos padrão em dependências transitivas

Ao gerenciar dependências com vcpkg, você pode descobrir que as dependências transitivas estão instaladas com seus recursos padrão, mesmo quando talvez você não queira esses recursos para seu projeto. Essa situação pode levar a uma sobrecarga ou funcionalidade inesperada na sua versão final.

Cenário

Você tem uma dependência da biblioteca Y, que, por sua vez, depende da biblioteca X. Biblioteca X tem recursos padrão, incluindo foo, que você deseja excluir do seu projeto. O seu manifesto de nível superior para a biblioteca Y pode ter esta aparência:

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"],
      "default-features": false
    }
  ]
}

Você espera que X seja instalado sem seus recursos padrão devido à configuração de "default-features": false. No entanto, X ainda está instalado com o recurso padrão foo.

Razão

A propriedade default-features é considerada somente no manifesto de nível superior. Isso significa que os recursos padrão de dependências transitivas (como X neste cenário) ainda estão incluídos, a menos que explicitamente desabilitados no nível superior. Quando a biblioteca Y é resolvida, vcpkg não propaga a configuração de "default-features": false para a dependência transitiva X, resultando na instalação de X com suas funcionalidades padrão.

Resolução

Para garantir que dependências transitivas como X sejam instaladas sem seus recursos padrão, você precisa promovê-las para direcionar dependências em seu manifesto de nível superior e desabilitar explicitamente seus recursos padrão. Modifique seu vcpkg.json para incluir X diretamente com "default-features": false:

{
  "name": "my-project",
  "dependencies": [
    {
      "name": "Y",
      "features": ["featureB"]
    },
    {
      "name": "X",
      "default-features": false
    }
  ]
}

Essa abordagem garante que X esteja instalado sem seus recursos padrão, pois agora X é uma dependência direta com uma instrução explícita para excluir recursos padrão.

Para obter informações mais detalhadas sobre como os recursos padrão funcionam e como gerenciá-los, consulte o artigo de conceito sobre recursos padrão.

O problema não está listado aqui

Se o problema não estiver listado aqui, visite nosso repositório para criar um novo problema.

Compartilhar via