使用 vcpkg 搭配 GitHub Actions 測試自定義登錄埠

發行項
03/05/2024

設定 vcpkg 埠的自訂登錄後，您可能會想要新增連續整合，以驗證所有相依性都可以成功建置。

Microsoft/vcpkg 的主要 vcpkg 登錄是由 vcpkg 小組使用持續整合（CI）與 Azure DevOps 進行測試。這可確保新增套件或更新現有的套件不會中斷取用者。

在本文中，我們會說明如何設定 CI 環境，以在您自己的登錄中測試 vcpkg 埠。

在本文中，您將了解如何：

為您的 GitHub Actions 工作流程設定二進位快取和資產快取
設定工作流程以測試登錄的埠

必要條件

GitHub 帳戶
您自己的 vcpkg Git 登錄
完成二進位快取和資產快取教學課程。
GitHub Actions 工作流程的知識

為您的 GitHub Actions 工作流程設定二進位快取和資產快取

在時間和運算能力方面，建置大量的埠集合是一項昂貴的工作。我們強烈建議在為您的埠吸引 CI 之前，先投資為 GitHub Action 工作流程設定二進位快取和資產快取。

二進位快取可確保每次執行 CI 時都不會重建未修改的套件，以提供 CI 案例的最大好處。資產快取會鏡像在執行期間為套件下載的成品，並在後續執行中使用快取的成品。它也有助於減輕上游存放庫不穩定的問題：例如，中斷的下載 URL。

如需有關如何設定這些快取的詳細指示，請參閱我們的二進位快取和資產快取文章。

範例：在 GitHub Actions 工作流程中啟用資產和二進位快取

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"

此範例示範如何在 GitHub Actions 工作流程中設定二進位快取和資產快取。您應該調整此代碼段，以在您自己的工作流程 YAML 檔案上使用。

細分此代碼段：

X_VCPKG_ASSET_SOURCES 是用來在 vcpkg 中設定資產快取的環境變數。在這裡範例中，它會設定為 x-azurl,https://my.domain.com/container,{{secrets.SAS}},readwrite。後端x-azurl會指示 vcpkg 使用 Azure 儲存體容器作為記憶體提供者。 x-azurl後面接著三個以逗號分隔的參數（,）。

https://my.domain.com/container 是記憶體容器 URL。
{{secrets.SAS}} 是 GitHub Actions 秘密變數，其中包含要向記憶體容器驗證的 SAS 令牌。
readwrite 會設定資產快取的讀取和寫入許可權。這表示此資產快取可用來儲存成品，以及從中還原成品。

VCPKG_BINARY_SOURCES 是用來在 vcpkg 中設定二進位快取的環境變數。在這裡範例中，它會設定為 clear;x-gha,readwrite。這會啟用二進位快取的 GitHub Actions 快取後端。您的工作流程中需要額外的步驟，才能成功啟用此後端。

下列步驟應依目前方式包含在 GitHub Action 工作流程步驟中。此步驟會匯出後端需要運作的 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 || '');

閱讀資產快取和二進位快取功能的相關文件，深入瞭解所有這些工作方式。

設定工作流程以測試登錄的埠

在您為 CI 環境設定二進位快取和資產快取之後，下一個步驟是設定工作流程來測試所有登錄的埠。您可以決定此工作流程是否依排程執行，或是否由新的認可或提取要求觸發。

主要 vcpkg 登錄會使用 vcpkg ci 命令，該命令已針對 vcpkg 專案的需求量身打造，並不適合維持穩定或供 vcpkg 取用者使用。因此，它不適合用來測試您自己的 vcpkg 登錄。建議您改為遵循本文中所述的步驟。

使用指令清單檔案來包含所有埠

我們建議使用指令清單檔來建立相依於登錄中所有套件的組建，而不是使用 vcpkg ci 命令。

下列範例會建立指令清單檔，以測試假設 vcpkg 登錄中的所有埠。取代相依性清單，以在登錄中包含所有埠，並將它放在存放庫的根目錄中。

vcpkg.json

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

您自己的埠可能相依於主要 vcpkg 登錄或其他第三方登錄，在此情況下，您需要在檔案中 vcpkg-configuration.json 新增這些登錄。雖然 vcpkg 可以從主要登錄解析套件，而不需額外的設定，但我們強烈建議您明確地將其新增至登錄清單，以供版本控制之用。這可確保您可以控制一組基礎埠版本。請查看 vcpkg x-update-baseline 命令，以協助管理登錄的基準。

vcpkg-configuration.json

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

vcpkg.json閱讀和 vcpkg-configuration.json 參考文章以深入瞭解。以及指令清單模式檔，以了解它們如何一起運作。

在 GitHub Actions 工作流程中取得 vcpkg

接下來，您必須取得 vcpkg，才能在工作流程中使用。新增下列步驟以安裝 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

完成這些步驟之後，您應該會有要使用的 vcpkg 可執行檔。

執行 vcpkg install 以建置您的埠

最後一個步驟是告訴 vcpkg 建置所有埠。您可能已經注意到自己的登錄不存在於 vcpkg-configuration.json 上述建立的幾個步驟中。原因是您想要測試目前在工作目錄中的埠版本，而不是儲存機制中發行的版本。

若要達到這個目標，您必須將環境變數設定VCPKG_OVERLAY_PORTS為登錄的ports目錄，將登錄的埠新增為重疊埠。

下列代碼段示範如何將登錄的埠設定為重疊埠，並在指令清單模式中執行 vcpkg install ，以安裝所有自定義埠。

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

在此範例中，我們假設 vcpkg.json 檔案是在登錄存放庫的根目錄中建立的。

將其全部放在工作流程的 YAML 檔案看起來應該如下所示：

.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

這是 CI 工作流程用來測試登錄埠的基本結構。您可能需要執行一些額外的工作，才能向私人存放庫或 NuGet 摘要進行驗證。

您可能也想要新增步驟來自動產生 vcpkg.json 檔案，或確認新新增至登錄的埠未排除在測試中的步驟。

下一步

設定 CI 環境時，下列文章對您很有用。

共用方式為