教學課程：封裝私人 Azure DevOps 相依性

發行項
03/05/2024

本教學課程會引導您為裝載在私人 Azure DevOps 存放庫上的連結庫建立重迭埠，涵蓋驗證設定和封裝成重疊。

先決條件：

對 Git 和 vcpkg 的基本瞭解。
具有建立專案和管理 SSH 金鑰許可權的 Azure DevOps 存取權。
vcpkg 安裝在系統上。
安裝在系統上的 Git。

1 - 建立私人專案

登入您的 Azure DevOps 帳戶
建立新的私人專案。如果您沒有組織，系統會提示您在專案建立程式期間建立一個。
- 為您的專案命名：選擇反映連結庫或其用途的有意義名稱。
- 可見度：確定項目設定為「私人」，以控制存取。

2 - 在 Azure DevOps 中設定驗證

使用 SSH 金鑰安全地存取您的存放庫。

產生 SSH 金鑰組
- 開啟終端機或命令提示字元。
- 執行以下命令：
```
ssh-keygen -t rsa -b 4096 -C "ADO-RSA" -f /path/to/.ssh/id_rsa_ado
```
  - -t rsa：指定要建立的金鑰類型，在此案例中為 RSA。
  - -b 4096：設定金鑰中的位數目，在此案例中為 4096，這被視為強式且安全。
  - -C "ADO-RSA"：將標籤新增至索引鍵以進行識別，當您有多個索引鍵時，這特別有用。
  - -f /path/to/.ssh/id_rsa_ado：指定新索引鍵的檔名。這個指令會將私密鑰儲存至， id_rsa_ado 並將公鑰儲存至 id_rsa_ado.pub。
  系統會提示您輸入複雜密碼以取得其他安全性。您可以輸入複雜密碼，或按 Enter 鍵繼續，而不需要輸入密碼。複雜密碼會藉由要求在使用密鑰時輸入複雜密碼，來增加額外的安全性層。
- 在產生金鑰之後，再次列出目錄 /.ssh/ 的內容，確認已建立新的金鑰：
```
ls /path/to/.ssh
```
將 SSH 金鑰新增至 Azure DevOps
- id_rsa_ado.pub使用文字編輯器開啟檔案，以檢視公鑰。
- 複製檔案的整個內容。
- 流覽至您的使用者設定 > SSH 公鑰。
- 貼上複製的內容併為您的金鑰命名，以供日後參考，以新增您的密鑰。
將 SSH 金鑰載入 SSH 代理程式。

請確定您的 SSH 金鑰可供驗證：
```
ssh-add /path/to/.ssh/id_rsa_ado
```

測試 SSH 連線

確認 Azure DevOps 的連線能力：

ssh -T git@ssh.dev.azure.com

預期訊息指出驗證成功，但指出不支援殼層存取。

ssh -T git@ssh.dev.azure.com
remote: Shell access is not supported.
shell request failed on channel 0

3 - 將連結庫上傳至 Azure DevOps 存放庫

初始化本機 Git 存放庫

瀏覽至連結庫的原始碼目錄，並初始化 Git 存放庫：
```
git init
```

認可連結庫新增並認可連結庫的原始碼：

git add .
git commit -m "Initial commit of the sample library"

連結至您的 Azure DevOps 存放庫

從 Azure DevOps 擷取存放庫的 SSH URL，並將其新增為遠端：
```
git remote add origin <Your-Repo-SSH-URL>
```
推送您的連結庫

將您的連結庫上傳至 Azure DevOps 存放庫：
```
git push -u origin master:main
```

4 - 將您的連結庫封裝成重迭埠

重疊埠可讓您搭配 vcpkg 使用本機埠。

建立重迭埠目錄

mkdir vcpkg-overlay-ports
cd vcpkg-overlay-ports

設定埠檔案

vcpkg.json：此指令清單檔案會定義連結庫的元數據和相依性。

免責聲明：下列範例使用佔位符。以實際數據取代它們。
```
{
    "name": "your-library-name",
    "version": "1.0.0",
    "description": "Description of your library.",
    "dependencies": []
}
```
此 vcpkg.json 檔案可作為定義 C++ 連結庫元數據和相依性的指令清單，為 vcpkg 提供建置、安裝及管理套件的必要資訊。
- name：指定連結庫的名稱。這會當做封裝標識碼使用。
- version：表示連結庫的版本號碼。
- description：描述連結庫用途的簡短文字。這適用於檔和使用者。
- dependencies：陣列，包含連結庫所需的相依性清單。
如需如何設定的詳細資訊 vcpkg.json，請參閱我們的參考檔。
portfile.cmake ：此腳本會告知 vcpkg 如何建置您的連結庫。
```
vcpkg_from_git(
    OUT_SOURCE_PATH SOURCE_PATH
    URL "git@ssh.dev.azure.com:v3/YourOrg/YourProject/YourRepo"
    REF "<commit-sha>"
)

vcpkg_cmake_configure(SOURCE_PATH "${SOURCE_PATH}")
vcpkg_cmake_install()
vcpkg_cmake_config_fixup(PACKAGE_NAME your-library-name)
file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/your-library-name")
```
此 portfile 會定義如何使用 vcpkg 從 GitHub 下載、建置、安裝及封裝特定的 C++ 連結庫。
- vcpkg_from_git：啟動函式以從 Git 存放庫下載原始程式碼。
- OUT_SOURCE_PATH SOURCE_PATH：設定將擷取原始程式碼的目錄。
- URL git@ssh.dev.azure.com:v3/YourOrg/YourProject/YourRepo：包含原始程式碼之存放庫的 SSH URL。
- REF <commit-sha>：Azure DevOps 中連結庫程式代碼的認可SHA。
- vcpkg_cmake_configure：使用 CMake 設定專案，並設定組建。
  - SOURCE_PATH "${SOURCE_PATH}"：稍早下載之原始程式碼的路徑。
- vcpkg_cmake_install()：使用 CMake 建置並安裝套件。
- vcpkg_cmake_config_fixup(PACKAGE_NAME your-library-name)：修正 CMake 套件組態檔以與 Vcpkg 相容。
- file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...)：將 LICENSE 檔案安裝至套件的共享目錄，並將它重新命名為著作權。
若要取得認可 SHA：
```
mkdir temp && cd temp
git init
git fetch <Your-Repo-SSH-URL> main --depth 1 -n
git rev-parse FETCH_HEAD
```
如需如何設定的詳細資訊 portfile.cmake，請參閱下列文章：

安裝您的埠

回到主要 vcpkg 目錄，安裝指定重疊埠目錄的連結庫：
```
vcpkg install your-library-name --overlay-ports=/path/to/vcpkg-overlay-ports
```

後續步驟

您已成功將私人 Azure DevOps 存放庫封裝為 vcpkg 埠。本教學課程旨在做為指導方針;請調整指示以符合您的特定連結庫和開發環境。

共用方式為