維護者指南

本檔列出新增或更新埠配方時應套用的原則集。 它的目的是為 Debian 的政策手冊、 Homebrew 的維護者指導方針和 Homebrew 的公式食譜的角色提供服務。

整體登錄設計目標

目前基準中的埠必須同時安裝

我們希望能夠在策劃的登錄中顯示連結庫的下游用戶，我們發佈的任何給定基準中的連結庫組合已經過測試，以至少在某些組態中一起運作。 允許埠彼此排除會中斷測試這類組態的能力，因為這類測試所需的組建數目會成長為 2^number_of_such_cases。 此外，安裝其他相依性一律會被視為「安全」：埠或使用者無法判斷其需求中未安裝相依性。

如果您想要為使用者代表這類替代情況，請考慮描述某人如何建立覆 迭埠 ，以在 中 portfile.cmake 實作替代窗體，而不嘗試新增從未在策劃登錄持續整合中建置的其他埠。 例如，請參閱 glad@0.1.36。

在引進 登錄之前，我們接受了數個未測試的埠即替代專案，例如 boringssl，讓撰寫重迭埠更容易。 這已不再接受，因為登錄允許發佈這些未經測試的埠，而不需要修改策劃的登錄。

PR 結構

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

盡可能將變更分成多個 PR。 這可讓它們更容易檢閱，並防止一組變更的問題阻礙所有其他變更。

避免未變更檔案中的簡單變更

例如，請避免在 portfiles 中重新格式化或重新命名變數，否則沒有理由針對目前的問題進行修改。 不過，如果您需要將檔案修改為PR的主要用途（更新連結庫），則很欣賞修正錯字等明顯有益的變更！

檢查其他存放庫的名稱

埠名稱應該嘗試明確安裝埠的套件。 在理想情況下，搜尋搜尋引擎中的埠名稱應該會快速引導您前往對應的專案。 一次檢查多個存放庫上許多套件名稱的好服務是 Repology。

具有簡短名稱或以一般單字命名的專案可能需要釐清，特別是當沒有與指定單字有強關聯的專案時。 例如，無法接受名稱為的 ip 埠，因為它可能會以類似的方式命名多個專案。

良好的解譯器範例包括：

• 存放庫的擁有者用戶名稱或組織： google-cloud-cpp。
• 項目連結庫套件的名稱為： boost-dll。

C++和 開放原始碼 專案所使用的常見前置詞和後置詞不是有效的釐清子，有些範例包含但不限於：

• cpp,
• free,
• lib,
• open,
• numbers

例如，在比較下列埠名稱時：ip-cpp， 和 和 ip5 移除無效的去除混淆器時，它們都會縮減為相同的字幹 （ip），因此會libip被視為具有相同的名稱。

這個指導方針的例外狀況是針對與單一專案有強烈關聯的名稱。 例如： libpng、 openssl 與 zlib。

使用 GitHub 草稿 PR

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

如需 GitHub 草稿 PR 的詳細資訊，請參閱 簡介草稿提取要求。

Portfiles

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

此時，下列協助程式已被取代：

• vcpkg_extract_source_archive_ex() 應該由 支援的 多載 vcpkg_extract_source_archive() 取代 （使用 ARCHIVE）
• 不使用 的vcpkg_extract_source_archive()ARCHIVE已取代多載，應該由支援的多載取代為 ARCHIVE。
• vcpkg_apply_patches() 應該由 PATCHES 「擷取」協助程式自變數取代 （例如 vcpkg_from_github()）
• vcpkg_build_msbuild() 應該取代為 vcpkg_install_msbuild()
• vcpkg_copy_tool_dependencies() 應該取代為 vcpkg_copy_tools()
• vcpkg_configure_cmake拿掉之後應該取代為vcpkg_cmake_configure()PREFER_NINJA
• vcpkg_build_cmake 應該取代為 vcpkg_cmake_build()
• vcpkg_install_cmake 應該取代為 vcpkg_cmake_install()
• vcpkg_fixup_cmake_targets 應該取代為 vcpkg_cmake_config_fixup

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

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

避免在 portfiles 中過度批注

在理想情況下，portfiles 應該是簡短、簡單且盡可能宣告式。 提交PR之前，請先移除命令所 create 引進的任何鍋爐板批注。

埠不得相依於路徑

埠不得根據哪些埠已安裝的形式變更其行為，而該窗體會變更埠所安裝的內容。 例如，假設：

> 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) 作為取得 unique-to-vcpkg 套件的方式
• unofficial::<port>::<target> 做為從該埠匯出的目標。

範例：

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

安裝著作權檔案

每個埠必須在資料夾中${CURRENT_PACKAGES_DIR}/share/${PORT}提供名為 copyright 的檔案。 如果套件的授權內容可在其原始程式檔內使用，則應該透過呼叫 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
]])

埠中的版本條件約束

通常應避免埠內的版本限制，因為它們可能會阻礙項目的獨立演進。 只有在有妥善記載的理由時，才允許新增這類條件約束，例如證明與特定舊版不相容。 這些條件約束不應只用來維持與獨立專案的同位。

功能

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

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

在此情況下，連結庫必須選擇 vcpkg 中所表示的其中一個可用選項，而想要不同設定的使用者此時必須使用重迭埠。

我們目前不接受的現有範例會保留回溯相容性：

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

功能可能會參與預覽或 Beta 功能

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

範例：

• Azure SDK（形式 azure-Xxx為 ）具有一項 public-preview 功能。
• imguiexperimental-docking具有參與其預覽對接分支的功能，其使用附加至每個公用編號版本的合併認可。

預設功能不得新增 API

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

必須仔細考慮是否應該默認開啟某個功能，因為停用預設功能很複雜。

將預設功能停用為「可轉移」取用者需要：

• 所有客戶都會透過命令行的功能清單中明確停用或包含[core]預設功能"default-features": false。
• 在命令行上 vcpkg install 命名可轉移相依性，或在最上層指令清單中將直接相依性命名為

在 vcpkg 策劃的登錄中，如果功能新增其他 API、可執行檔或其他二進位檔，則預設必須關閉。 如有疑問，請勿將功能標示為預設值。

請勿使用功能來控制已發佈介面中的替代專案

如果埠的取用者只相依於該埠的核心功能，則開啟功能不可能中斷。 當替代專案不是由取用者直接控制，而是由像是的 /std:c++17 / -std=c++17編譯程式設定控制時，這更為重要。

我們目前不接受的現有範例會保留回溯相容性：

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

功能可能會以別名取代 polyfill，前提是取代會模擬到已安裝的樹狀結構中

儘管如此，只要下列情況，埠可能會移除具有功能的 polyfills：

1. 開啟功能會將 polyfills 變更為 polyfilled 實體的別名
2. polyfill 的狀態會模擬到已安裝的標頭中，因此 ABI 不相符的「不可能」運行時間錯誤不太可能
3. 埠的取用者可以撰寫這兩種模式中運作的程序代碼，例如，使用 polyfilled 或不是 polyfill 的 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")

建置技術

請勿使用廠商的相依性

請勿使用連結庫的內嵌複本。 所有相依性都應該分開分割和封裝，以便更新和維護它們。

偏好使用 CMake

當有多個建置系統可用時，偏好使用 CMake。 此外，適當時，使用指示詞將替代建置系統重寫為 CMake file(GLOB) 可能更容易且更容易維護。

範例： 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> 檔。

將衝突的連結庫放在 manual-link 目錄中

如果連結庫執行下列任一項，則會被視為衝突：

• 定義 main
• 定義 malloc
• 定義其他連結庫中也宣告的符號

衝突的連結庫通常是依設計而未視為瑕疵。 由於某些組建系統會連結至 lib 目錄中的所有專案，因此應該將這些專案移至名為 manual-link的子目錄。

版本控制

遵循欄位的 "version" 常見慣例

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

如果上游在一段時間內尚未發行發行，請勿將埠的版本設定配置變更為 version-date ，以取得最新的變更。 這些認可可能包含尚未準備好生產環境的變更。 相反地，請要求上游存放庫發佈新版本。

"port-version"更新任何已修改埠指令清單檔中的欄位

vcpkg 會使用此字段來判斷指定的埠是否過期，而且應該在埠的行為變更時變更。

我們的慣例是使用 "port-version" 欄位來變更不會變更上游版本的埠，並在進行上游版本的更新時，將 重設為 "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

我們預期每次更新埠時，您也會更新其版本檔案。

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

vcpkg x-add-version zlib

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

vcpkg x-add-version --all

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

注意

這些命令會要求您先將變更認可至埠，再執行這些變更。 原因是這些版本檔案中需要埠目錄的 Git SHA。 但別擔心，如果您有尚未認可的本機變更， x-add-version 命令會警告您。

如需詳細資訊，請參閱 版本設定參考 和 建立登錄。

修補

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

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

針對上游相關修補程式通知上游擁有者

如果上游可能有用修補程式，則上游必須收到修補程序內容的通知。 （套用 vcpkg 特定行為與上游無關的修補程式，例如取消裝飾相依性，不需要通知。

為了避免上游與修補程式不一致的情況，我們將等待至少 30 天來套用這類修補程式。

如果我們對變更正確充滿信心，我們會略過此等候期間。 高信賴修補程式的範例包括，但不限於：

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

偏好選項而不是修補

最好是在呼叫 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 檔

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

如果可以從上游取得已核准或合併的修補程式檔案，埠應該嘗試下載並套用它們，而不是將它們作為埠檔案的一部分。 此程式偏好使用，因為它：

• 確認上游已接受修補程序變更
• 藉由將 onus 上游移位來簡化檢閱程式
• 減少未使用修補程式之使用者的 vcpkg 存放庫大小
• 避免與 vcpkg 存放庫的授權衝突

應從穩定端點下載修補程式，以避免SHA衝突。 從提取要求下載修補程式檔案或從 GitHub 和 GitLab 認可時， ?full_index=1 參數應該附加至下載 URL。

範例：

• https://github.com/google/farmhash/pull/40.diff?full_index=1
• https://github.com/linux-audit/audit-userspace/commit/f8e9bc5914d715cdacb2edc938ab339d5094d017.patch?full_index=1
• https://gitlab.kitware.com/paraview/paraview/-/merge_requests/6375.diff?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時直接修補組建系統。

最小化修補程式

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

如果埠已過期，且將埠更新為較新版本，請勿新增修補程式，可解決相同的問題。 vcpkg 偏好更新埠，而不是修補過時的版本。

這有助於將 vcpkg 存放庫的大小保持關閉，並改善修補程式將套用至未來程式代碼版本的可能性。

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

在 vcpkg 中修補的目的是要啟用與編譯程式、連結庫和平臺的相容性。 不實作新功能，而不是遵循適當的開放原始碼程式（提交問題/PR/等）。

默認不要建置測試/docs/examples

提交新的埠時，請檢查或 或 WITH_TESTS POCO_ENABLE_SAMPLES 之類的BUILD_TESTS任何選項，並確定已停用其他二進位檔。 這會將平均使用者的建置時間和相依性降到最低。

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

讓連結庫的現有使用者切換至 vcpkg

不要新增 CMAKE_WINDOWS_EXPORT_ALL_SYMBOLS

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

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

這表示如果上游連結庫在 release 和 debug 中有不同的名稱（libx 與 libxd），則不應該將偵錯連結庫重新命名為 libx。 相反地，如果上游連結庫在發行和偵錯中具有相同的名稱，我們不應該引進新的名稱。

重要注意事項：

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

如果連結庫產生 CMake 整合檔案 （foo-config.cmake），則必須透過修補 CMake 組建本身來完成重新命名，而不是只呼叫 file(RENAME) 輸出封存/LIB。

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

資訊清單

我們需要格式化指令清單檔。 使用下列命令來格式化所有指令清單檔：

> vcpkg format-manifest --all

三胞 胎

我們目前不接受新增非社群三胞胎的要求。 從社群升階到完整三元組狀態主要是根據硬體的預算來測試這類三胞胎，並由 vcpkg 提交的計量所驅動，以充分發揮人們實際使用的可能性進行完整測試。

如果：

• 它表明，人們實際上會使用該社區三重：和
• 我們不知道這樣的三重奏被打破了。

例如，我們並未在 中 https://github.com/microsoft/vcpkg/pull/29034 新增三元，因為作者只是嘗試「完成集合」，而不是指出它們實際會使用這類專案，而且直到 patchlf 解決方案建立可重新放置結果之前，我們才新增 linux-dynamic。

實用的實作注意事項

Portfiles 是在腳本模式中執行

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

Portfiles 可直接存取在三重檔案中設定的變數，但 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）。

另請參閱我們的 三重檔 ，以取得可能設定的完整列舉。