本地 vcpkg 共用 Registry 規劃與使用指南

1. 目的與規劃資訊

在一個組織或多個倉庫 (repo) 之間共用自訂 C++ 套件 (ports)，可建立一個本地 vcpkg registry。透過 filesystem registry：

多個專案可引用相同的自訂 ports（如 pathinfo）。
避免每個 repo 都複製 port 內容。
可控版本管理 (versions 資料夾 + baseline)。
目錄規劃建議 (範例路徑)：

C:/vcpkg-registry/
  ports/
    pathinfo/
      portfile.cmake
      vcpkg.json
  versions/
    p-/
      pathinfo.json
  baseline.json

ports/<name>: 放置單一 port 定義。
versions/<first-letter>/<name>.json: 每個版本的索引。
baseline.json: 指定 registry 的預設版本錨點。

2. 建置本地 registry Step-by-Step

建立目錄：C:/vcpkg-registry
建立子目錄：ports, versions/p-。
將現有 pathinfo port 複製到：C:/vcpkg-registry/ports/pathinfo/。
- 需包含：portfile.cmake, vcpkg.json。
建立版本檔：C:/vcpkg-registry/versions/p-/pathinfo.json
範例內容：
```
{
  "versions": [
    {
      "version-string": "1.0.0",
      "port-version": 0,
      "git-tree": "<COMMIT_OR_TREE_ID>"
    }
  ]
}
```
說明：git-tree 可用來源 repo 的 git tree hash（若無版本控管可暫填假值並後續修正）。

建立 baseline：C:/vcpkg-registry/baseline.json

{
  "default": {
    "pathinfo": {
      "version-string": "1.0.0",
      "port-version": 0
    }
  }
}

確保 vcpkg.json (port) 內含正確 name, version-string, supports。
(選擇性) 將 registry 放入版本控制 (Git) 以追蹤演進。

3. 安裝並設定 vcpkg (一次性全域)

取得 vcpkg：

git clone https://github.com/microsoft/vcpkg C:/vcpkg
C:/vcpkg/bootstrap-vcpkg.bat

建議將 C:/vcpkg/vcpkg.exe 加入 PATH。
啟用 manifest mode：set VCPKG_FEATURE_FLAGS=manifests (或使用 vcpkg >= 已預設啟用)。

4. 各 Repo 專案使用本地 registry 步驟

在每個專案根目錄：

新增 vcpkg-configuration.json：

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<builtin-baseline-date-or-tag>"
  },
  "registries": [
    {
      "kind": "filesystem",
      "path": "C:/vcpkg-registry",
      "packages": ["pathinfo"]
    }
  ]
}

baseline 可從官方 vcpkg repo versions/baseline.json 取得 (建議鎖定)。

新增/修改專案 vcpkg.json (manifest)：

{
  "name": "myapp",
  "version-string": "0.1.0",
  "dependencies": ["pathinfo"]
}

建置時指定 toolchain：

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

若使用 Visual Studio：在 CMakeSettings.json 或 GUI 中加入 CMAKE_TOOLCHAIN_FILE。

使用程式碼：

#include <pathinfo/PathInfo.h>
// link: target_link_librariespathinfo

若需更新 port 版本：
- 更新 registry 中 ports/pathinfo/。
- 更新 versions/p-/pathinfo.json 加入新版本條目。
- 覆寫或新增 baseline 對應版本。
- 專案重新執行 vcpkg install / CMake configure。

5. 自動快取與整合

可設定 VCPKG_ROOT 指向 C:/vcpkg，減少重複 bootstrap。
可使用 CMAKE_MSVCIDE_RUN_PATH 或 VCPKG_DEFAULT_TRIPLET 設定預設三合一 (如 x64-windows)。

6. 機制與原理說明

Manifest Mode：每個專案透過 vcpkg.json 宣告依賴，避免手動安裝與 global state 汙染。
Registry 解析順序：vcpkg 讀取 vcpkg-configuration.json，依 registries 列表尋找對應 packages；若找不到則 fallback 到 builtin registry。
Filesystem Registry：直接指向一個本地路徑，該路徑結構需符合：ports/<name> + versions/<prefix>/<name>.json + baseline.json。
baseline：提供各 port 的預設版本錨定，確保穩定與可重現建置。
versions 檔：列出歷史版本 (包含 git-tree)，支援 version-string + port-version 比對與升級。
安裝結果：vcpkg 會根據 triplet (例 x64-windows) 建置並放入 installed/<triplet>/；CMake toolchain 會自動設定 include/link path。
更新流程：修改 port → 更新 versions → 調整 baseline → 專案重新 configure → 解析新版本。

7. Debug 與排錯建議

檢查 vcpkg-configuration.json 路徑是否正確放在專案根。
使用 vcpkg x-add-version --all (官方工具) 自動生成 versions 檔案 (需在 registry git repo 上)。
使用 vcpkg install --debug 查看解析過程。
若 port 未被找到：確認 packages 陣列是否包含名稱，或移除 packages 讓 registry 提供所有 ports。

8. 範例快速驗證

# 於專案根
vcpkg install
# 生成 build
cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Debug

9. 推薦最佳實務

registry 與各專案獨立版本控制。
baseline 鎖定到特定日期或 commit，確保重現性。
每次新增 port 版本都更新 versions 檔並執行 CI 驗證。
在 CI 中快取 installed/ 以加速建置。

10. 常見問題

問題	原因	解法
找不到 port	路徑/registries packages 限制	確認 path 與 packages 設定
版本未更新	baseline 未改	更新 baseline.json
include 失敗	未使用 toolchain	加入 `-DCMAKE_TOOLCHAIN_FILE`
triplet 不符	預設 triplet 未指定	設定 `VCPKG_DEFAULT_TRIPLET`

本文件可供多個 C++ 專案快速導入本地共享 vcpkg registry。

Also See

File8	File	Last Modified
vcpkg_checker	vcpkg_checker	1:22 AM - December 07, 2025
vcpkg 指令總覽表	vcpkg 指令總覽表	1:22 AM - December 07, 2025
模組化開發-用 CMake + VCpkg 封裝並重用 C++ 函式庫	模組化開發-用 CMake + VCpkg 封裝並重用 C++ 函式庫	8:20 PM - December 06, 2025
模組化開發-VCpkg工具	模組化開發-VCpkg工具	8:20 PM - December 06, 2025
查詢目前vcpkg registry所在路徑	查詢目前vcpkg registry所在路徑	8:20 PM - December 06, 2025
本地 `src` vs. `vcpkg_from_git`	本地 `src` vs. `vcpkg_from_git`	8:20 PM - December 06, 2025
如何產生 git-tree	如何產生 git-tree	8:20 PM - December 06, 2025
使用 vcpkg x-add-version 搭配 Git 或目錄結構工具，自動建立與維護本地 vcpkg registry	使用 vcpkg x-add-version 搭配 Git 或目錄結構工具，自動建立與維護本地 vcpkg registry	8:20 PM - December 06, 2025