Portas auxiliares de autor

As portas auxiliares, também chamadas de portas de script, expõem funções para outras portas consumirem durante seu processo de compilação. Por exemplo, a vcpkg-cmake porta define a vcpkg_cmake_configure() função para outras portas consumirem. Ao empacotar scripts comuns em uma porta auxiliar, a manutenção se torna mais simplificada, pois as atualizações podem ser feitas em um único local. Além disso, as portas auxiliares podem ser versionadas e dependem do uso dos mesmos mecanismos que as portas regulares.

Como eles funcionam?

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

Antes de uma porta ser executada, 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 auxiliar para auxiliar não devem ser marcadas como dependências de host, isso garante que um script possa depender de o outro estar 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 seu vcpkg-port-config.cmake arquivo em um share/${PORT} subdiretório na árvore de instalação.

Exemplo: Escrever uma porta auxiliar simples

1 - Crie um arquivo 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) na 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 chamada my_helper_function que exibe uma mensagem e chama o my_other_helper_function que é definido em uma porta auxiliar diferente.

2 - Criar o arquivo da porftile.cmake porta auxiliar

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)

Ao habilitar a política, o VCPKG_POLICY_HELPER_PORT vcpkg habilita verificações pós-compilação que se aplicam especificamente às portas 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 seu local correto (share/${PORT}).

3 - Crie 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" } 
  ]
}

Recomendamos usar version-date como esquema de controle de versão para portas auxiliares.

O dependencies neste exemplo contém uma referência a outra porta auxiliar chamada my-other-helper. A dependência não é marcada propositalmente como uma dependência de host, pois essa é uma dependência de porta auxiliar para auxiliar.

4 - Crie o arquivo 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 arquivo consiste em três linhas, a primeira é um protetor 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 disponibilizar as funções para my-other-helper portas que dependem sem my-helper que elas precisem incluir my-other-helper em sua lista de dependências diretas.

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

5 - Consumir my-helper em um manifesto

Qualquer consumidor de my-helper apenas precisa incluir uma dependência direta para my-helper si mesmo, nenhuma dependência my-other-helper é necessária. 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 é my_helper_function disponibilizado em my-port/portfile.cmake.

my-port/portfile.cmake

my_helper_function()