Compartilhar via

Testar suas portas de registro personalizadas usando vcpkg com ações do GitHub

  • Artigo

Depois de configurar um registro personalizado de portas vcpkg, convém adicionar a Integração Contínua para validar que todas as suas dependências podem ser criadas com êxito.

O registro vcpkg principal na Microsoft/vcpkg é testado pela equipe vcpkg usando a integração contínua (CI) com o Azure DevOps. Isso garante que adicionar novos pacotes ou atualizar os existentes não prejudique os consumidores.

Neste artigo, mostramos como configurar um ambiente de CI para testar as portas vcpkg em seu próprio registro.

Neste artigo, você aprenderá a:

  • Configurar um cache binário e um cache de ativos para seus fluxos de trabalho do GitHub Actions
  • Configurar um fluxo de trabalho para testar as portas do Registro

Pré-requisitos

Configurar um cache binário e um cache de ativos para seus fluxos de trabalho do GitHub Actions

Construir uma grande coleção de portas é uma tarefa cara tanto em termos de tempo quanto de poder de computação. É altamente recomendável que, antes de contratar o CI para suas portas, você invista na configuração de um cache binário e um cache de ativos para seus fluxos de trabalho do GitHub Action.

Um cache binário fornece o maior benefício para cenários de CI, garantindo que pacotes não modificados não sejam recriados em cada execução de CI. Um cache de ativos espelha artefatos baixados para seus pacotes durante uma execução e usa os artefatos armazenados em cache em execuções subsequentes. Ele também pode ajudar a mitigar problemas em que o repositório upstream não é confiável: por exemplo, uma URL de download quebrada.

Para obter instruções detalhadas sobre como configurar esses caches, leia nossos artigos sobre cache binário e cache de ativos.

Exemplo: Habilitar o cache de ativos e binários em um fluxo de trabalho de Ações do 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"

Este exemplo mostra como configurar um cache binário e um cache de ativos em um fluxo de trabalho de Ações do GitHub. Você deve adaptar esse trecho para usar no arquivo YAML do seu próprio fluxo de trabalho.

Detalhando este trecho:

X_VCPKG_ASSET_SOURCES é a variável de ambiente usada para configurar caches de ativos em VCPKG. Neste exemplo, ele é definido como x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. O x-azurl back-end instrui vcpkg a usar um contêiner de Armazenamento do Azure como o provedor de armazenamento. O x-azurl é seguido por três parâmetros separados por vírgulas (,).

  • https://my.domain.com/container é uma URL de contêiner de armazenamento.
  • {{secrets.SAS}} é uma variável secreta GitHub Actions que contém um token SAS para autenticar no contêiner de armazenamento.
  • readwrite Define permissões de leitura e gravação para o cache de ativos. Isso significa que esse cache de ativos é usado para armazenar artefatos, bem como para restaurar artefatos a partir dele.

VCPKG_BINARY_SOURCES é a variável de ambiente usada para configurar caches binários em vcpkg. Neste exemplo, ele é definido como clear;x-gha,readwrite. Isso habilita o back-end do Cache de Ações do GitHub para o cache binário. Uma etapa extra é necessária em seu fluxo de trabalho para habilitar esse back-end com êxito.

A etapa a seguir deve ser incluída no estado em que se encontra nas etapas do fluxo de trabalho da Ação do GitHub. Esta etapa exporta duas variáveis de ambiente exigidas pelo back-end para funcionar e devem ser executadas antes de qualquer tarefa que envolva x-gha 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 || '');

Saiba mais sobre como tudo isso funciona lendo a documentação sobre os recursos de cache de ativos e cache binário.

Configurar um fluxo de trabalho para testar as portas do Registro

Depois de configurar um cache binário e um cache de ativos para seu ambiente de CI, a próxima etapa é configurar um fluxo de trabalho para testar todas as portas do Registro. Você pode decidir se esse fluxo de trabalho é executado em uma agenda ou se é acionado por novas confirmações ou solicitações pull.

O registro principal vcpkg usa o vcpkg ci comando, que foi adaptado às necessidades do projeto vcpkg e não se destina a permanecer estável ou ser usado por consumidores de vcpkg. Como tal, não é adequado para usar para testar seus próprios registros vcpkg. Em vez disso, recomendamos seguir as etapas descritas neste artigo.

Usar um arquivo de manifesto para incluir todas as portas

Em vez de usar o comando, sugerimos usar um arquivo de manifesto vcpkg ci para criar uma compilação que depende de todos os pacotes em seu registro.

O exemplo a seguir cria um arquivo de manifesto para testar todas as portas em um registro vcpkg hipotético. Substitua a lista de dependências para incluir todas as portas no registro e coloque-a na raiz do repositório.

vcpkg.json

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

Suas próprias portas podem ter dependências no registro vcpkg principal ou em outros registros de terceiros, nesse caso, você precisa adicionar esses registros em um vcpkg-configuration.json arquivo. Embora o vcpkg possa resolver pacotes do registro principal sem configuração adicional, é altamente recomendável adicioná-lo explicitamente à lista de registros para fins de controle de versão. Isso garante que você tenha controle do conjunto de versões de porta subjacentes. Confira o vcpkg x-update-baseline comando para ajudar a gerenciar a linha de base de seus registros.

vcpkg-configuration.json

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

Leia os vcpkg.json artigos e vcpkg-configuration.json referências para saber mais. E a documentação do modo manifesto para saber como eles funcionam juntos.

Adquira vcpkg em seu fluxo de trabalho de Ações do GitHub

Em seguida, você precisa adquirir vcpkg para usá-lo em seu fluxo de trabalho. Adicione as seguintes etapas para instalar o 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

Depois que essas etapas forem concluídas, você deve ter um executável vcpkg para trabalhar.

Execute vcpkg install para construir suas portas

O último passo é dizer ao vcpkg para construir todas as suas portas. Você pode ter notado que seu próprio registro está ausente do vcpkg-configuration.json criado um par de etapas acima. O motivo é que você deseja testar a versão das portas atualmente no diretório de trabalho, em vez das versões publicadas em seu repositório.

Para esse objetivo, você precisa adicionar as portas do Registro como portas de sobreposição, definindo a variável de ambiente para o VCPKG_OVERLAY_PORTS diretório do ports Registro.

O trecho abaixo mostra como configurar as portas do Registro como portas de sobreposição e é executado vcpkg install no modo manifesto para instalar todas as portas personalizadas.

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

Neste exemplo, assumimos que o vcpkg.json arquivo é criado na raiz do repositório do seu registro.

Juntando tudo isso, o arquivo YAML do seu fluxo de trabalho deve ser semelhante a este:

.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

Essa é a estrutura básica de um fluxo de trabalho de CI para testar as portas do Registro. Você pode precisar de algum trabalho extra para se autenticar em repositórios privados ou em seu feed NuGet.

Você também pode adicionar etapas para automatizar a vcpkg.json geração do arquivo ou uma etapa que verifica se as portas recém-adicionadas ao registro não são deixadas de fora dos testes.

Próximas etapas

Os artigos a seguir podem ser úteis para você ao configurar um ambiente de CI.