Creación de puertos de script

Los puertos de script, también llamados puertos auxiliares, exponen funciones para que otros puertos 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, se pueden versionar y depender de los puertos auxiliares utilizando los mismos mecanismos que los puertos normales.

¿Cómo funcionan?

Los puertos auxiliares se implementan mediante el mecanismo de extensión de vcpkg-port-config.cmake.

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 entre puertos auxiliares no deben marcarse como dependencias de host, lo que garantiza que un script pueda depender de que el otro esté 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_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)

Al habilitar la VCPKG_POLICY_CMAKE_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 vcpkg-port-config.cmake y copyright necesarios 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.

El dependencies en este ejemplo contiene una referencia a otro puerto auxiliar denominado my-other-helper. La dependencia no se marca intencionadamente como una dependencia de host, ya que esta es una dependencia de puerto entre auxiliares.

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 de my-helper sin tener que incluir 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 a my-helper por sí mismo, no se necesita 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()