Guia de solução de problemas de controle de versão

Artigo
04/04/2024

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

Inspecionando o arquivo de versão para uma porta

Observação

O processo descrito abaixo destina-se a funcionar para portas do registro 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 abrir a pasta chamada f-.
Abra o arquivo de versão de portas:
- Localize o arquivo JSON com o mesmo nome da porta. Por exemplo, o fmt arquivo de versões é nomeado 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 seu hash de objeto de árvore Git correspondente. Essas informações são exigidas pelo vcpkg para recuperar versões de porta específicas. Somente as versões contidas nessa 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: 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, 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.

Como 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 git pull comando para atualizar o 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 vcpkg.json arquivo.
- Altere a versão especificada para uma que esteja disponível no repositório vcpkg. Por exemplo, mude de "version>=": "100.0.0" para "version>=": "10.1.1".
Execute vcpkg install:
- Execute o vcpkg install comando novamente em seu terminal ou prompt de comando.

Causa: Especificando a restrição de versão em diferentes esquemas

Um conflito de esquema de versão ocorre quando a versão especificada no vcpkg.json arquivo 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 vcpkg não pode comparar versões em esquemas diferentes.

Se uma restrição declarada version>= usar um esquema de versão diferente daquele usado na versão de linha de base, 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 encontrar uma versão que use o mesmo esquema de controle de versão que a linha de boost-regex base.
- Atualize a version>= restrição em seu vcpkg.json para uma versão que usa um esquema compatível.
Substitua para a 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í-lo em seu manifesto.
- Modifique o para vcpkg.json 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 clone raso

Quando vcpkg é clonado com um histórico de confirmação limitado (clone raso), 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 de objeto de árvore do Git usados pelo vcpkg para recuperar versões específicas de portas só estão disponíveis quando é feito check-out do histórico de confirmação completo. vcpkg detecta quando ele foi clonado em um repositório raso e produz uma mensagem de erro quando ele não consegue recuperar uma versão de 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 para clone completo:
```
git fetch --unshallow
```
Usando ações do GitHub (clones superficiais padrão)
- As Ações do GitHub geralmente usam como 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 o seguinte passo antes de utilizar 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 são instaladas com seus recursos padrão, mesmo quando você pode não querer esses recursos para seu projeto. Essa situação pode levar a um inchaço ou funcionalidade inesperada em sua 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. Seu manifesto de nível superior para biblioteca Y pode ter a seguinte aparência:

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

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

Motivo

A default-features propriedade só é considerada 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 "default-features": false configuração para a dependência Xtransitiva, resultando na instalação de X com 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 o 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 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 do artigo de 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.

Compartilhar via