Autoria de portas de script

As portas script, também chamadas de portas auxiliares, expõem funções para outras portas serem consumidas durante o seu processo de compilação. Por exemplo, a vcpkg-cmake porta define a vcpkg_cmake_configure() função para ser utilizada por outras portas. Ao empacotar scripts comuns numa porta auxiliar, a manutenção torna-se mais simplificada, pois as atualizações podem ser feitas num único local. Além disso, as portas auxiliares podem ser versionadas e dependentes usando os mesmos mecanismos das portas normais.

Como funcionam?

Portas auxiliares são implementadas através do mecanismo de extensão vcpkg-port-config.cmake.

Antes de uma porta ser executada, o vcpkg irá importar qualquer vcpkg-port-config.cmake ficheiro que tenha sido exportado pelas dependências diretas da porta prestes a ser executada.

Se uma porta auxiliar depender de uma porta auxiliar diferente, deve importar explicitamente o vcpkg-port-config.cmake ficheiro da sua dependência. As dependências de portas Helper-to-helper não devem ser marcadas como dependências de host; isto garante que um script possa depender da presença do outro no mesmo directório de instalação.

Portas que dependem de uma porta auxiliar devem marcar a dependência como uma dependência de host.

As portas auxiliares devem sempre instalar o seu vcpkg-port-config.cmake ficheiro num share/${PORT} subdiretório na árvore de instalação.

Exemplo: Criar uma porta auxiliar simples

1 - Criar um ficheiro CMake que defina a função 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()

O include_guard(GLOBAL) topo do ficheiro protege contra a redefinição desta função quando o ficheiro é incluído várias vezes.

As linhas seguintes declaram uma função chamada my_helper_function que apresenta uma mensagem e chama a my_other_helper_function que está definida numa porta auxiliar diferente.

2 - Criar o ficheiro da porftile.cmake porta auxiliar

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)

Ao ativar a VCPKG_POLICY_CMAKE_HELPER_PORT política, o vcpkg possibilita verificações pós-construção que se aplicam especificamente às portas auxiliares. Especificamente, verifica se vcpkg-port-config.cmake está instalado no caminho correto e que não há ficheiros instalados no include diretório.

As linhas seguintes instalam os ficheiros necessários vcpkg-port-config.cmake e copyright na sua localização correta (share/${PORT}).

3 - Criar o ficheiro da vcpkg.json porta auxiliar

my-helper/vcpkg.json

{
  "name": "my-helper",
  "version-date": "2024-03-20",
  "description": "Provide my_helper_function()",
  "license": "MIT",
  "dependencies": [ 
    { "name": "my-other-helper" } 
  ]
}

Recomendamos usar version-date como esquema de versões para ports auxiliares.

Neste dependencies exemplo contêm uma referência a outra porta auxiliar chamada my-other-helper. A dependência é propositadamente não marcada como dependência do host, pois é uma dependência da porta helper-to-helper.

4 - Criar o ficheiro da vcpkg-port-config.cmakeporta auxiliar

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

O vcpkg-port-config.cmake ficheiro consiste em três linhas, sendo a primeira uma proteção global de inclusão que impede que o ficheiro seja incluído várias vezes.

A segunda linha inclui my-other-helper/vcpkg-port-config.cmake para tornar as funções em my-other-helper disponíveis para portas que dependem de my-helper sem que estas tenham de incluir my-other-helper na sua lista de dependências diretas.

Finalmente, o my_helper_function.cmake ficheiro que contém a my_helper_function definição é incluído.

5 - Consumir my-helper num ficheiro de manifesto

Qualquer consumidor de my-helper só precisa de incluir uma dependência direta ao my-helper em si, não é necessária uma dependência para my-other-helper. O manifesto consumidor deve marcar a dependência como uma dependência do hospedeiro.

my-port/vcpkg.json

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

Isto torna my_helper_function disponível em my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()