Compartir a través de

Creación de registros

  • Artículo

Para obtener información sobre el consumo de registros, consulte Uso de registros.

Información general

Los registros son colecciones de puertos y sus versiones. Hay dos opciones principales de implementación para los registros, si desea crear sus propios registros: registros git y registros del sistema de archivos.

Los registros de Git son repositorios de Git simples y se pueden compartir pública o privadamente a través de mecanismos normales para los repositorios de Git. El repositorio vcpkg, por ejemplo, es un registro de Git.

Los registros del sistema de archivos están diseñados como más de un terreno de prueba. Dado que literalmente residen en el sistema de archivos, la única forma de compartirlos es a través de directorios compartidos. Sin embargo, los registros del sistema de archivos pueden ser útiles como una manera de representar registros mantenidos en sistemas de control de versiones que no son git, suponiendo que uno tiene alguna manera de obtener el registro en el disco.

Esperamos que el conjunto de tipos de registro crezca con el tiempo; Si desea admitir registros integrados en su sistema de control de versiones público favorito, no dude en abrir una solicitud de incorporación de cambios.

La estructura básica de un registro es:

  • Conjunto de versiones que se consideran "más recientes" en determinados momentos del historial, conocidos como "línea base".
  • Conjunto de todas las versiones de todos los puertos y dónde buscar cada uno de ellos en el Registro.

Registros de Git

Como sigue junto con esta documentación, puede resultar útil tener un ejemplo de trabajo al que hacer referencia. Hemos escrito uno y lo pusimos aquí:

Microsoft/vcpkg-docs: registro vcpkg.

Todos los registros de Git deben tener un versions/baseline.json archivo. Este archivo contiene el conjunto de "versiones más recientes" en una confirmación determinada. Se establece como un objeto de nivel superior que contiene solo el "default" campo. Este campo debe contener nombres de puerto de asignación de objetos a la versión más reciente.

Este es un ejemplo de un baseline.json válido:

{
  "default": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

El versions directorio contiene toda la información sobre qué versiones de los paquetes se incluyen en el Registro, junto con dónde se almacenan esas versiones. El resto del registro solo actúa como almacén de respaldo, en lo que respecta a vcpkg: solo se usarán cosas dentro del directorio para dirigir cómo vcpkg ve el versions registro.

Cada puerto de un registro debe existir en el directorio versions como <first letter of port>-/<name of port>.json; en otras palabras, la información sobre el kitten puerto se ubicaría en versions/k-/kitten.json. Debe ser un objeto de nivel superior con un solo campo: "versions". Este campo debe contener una matriz de objetos de versión:

  • La versión del puerto en cuestión; debe ser exactamente igual que el vcpkg.json archivo, incluidos los campos de versión y "port-version".
  • El "git-tree" campo , que es un árbol de Git; en otras palabras, lo que se obtiene al escribir git rev-parse COMMIT-ID:path/to/port.

El campo de versión de los puertos con archivos en desuso CONTROL es "version-string".

Advertencia

Una parte muy importante de los registros es que las versiones nunca deben cambiarse. La actualización a una referencia posterior nunca debe quitar ni cambiar una versión existente. Siempre debe ser seguro actualizar un registro.

Este es un ejemplo de una base de datos de versión válida para un kitten puerto con una versión:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

En general, no es importante colocar directorios de puertos. Sin embargo, la expresión en vcpkg es seguir lo que hace el registro vcpkg integrado: el kitten puerto debe colocarse en ports/kitten.

Advertencia

Otra cosa que hay que tener en cuenta es que, al actualizar un registro, también se debe tener acceso a todas las versiones anteriores. Dado que el usuario establecerá su línea base en un identificador de confirmación, ese identificador de confirmación siempre debe existir y ser accesible desde la confirmación head, que es lo que realmente se captura. Esto significa que la confirmación head debe ser un elemento secundario de todas las confirmaciones head anteriores.

Registros integrados

Los registros integrados se tratan como registros de Git especiales. En lugar de capturar desde una dirección URL remota, los registros integrados consultan el $VCPKG_ROOT/.git directorio del clon vcpkg. Usan el directorio desprotegido $VCPKG_ROOT/versions actualmente como origen para obtener información de control de versiones.

Adición de una nueva versión

Hay algunos trucos de Git implicados en la creación de una nueva versión de un puerto. Lo primero que debe hacer es realizar algunos cambios, actualizar el "port-version" campo de versión normal y según sea necesario y, a continuación, probar con overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten.

Una vez que haya terminado las pruebas, deberá asegurarse de que el directorio tal como está en purview de Git. Para ello, creará una confirmación temporal:

> git add ports/kitten
> git commit -m 'temporary commit'

A continuación, obtenga el identificador del árbol de Git del directorio:

> git rev-parse HEAD:ports/kitten
73ad3c823ef701c37421b450a34271d6beaf7b07

A continuación, puede agregar esta versión a la base de datos de versiones. En la parte superior de versions/k-/kitten.json, puede agregar (suponiendo que va a agregar la versión 2.6.3#0):

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "git-tree": "73ad3c823ef701c37421b450a34271d6beaf7b07"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "git-tree": "67d60699c271b7716279fdea5a5c6543929eb90e"
    }
  ]
}

A continuación, también querrá modificar versions/baseline.json con la nueva versión:

{
  "default": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  }
}

y modifique la confirmación actual:

> git commit --amend

entonces compartir lejos!

Registros del sistema de archivos

Como sigue junto con esta documentación, puede resultar útil tener un ejemplo de trabajo al que hacer referencia. Hemos escrito uno y lo pusimos aquí:

Registro de sistema de archivos de ejemplo.

Todos los registros del sistema de archivos deben tener un versions/baseline.json archivo. Este archivo contiene el conjunto de "versiones más recientes" para una determinada versión del Registro. Se presenta como un objeto de nivel superior que contiene un mapa del nombre de la versión a "objetos de línea base", que asigna los nombres de puerto a la versión que se considera "más reciente" para esa versión del Registro.

Los registros del sistema de archivos deben decidir sobre un esquema de control de versiones. A diferencia de los registros de Git, que tienen el esquema de control de versiones implícito de referencias, los registros del sistema de archivos no pueden confiar en el sistema de control de versiones aquí. Una posible opción es hacer una versión diaria y hacer que sus "versiones" sean fechas.

Advertencia

Una línea base no se debe modificar una vez publicada. Si desea cambiar o actualizar versiones, debe crear una nueva línea base en el baseline.json archivo.

Este es un ejemplo de un objeto válido baseline.jsonpara un registro que ha decidido fechas para sus versiones:

{
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

El versions directorio contiene toda la información sobre qué versiones de los paquetes se incluyen en el Registro, junto con dónde se almacenan esas versiones. El resto del registro solo actúa como almacén de respaldo, en lo que respecta a vcpkg: solo se usarán cosas dentro del directorio para dirigir cómo vcpkg ve el versions registro.

Cada puerto de un registro debe existir en el directorio versions como <first letter of port>-/<name of port>.json; en otras palabras, la información sobre el kitten puerto se ubicaría en versions/k-/kitten.json. Debe ser un objeto de nivel superior con un solo campo: "versions". Este campo debe contener una matriz de objetos de versión:

  • La versión del puerto en cuestión; debe ser exactamente igual que el vcpkg.json archivo, incluidos los campos de versión y "port-version".
  • El "path" campo: un directorio relativo, con raíz en la base del Registro (es decir, el directorio donde versions se encuentra) al directorio de puerto. Debería tener un aspecto similar "$/path/to/port/dira "

El campo de versión de los puertos con archivos en desuso CONTROL es "version-string".

En general, no es importante colocar directorios de puertos. Sin embargo, el idiom de vcpkg es seguir un poco a lo que hace el registro vcpkg integrado: el kitten puerto en versión x.y.z debe colocarse en ports/kitten/x.y.z, con versiones de puerto anexadas como se ajuste (aunque dado # que no es un buen carácter para usar para los nombres de archivo, quizás use _).

Advertencia

Una parte muy importante de los registros es que las versiones nunca deben cambiarse. Uno nunca debe quitar o cambiar una versión existente. Los cambios realizados en el registro no deben cambiar el comportamiento a los usuarios de nivel inferior.

Este es un ejemplo de una base de datos de versión válida para un kitten puerto con una versión:

{
  "versions": [
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

Agregar una nueva versión

A diferencia de los registros de Git, agregar una nueva versión a un registro de sistema de archivos implica principalmente una gran cantidad de copia. Lo primero que debe hacer es copiar la versión más reciente del puerto en un nuevo directorio de versión, actualizar la versión y "port-version" los campos según sea necesario y, a continuación, probar con overlay-ports:

vcpkg install kitten --overlay-ports=ports/kitten/new-version.

Una vez finalizada la prueba, puede agregar esta nueva versión a la parte superior de versions/k-/kitten.json:

{
  "versions": [
    {
      "version": "2.6.3",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.3_0"
    },
    {
      "version": "2.6.2",
      "port-version": 0,
      "path": "$/ports/kitten/2.6.2_0"
    }
  ]
}

A continuación, querrá modificar versions/baseline.json también con la nueva versión (recuerde no modificar las líneas base existentes):

{
  "2021-04-17": {
    "kitten": {
      "baseline": "2.6.3",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-16": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 2
    }
  },
  "2021-04-15": {
    "kitten": {
      "baseline": "2.6.2",
      "port-version": 0
    },
    "port-b": {
      "baseline": "19.00",
      "port-version": 1
    }
  }
}

¡Y ya está!