撰寫協助程式埠

協助程式埠，也稱為腳本埠，公開函式供其他埠在其建置程式期間取用。 例如，埠 vcpkg-cmake 會定義要取用之其他埠的 vcpkg_cmake_configure() 函式。 藉由將一般腳本封裝到協助程式埠，維護會變得更簡化，因為可以在單一位置進行更新。 此外，協助程式埠可以進行版本設定，並取決於使用與一般埠相同的機制。

這些功能如何運作？

協助程式埠是透過擴充機制實作 vcpkg-port-config.cmake 。

在執行埠之前，vcpkg 會匯入即將執行之埠直接相依性所導出的任何 vcpkg-port-config.cmake 檔案。

如果協助程式埠相依於不同的協助程式埠，則必須明確匯 vcpkg-port-config.cmake 入其相依性檔案。 協助程式對協助程式埠相依性不應標示為 主機相依性，這可確保一個腳本可以相依於相同安裝目錄中的另一個腳本。

相依於協助程式埠的埠應該將相依性標示為 主機相依性。

協助程式埠必須一律在share/${PORT}安裝樹狀目錄中的子目錄中安裝其vcpkg-port-config.cmake檔案。

範例：撰寫簡單的協助程式埠

1 - 建立定義協助程式函式的 CMake 檔案。

my-helper/my_helper_function.cmake

include_guard(GLOBAL)

function(my_helper_function)
  message(STATUS "my_helper_function() was called")
  my_other_helper_function()
endfunction()

include_guard(GLOBAL)檔案頂端的 ，可防止在檔案包含多次時重新定義此函式。

下列幾行會宣告名為 my_helper_function 的函式，該函式會顯示訊息，並呼叫 my_other_helper_function 在不同的協助程式埠中定義的 。

2 - 建立協助程式埠的 porftile.cmake 檔案

my-helper/portfile.cmake

set(VCPKG_POLICY_HELPER_PORT enabled)

file(INSTALL
  "${CMAKE_CURRENT_LIST_DIR}/vcpkg-port-config.cmake"
  DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")

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

透過啟用 VCPKG_POLICY_HELPER_PORT 原則，vcpkg 會啟用特別套用至協助程式埠的建置後檢查。 具體來說，檢查是否已 vcpkg-port-config.cmake 安裝在正確的路徑中，且目錄中未安裝 include 任何檔案。

下一行會在正確的位置安裝必要的 vcpkg-port-config.cmake 和 copyright 檔案 。share/${PORT}。

3 - 建立協助程式埠的 vcpkg.json 檔案

my-helper/vcpkg.json

{
  "name": "my-helper",
  "version-date": "2024-03-20",
  "description": "Provide my_helper_function()",
  "license": "MIT",
  "dependencies": [ 
    { "name": "my-other-helper" } 
  ]
}

我們建議使用 version-date 作為 協助程式埠的版本設定配置 。

dependencies此範例中的 ，包含另my-other-helper一個名為的協助程式埠參考。 相依性是有目的的，不會標示為主機相依性，因為這是協助程式對協助程式埠相依性。

4 - 建立協助程式埠的 vcpkg-port-config.cmake檔案

my-helper/vcpkg-port-config.cmake

include_guard(GLOBAL)

include("${CMAKE_CURRENT_LIST_DIR}/../my-other-helper/vcpkg-port-config.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/my_helper_function.cmake")

檔案 vcpkg-port-config.cmake 包含三行，第一行是全域 Include 防護，可防止檔案多次包含。

第二行包含 my-other-helper/vcpkg-port-config.cmake ，讓 my-other-helper 相依 my-helper 的埠能夠使用函式，而不需要將它們包含在 my-other-helper 其直接相依性清單中。

最後， my_helper_function.cmake 包含 my_helper_function 定義的檔案會包含在內。

5 - 在指令清單中取用my-helper

的任何取用者 my-helper 只需要包含本身的直接相 my-helper 依性，就不需要相依性 my-other-helper 。 取用指令清單應該將相依性標示為主機相依性。

my-port/vcpkg.json

{
  "name": "my-port",
  "version": "1.0.0",
  "dependencies": [
    {
      "name": "my-helper",
      "host": true
    }
  ]
}

這可在 my_helper_function 中使用 my-port/portfile.cmake。

my-port/portfile.cmake

my_helper_function()