Porte helper autore

Le porte helper, dette anche porte script, espongono funzioni per altre porte da utilizzare durante il processo di compilazione. Ad esempio, la vcpkg-cmake porta definisce la funzione per l'utilizzo vcpkg_cmake_configure() di altre porte. Tramite la creazione di pacchetti di script comuni in una porta helper, la manutenzione diventa più semplificata perché gli aggiornamenti possono essere eseguiti in un'unica posizione. Inoltre, le porte helper possono essere con controllo delle versioni e dipendono dall'uso degli stessi meccanismi delle porte regolari.

Come funziona?

Le porte helper vengono implementate tramite il meccanismo di vcpkg-port-config.cmake estensione.

Prima dell'esecuzione di una porta, vcpkg importerà qualsiasi vcpkg-port-config.cmake file esportato dalle dipendenze dirette della porta da eseguire.

Se una porta helper dipende da una porta helper diversa, deve importare esplicitamente il vcpkg-port-config.cmake file della relativa dipendenza. Le dipendenze delle porte helper-to-helper non devono essere contrassegnate come dipendenze host, in modo da garantire che uno script possa dipendere dall'altro nella stessa directory di installazione.

Le porte che dipendono da una porta helper devono contrassegnare la dipendenza come dipendenza host.

Le porte helper devono sempre installare il vcpkg-port-config.cmake file in una share/${PORT} sottodirectory nell'albero di installazione.

Esempio: Scrivere una semplice porta helper

1 - Creare un file CMake che definisce la funzione helper.

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

Nella include_guard(GLOBAL) parte superiore del file proteggere dalla ridefinizione di questa funzione quando il file viene incluso più volte.

Le righe seguenti dichiarano una funzione denominata my_helper_function che visualizza un messaggio e chiama l'oggetto my_other_helper_function definito in una porta helper diversa.

2 - Creare il file della porta helper 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)

Abilitando il VCPKG_POLICY_HELPER_PORT criterio, vcpkg abilita i controlli post-compilazione che si applicano in modo specifico alle porte helper. In particolare, verifica che vcpkg-port-config.cmake sia installato nel percorso corretto e che non siano installati file nella include directory.

Le righe successive installano i file necessari vcpkg-port-config.cmake e copyright nel percorso corretto (share/${PORT}).

3 - Creare il file della porta helper 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" } 
  ]
}

È consigliabile usare version-date come schema di controllo delle versioni per le porte helper.

In dependencies questo esempio contiene un riferimento a un'altra porta helper denominata my-other-helper. La dipendenza non è intenzionale non contrassegnata come dipendenza host perché si tratta di una dipendenza da porta helper-to-helper.

4 - Creare il file della porta helper 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")

Il vcpkg-port-config.cmake file è costituito da tre righe, il primo è una protezione di inclusione globale che impedisce l'inclusione del file più volte.

La seconda riga include my-other-helper/vcpkg-port-config.cmake per rendere le funzioni disponibili per my-other-helper le porte che my-helper dipendono da senza dover includere my-other-helper nell'elenco delle dipendenze dirette.

Infine, viene incluso il my_helper_function.cmake file che contiene la my_helper_function definizione.

5 - Utilizzare my-helper in un manifesto

Qualsiasi consumer di my-helper deve includere solo una dipendenza diretta a my-helper se stessa, non è necessaria alcuna dipendenza da my-other-helper . Il manifesto di utilizzo deve contrassegnare la dipendenza come dipendenza host.

my-port/vcpkg.json

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

In questo modo è my_helper_function disponibile in my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()