Compartir a través de

Conceptos de registros

  • Artículo

Visión general

vcpkg hospeda una selección de bibliotecas empaquetadas en puertos en https://github.com/Microsoft/vcpkg. Esta colección de puertos se denomina registro mantenido. Sin embargo, vcpkg no se limita al registro curado. Los usuarios pueden ampliar la selección de puertos mediante la creación de registros personalizados.

Un registro es una colección de puertos y archivos auxiliares organizados en una estructura específica. Siguiendo la estructura del registro, los puertos contenidos en un registro se pueden instalar con las mismas características (control de versiones, almacenamiento en caché binario) que se ofrecen a los puertos del registro gestionado.

Actualmente hay tres tipos de registros:

Mediante un archivo vcpkg-configuration.json, se le puede indicar a vcpkg que tenga en cuenta los puertos disponibles en los registros personalizados. Consulte el artículo Tutorial: Instalación de una dependencia desde un registro basado en Git para ver un tutorial sobre cómo usar registros personalizados en los proyectos.

Estructura del Registro

Para que vcpkg se interfaz con un registro, debe ajustarse a la estructura siguiente:

  • Un directorio denominado ports contiene la colección de puertos, con cada subdirectorio que contiene un puerto específico que coincide con el nombre del subdirectorio. Por ejemplo, los archivos del puerto foo se encuentran en ports/foo.
  • Un directorio denominado versions contiene los archivos que componen la base de datos versiones.

Ejemplo: estructura del Registro

ports/
  foo/
    portfile.cmake
    vcpkg.json
versions/
  f-/
    foo.json
  baseline.json

Base de datos de versiones

Todos los registros contienen un directorio versions en la raíz del registro que contiene la base de datos de versiones de .

Hay dos componentes en la base de datos de versiones:

  • El archivo de línea base
  • Los archivos de versión

El archivo de línea base es un archivo JSON denominado baseline.json ubicado en la raíz del directorio versions.

Los archivos de versiones son archivos JSON con los mismos nombres que los puertos disponibles. Deben existir en versions/<prefix>/<port name>.json, donde <prefix> es la primera letra del nombre del puerto seguido de un guion. Por ejemplo, el archivo de versiones del puerto foo debe estar en versions/f-/foo.json.

El propósito del archivo de versiones es doble:

  • Enumerar todas las versiones disponibles de cada puerto
  • Indique los puntos de recuperación de cada versión.

El formato del archivo de versión depende del tipo del registro.

Archivo de línea base

Todos los registros, independientemente de su tipo, deben contener un archivo denominado baseline.json ubicado en versions/baseline.json.

El propósito del archivo de línea base es describir el conjunto de versiones que se consideran la más reciente para todos los puertos del Registro. Se espera que este archivo se actualice cada vez que se agregue una nueva versión de un puerto al registro.

El archivo es un archivo JSON compuesto por un único objeto cuyas propiedades se denominan objetos de línea base. Las propiedades de cada objeto de línea base son nombres de puerto, cuyos valores son entradas de versión. En el artículo de referencia de los registros se describe el diseño de los archivos de línea base con más detalle.

Cada entrada de versión de línea base es un objeto con las siguientes propiedades:

  • baseline: el valor es la versión del puerto que coincide con su archivo vcpkg.json correspondiente.
  • port-version: el valor es el port-version del puerto que coincide con su correspondiente archivo de vcpkg.json.

Archivo de ejemplo de línea base

{
  "default": {
    "foo": { "baseline": "1.0.0", "port-version": 0 },
    "bar": { "baseline": "2024-08-01", "port-version": 1 },
    "baz": { "baseline": "vista-xp", "port-version": 0 }
  }
}

Consulte la documentación de referencia para:

  • Diseño de archivo de línea base para registros de Git
  • Estructura básica de archivos para los registros del sistema de archivos

Archivos de versiones

Cada puerto del Registro tiene un archivo de versiones correspondiente. Los archivos de versiones se almacenan en versions/<prefix>/<port name>.json , donde <prefix> es la primera letra del nombre del puerto seguido de un guión. Por ejemplo, el archivo de versiones del puerto foo está en versions/f-/foo.json.

El propósito del archivo de versiones es doble:

  • Enumerar todas las versiones disponibles de cada puerto
  • Indicar las ubicaciones de recuperación de cada una de estas versiones

El diseño del archivo de versiones es un objeto que contiene una matriz de "versions", y cada entrada de esa matriz es un objeto de versión. Un objeto de versión debe contener las siguientes propiedades:

  • Una propiedad de versión: la clave y el valor de la propiedad deben coincidir con las usadas por el puerto en su archivo vcpkg.json. La clave debe ser una de version, version-semver, version-dateo version-string; el valor debe ser la versión tal como aparece en el archivo de manifiesto del puerto (vcpkg.json).
  • port-version: el valor es el port-version del puerto tal como aparece en el archivo vcpkg.json del puerto.
  • git-tree: (solo en los registros de Git) el valor es el SHA del árbol de Git correspondiente al directorio del puerto. Se trata de un SHA calculado mediante el hash del contenido del directorio del puerto; Git puede usar este SHA de árbol de Git para recuperar el contenido del puerto que coincide con el árbol de Git proporcionado. Esto permite que vcpkg recupere versiones anteriores de los puertos del historial de Git de registros. Lea la sección registros de Git para obtener este valor para cualquier versión de puerto determinada.
  • path: (solo en los registros del sistema de archivos) el valor es la ruta de acceso completa a un directorio que contiene los archivos de puerto de la versión específica.

Ejemplo de un archivo de versión del registro del sistema de archivos

{
  "versions": [
    {
      "path": "$/ports/foo/1.2.0",
      "version": "1.2.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.1.0",
      "version": "1.1.0",
      "port-version": 0
    },
    {
      "path": "$/ports/foo/1.0.0",
      "version": "1.0.0",
      "port-version": 0
    }
  ]
}

Consulte la documentación de referencia para:

Registro integrado

El registro integrado es un tipo especial de registro. Es el registro predeterminado usado en modo clásico. En modo manifiesto, sin especificar un registro predeterminado, vcpkg usa implícitamente el registro integrado.

El registro integrado se refiere a la copia local del registro mantenido que se crea cuando git clone el repositorio vcpkg de https://github.com/Microsoft/vcpkg. Algunas operaciones esperan que la variable de entorno VCPKG_ROOT apunte a un registro integrado.

Si vcpkg se adquiere a través del "one liner" o el instalador de Visual Studio, el registro integrado se convierte en equivalente a un registro de Git de que apunta al repositorio de https://github.com/Microsoft/vcpkg.

Registros de Git

Un registro de Git es un repositorio que sigue la estructura del registro y aprovecha las funcionalidades de Git para proporcionar control de versiones para los puertos del registro. El registro curado en https://github.com/Microsoft/vcpkg es una implementación de un registro de Git.

Los registros de Git se pueden hospedar en cualquier proveedor de repositorios de Git, lo que le permite usar el servicio de hospedaje de Git elegido para controlar el acceso al registro personalizado, a la vez que facilita el uso compartido del registro.

Los registros de Git son el método recomendado para implementar un registro personalizado. Dado que el mecanismo de control de versiones es el mismo que usa el registro mantenido, los registros de Git pueden usar el x-add-version para administrar los archivos de base de datos de versiones.

Consulte la referencia de registros para obtener detalles sobre la implementación de los registros de Git.

Agregar una nueva versión a un registro de Git

El comando x-add-version se puede usar para agregar un puerto nuevo o una nueva versión al Registro. Al agregar versiones con este comando, hay un par de cosas que debe tener en cuenta:

Importante

Al agregar una nueva versión, recuerde actualizar siempre la versión declarada del puerto a una no publicada, para evitar volver a escribir el historial de versiones.

Al realizar cambios en un puerto, el primer paso debe ser aumentar su versión en el archivo vcpkg.json. Si los cambios incluyen una actualización de la versión ascendente del paquete, recuerde establecer el port-version en 0; de lo contrario, recuerde aumentar el port-version por uno.

El comando x-add-version requiere que todos los cambios de puerto se confirmen en el repositorio antes de actualizar la base de datos de versión.

Ejemplo: adición de una nueva versión de puerto a un registro de Git

git add ports/foo/.
git commit -m "Temporary commit"
vcpkg x-add-version --x-builtin-ports-root=./ports --x-builtin-registry-versions-dir=./versions foo
added version 1.0.0#1 to path/to/registry/versions/f-/foo.json
added version 1.0.0#1 to path/to/registry/versions/baseline.json

Las opciones de redireccionamiento --x-builtin-ports-root y --x-builtin-registry-versions-dir deben apuntar a los directorios de ports y versions del registro, respectivamente.

Una vez que el comando x-add-version se ejecuta correctamente, modifique la última confirmación para incluir los cambios en el archivo de versiones.

git commit --amend -m "Update foo to new version"

Registros del sistema de archivos

Los registros del sistema de archivos son una implementación de un registro que reside en un sistema de archivos. Siguen la estructura del Registro común, pero no hacen uso de Git para ofrecer funcionalidades de control de versiones. En su lugar, usan una forma primitiva de control de versiones mediante una ruta de acceso distinta para cada versión de sus puertos.

Este tipo de registro es adecuado para ser un terreno de prueba para los puertos o para proporcionar una alternativa para un registro en un sistema de control de versiones que no es de Git. Los registros del sistema de archivos no se recomiendan para una gran colección de puertos y no se proporciona ninguna herramienta para manipular los archivos de base de datos de versión para este tipo de registro.

Consulte la referencia de registros de para obtener más información sobre cómo implementar un registro de sistema de archivos.

Consumo de registros

Para consumir un registro personalizado en su proyecto, debe crear un archivo de configuración (vcpkg-configuration.json) junto al archivo de manifiesto (vcpkg.json) de su proyecto.

Registro predeterminado

Al resolver nombres de puerto, el registro predeterminado funciona como reserva cuando el nombre de un puerto no coincide con ninguno de los patrones de paquete declarados por otros registros de la matriz registries.

Como comodidad para los usuarios que no interactúan con registros personalizados, vcpkg agrega implícitamente el registro integrado como registro predeterminado. Para cambiar este comportamiento, el registro predeterminado se puede establecer en cualquier registro o deshabilitarse completamente mediante el Propiedad default-registry.

Ejemplo: Establecimiento de un registro personalizado como predeterminado

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  }
}

Ejemplo: Deshabilitar el registro predeterminado

vcpkg-configuration.json

{
  "default-registry": null
}

Matriz de registros

Para ampliar la selección de puertos disponibles para instalar con vcpkg, puede especificar registros adicionales mediante la matriz registries.

Ejemplo: Adición de registros personalizados a la configuración

Nota

Según el tipo de registro, es posible que tenga que proporcionar información diferente en la matriz registries. Consulte la referencia de vcpkg-configurtion.json para saber qué propiedades son necesarias para cada tipo de registro.

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/Microsoft/vcpkg",
    "baseline": "84a143e4caf6b70db57f28d04c41df4a85c480fa"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://my.privateregistry.git",
      "baseline": "caf6b70db5784a143e4f28d05c480fa4c41df4a8",
      "packages": [ "foo" ]
    },
    {
      "kind": "filesystem",
      "path": "C:/path/to/registry",
      "baseline": "baseline1",
      "packages": [ "bar" ]
    }
  ]
}

No reescribir el historial de versiones

Una vez publicada una versión en los archivos de versiones, no cambie su git-tree asociado en un registro o directorio de Git en un registro del sistema de archivos.

Uno de los principios de diseño de vcpkg es que las versiones de las dependencias instaladas no cambian sin intervención del usuario. Al volver a escribir el historial de archivos de versiones, el cambio de una entrada de git-tree infringe este principio.

Si la versión existente tiene problemas, prefiera crear un nuevo port-version.

No elimine archivos de versiones

Nota

Esta sección solo se aplica a registros de Git

Al quitar un puerto del registro, quite su contenido del directorio ports y su entrada en el archivo de línea base. Pero no quite su archivo de versiones asociado.

Incluso si ya no existe un puerto en el Registro, siempre y cuando el archivo de versiones permanezca, los usuarios del puerto pueden instalar versiones anteriores mediante versión overrides.

Pasos siguientes

Estas son algunas tareas que se van a probar a continuación: