Compartir a través de

Prueba de los puertos del Registro personalizados mediante vcpkg con Acciones de GitHub

  • Artículo

Una vez que haya configurado un registro personalizado de puertos vcpkg, es posible que quiera agregar Continous Integration para validar que todas las dependencias se pueden compilar correctamente.

El equipo de vcpkg prueba el registro vcpkg principal de Microsoft/vcpkg mediante la integración continua (CI) con Azure DevOps. Esto garantiza que agregar nuevos paquetes o actualizar los existentes no interrumpa a los consumidores.

En este artículo, le mostramos cómo configurar un entorno de CI para probar los puertos vcpkg en su propio registro.

En este artículo aprenderá lo siguiente:

  • Configuración de una caché binaria y una caché de recursos para los flujos de trabajo de Acciones de GitHub
  • Configuración de un flujo de trabajo para probar los puertos del registro

Requisitos previos

Configuración de una caché binaria y una caché de recursos para los flujos de trabajo de Acciones de GitHub

La creación de una gran colección de puertos es una tarea costosa tanto en términos de tiempo como de potencia informática. Se recomienda encarecidamente que antes de interactuar con ci para los puertos, invierta en configurar una caché binaria y una caché de recursos para los flujos de trabajo de acción de GitHub.

Una caché binaria proporciona la mayor ventaja para los escenarios de CI al garantizar que los paquetes sin modificar no se vuelvan a compilar en cada ejecución de CI. Una caché de recursos refleja los artefactos descargados para los paquetes durante una ejecución y usa los artefactos almacenados en caché en ejecuciones posteriores. También puede ayudar a mitigar los problemas en los que el repositorio ascendente no es confiable: por ejemplo, una dirección URL de descarga interrumpida.

Para obtener instrucciones detalladas sobre cómo configurar estas cachés, lea nuestros artículos de almacenamiento en caché binario y almacenamiento en caché de recursos.

Ejemplo: Habilitación del almacenamiento en caché binario y de recursos en un flujo de trabajo de Acciones de GitHub

steps:
  - name: Enable GitHub Actions Cache backend
    uses: actions/github-script@v7
    with:
      script: |
        core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
        core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

  - name: some vcpkg task
    run: "${{ github.workspace }}/vcpkg/vcpkg install"
    env: 
      X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,{{ secrets.SAS }},readwrite"
      VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"

En este ejemplo se muestra cómo configurar una caché binaria y una caché de recursos en un flujo de trabajo de Acciones de GitHub. Debe adaptar este fragmento de código para usarlo en el archivo YAML de su propio flujo de trabajo.

Desglosar este fragmento de código:

X_VCPKG_ASSET_SOURCES es la variable de entorno que se usa para configurar las cachés de recursos en vcpkg. En este ejemplo, se establece en x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. El x-azurl back-end indica a vcpkg que use un contenedor de Azure Storage como proveedor de almacenamiento. x-azurl Va seguido de tres parámetros separados por comas (,).

  • https://my.domain.com/container es una dirección URL del contenedor de almacenamiento.
  • {{secrets.SAS}} es una variable secreta de Acciones de GitHub que contiene un token de SAS para autenticarse en el contenedor de almacenamiento.
  • readwrite establece permisos de lectura y escritura para la caché de recursos. Esto significa que esta caché de recursos se usa para almacenar artefactos, así como para restaurar artefactos a partir de él.

VCPKG_BINARY_SOURCES es la variable de entorno que se usa para configurar cachés binarias en vcpkg. En este ejemplo, se establece en clear;x-gha,readwrite. Esto habilita el back-end de caché de acciones de GitHub para la caché binaria. Se requiere un paso adicional en el flujo de trabajo para habilitar este back-end correctamente.

El siguiente paso debe incluirse tal como está en los pasos de flujo de trabajo de acción de GitHub. Este paso exporta dos variables de entorno necesarias para que el x-gha back-end funcione y debe ejecutarse antes de cualquier tarea que implique vcpkg.

- name: Enable GitHub Actions Cache backend
  uses: actions/github-script@v7
  with:
  script: |
    core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
    core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

Obtenga más información sobre cómo funcionan todos estos elementos; para ello, lea la documentación sobre las características de caché de recursos y caché binaria.

Configuración de un flujo de trabajo para probar los puertos del registro

Después de configurar una caché binaria y una caché de recursos para el entorno de CI, el siguiente paso es configurar un flujo de trabajo para probar todos los puertos del registro. Puede decidir si este flujo de trabajo se ejecuta según una programación o si se desencadena mediante nuevas confirmaciones o solicitudes de incorporación de cambios.

El registro vcpkg principal usa el vcpkg ci comando , que se ha adaptado a las necesidades del proyecto vcpkg y no está pensado para permanecer estable o ser utilizado por los consumidores de vcpkg. Por lo tanto, no es adecuado usar para probar sus propios registros de vcpkg. Se recomienda seguir los pasos descritos en este artículo en su lugar.

Usar un archivo de manifiesto para incluir todos los puertos

En lugar de usar el vcpkg ci comando , se recomienda usar un archivo de manifiesto para crear una compilación que dependa de todos los paquetes del registro.

En el ejemplo siguiente, se crea un archivo de manifiesto para probar todos los puertos de un registro hipotético de vcpkg. Reemplace la lista de dependencias para incluir todos los puertos del registro y colóquelo en la raíz del repositorio.

vcpkg.json

{
  "dependencies": [
    "beicode",
    "beison"
  ]
}

Sus propios puertos pueden tener dependencias en el registro vcpkg principal u otros registros de terceros, en cuyo caso, debe agregar esos registros en un vcpkg-configuration.json archivo. Aunque vcpkg puede resolver paquetes del registro principal sin configuración adicional, se recomienda agregarlos explícitamente a la lista de registros con fines de control de versiones. Esto garantiza que tiene el control del conjunto de versiones de puerto subyacentes. Consulte el vcpkg x-update-baseline comando para ayudar a administrar la línea base de los registros.

vcpkg-configuration.json

{
  "default-registry": null,
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/Microsoft/vcpkg",
      "baseline": "42bb0d9e8d4cf33485afb9ee2229150f79f61a1f",
      "packages": ["*"]
    }
  ]
}

Lea los vcpkg.json artículos de referencia y vcpkg-configuration.json para obtener más información. Y la documentación del modo de manifiesto para obtener información sobre cómo funcionan conjuntamente.

Adquisición de vcpkg en el flujo de trabajo de Acciones de GitHub

A continuación, debe adquirir vcpkg para usarlo en el flujo de trabajo. Agregue los pasos siguientes para instalar vcpkg.

steps:
- uses: actions/checkout@v4
  with:
    repository: "https://github.com/Microsoft/vcpkg"
    path: "vcpkg"

- name: Bootstrap vcpkg
  run: "${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh"
  shell: bash

Una vez completados estos pasos, debe tener un archivo ejecutable vcpkg con el que trabajar.

Ejecución de la instalación de vcpkg para compilar los puertos

El último paso es indicar a vcpkg que compile todos los puertos. Es posible que haya observado que su propio registro no está presente en el vcpkg-configuration.json creado un par de pasos anteriores. El motivo es que desea probar la versión de los puertos que se encuentran actualmente en el directorio de trabajo, en lugar de las versiones publicadas en el repositorio.

Para ese objetivo, debe agregar los puertos del Registro como puertos de superposición estableciendo la variable de entorno en el VCPKG_OVERLAY_PORTS directorio del ports registro.

En el fragmento de código siguiente se muestra cómo configurar los puertos del registro como puertos de superposición y se ejecuta vcpkg install en modo de manifiesto para instalar todos los puertos personalizados.

  - name: some vcpkg task
    run: "${{ github.workspace }}/vcpkg/vcpkg install"
    env: 
      X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,{{ secrets.SAS }},readwrite"
      VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
      VCPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"

En este ejemplo se supone que el vcpkg.json archivo se crea en la raíz del repositorio del registro.

La colocación de todo el archivo YAML del flujo de trabajo debe tener un aspecto similar al siguiente:

.github/workflows/test-ports.yml

name: Test vcpkg ports

on:
  push:
    branches: ["main"]
  pull_request:
    branches: ["main"]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4
    
    - name: Acquire vcpkg
      uses: actions/checkout@v4
      with:
        repository: "Microsoft/vcpkg"
        path: vcpkg

    - name: Bootstrap vcpkg
      run: "${{ github.workspace }}/vcpkg/bootstrap-vcpkg.sh"
      shell: bash

    - name: Enable GitHub Actions Cache backend
      uses: actions/github-script@v7
      with:
        script: |
          core.exportVariable('ACTIONS_CACHE_URL', process.env.ACTIONS_CACHE_URL || '');
          core.exportVariable('ACTIONS_RUNTIME_TOKEN', process.env.ACTIONS_RUNTIME_TOKEN || '');

    - name: Build ports
      run: ${{ github.workspace }}/vcpkg/vcpkg install
      env:
        X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://your.domain.com/container,${{ secrets.SAS }},readwrite"
        VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
        VCPKG_OVERLAY_PORTS: "${{ github.workspace }}/ports"
      shell: bash

Esta es la estructura básica de un flujo de trabajo de CI para probar los puertos del registro. Es posible que necesite algún trabajo adicional para autenticarse en repositorios privados o en la fuente de NuGet.

También puede agregar pasos para automatizar la generación del vcpkg.json archivo o un paso que compruebe que los puertos recién agregados al registro no se quedan fuera de las pruebas.

Pasos siguientes

Los artículos siguientes pueden resultarle útiles al configurar un entorno de CI.