Leer en inglés

Compartir a través de


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

Esta guía está pensada para los usuarios que experimentan problemas con el control de versiones.

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

Nota

El proceso que se describe a continuación está diseñado para funcionar para los puertos del registro vcpkg. Consulte nuestra documentación del Registro para obtener información sobre cómo se implementa la base de datos de control de versiones en registros personalizados.

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 abrir 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 fmt versiones se denomina fmt.json.

El archivo de versión del puerto contiene una lista de versiones disponibles con detalles como etiquetas de versión y su hash de objeto de árbol de Git correspondiente. 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:

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, ejecute el git pull comando para actualizar el registro vcpkg a la confirmación más reciente.
  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 vcpkg.json archivo.
    • 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:
    • Vuelva a ejecutar el comando en el vcpkg install terminal o en el 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 vcpkg.json archivo para una dependencia usa un esquema de control de versiones diferente al usado en la versión de línea de base del repositorio vcpkg. Esto da como resultado un error ya que vcpkg no puede comparar versiones entre esquemas diferentes.

Si una restricción declarada version>= 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.

Soluciones:

  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 que use el mismo esquema de control de boost-regex versiones que la línea base.
    • Actualice la version>= restricción de a vcpkg.json una versión que use un esquema compatible.
  2. Invalide a la versión deseada:
    • Si necesita una versión específica de boost-regex que use un esquema de control de versiones diferente, puede invalidarlo en el manifiesto.
    • vcpkg.json Modifique para incluir una sección de invalidaciones que especifique la versión deseada:
    {
      "dependencies": [
        { "name": "boost-regex" }
      ],
      "overrides": [
        { "name": "boost-regex", "version": "1.75.0" }
      ]
    }
    

Causa: Historial de confirmaciones inadecuado en 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 desprotegió el historial de confirmaciones completo. vcpkg detecta cuándo se ha clonado en un repositorio superficial y genera un mensaje de error cuando no puede recuperar una versión del puerto.

Por ejemplo, mediante un vcpkg.json con una línea base específica, como la siguiente:

{
  "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.

Soluciones:

  1. Conversión 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 acciones de GitHub (clones superficial predeterminados)

    • Acciones de GitHub suele tener como valor predeterminado clones poco profundos. 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 provocar un sobredimensionamiento inesperado o funcionalidad en la compilación final.

Escenario

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 sus características predeterminadas debido a la "default-features": false configuración. Sin embargo, X todavía se instala con la característica foopredeterminada .

Motivo

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

Solució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. vcpkg.json Modifique 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 se instala sin sus características predeterminadas, ya que X 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 sobre el concepto de características predeterminadas.

El problema no aparece aquí

Si el problema no aparece aquí, visite nuestro repositorio para crear un nuevo problema.