Créer des ports d’assistance

Les ports d’assistance, également appelés ports de script, exposent les fonctions d’autres ports à consommer pendant leur processus de génération. Par exemple, le vcpkg-cmake port définit la vcpkg_cmake_configure() fonction pour les autres ports à consommer. En empaquetant des scripts courants dans un port d’assistance, la maintenance devient plus rationalisée, car les mises à jour peuvent être effectuées dans un emplacement unique. En outre, les ports d’assistance peuvent être versionnés et dépendent de l’utilisation des mêmes mécanismes que les ports standard.

Comment fonctionnent-ils ?

Les ports d’assistance sont implémentés via le mécanisme d’extension vcpkg-port-config.cmake .

Avant l’exécution d’un port, vcpkg importe tout vcpkg-port-config.cmake fichier exporté par les dépendances directes du port sur le point d’être exécuté.

Si un port d’assistance dépend d’un autre port d’assistance, il doit importer explicitement le vcpkg-port-config.cmake fichier de sa dépendance. Les dépendances de port d’assistance à assistance ne doivent pas être marquées comme dépendances d’hôte, ce qui garantit qu’un script peut dépendre de l’autre étant dans le même répertoire d’installation.

Les ports qui dépendent d’un port d’assistance doivent marquer la dépendance comme dépendance hôte.

Les ports d’assistance doivent toujours installer leur vcpkg-port-config.cmake fichier dans un share/${PORT} sous-répertoire dans l’arborescence d’installation.

Exemple : Écrire un port d’assistance simple

1 - Créez un fichier CMake qui définit la fonction d’assistance.

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

En include_guard(GLOBAL) haut du fichier, protégez-vous contre la redéfinition de cette fonction lorsque le fichier est inclus plusieurs fois.

Les lignes suivantes déclarent une fonction nommée my_helper_function qui affiche un message et appelle celle my_other_helper_function définie dans un autre port d’assistance.

2 - Créer le fichier du port d’assistance 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)

En activant la VCPKG_POLICY_HELPER_PORT stratégie, vcpkg active les case activée post-build qui s’appliquent spécifiquement aux ports d’assistance. Plus précisément, les case activée installées vcpkg-port-config.cmake dans le chemin d’accès correct et qu’aucun fichier n’est installé dans le include répertoire.

Les lignes suivantes installent les fichiers requis vcpkg-port-config.cmake à copyright leur emplacement correct (share/${PORT}).

3 - Créer le fichier du port d’assistance 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" } 
  ]
}

Nous vous recommandons d’utiliser version-date le schéma de contrôle de version pour les ports d’assistance.

L’exemple dependencies suivant contient une référence à un autre port d’assistance nommé my-other-helper. La dépendance n’est pas marquée comme une dépendance hôte, car il s’agit d’une dépendance de port d’assistance à assistance.

4 - Créer le fichier du port d’assistance 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")

Le vcpkg-port-config.cmake fichier se compose de trois lignes, le premier est un garde d’inclusion global qui empêche le fichier d’être inclus plusieurs fois.

La deuxième ligne inclut my-other-helper/vcpkg-port-config.cmake de rendre les fonctions my-other-helper disponibles pour les ports qui dépendent my-helper sans qu’elles n’ont à inclure my-other-helper dans leur liste de dépendances directes.

Enfin, le my_helper_function.cmake fichier qui contient la my_helper_function définition est inclus.

5 - Consommer my-helper dans un manifeste

Tout consommateur de n’a my-helper besoin d’inclure qu’une dépendance directe à my-helper elle-même, aucune dépendance n’est my-other-helper nécessaire. Le manifeste consommateur doit marquer la dépendance en tant que dépendance hôte.

my-port/vcpkg.json

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

Cela rend my_helper_function disponible en my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()