使用 vcpkg 搭配 Azure DevOps 測試自定義登錄埠

發行項
02/27/2024

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

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

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

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

設定 Azure DevOps 管線的二進位快取和資產快取
設定管線以測試登錄的埠

必要條件

Azure DevOps 帳戶
您自己的 vcpkg Git 登錄
完成二進位快取和資產快取教學課程。
ADO 管線的知識

為您的 Azure DevOps 管線設定二進位快取和資產快取

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

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

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

範例：在 Azure DevOps 管線中啟用資產和二進位快取

steps: 
- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install --triplet=x64-windows
  displayName: some vcpkg task
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json,readwrite"

此範例示範如何在 Azure DevOps 管線中設定二進位快取和資產快取。您應該調整此代碼段，以在您自己的管線 YAML 檔案上使用。

細分此代碼段：

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

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

VCPKG_BINARY_SOURCES 是用來在 vcpkg 中設定二進位快取的環境變數。在這裡範例中，它會設定為 clear;nuget,https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.json,readwrite。這會使用上的 https://my.domain.com/vcpkgBinaryCache/nuget/v3/index.jsonNuGet 摘要，為二進位快取啟用 NuGet 後端。若要向 NuGet 摘要進行驗證，可能需要一些額外的步驟，請閱讀教學課程，以取得使用 ADO 設定 NuGet 驗證的指示。

您的管線中應新增下列工作，以便向 Azure Artifacts NuGet 摘要進行驗證。此工作也應該在涉及 vcpkg 的任何工作之前執行。

- task: NuGetAuthenticate@1

如果您針對 NuGet 摘要使用不同的主機，請閱讀有關如何驗證 NuGet 的檔。

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

設定管線以測試登錄的埠

設定 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 參考文章以深入瞭解。以及指令清單模式檔，以了解它們如何一起運作。

在 Azure DevOps 管線中取得 vcpkg

如果您使用 vcpkg 作為專案中的子模組，您可以在步驟中取得 vcpkg 存放庫，以簽出您自己的專案，如下所示。

steps:
- checkout: self
  submodules: true

否則，您必須取得 vcpkg，才能在管線中使用。新增下列步驟以複製 vcpkg 存放庫。

resources:
  repositories:
    - repository: vcpkgRepo
      type: github
      name: Microsoft/vcpkg
      endpoint: MyGitHubServiceConnection

steps:
  - checkout: vcpkgRepo

若要複製 vcpkg 存放庫，您需要定義管線的存放庫資源。下列代碼段示範如何將 vcpkg 存放庫新增為資源，您必須設定服務連線，才能將管線連線至 GitHub。

簽出 vcpkg 存放庫作為子模組或從 GitHub 複製它之後，您必須執行 vcpkg 的啟動程式腳本。

steps:
  - script: vcpkg/bootstrap-vcpkg.sh

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

執行 vcpkg install 以建置您的埠

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

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

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

steps:
- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    VCPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

在此範例中， vcpkg.json 我們假設檔案是在登錄存放庫根目錄中建立，且 vcpkg 存放庫會新增為子模組。

將所有管線的 YAML 檔案放在一起應該如下所示：

.azure-pipelines/test-ports.yml

trigger:
- main

pool:
  vmImage: windows-latest

steps:
- checkout: self
  submodules: true

- task: NuGetAuthenticate@1

- script: $(Build.Repository.LocalPath)/vcpkg/bootstrap-vcpkg.bat
  displayName: Bootstrap vcpkg

- script: $(Build.Repository.LocalPath)/vcpkg/vcpkg install --triplet=x64-windows
  env:
    X_VCPKG_ASSET_SOURCES: "clear;x-azurl,https://my.domain.com/container,$(VcpkgAssetCache),readwrite"
    VCPKG_BINARY_SOURCES: "clear;nuget,https://my.domain.com/demoBinaries/nuget/v3/index.json,readwrite"
    VCPKG_OVERLAY_PORTS: "$(Build.Repository.LocalPath)/ports"

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

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

下一步

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

共用方式為