Criando portas de script

As portas de script, também chamadas de portas auxiliares, expõem funções para outras portas consumirem durante o processo de build. Por exemplo, a porta vcpkg-cmake define a função vcpkg_cmake_configure() para que outras portas possam consumi-la. Ao empacotar scripts comuns em uma porta auxiliar, a manutenção se torna mais simplificada à medida que as atualizações podem ser feitas em um único local. Além disso, as portas auxiliares podem ser versionadas e podem contar com os mesmos mecanismos utilizados pelas portas regulares.

Como eles funcionam?

As portas auxiliares são implementadas por meio do vcpkg-port-config.cmake mecanismo de extensão.

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

Se uma porta auxiliar depender de uma porta auxiliar diferente, ela deverá importar explicitamente o vcpkg-port-config.cmake arquivo de sua dependência. As dependências de porta de ajudante para ajudante não devem ser marcadas como dependências de host, isso garante que um script possa depender do outro que esteja no mesmo diretório de instalação.

As 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 vcpkg-port-config.cmake arquivo em um share/${PORT} subdiretório na árvore de instalação.

Exemplo: escrever uma porta auxiliar simples

1 – Criar um arquivo CMake que define 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()

A include_guard(GLOBAL) parte superior do arquivo protege contra a redefinição dessa função quando o arquivo é incluído várias vezes.

As linhas a seguir declaram uma função nomeada my_helper_function que exibe uma mensagem e chama a my_other_helper_function que é definida em uma porta auxiliar diferente.

2 – Criar o arquivo 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 habilitar a política VCPKG_POLICY_CMAKE_HELPER_PORT, o vcpkg permite verificações pós-build que se aplicam especificamente aos ports auxiliares. Especificamente, verifica se vcpkg-port-config.cmake está instalado no caminho correto e se nenhum arquivo está instalado no include diretório.

As próximas linhas instalam os arquivos necessários vcpkg-port-config.cmake e copyright em seus locais corretos (share/${PORT}).

3 – Criar o arquivo 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" } 
  ]
}

É recomendável usar version-date como o esquema de controle de versão para portas auxiliares.

Neste dependencies exemplo, contém uma referência a outra porta auxiliar chamada my-other-helper. A dependência não é propositalmente marcada como uma dependência de host, pois trata-se de uma dependência de porta entre auxiliares.

4 – Criar o arquivo da porta 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")

O vcpkg-port-config.cmake arquivo consiste em três linhas, a primeira é uma guarda de inclusão global que impede que o arquivo 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 precisar incluir my-other-helper na lista de dependências diretas.

Por fim, o my_helper_function.cmake arquivo que contém a my_helper_function definição está incluído.

5 – Consumir my-helper em um manifesto

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

my-port/vcpkg.json

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

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

my-port/portfile.cmake

my_helper_function()