Guia de resolução de problemas de versionamento

Artigo
02/06/2025

Este guia destina-se a utilizadores que estejam a enfrentar problemas com o versionamento .

Inspecionar o ficheiro de versão de uma porta

Observação

O processo descrito abaixo destina-se a funcionar para portas do registro vcpkg. Consulte a documentação de registo para saber como a base de dados de controlo de versão é implementada em registos 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:
- Encontre 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 é chamado fmt.json.

O arquivo de versão da porta contém uma lista de versões disponíveis com detalhes como tags de versão e seus de hash de objeto de árvoreGit correspondentes. Essas informações são exigidas 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 controle de versão, consulte nossa documentação de referência:

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

Causa: Solicitar 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, 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 em sua cópia local do banco de dados de versões. Nesse caso, execute o comando git pull para atualizar o de registro vcpkg para a confirmação mais recente.
Confira 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 vcpkg.json.
- Altere a versão especificada para uma que esteja disponível no repositório vcpkg. Por exemplo, mude de "versão>=": "100.0.0" para "versão>=": "10.1.1".
Execute vcpkg install:
- Execute o comando vcpkg install novamente no 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 daquele usado na versão de linha de base do repositório vcpkg. Isso resulta em um erro, pois o 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, vcpkg não poderá determinar qual versão é maior ou igual à outra.

Por exemplo, se especificar:

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

VCPKG emite 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 encontrar uma versão do boost-regex que use o mesmo esquema de controle de versão da linha de base.
- Atualize a restrição de version>= em seu vcpkg.json para uma versão que use um esquema compatível.
Substitua pela versão desejada
- Se precisar de uma versão específica do boost-regex que use um esquema de controlo de versão diferente, pode alterá-lo no seu manifesto.
- Modifique seu 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 em clones superficiais

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 específicas ou linhas de base. Os hashes dos objetos árvore do Git usados pelo vcpkg para recuperar versões específicas de portas só estão disponíveis quando o histórico completo dos commits é examinado. O vcpkg deteta quando foi clonado em um repositório superficial e produz uma mensagem de erro quando não consegue recuperar uma versão de porta.

Por exemplo, usar um vcpkg.json com uma linha de base específica, como o 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

Este 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 este problema é converter para clone completo:
```
git fetch --unshallow
```
Usando ações do GitHub (clones superficiais padrão)
- As Ações do GitHub muitas vezes definem por padrão clones superficiais. Para contornar isso, você pode modificar o fluxo de trabalho de ações do GitHub 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 achar que as dependências transitivas são instaladas com seus recursos padrão, mesmo quando você pode não querer esses recursos para seu projeto. Esta situação pode levar a uma sobrecarga inesperada ou a uma alteração na funcionalidade na compilação final.

Cenário

Você tem uma dependência da biblioteca Y, que por sua vez depende da biblioteca X. A 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 "default-features": false. No entanto, X ainda está instalado com o recurso padrão foo.

Justificação

A propriedade default-features só é considerada no manifesto principal. 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 "default-features": false para a dependência transitiva X, resultando na instalação de X com os seus recursos 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 o X seja 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 conceito de recursos padrão.

O problema não está listado aqui

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

Partilhar via