維護者指南

本文件說明了在貢獻 vcpkg 時應遵循的政策、指引及最佳實務。

它旨在扮演以下角色相同的功能:

精心規劃的註冊表設計目標

埠口必須同時安裝

被納入精選註冊表的端口必須能在與所有其他端口共存的情況下成功建置。 整個埠組合會定期由 vcpkg 的自動化 CI 測試。

埠口不得執行以下任何一項:

以下情況有例外:

  • 以官方身分取代另一個連接埠的連接埠。 這包括以下情況:
    • 同一專案會推出一個後繼元件。
    • 另一個專案則負責維護被遺棄的元件,包括透過分叉。
    • 另一個專案則發布了後繼元件。
  • 沒有平台重疊的港口。 例如,一個僅支援 Windows、用來取代不支援 Windows 的 Linux 元件的替代品。
  • 這些港口是在此政策之前,且擁有顯著數量的用戶和貢獻者。

vcpkg 維護者會逐案評估祖父條款例外情況。 例如,boringssl 在可使用自訂登錄庫之前就已加入,且仍留在策展登錄庫中,因為它仍有實際使用者,儘管 openssl 是 OpenSSL 分支家族的正統提供者。 僅有先前接受並不保證破例。

不符合此政策的端口無法被納入精選登錄。

小提示

如果你的移植無法被納入精選登錄檔,可以考慮 發佈自訂登錄檔 或使用 疊加移植。

端口必須在至少一個官方組合中進行測試

所有精選登錄檔中的埠口都必須在 CI 中測試至少一個官方 三重組。

以下情況有例外:

  • 臨時情況,例如:
    • 沒有更新 CI 基礎架構,埠號是無法建構的。
    • 因為上游相依關係的重大改變,埠目前無法建置,正在努力進行修復工作以解決該情況。
  • 這些港口是在此政策之前,且擁有顯著數量的用戶和貢獻者。

無法在至少一個官方三元組中測試的新程式移植,不會被納入精選註冊表。 已不再符合此政策且不符合上述例外條件的現有連接埠,將從登錄檔中除名。 例如,若某個埠所支援的每個官方三元組都已停用 CI 測試,且無例外,該埠便會遭到除名。

小提示

如果你的移植無法被納入精選登錄檔,可以考慮 發佈自訂登錄檔 或使用 疊加移植。

封裝中的元件應該是穩定且處於持續積極維護中的

收錄於精選 registry 的元件必須處於持續維護狀態。 非活躍元件的埠可能會從清單中移除。

若有以下情況,該元件被視為停用:

  • 其維護者已宣布該組件已廢棄。
  • 其原始碼儲存庫已被封存,或不再接受貢獻。
  • 維護者無法回應或無法聯繫。
  • 很長一段時間沒有實質改變。

對於被視為成熟且穩定且不常變動的基礎組件,會作例外處理。 例如: zlib 。

包裝好的元件應該是穩定的

精選登錄庫中所封裝的元件必須成熟且適合 vcpkg 使用者使用。 供個人使用的元件應發佈至自訂登錄。

若下列任一陳述為真,該元件即被視為足夠成熟,可納入精選登錄檔:

  • 這個元件的發行版本至少已經有六個月了。
  • 該組件至少展現了六個月的公開且持續開發。
  • 該元件是專案的正式組成部分,且至少有六個月的釋出或活躍公開開發。 例如,新增一個 Boost 函式庫或 Qt 元件。
  • 該組件以其他身分展現出與前述要求同等的成熟度。

部分元件未成熟的指標包括:

  • 這個元件不會在搜尋引擎中出現。
  • 該元件經常被重新命名。
  • 和其他程式庫有衝突。

小提示

如果你的移植無法被納入精選登錄檔,可以考慮 發佈自訂登錄檔 或使用 疊加移植。

PR 結構

為每個埠提出個別的提取要求

較小的 pull request(PR)比較容易審查。 Pull Request 應該只對單一埠進行變更。 這也縮短了持續整合(CI)結果的等待時間。

在某些情況下,限制 PR 只用單一埠可能無法實現。 例如,當更換端口時,下游消費者需要更新或修補。

避免無關的非實質變更

不要對原本未經修改的移植版做無關的外觀改動,例如格式化、變數命名或修正錯字。 這些變更會消耗本應用於其他地方的計算時間。 提升建置正確性、相容性、可靠性或可重現性的變更,並非僅因為已安裝的檔案未被更改而被視為微不足道。

使用獨特的埠名

港口名稱應反映其內容。

在搜尋引擎或專門的套件瀏覽器(如 Repology)中搜尋該移植套件名稱,應該會找到對應的元件。

名稱較短或以常用詞命名的港口需要釐清歧義。 此規定僅適用於策展登錄檔中的埠名稱,封裝元件名稱及其內容不需遵守此政策。

對於將與其埠名稱有強烈關聯之元件打包在一起的埠,則有例外。 例如:libpng、openssl 或 zlib。

為了符合此政策,名稱模糊的新埠口可以使用前綴,例如:

  • 該倉庫的擁有者、使用者名稱或組織。 範例:google-cloud-cpp。 對於託管在 GitHub 上的元件移植版本,GitHub 擁有者是一個可接受且明確的前綴 <github owner>-<repository name>。
  • 該套件所屬的套件名稱為: boost-dll。 只有當該套件是該套裝軟體的官方組件時才會如此。

範例:模糊的埠名

帶有該名稱 ip 的埠號被視為歧義,原因如下:

  • 名稱太短了,
  • 這個名字是一個常見的詞彙,且
  • 這個名稱並不強烈地與任何單一組件相關聯。

為了判斷名稱是否歧義,請從埠名中移除以下 C++ 及 開放原始碼 元件常用的前綴與後綴:

  • cpp
  • free
  • lib
  • open
  • 數字

例如: ip-cpp、和 libipip5,之所以有歧義,是因為它們被簡化為同一 ip 詞幹。

限制埠名重命名

為避免使用者混淆,一個連接埠在任何 12 個月內不得被重新命名超過一次。

使用 GitHub 草稿 PR

GitHub 草稿 PR 是取得尚未準備好合併之工作 CI 或人為意見反應的絕佳方式。 大多數新的 PR 應該以草稿的形式開啟,並在 CI 通過後轉換為一般 PR。

如需 GitHub 草稿拉取請求的詳細資訊,請參閱 介紹草稿拉取請求。

vcpkg 維護者可能會在審查過程中將您的 PR 轉換為草稿,通常是在要求變更或留下註解,指示何時將 PR 標記為可審查時。

關閉非作用中的 PR

vcpkg 維護者可在等待貢獻者行動超過 60 天後關閉 PR。 閒置倒數計時僅在需要貢獻者採取行動時執行。 當 PR 等待建置實驗室驗證或 vcpkg 維護者審核時,它不會執行。

當永久居民(PR)處於可審查狀態時:

  • 沒有未通過的 PR 驗證,或貢獻者尋求幫助或解釋失敗的原因。
  • 沒有任何待處理的由 vcpkg 維護者要求的變更或澄清。
  • 沒有合併衝突。

倒數計時從PR進入需要貢獻者行動的狀態開始。 這可能發生在當 PR 開啟且其中有貢獻者需要解決的問題時,或是 vcpkg 維護者要求變更或澄清。 vcpkg 維護者在請求貢獻者行動時,可能會將 PR 標記為草稿。

貢獻者若有實質回應,倒數計時會被重置。 如果回應解決了所有待處理的請求,且 PR 準備好供審查,倒數計時會停止,直到再次需要貢獻者採取行動。 若貢獻者在需要採取行動的情況下 60 天內未回應,PR 將被視為過時,並可由 vcpkg 維護者自行決定關閉。

埠檔

避免已被取代的協助程式函式

此時,下列協助程式已被取代:

某些取代協助程式函式位於「工具埠」中,可讓取用者在特定版本釘選其行為,以允許鎖定特定版本的協助程序行為。 工具端口必須新增至您的埠的 "dependencies",如下例所示:

{
  "name": "vcpkg-cmake",
  "host": true
},
{
  "name": "vcpkg-cmake-config",
  "host": true
}

避免在 portfiles 中過度註解

在理想情況下,portfiles 應該是簡短、簡單且盡可能宣告式。 提交 PR 之前,請先移除 create 命令引入的任何樣板註釋。

將小寫用於十六進位數位字串

vcpkg 中的許多功能都依賴比較十六進位數位的字串。 某些範例包括 SHA512 哈希、Git 認可標識碼和樹狀物件哈希。

在內部,vcpkg 會使用小寫正規化來比較這些值,其中大小寫無關。 不過,在 vcpkg 基礎結構之上建置的工具可能無法進行相同的考慮。 基於這個理由,我們需要十六進位字串

在下列場景中,應使用小寫以保持一致性:

  • vcpkg 協助程式函式中的 SHA512 參數。
  • vcpkg 協助程式函式中的REF參數,當值是十六進位字串時。
  • 版本git-tree資料庫檔案中的物件。
  • sha512檔案中的 scripts/vcpkg-tools.json 物件。
  • 十六進位字串大小寫不重要的其他位置。

埠不得相依於路徑

埠不得根據已安裝的埠而改變其行為,這樣改變會影響該埠所安裝的內容。 例如,假設:

> vcpkg install a
> vcpkg install b
> vcpkg remove a

及

> vcpkg install b

所 b 安裝的檔案必須相同,不論先前安裝 a的影響為何。 這表示埠在採取一些動作之前,不得嘗試偵測安裝樹狀結構中是否有專案由另一個埠提供。 以下說明「定義功能時,明確控制相依性」中這類「路徑相依性」行為的特定和常見原因。

唯一埠指派規則

在整個 vcpkg 系統中,預期用戶不能同時使用兩個提供相同檔案的埠。 如果一個埠嘗試安裝另一個埠已經提供的檔案,安裝就會失敗。 如果埠要使用極通用的名稱作為標頭,例如,它應該將這些標頭放在子目錄中,而不是在include中。

持續整合過程會定期檢查此屬性,並嘗試在登錄中安裝所有埠。如果兩個埠提供相同的檔案,FILE_CONFLICTS 將會導致失敗。

在一個非官方命名空間中新增 CMake 匯出。

vcpkg 的核心設計理念之一是不要為使用者建立「綁定」。 在建置系統中,依賴來自系統的函式庫和依賴 vcpkg 的函式庫,應該沒有任何差異。 為此,我們避免將 CMake 專案匯出或目標新增至具有「顯而易見的名稱」的既有函式庫,以允許上游專案新增自己的官方 CMake 專案匯出,而不會與 vcpkg 衝突。

為此,埠導出的任何 CMake 設定,不在上游連結庫中,都應該有 unofficial- 作為前置詞。 任何其他目標都應該位於 命名空間中 unofficial::<port>:: 。

這表示用戶應該會看到:

  • find_package(unofficial-<port> CONFIG) 作為獲取 vcpkg 獨有套件的方法
  • unofficial::<port>::<target> 作為從該端口匯出的目標。

範例:

  • brotli 會建立 unofficial-brotli 封裝,產生目標 unofficial::brotli::brotli。

每個埠必須在資料夾copyright中提供名為${CURRENT_PACKAGES_DIR}/share/${PORT}的檔案。 如果套件的授權內容可在其原始程式檔內使用,則應該透過呼叫 vcpkg_install_copyright()來建立此檔案。 vcpkg_install_copyright 如有必要,也會配套多個著作權檔案。

vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

手動建立此檔案的較舊方法是使用 CMake 的內 file 建命令。 不建議 vcpkg_install_copyright 在新的埠中使用,但仍允許這樣做。

file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)

如果上游原始程式檔中的授權內容不是文字格式(例如 PDF 檔案), copyright 則應該包含使用者如何找到授權需求的說明。 可能的話,它也應該包含原始來源檔案的連結,指出這一點,讓使用者可以檢查它是否為最新狀態。

file(WRITE "${CURRENT_PACKAGES_DIR}/share/${PORT}/copyright" [[As of 2023-07-25, according to
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/README.md#end-user-license-agreement
this software is bound by the "SOFTWARE DEVELOPMENT KIT LICENSE AGREEMENT" PDF located at
https://github.com/GPUOpen-LibrariesAndSDKs/display-library/blob/master/Public-Documents/ADL%20SDK%20EULA.pdf
]])

埠的版本限制條件

通常應避免在埠中設置版本限制,因為這會阻礙元件的獨立演進。 只有在有妥善記載的理由時,才允許新增這類條件約束,例如證明與特定舊版不相容。 這些約束不應僅用於維持與獨立元件的一致性。

中的 MAYBE_UNUSED_VARIABLES 變數必須套用至至少一個組態

將新的變數新增至 MAYBE_UNUSED_VARIABLES 以在 CMake 設定步驟期間將警告靜音時,您必須新增批注,說明新變數套用時的情況。 如果變數在任何設定中都不適用,那麼很可能存在潛在的錯誤(例如變數名稱拼錯),加入變數對建置沒有實際影響。

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    windowsfeature WINDOWS_OPTION
)

vcpkg_cmake_configure(
  SOURCE_PATH "${SOURCE_PATH}"
  OPTIONS
    ${FEATURE_OPTIONS}
  MAYBE_UNUSED_VARIABLES
    WINDOWS_OPTION # Applies only on Windows
)

功能

請勿使用功能來實作替代專案

特徵必須被視為加法性功能。 如果 port[featureA] 安裝和 port[featureB] 安裝,那麼 port[featureA,featureB] 必須安裝。 此外,如果第二個埠相依 [featureA] ,而第三個埠相依於 [featureB],則安裝第二個和第三個埠應該符合其相依性。

在此情況下,程式庫必須選擇 vcpkg 所列出的可用選項之一,而想要不同設定的使用者此時必須使用 overlay 移植工具。

現有的範例是我們現今不會接受的,但會保留來確保向後相容。

  • libgit2、 libzip、 open62541 都有選取 TLS 或密碼編譯後端的功能。 curl 有不同的密碼編譯後端選項,但允許在運行時間進行選取,這表示會維護上述原則。
  • darknet 具備 opencv2 和 opencv3 功能,能控制用於相依性的 OpenCV 版本。

此功能可能提供預覽或 Beta 測試功能。

儘管如此,如果有預覽分支或類似的分支,預覽功能很有可能不會中斷非預覽功能(例如,沒有 API 移除),則模型化這項設定是可接受的功能。

範例:

  • Azure SDK(azure-Xxx的形式)具有一項 public-preview 功能。
  • imgui experimental-docking具有啟用其預覽碼合併分支的特性,此特性會使用附加至每個公開編號版本的合併提交。

預設功能不得新增 API

備註

由上游建置系統預設啟用的功能,並不代表該功能必須被 default-features 加入條目中。 因為 的 default-features 目的不是模擬上游的決策,而是為 經典模式 使用者提供便利。

預設功能旨在確保為不知道自己正在使用程式庫的客戶安裝合理運作的程式庫組建。 如果他們不知道自己正在使用程式庫,他們就無法知道要列出哪些功能。 例如, libarchive 會將啟用壓縮演算法的功能公開至現有的泛型介面;如果建置時沒有這類功能,連結庫可能沒有任何公用程式。

在此,使用者包含了消耗套件圖的使用者專案以及該圖中的下游移植套件。 兩者都透過相同的特性介面表達相依需求。

請仔細考慮某功能是否應該預設開啟,因為停用預設啟用的功能很複雜。

要停用傳遞依賴的預設功能:

  • 每個依賴該埠的客戶都必須在其相依性宣告中使用 "default-features": false 停用其預設功能。
  • 頂層專案也必須直接指定傳遞相依性,無論是在其資訊清單中使用 "default-features": false,或在 vcpkg install 命令列上使用 [core]。

停用預設功能並不會阻止其他客戶明確要求這些功能。

在此政策中,API 指的是任何對消費者開放的介面,包括函式庫介面、可執行的命令列介面及其他二進位介面。 當某功能在現有 API 背後新增行為時,可能會預設啟用,例如透過現有通用介面支援額外的壓縮演算法。

在 vcpkg 的精選登錄中,如果某功能新增了 API,預設必須關閉。 如有疑問,請勿將功能標示為預設值。

請勿使用介面功能來控制已發佈介面中的選項

如果某個埠的使用者只需依賴該埠的核心功能,那麼他們在開啟該功能時,大概率上不應該受到影響。 當替代專案不是由取用者直接控制,而是由像是的 /std:c++17 / -std=c++17編譯程式設定控制時,這更為重要。

現有的範例是我們現今不會接受的,但會保留來確保向後相容。

  • redis-plus-plus[cxx17] 會控制 polyfill,但不會將設定嵌入至已安裝的樹狀結構中。
  • ace[wchar] 將所有 API 變更為接受 const wchar_t* ,而不是 const char*。

功能可能會以別名取代 polyfills,前提是這些取代已經整合到已安裝的樹狀結構中。

儘管上述情況,只要符合以下條件,埠就可以將移除 polyfills 作為一種功能。

  1. 啟用此功能會將 polyfills 轉換為 polyfilled 實體的別名
  2. polyfill 的狀態已嵌入到已安裝的標頭中,因此不太可能出現因 ABI 不相符而產生的「不可能」執行時錯誤。
  3. 埠的使用者可以撰寫同時適用於兩種模式的程式碼,例如使用填充後或未填充的 typedef。

範例:

  • abseil[cxx17] 變更 absl::string_view 為取代 或 std::string_view; 修補程序 會實作烘焙需求。

如果公開基礎替代方案非常重要,建議您在建置階段提供訊息,以指示使用者如何將埠複製到私人重疊:

set(USING_DOG 0)
message(STATUS "This version of LibContoso uses the Kittens backend. To use the Dog backend instead, create an overlay port of this with USING_DOG set to 1 and the `kittens` dependency replaced with `dog`.")
message(STATUS "This recipe is at ${CMAKE_CURRENT_LIST_DIR}")
message(STATUS "See the overlay ports documentation at https://github.com/microsoft/vcpkg/blob/master/docs/specifications/ports-overlay.md")

建置技術

請勿使用廠商的相依性

偏好將相依性分開打包,讓使用者可以透過 vcpkg 選擇並更新它們。 隨附的第三方相依套件帶來多項挑戰:

  • 更新困難: 內嵌相依套件較難追蹤與更新,包括在套用安全性修補時。
  • 符號衝突: 供應商依賴可能定義與其他版本相同的符號,導致執行時錯誤或行為未定義。
  • 授權合規: 隨附的相依套件可能模糊授權要求或造成授權相容性問題。
  • 維護增加: 保持廠商相依與上游版本同步,增加了維護工作量,且可能在各移植版本之間重複工作。

基於這些原因,盡可能去除供應商相依性。 隨附的相依套件不得暴露於使用者的連結範圍。

連結域是一組可在執行時相互參照解析的符號。 在 Windows 上,每個 DLL 通常都有自己的連結域。 在具有全程序符號表的平台上,連結網域通常包含整個程序。

如果元件將內建相依性與透過 vcpkg 選擇的相依關係暴露於相同的連結域,兩個副本都可以定義相同的符號。 這違反了單一定義規則,可能導致執行時錯誤或未定義的行為。 這個問題可能只在兩個版本差異到不相容時出現。

內嵌相依項目僅在與下游 port 及使用者應用程式使用的連結網域完全隔離時才被允許。 例如,僅限主機端的建置工具可以包含靜態連結的依賴,前提是下游二進位檔不會與該工具連結,且該依賴的符號無法進入其連結領域。

偏好使用 CMake

當有多個建置系統可用時,偏好使用 CMake。 此外,適當時,使用 file(GLOB) 指令將替代建置系統重寫為 CMake,可能更簡便且維護性更佳。

範例: abseil

選擇靜態或共用二進位檔

建立 CMake 庫時,vcpkg_cmake_configure() 會根據使用者所要求的變體來傳入正確的值 BUILD_SHARED_LIBS 。

您可以使用 string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" ...)工具來計算替代配置參數。

# portfile.cmake

string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "static" KEYSTONE_BUILD_STATIC)
string(COMPARE EQUAL "${VCPKG_LIBRARY_LINKAGE}" "dynamic" KEYSTONE_BUILD_SHARED)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
        -DKEYSTONE_BUILD_STATIC=${KEYSTONE_BUILD_STATIC}
        -DKEYSTONE_BUILD_SHARED=${KEYSTONE_BUILD_SHARED}
)

如果函式庫未提供設定選項來選擇組建變體,則必須對組建進行修補。 修補組建時,您應該一律嘗試最大化埠的未來可維護性。 這通常表示將需要修改的行數降至最低,以解決當前的問題。

範例:修補 CMake 連結庫以避免建置不必要的變體

例如,當修補以 CMake 為基礎的函式庫時,可能只需將 EXCLUDE_FROM_ALL 新增至不必要的目標,並將 install(TARGETS ...) 呼叫包裝在 if(BUILD_SHARED_LIBS) 中。 這比包裝或刪除每行提及不需要的變體要來得簡單。

以具有下列內容的專案 CMakeLists.txt 為例:

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

install(TARGETS contoso contoso_static EXPORT ContosoTargets)

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

將該 install(TARGETS) 行替換成條件區塊,同時排除預設建構中不想要的目標:

add_library(contoso SHARED contoso.c)
add_library(contoso_static STATIC contoso.c)

if(BUILD_SHARED_LIBS)
  set_target_properties(contoso_static PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso EXPORT ContosoTargets)
else()
  set_target_properties(contoso PROPERTIES EXCLUDE_FROM_ALL 1)
  install(TARGETS contoso_static EXPORT ContosoTargets)
endif()

install(EXPORT ContosoTargets
  FILE ContosoTargets
  NAMESPACE contoso::
  DESTINATION share/contoso)

定義功能時,明確控制相依性

定義擷取選擇性相依性的功能時,請確定未明確啟用此功能時,不會意外使用相依性。

set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB ON)
set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB OFF)
if ("zlib" IN_LIST FEATURES)
  set(CMAKE_DISABLE_FIND_PACKAGE_ZLIB OFF)
  set(CMAKE_REQUIRE_FIND_PACKAGE_ZLIB ON)
endif()

vcpkg_cmake_configure(
  SOURCE_PATH ${SOURCE_PATH}
  OPTIONS
    -DCMAKE_DISABLE_FIND_PACKAGE_ZLIB=${CMAKE_DISABLE_FIND_PACKAGE_ZLIB}
    -DCMAKE_REQUIRE_FIND_PACKAGE_ZLIB=${CMAKE_REQUIRE_FIND_PACKAGE_ZLIB}
)

以下使用 vcpkg_check_features() 的代碼段是相等的。

vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
  FEATURES
    "zlib"    CMAKE_REQUIRE_FIND_PACKAGE_ZLIB
  INVERTED_FEATURES
    "zlib"    CMAKE_DISABLE_FIND_PACKAGE_ZLIB
)

vcpkg_cmake_configure(
    SOURCE_PATH ${SOURCE_PATH}
    OPTIONS
      ${FEATURE_OPTIONS}
)

ZLIB 程式碼片段中是區分大小寫的。 如需詳細資訊,請參閱 CMAKE_DISABLE_FIND_PACKAGE_<PackageName> 和 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> 檔。

安裝於 lib 或 debug/lib的連結器輸入檔案,如 .lib、 .a、 .so或 .dylib 檔案,若發生以下任一情況,則被視為衝突:

  • 定義 main。
  • 定義 malloc。
  • 定義了其他函式庫中也定義的符號。

部分連結輸入檔案會故意提供範圍較窄的符號替換,這些符號本來會被使用端定義或從其他地方取得。 例如,Google Test 的 gtest-main.lib 為作者選擇使用它而非自行定義入口點的測試執行檔提供 main。

把衝突的連結器輸入檔放進 lib/manual-link 或 debug/lib/manual-link,讓會自動連結函式庫目錄中檔案的建置系統不會選取它們。 Windows DLL 會保留在 bin 或 debug/bin;在需要明確連結時,將匯入函式庫置於 manual-link。 消費者必須明確選擇連結這些檔案,並有責任避免定義衝突。 此例外並非用來包裝其他元件替代提供者的通用機制,且將連結器輸入檔案移入 manual-link 並不會將其符號與消費者的連結域隔離。

安裝預先建置的二進位檔

允許安裝預先建構(僅二進位)的成品,但強烈不建議,前提是這些成品不會阻止使用者透過 vcpkg 選擇或更新相依性。 從原始碼建置是首選,因為它尊重控制編譯器和旗標的 vcpkg 設定。

我們將拒絕符合以下所有條件的連接埠:

  1. 安裝預先建置的二進位檔,而不是從原始碼建置,以及
  2. 這些二進位檔包含或需要由精選登錄庫中其他套件埠所提供的執行階段相依性,且
  3. 安裝的產物會將這些相依性暴露給一個連結域,該連結域中也可能包含透過 vcpkg 選擇的版本。

此組合實際上鎖定了依賴圖,鎖定為上游預建版本建立時所使用的版本。 如果 vcpkg 更新了像 zlib 或 openssl 這樣的相依性,預建版本和使用者選擇的版本可以在相同的連結域中定義不相容的符號。 這可能導致單一定義規則違規、ABI 不相容或錯過安全更新。

當該相依性參與使用者的連結網域時,構件即會暴露該相依性,無論上游是否有意圖公開該相依性。 這包括:

  • 供使用者連結的.lib、.a、.so、.dylib或匯入函式庫,將相依性帶入使用者的連結領域。
  • 已安裝的標頭檔,直接或透過內嵌/範本程式碼參考其他 vcpkg 埠的符號、類型或巨集。
  • 安裝了 CMake config 或 pkg-config 檔案,這些檔案會呼叫其他 vcpkg 埠口上的 find_dependency() 或 Requires:。

允許(但仍不鼓勵)的場景:

  • 僅限主機使用、在建置時使用的輔助工具,其輸出會被使用,但相依埠不會連結到它們,前提是它們能隔離捆綁依賴或僅依賴普遍的系統執行時函式庫。
  • 預建函式庫的相依性完全存在於獨立的連結域,且不會出現在已安裝的標頭或匯出介面中。 僅靠靜態連結無法將相依性隔離於使用者的連結域之外。
  • 未連結至使用者程式碼的純資料、韌體或資產套件。

禁止的例子:

  • 一個預先建構的函式庫,靜態連結私有副本 zlib 並將其符號暴露到連結域,該連結域中也能包含透過 vcpkg 選擇的 zlib 版本。
  • 預先建置的 libfoo ,會安裝 lib/libfoo.lib ,加上標頭,包括 <zlib.h> ,並已針對特定 zlib 版本編譯;然後使用者會連結到 libfoo ,預期相容性。
  • 預先建置的 SDK,可在針對較舊的 OpenSSL 版本編譯二進位檔時安裝呼叫 find_dependency(OpenSSL) 的 CMake 套件檔案。

緩解措施/替代方案:

  • 使用上游指令碼提供原始碼組建,或新增精簡 CMake 包裝函式。
  • 要求上游發佈基於源代碼的版本或可重現的構建說明;在portfile.cmake或vcpkg.json的註解中連結上游問題或 PR。
  • 針對無法滿足這些規則的組織特定預先建置,請使用 覆疊埠 或專用登錄。

版本控制

請遵循在 "version" 欄位中常見的慣例

建立新的埠時,請遵循套件作者所使用的版本設定慣例。 更新埠時,除非上游另有說明,否則請繼續使用相同的慣例。 如需慣例的完整說明,請參閱我們的 版本控制檔。

如果上游在一段時間內尚未發行版本,請勿將埠的版本號變更為 version-date,以獲取最新的變更。 這些提交可能包含尚未準備好上線的變更。 相反地,請要求上游存放庫發佈新版本。

更新每個已修改連接埠的 "port-version" 欄位

每個修改埠口的 PR 必須產生該埠的新版本。 PR 是壓縮合併的,因此每個修改過的埠,其版本在每個 PR 中只更新一次,而非每次提交或審查修訂時都更新一次。

如果上游版本沒有改變,就遞增 "port-version" 欄位。 若上游版本已更改,則透過移除欄位或將0設為"port-version"來重置為零。

例如:

  • Zlib 的套件版本目前為 1.2.1,沒有明確的 "port-version"(這等同於 "port-version" 的 0)。
  • 您已發現已部署錯誤的著作權檔案,並已修正 portfile 中的該檔案。
  • 您應該將 "port-version" 指令清單檔中的欄位更新為 1。

如需詳細資訊,請參閱 版本控制檔 。

在 versions/ 中更新每個已修改連接埠的版本檔案

vcpkg 會使用一組元數據檔案來提供其版本設定功能。 這些檔案位於下列位置:

  • ${VCPKG_ROOT}/versions/baseline.json、(此檔案適用於所有埠) 和
  • ${VCPKG_ROOT}/versions/${first-letter-of-portname}-/${portname}.json (每個埠一個)。

例如,相關 zlib 檔案如下:

  • ${VCPKG_ROOT}/versions/baseline.json
  • ${VCPKG_ROOT}/versions/z-/zlib.json

對於 PR 中每個修改過的埠,更新其版本檔以記錄最終的 Git 樹。 如果您在審查過程中有進一步變更,請執行 vcpkg x-add-version <port-name> --overwrite-version 重新整理未合併版本的條目

而不會再次遞增 "port-version"。

更新這些檔案的建議方法是執行 x-add-version 命令,例如:

vcpkg x-add-version zlib

如果您要同時更新多個埠,您可以改為執行:

vcpkg x-add-version --all

以一次更新所有已修改埠的檔案。

如需詳細資訊,請參閱 版本設定參考 和 登錄 文章。

修補

vcpkg 是封裝解決方案,不是我們部署之元件的最終擁有者。 在某些情況下,我們確實需要套用修補程式,以改善元件與平臺的相容性,或彼此的元件相容性。

  • 我們想要避免軟體修補:
    • 上游會不同意
    • 造成弱點或當機
    • 我們無法維護上游版本的更新
    • 足以讓 vcpkg 存放庫本身發生授權糾纏

上游通知與等待期間

上游擁有者是其元件行為的最終裁決者。 VCPKG 維護者要求在新 port 提交時,對與上游相關的修補程式以及 AI 程式碼審查工具發現的錯誤通知上游。

與上游相關的修補程式

如果補丁可能對上游有用,vcpkg 維護者要求將補丁內容通知上游。 那些套用與上游無關的 vcpkg 特定行為(例如移除內嵌相依套件)的修補程式,則不需要通知。

為避免上游不同意修補程式的情況,vcpkg 維護者在上游通知後至少等待 30 天後才會套用此類修補程式。

如果 vcpkg 維護者對變更正確有高度信心,會跳過此等待期。 高信賴修補程式的範例包括,但不限於:

  • 上游接受作為補丁(例如,從上游的合併請求中反向移植特定變更)。
  • 新增遺漏的 #include。
  • 小型且明顯的產品代碼修正(例如,初始化未初始化的變數)。
  • 停用組建中無關緊要的 vcpkg 元件,例如測試或範例。

新移植版中 AI 識別的錯誤

這個精心策劃的註冊庫旨在避免發佈已知可被利用的程式碼,但 vcpkg 維護者無法全面審核每個元件的原始碼。 AI 程式碼審查的結果本身並非最終判斷上游程式碼是否有漏洞。

當 AI 程式碼審查工具在審查新的移植提交時發現錯誤時,vcpkg 維護者要求必須向上游回報該錯誤,並依照專案對於可能可被利用錯誤的安全通報流程辦理。 即使該發現涉及該埠未修補的上游程式碼,這項要求也同樣適用。

  • 如果上游判定所回報的行為不是錯誤,vcpkg 維護者會接受該判定為最終結論,並不會因此拒絕新的 port 提交。
  • 若上游修正錯誤,vcpkg 維護者會接受已修正版本或上游核准的修補程式,但須遵守修補政策及新套件的其他要求。
  • 如果上游在錯誤報告後 30 天內未回應,vcpkg 維護者會將 AI 發現視為可被利用的問題,並關閉新的 port 提交。

高可信度的補丁等待期例外並未免除此錯誤回報要求或上游回應的需求。

偏好選項而不是修補

最好是在呼叫 vcpkg_configure_xyz() 中設定選項,而不是直接修補設定。

可讓您避免修補的常見選項:

  • [MSBUILD] <PropertyGroup> 項目檔內的設定可以透過 /p: 參數覆寫
  • [CMAKE] 可以透過find_package(XYz)停用CMake腳本中的-DCMAKE_DISABLE_FIND_PACKAGE_XYz=ON呼叫。
  • [CMAKE] 快取變數(宣告為 set(VAR "value" CACHE STRING "Documentation") 或 option(VAR "Documentation" "Default Value"))可以在命令列上傳入來覆蓋為 -DVAR:STRING=Foo。 其中一個值得注意的例外狀況是,如果 FORCE 參數傳遞至 set()。 如需詳細資訊,請參閱 CMake set 檔

偏好下載已核准的修補程式,而不是將修補程式簽入埠

如果能從上游提交取得已核准或已合併的修補檔,請下載並套用,而不是將其納入該 port。 此過程之所以被偏好,是因為它:

  • 確認上游已經接受了修補程式的變更。
  • 透過將審查責任轉移到流程前段,簡化審查流程。
  • 對未使用補丁的使用者來說,可以減少 vcpkg 儲存庫的大小。
  • 避免與 vcpkg 儲存庫的授權衝突。

只從固定到完整 commit ID 的 URL 下載補丁,不能從內容可能變更的拉取請求或合併請求差異 URL 下載。 從 GitHub 或 GitLab 下載提交修補程式時,請在網址後附加 ?full_index=1。 此參數在差異中請求完整的物件 ID;它不會讓可變的網址變成不可變的。

例如:

https://github.com/linux-audit/audit-userspace/commit/f8e9bc5914d715cdacb2edc938ab339d5094d017.patch?full_index=1

偏好修補而非覆寫 VCPKG_<VARIABLE> 值

某些前面加上 VCPKG_<VARIABLE> 的變數具有等效的 CMAKE_<VARIABLE>。 不過,並非所有套件都會傳遞至內部套件組建(請參閱實作:Windows 工具鏈)。

請考慮下列範例:

set(VCPKG_C_FLAGS "-O2 ${VCPKG_C_FLAGS}")
set(VCPKG_CXX_FLAGS "-O2 ${VCPKG_CXX_FLAGS}")

使用 vcpkg的內建工具鏈可正常運作,因為的值 VCPKG_<LANG>_FLAGS 會轉送至適當的 CMAKE_<LANG>_FLAGS 變數。 但是,不知道 vcpkg變數的自定義工具鏈不會轉寄它們。

因此,最好在設定 CMAKE_<LANG>_FLAGS時直接修補組建系統。

盡量減少修補程式數量

對連結庫進行變更時,請努力將最終差異降到最低。 這表示在進行會影響區域的變更時,您不應該重新格式化上游原始程式碼。 在禁用條件時,最好是將 AND FALSE 或 && 0 新增到條件中,而不是刪除該條件的每一行。 如果需要停用大型區域,則在區域周圍新增一個 if(0) 或 #if 0,這樣比刪除修補程式中的每一行更簡便。

如果埠已過期,而將埠更新為較新發布的版本能夠解決問題,則請勿新增修補程式。 vcpkg 偏好更新埠,而不是修補過時的版本。

這有助於保持 vcpkg 存放庫的大小減少,並提高修補程式應用到未來程式碼版本的可能性。

請勿在修補程式中實作功能

在 vcpkg 中修補的目的是要啟用與編譯程式、連結庫和平臺的相容性。 不要以不遵循適當的開放原始碼程序(例如提交 Issue/PR 等)來實作新功能。

預設情況下不要建置測試、文檔和示例

提交新的埠時,請檢查是否有像 BUILD_TESTS、WITH_TESTS 或 POCO_ENABLE_SAMPLES 這樣的選項,並確保附加的二進位檔已停用。 這會將平均使用者的建置時間和相依性降到最低。

或者,您可以新增功能 test 來建置測試,不過這不應該出現在 Default-Features 清單中。

讓程式庫的現有使用者切換至 vcpkg

不要新增 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS

除非連結庫的作者已經使用它,否則我們不應該使用此 CMake 功能,因為它與C++範本互動不佳,並中斷某些編譯程式功能。 未提供 .def 檔案且不使用 __declspec() 宣告的連結庫只是不支援 Windows 的共享組建,且應該標示為:

if(VCPKG_TARGET_IS_WINDOWS)
    vcpkg_check_linkage(ONLY_STATIC_LIBRARY)
endif()

請勿在上游指定的名稱之外重新命名二進位檔

這表示如果上游連結庫在 release 和 debug 中有不同的名稱(libx 與 libxd),則不應該將偵錯連結庫重新命名為 libx。 相反地,如果上游庫在發布模式和除錯模式中具有相同的名稱,我們不應該引入新名稱。

重要注意事項:

  • 靜態和共用變體通常應該重新命名為通用配置。 這可讓取用者使用一般名稱,並忽略下游連結。 這是安全的,因為我們一次只提供一個。

如果庫產生 CMake 整合文件(foo-config.cmake),則必須透過修改 CMake 組建本身來完成重新命名,而不是只呼叫 file(RENAME) 來處理輸出存檔/LIB。

最後,Windows 上的 DLL 檔案不應該在建置後重新命名,因為它會中斷產生的 LIB。

資訊清單

我們要求對 manifest 檔案進行格式化。 使用下列命令來格式化所有資訊清單:

> vcpkg format-manifest --all

三胞 胎

我們目前不接受新增非社群三胞胎的要求。 從社群支援狀態提升至官方支持的三元組狀態,主要取決於用於測試這類三元組的硬體預算,並由 vcpkg 提交的指標來驅動,以最大化可能性確保人們實際使用的項目經過完整測試。

我們會新增社群三元組,如果:

  • 證明了,人們實際上會使用那個社區三重組合。
  • 我們不知道這樣的三重奏被打破了。

例如,我們並未在https://github.com/microsoft/vcpkg/pull/29034中新增三元組,因為作者只是嘗試「完成集合」,而不是指出他們實際會使用這類東西。此外,我們直到創建了可將結果重新定位的patchelf解決方案後,才新增linux-dynamic。

實用的實作注意事項

Portfiles 是在腳本模式中執行

雖然 portfile.cmake和 CMakeLists.txt's 共用通用語法和核心 CMake 語言建構(也稱為「腳本命令」),但 portfiles 會在「腳本模式」中執行,而 CMakeLists.txt 檔案則以「專案模式」執行。 這兩種模式之間的最重要差異是「腳本模式」沒有「工具鏈」、「語言」和「目標」的概念。 任何操作,包括文稿命令,若相依於這些建構(例如 CMAKE_CXX_COMPILER,CMAKE_EXECUTABLE_SUFFIX,CMAKE_SYSTEM_NAME),將不正確。

Portfiles 可以直接存取在 triplet 檔案中設定的變數,但 CMakeLists.txt 不能(雖然 VCPKG_LIBRARY_LINKAGE 與 BUILD_SHARED_LIBS 之間經常會進行轉換)。

Portfiles 叫用的 Portfiles 和 Project 組建會在不同的進程中運行。 概念上:

+----------------------------+       +------------------------------------+
| CMake.exe                  |       | CMake.exe                          |
+----------------------------+       +------------------------------------+
| Triplet file               | ====> | Toolchain file                     |
| (x64-windows.cmake)        |       | (scripts/buildsystems/vcpkg.cmake) |
+----------------------------+       +------------------------------------+
| Portfile                   | ====> | CMakeLists.txt                     |
| (ports/foo/portfile.cmake) |       | (buildtrees/../CMakeLists.txt)     |
+----------------------------+       +------------------------------------+

若要判斷 portfile 中的主機,標準 CMake 變數很好(CMAKE_HOST_WIN32)。

若要判斷 portfile 中的目標,應該使用 vcpkg triplet 變數 (VCPKG_CMAKE_SYSTEM_NAME)。

另請參閱我們的 三元組文檔 ,用來完整列舉所有可能的設定。