Creación de puertos auxiliares

Los puertos auxiliares, también denominados puertos de script, exponen funciones para que otros puertos los consuman durante su proceso de compilación. Por ejemplo, el vcpkg-cmake puerto define la vcpkg_cmake_configure() función para que otros puertos consuman. Al empaquetar scripts comunes en un puerto auxiliar, el mantenimiento se simplifica más a medida que se pueden realizar actualizaciones en una sola ubicación. Además, los puertos auxiliares se pueden versionar y depender del uso de los mismos mecanismos que los puertos normales.

¿Cómo funcionan?

Los puertos auxiliares se implementan a través del mecanismo de vcpkg-port-config.cmake extensión.

Antes de ejecutar un puerto, vcpkg importará cualquier vcpkg-port-config.cmake archivo exportado por las dependencias directas del puerto a punto de ejecutarse.

Si un puerto auxiliar depende de un puerto auxiliar diferente, debe importar explícitamente el vcpkg-port-config.cmake archivo de su dependencia. Las dependencias del puerto auxiliar a asistente no deben marcarse como dependencias de host, lo que garantiza que un script pueda depender del otro que se encuentra en el mismo directorio de instalación.

Los puertos que dependen de un puerto auxiliar deben marcar la dependencia como una dependencia de host.

Los puertos auxiliares siempre deben instalar su vcpkg-port-config.cmake archivo en un share/${PORT} subdirectorio en el árbol de instalación.

Ejemplo: Escritura de un puerto auxiliar sencillo

1 - Cree un archivo CMake que defina la función auxiliar.

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

La include_guard(GLOBAL) parte superior del archivo protege contra la redefinición de esta función cuando el archivo se incluye varias veces.

Las líneas siguientes declaran una función denominada my_helper_function que muestra un mensaje y llama al my_other_helper_function que se define en un puerto auxiliar diferente.

2 - Creación del archivo del puerto auxiliar 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)

Al habilitar la VCPKG_POLICY_HELPER_PORT directiva, vcpkg habilita comprobaciones posteriores a la compilación que se aplican específicamente a los puertos auxiliares. En concreto, comprueba que vcpkg-port-config.cmake está instalado en la ruta de acceso correcta y que no hay ningún archivo instalado en el include directorio.

Las líneas siguientes instalan los archivos y copyright necesarios vcpkg-port-config.cmake en su ubicación correcta (share/${PORT}).

3 - Crear el archivo del puerto auxiliar 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" } 
  ]
}

Se recomienda usar version-date como esquema de control de versiones para los puertos auxiliares.

En dependencies este ejemplo, contiene una referencia a otro puerto auxiliar denominado my-other-helper. La dependencia es intencionada y no está marcada como una dependencia de host, ya que se trata de una dependencia de puerto auxiliar a auxiliar.

4 - Creación del archivo del puerto auxiliar 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")

El vcpkg-port-config.cmake archivo consta de tres líneas, la primera es una protección de inclusión global que impide que el archivo se incluya varias veces.

La segunda línea incluye my-other-helper/vcpkg-port-config.cmake para que las funciones de my-other-helper estén disponibles para los puertos que dependen my-helper de sin tener que incluirlas my-other-helper en su lista de dependencias directas.

Por último, se incluye el my_helper_function.cmake archivo que contiene la my_helper_function definición.

5 - Consumir my-helper en un manifiesto

Cualquier consumidor de my-helper solo necesita incluir una dependencia directa para my-helper sí misma, no se necesita ninguna dependencia a my-other-helper . El manifiesto de consumo debe marcar la dependencia como una dependencia de host.

my-port/vcpkg.json

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

Esto hace que esté my_helper_function disponible en my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()