Partilhar via

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

Depois de configurar um registro personalizado de portas vcpkg, convém adicionar a Integração Contínua (CI) 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 o Azure DevOps Pipelines. Isso garante que a adição de novos pacotes ou a atualização dos existentes não quebre 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 fluxo de trabalho de CI para seu registro em execução no GitHub Actions:

  • 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

Testar 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 usar o CI para os seus ports, invista na configuração de um cache binário e um cache de ativos para os seus fluxos de trabalho do GitHub Actions.

Um cache binário fornece o maior benefício para cenários de CI, garantindo que pacotes não modificados não sejam reconstruídos 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, um URL de download quebrado.

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 binário e de ativos em um fluxo de trabalho do GitHub Actions

env:
  FEED_URL: https://nuget.pkg.github.com/<OWNER>/index.json

steps:
  - name: Install vcpkg ports
    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;nuget,https://nuget.pkg.github.com/<OWNER>/index.json,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 no VCPKG. Neste exemplo, ele é definido como x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite. O x-azurl backend instrui o vcpkg a usar um contentor de Armazenamento do Azure como o fornecedor de armazenamento. O x-azurl é seguido por três parâmetros separados por vírgulas (,).

  • https://my.domain.com/container é um URL de contêiner de armazenamento.
  • {{secrets.SAS}} é uma variável secreta de Ações do GitHub que contém um token SAS para autenticação 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 nas etapas do fluxo de trabalho do GitHub Actions as-is. Esta etapa exporta duas variáveis de ambiente exigidas pelo back-end para funcionar e deve ser executada 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 o cache de ativos e os recursos de 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 seu registro. Você pode decidir se este fluxo de trabalho é executado em um horário programado ou se é acionado por novos commits ou pull requests.

O registro vcpkg principal 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 testar os seus próprios registos vcpkg. Em vez disso, recomendamos seguir as etapas descritas neste artigo.

Use um arquivo de manifesto para incluir todas as suas portas

Em vez de usar o vcpkg ci comando, sugerimos usar um arquivo de manifesto 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 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 artigos de referência vcpkg.json e vcpkg-configuration.json para saber mais. Consulte 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

Uma vez concluídas estas etapas, deverá ter um ficheiro executável vcpkg com o qual 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 alguns passos acima. O motivo é que você deseja testar a versão das portas atualmente no diretório de trabalho, em oposição às versões publicadas no repositório.

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

O trecho abaixo mostra como configurar as portas do registro como portas 'overlay' e executar vcpkg install no modo de manifesto para instalar todas as suas 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, 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

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

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

Próximos passos

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