Порты скриптов разработки

Порты скриптов, также называемые вспомогательными портами, предоставляют функции для других портов, которые будут использоваться во время сборки. Например, vcpkg-cmake порт задает функцию vcpkg_cmake_configure() для использования другими портами. Упаковав распространенные сценарии в вспомогательный модуль, обслуживание упрощается, так как обновления можно выполнять в одном месте. Кроме того, вспомогательные порты можно версионировать и использовать зависимости с помощью тех же механизмов, что и обычные порты.

Как они работают?

Порты-помощники реализуются с помощью механизма расширения vcpkg-port-config.cmake.

Перед выполнением порта, который предстоит выполнить, vcpkg импортирует любой файл vcpkg-port-config.cmake, экспортированный прямыми зависимостями этого порта.

Если вспомогательный порт зависит от другого вспомогательного порта, он должен явно импортировать vcpkg-port-config.cmake файл своей зависимости. Вспомогательные зависимости между портами не должны быть помечены как зависимости хоста, это гарантирует, что один скрипт может зависеть от другого, находящегося в том же каталоге установки.

Порты, зависящие от вспомогательного порта, должны пометить зависимость как зависимость узла.

Вспомогательные порты всегда должны устанавливать свой vcpkg-port-config.cmake файл в share/${PORT} подкаталоге в дереве установки.

Пример. Создание простого вспомогательного порта

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_CMAKE_HELPER_PORT enabled)

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/my_helper_function.cmake" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
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_CMAKE_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 состоит из трех строк, первый — это глобальная защита включения, которая препятствует включению файла несколько раз.

Вторая строка включает 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()