Guía de solución de problemas de control de versiones

Esta guía está dirigida a los usuarios que experimentan problemas con Control de versiones.

Inspección del archivo de versión de un puerto

Para inspeccionar la base de datos de versiones de un puerto específico:

1. Vaya al directorio vcpkg/versions.
2. Busque la carpeta del puerto:
   • Busque la carpeta correspondiente a la primera letra del puerto. Por ejemplo, para fmt abra la carpeta denominada f-.
3. Abra el archivo de versión de puertos:
   • Busque el archivo JSON con el mismo nombre del puerto. Por ejemplo, el archivo de versiones de fmt se denomina fmt.json.

El fichero de versiones del port contiene una lista de versiones disponibles con detalles como etiquetas de versión y su correspondiente hash de objeto de árbol de Git. Vcpkg requiere esta información para recuperar versiones de puerto específicas. Solo las versiones contenidas en esta lista están disponibles para usarlas en los archivos de manifiesto.

Para más información sobre el control de versiones, consulte nuestra documentación de referencia:

• Conceptos de versión
• versiones

Para obtener más información sobre el uso de un manifiesto, consulte manifiesto

Causa: Solicitar una versión inexistente de un paquete

Cuando una versión especificada en el archivo de manifiesto no existe en la base de datos de versión vcpkg, vcpkg no puede resolver la dependencia y genera un mensaje de error similar al siguiente:

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 el problema:

1. Actualice la base de datos de versiones:
   • Es posible que la versión que desee no esté en la copia local de la base de datos de versiones. En ese caso, ejecuta el comando git pull para actualizar el registro de vcpkg al último commit.
2. Compruebe las versiones disponibles:
   • Elija una de las versiones disponibles en la base de datos de versiones.
3. Actualizar archivo de manifiesto:
   • Edite el archivo vcpkg.json.
   • Cambie la versión especificada a una que esté disponible en el repositorio vcpkg. Por ejemplo, cambie de "version>=": "100.0.0" a "version>=": "10.1.1".
4. Ejecute vcpkg install:
   • Ejecute de nuevo el comando vcpkg install en su terminal o símbolo del sistema.

Causa: Especificar la restricción de versión en distintos esquemas

Un conflicto de esquema de versión se produce cuando la versión especificada en el archivo vcpkg.json para una dependencia usa un esquema de control de versiones diferente al usado en la versión de línea base del repositorio vcpkg. Esto da como resultado un error ya que vcpkg no puede comparar versiones entre esquemas diferentes.

Si una restricción de version>= declarada usa un esquema de versión diferente al usado en la versión de línea base, vcpkg no puede determinar qué versión es mayor o igual que la otra.

Por ejemplo, si especifica:

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

vcpkg genera el siguiente mensaje de error:

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.

Resoluciones:

1. Use un esquema de versión compatible:
   • Inspeccione la base de datos de versiones en el repositorio vcpkg en versions/b-/boost-regex.json para buscar una versión de boost-regex que use el mismo esquema de control de versiones que la línea base.
   • Actualice la restricción version>= de la vcpkg.json a una versión que use un esquema compatible.
2. Anule a la versión deseada:
   • Si necesita una versión específica de boost-regex que emplee un esquema de versionado diferente, puede anular esta configuración en su manifiesto.
   • Modifique su vcpkg.json para incluir una sección overrides especificando la versión deseada:

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

Causa: Historial de confirmaciones inadecuado en un clon superficial

Cuando vcpkg se clona con un historial de confirmaciones limitado (clon superficial), carece del historial de confirmaciones necesario para resolver restricciones de versión específicas o líneas base. Los hashes de objeto de árbol de Git usados por vcpkg para recuperar versiones específicas de puertos solo están disponibles cuando se ha extraído el historial de confirmaciones completo. vcpkg detecta cuándo se ha clonado en un repositorio poco profundo y genera un mensaje de error cuando no puede recuperar versiones de puertos.

Por ejemplo, utilizando un vcpkg.json con una línea base específica como esta:

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

Se producirá el siguiente error:

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 error indica que la confirmación (4f8427eb0bd40da1856d4e67bde39a4fda689d72) necesaria para la versión específica del paquete fmt no está disponible en el clon superficial.

Resoluciones:

1. Convertir a un clon completo

   • La solución más fácil a este problema es convertir a clonación completa:

   git fetch --unshallow
   

2. Uso de las acciones de GitHub (clones superficiales por defecto)

   • Las Acciones de GitHub a menudo utilizan por defecto clones superficiales. Para solucionar este problema, puede modificar el flujo de trabajo de Acciones de GitHub para realizar un clon completo. Agregue el paso siguiente antes de usar vcpkg:

   - name: Convert to Full Clone
     run: git fetch --unshallow
   

Causa: Inclusión inesperada de características predeterminadas en dependencias transitivas

Al administrar dependencias con vcpkg, es posible que encuentre que las dependencias transitivas se instalan con sus características predeterminadas, incluso cuando es posible que no desee esas características para el proyecto. Esta situación puede llevar a una sobrecarga o funcionalidad inesperada en tu compilación final.

Escenario

Usted tiene una dependencia de la biblioteca Y, que a su vez depende de la biblioteca X. La biblioteca X tiene características predeterminadas, como foo, que desea excluir del proyecto. El manifiesto de nivel superior de la biblioteca Y podría tener un aspecto similar al siguiente:

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

Espera que X se instale sin las funciones predeterminadas debido a la configuración de "default-features": false. Sin embargo, X todavía está instalado con la característica predeterminada foo.

Razón

La propiedad default-features solo se tiene en cuenta en el manifiesto de nivel superior. Esto significa que las características predeterminadas de dependencias transitivas (como X en este escenario) se siguen incluyendo a menos que se deshabilite explícitamente en el nivel superior. Cuando se resuelve la biblioteca Y, vcpkg no propaga "default-features": false a la dependencia transitiva X, lo que resulta en la instalación de X con sus características predeterminadas.

Resolución

Para asegurarse de que las dependencias transitivas como X estén instaladas sin sus características predeterminadas, debe promoverlas para dirigir las dependencias en el manifiesto de nivel superior y deshabilitar explícitamente sus características predeterminadas. Modifique el vcpkg.json para incluir X directamente con "default-features": false:

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

Este enfoque garantiza que X esté instalado sin sus características predeterminadas, ya que ahora X es una dependencia directa con una instrucción explícita para excluir las características predeterminadas.

Para obtener información más detallada sobre cómo funcionan las características predeterminadas y cómo administrarlas, consulte el artículo concepto de características predeterminadas artículo.

El problema no aparece aquí

Si la incidencia no está aquí, visite nuestro repositorio para abrir una nueva incidencia.