Tworzenie portów pomocnika

Porty pomocnika, nazywane również portami skryptów, udostępniają 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 pomocnika 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ć vcpkg-port-config.cmake plik zależności. 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 pomocnika muszą zawsze instalować plik vcpkg-port-config.cmake w share/${PORT} podkatalogu 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()

W include_guard(GLOBAL) górnej części pliku ochrona 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 my_other_helper_function element zdefiniowany w innym porcie pomocnika.

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

Po włączeniu VCPKG_POLICY_HELPER_PORT zasad program vcpkg umożliwia sprawdzanie po kompilacji, które mają zastosowanie specjalnie 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 vcpkg-port-config.cmake pliki i copyright w 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-date jako 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 pomocy.

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 funkcje dostępne dla my-other-helper portów, które zależą od my-helper nich bez konieczności uwzględnienia my-other-helper ich na 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 uwzględniać tylko bezpośrednią zależność do my-helper siebie, nie jest wymagana żadna zależność my-other-helper . Manifest zużywający 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 Spowoduje to udostępnienie w programie my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()