Porty autorskie skryptu

Porty skryptu, nazywane również portami pomocnika, uwidaczniają funkcje innych portów do użytku podczas procesu kompilacji. Na przykład vcpkg-cmake port definiuje vcpkg_cmake_configure() funkcję do użytku przez inne porty. Dzięki pakowaniu typowych skryptów do portu pomocniczego konserwacja staje się bardziej usprawniona, ponieważ aktualizacje mogą być wprowadzane w jednej lokalizacji. Ponadto porty pomocnika mogą być wersjonowane i zależne od używania tych samych mechanizmów co zwykłe porty.

Jak działają?

Porty pomocnicze są implementowane za pośrednictwem vcpkg-port-config.cmake mechanizmu rozszerzenia.

Przed wykonaniem portu vcpkg zaimportuje dowolny vcpkg-port-config.cmake plik wyeksportowany przez bezpośrednie zależności portu, który ma zostać wykonany.

Jeśli port pomocnika zależy od innego portu pomocniczego, musi jawnie zaimportować plik swojej zależności vcpkg-port-config.cmake. Zależności portów pomocnika-pomocnika nie powinny być oznaczone jako zależności hosta. Gwarantuje to, że jeden skrypt może zależeć od drugiego z tego samego katalogu instalacji.

Porty zależne od portu pomocniczego powinny oznaczać zależność jako zależność hosta.

Porty pomocnicze muszą zawsze instalować plik vcpkg-port-config.cmake w podkatalogu share/${PORT} w drzewie instalacji.

Przykład: pisanie prostego portu pomocniczego

1 — Utwórz plik CMake definiujący funkcję pomocnika.

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()

Poprzez umieszczenie include_guard(GLOBAL) w górnej części pliku, chroni się przed ponownym zdefiniowaniem tej funkcji, gdy plik jest dołączany wiele razy.

Poniższe wiersze deklarują funkcję o nazwie my_helper_function, która wyświetla komunikat i wywołuje funkcję my_other_helper_function, zdefiniowaną w innym porcie pomocniczym.

2 — Tworzenie pliku portu pomocniczego 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)

Po włączeniu VCPKG_POLICY_CMAKE_HELPER_PORT polityki program vcpkg umożliwia sprawdzanie po kompilacji, które mają zastosowanie szczególnie do portów pomocnika. W szczególności sprawdza, czy vcpkg-port-config.cmake program jest zainstalowany we właściwej ścieżce i że żadne pliki nie są zainstalowane w include katalogu.

Następne wiersze instalują wymagane pliki vcpkg-port-config.cmake i copyright w ich odpowiedniej lokalizacji (share/${PORT}).

3 — Tworzenie pliku portu pomocniczego 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" } 
  ]
}

Zalecamy użycie version-datejako schematu przechowywania wersji dla portów pomocnika.

W dependencies tym przykładzie znajduje się odwołanie do innego portu pomocniczego o nazwie my-other-helper. Zależność nie jest celowo oznaczona jako zależność hosta, ponieważ jest to zależność portu pomocnika do pomocnika.

4 — Tworzenie pliku portu pomocniczego 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")

Plik vcpkg-port-config.cmake składa się z trzech wierszy, a pierwszy to globalna ochrona dołączania, która uniemożliwia wielokrotne dołączanie pliku.

Drugi wiersz zawiera my-other-helper/vcpkg-port-config.cmake w celu udostępnienia funkcji w my-other-helper portom, które zależą od my-helper, bez konieczności uwzględniania my-other-helper na ich liście bezpośrednich zależności.

my_helper_function.cmake Na koniec znajduje się plik zawierający definicjęmy_helper_function.

5 — Używanie my-helper w manifeście

Każdy konsument my-helper musi obejmować tylko bezpośrednią zależność do my-helper, nie wymaga zależności do my-other-helper. Manifest konsumpcyjny powinien oznaczać zależność jako zależność hosta.

my-port/vcpkg.json

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

my_helper_function staje się dostępne w my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()