Tutorial: Empacotar uma biblioteca com vcpkg

Este tutorial orienta você sobre como empacotar uma biblioteca para vcpkg usando uma sobreposição personalizada. Recomendamos que você leia o tutorial Instalar e usar pacotes com o CMake antes de continuar.

Pré-requisitos

• Um terminal
• Um compilador C++
• CMake
• Git

1 - Configurar vcpkg

1. Clonar o repositório

   O primeiro passo é clonar o repositório vcpkg do GitHub. O repositório contém scripts para adquirir o executável vcpkg e um registro de bibliotecas de código aberto com curadoria mantidas pela comunidade vcpkg. Para fazer isso, execute:

   git clone https://github.com/microsoft/vcpkg.git
   

   O registro com curadoria vcpkg é um conjunto de mais de 2.000 bibliotecas de código aberto. Essas bibliotecas foram validadas pelos pipelines de integração contínua do vcpkg para funcionar em conjunto. Embora o repositório vcpkg não contenha o código-fonte dessas bibliotecas, ele contém receitas e metadados para compilá-los e instalá-los em seu sistema.

2. Executar o script de bootstrap

   Agora que você clonou o repositório vcpkg, navegue até o vcpkg diretório e execute o script bootstrap:

   cd vcpkg && bootstrap-vcpkg.bat
   

   cd vcpkg; .\bootstrap-vcpkg.bat
   

   cd vcpkg && ./bootstrap-vcpkg.sh
   

   O script bootstrap executa verificações de pré-requisitos e baixa o executável vcpkg.

   É isso! VCPKG está configurado e pronto para uso.

2 - Configurar a VCPKG_ROOT variável de ambiente

Para definir as variáveis de VCPKG_ROOT ambiente, execute os seguintes comandos:

export VCPKG_ROOT=/path/to/vcpkg
export PATH=$VCPKG_ROOT:$PATH

set "VCPKG_ROOT=C:\path\to\vcpkg"
set PATH=%VCPKG_ROOT%;%PATH%

$env:VCPKG_ROOT="C:\path\to\vcpkg"
$env:PATH="$env:VCPKG_ROOT;$env:PATH"

A configuração VCPKG_ROOT informa ao vcpkg onde sua instância vcpkg está localizada. Adicioná-lo a PATH garante que possas executar comandos vcpkg diretamente a partir do shell.

3 - Configurar a sobreposição personalizada

1. Crie um novo diretório chamado custom-overlay ao lado do projeto Hello World que você criou no tutorial Instalar e usar pacotes com o CMake.
2. Dentro custom-overlay do diretório, crie uma pasta chamada vcpkg-sample-library.

4 - Configurar os arquivos de porta

Primeiro, crie o vcpkg.json arquivo dentro da custom-overlay/vcpkg-sample-library pasta com o seguinte conteúdo:

{
  "name": "vcpkg-sample-library",
  "version": "1.0.2",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "homepage": "https://github.com/MicrosoftDocs/vcpkg-docs/tree/cmake-sample-lib",
  "license": "MIT",
  "dependencies": [
    "fmt",
    {
      "name": "vcpkg-cmake",
      "host": true
    },
    {
      "name": "vcpkg-cmake-config",
      "host": true
    }
  ]
}

O vcpkg.json arquivo serve como um manifesto que define metadados e dependências para uma biblioteca C++, fornecendo ao vcpkg as informações necessárias para criar, instalar e gerenciar o pacote.

• name: Especifica o nome da biblioteca. Isso é usado como o identificador do pacote.
• version: Indica o número da versão da biblioteca.
• homepage: URL para a página inicial do projeto, geralmente seu repositório. Útil para quem quer saber mais ou contribuir.
• description: Breve texto descrevendo o que a biblioteca faz. Isso é para documentação e usuários.
• license: Especifica a licença sob a qual a biblioteca é distribuída.
• dependencies: Uma matriz que contém a lista de dependências de que a biblioteca precisa.
• name: vcpkg-cmake: Especifica uma dependência no vcpkg-cmake, que fornece funções CMake e macros comumente usadas em portas vcpkg.
• host: true: Especifica que é uma dependência de host, o que significa que vcpkg-cmake é necessário para criar o pacote, mas não para usá-lo.
• name: vcpkg-cmake-config: Especifica uma dependência do vcpkg-cmake-config, que auxilia no uso de scripts de configuração do CMake.
• fmt: Especifica uma dependência em tempo de execução da biblioteca fmt. Isso significa que fmt é necessário para a construção e para o uso do pacote.

Para obter mais informações sobre vcpkg.json, consulte a documentação seguinte sobre manifestos.

Agora, crie o usage arquivo dentro do custom-overlay\vcpkg-sample-library diretório com o seguinte conteúdo:

vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

O fornecimento de documentação de uso para portas permite que os usuários as adotem facilmente em seus projetos. É altamente recomendável fornecer um arquivo usage dentro do diretório da porta (ports/<port name>/usage) que descreva as etapas mínimas necessárias para integrar-se a um sistema de compilação. Para determinar as instruções de uso corretas, recomenda-se seguir as orientações do upstream. No caso de o upstream não fornecer informações de uso, pode ser necessário vasculhar seu sistema de compilação para encontrar os destinos exportados.

Para obter mais orientações, consulte Tratamento de arquivos de uso

Finalmente, crie o portfile.cmake arquivo dentro do custom-overlay\vcpkg-sample-library diretório com o seguinte conteúdo:

vcpkg_check_linkage(ONLY_STATIC_LIBRARY)

vcpkg_from_github(
    OUT_SOURCE_PATH SOURCE_PATH
    REPO MicrosoftDocs/vcpkg-docs
    REF "${VERSION}"
    SHA512 0 # This is a temporary value. We will modify this value in the next section.
    HEAD_REF cmake-sample-lib
)

vcpkg_cmake_configure(
    SOURCE_PATH "${SOURCE_PATH}"
)

vcpkg_cmake_install()

vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib")

file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")

file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}")
vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

Isso portfile define como baixar, compilar, instalar e empacotar uma biblioteca C++ específica do GitHub usando vcpkg.

• vcpkg_check_linkage(ONLY_STATIC_LIBRARY): Especifica que apenas a vinculação estática é suportada para este pacote.
• vcpkg_from_github: Inicia a função para baixar o código-fonte de um repositório GitHub.
  • OUT_SOURCE_PATH SOURCE_PATH: Define o diretório onde o código-fonte será extraído.
  • REPO MicrosoftDocs/vcpkg-docs: O repositório GitHub que contém o código-fonte.
  • REF "${VERSION}": A versão do código-fonte para download.
  • SHA512 0: Espaço reservado para o hash SHA-512 do código-fonte para verificação de integridade.
  • HEAD_REF main: Especifica a ramificação padrão para o repositório.
• vcpkg_cmake_configure: Configura o projeto usando CMake, configurando a compilação.
  • SOURCE_PATH "${SOURCE_PATH}": O caminho para o código-fonte baixado anteriormente.
• vcpkg_cmake_install(): Compila e instala o pacote usando o CMake.
• vcpkg_cmake_config_fixup(PACKAGE_NAME "my_sample_lib"): Corrige os arquivos de configuração do pacote CMake para serem compatíveis com vcpkg.
• file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Exclui da instalação de depuração o diretório include para evitar conflitos.
• file(INSTALL "${CMAKE_CURRENT_LIST_DIR}/usage" ...): Copia um arquivo de instruções de uso para o diretório de compartilhamento do pacote.
• vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE"): Instala o arquivo LICENSE no diretório de compartilhamento do pacote e o renomeia para copyright.

Para obter mais informações, consulte o guia do mantenedor.

5 - Atualização SHA512 para portfile.cmake

Executar:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Você receberá uma longa mensagem de erro. Analise a saída até encontrar:

Downloading https://github.com/MicrosoftDocs/vcpkg-docs/archive/1.0.2.tar.gz -> MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
Successfully downloaded MicrosoftDocs-vcpkg-docs-1.0.2.tar.gz
error: failing download because the expected SHA512 was all zeros, please change the expected SHA512 to: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Copie o "hash atual" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417, e substitua o valor SHA512 no portfile.cmake pelo seu valor.

Execute novamente o comando de instalação:

vcpkg install vcpkg-sample-library --overlay-ports=C:\path\to\custom-overlay

Computing installation plan...
The following packages will be built and installed:
    vcpkg-sample-library:x64-windows -> 1.0.2 -- C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
Detecting compiler hash for triplet x64-windows...
Restored 0 package(s) from C:\Users\dev\AppData\Local\vcpkg\archives in 174 us. Use --debug to see more details.
Installing 1/1 vcpkg-sample-library:x64-windows...
Building vcpkg-sample-library:x64-windows...
-- Installing port from location: C:\Users\dev\demo\custom-overlay\vcpkg-sample-library
-- Note: vcpkg-sample-library only supports static library linkage. Building static library.
-- Using cached Microsoft-vcpkg-docs-1.0.2.tar.gz.
-- Cleaning sources at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean. Use --editable to skip cleaning for the packages you specify.
-- Extracting source C:/Users/dev/demo/vcpkg/downloads/Microsoft-vcpkg-docs-1.0.2.tar.gz
-- Using source at C:/Users/dev/demo/vcpkg/buildtrees/vcpkg-sample-library/src/1.0.2-2aff836404.clean
-- Configuring x64-windows
-- Building x64-windows-dbg
-- Building x64-windows-rel
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/usage
-- Installing: C:/Users/dev/demo/vcpkg/packages/vcpkg-sample-library_x64-windows/share/vcpkg-sample-library/copyright
-- Performing post-build validation
Stored binaries in 1 destinations in 94 ms.
Elapsed time to handle vcpkg-sample-library:x64-windows: 6.1 s
Total install time: 6.1 s
vcpkg-sample-library provides CMake targets:

find_package(my_sample_lib CONFIG REQUIRED)
target_link_libraries(main PRIVATE my_sample_lib::my_sample_lib)

6 - Verifique a compilação da porta

Para verificar as compilações e links da biblioteca corretamente, adicione uma nova dependência ao helloworld projeto criado no tutorial de pacotes de instalação. Faça as seguintes alterações nos arquivos de manifesto e configuração do projeto.

Modificar helloworld/vcpkg.json para adicionar uma dependência em vcpkg-sample-library:

{
    "dependencies": [
        "fmt",
        "vcpkg-sample-library"
    ]
}

Modifique helloworld/vcpkg-configuration.json para incluir a overlay-ports pasta que contém a nova porta:

{
  "default-registry": {
    "kind": "git",
    "baseline": "45f6e57d3e10ad96b7db206cf7888f736ba5aa61",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ],
  "overlay-ports": [
    "../custom-overlay"
  ]
}

Em seguida, modifique helloworld/CMakeLists.txt e helloworld/main.cpp para usar a nova dependência.

Modifique o helloworld/CMakeLists.txt com o seguinte conteúdo:

cmake_minimum_required(VERSION 3.10)

project(HelloWorld)

find_package(fmt CONFIG REQUIRED)
find_package(my_sample_lib CONFIG REQUIRED)  # Add this line

add_executable(HelloWorld helloworld.cpp)

target_link_libraries(HelloWorld PRIVATE fmt::fmt)
target_link_libraries(HelloWorld PRIVATE my_sample_lib::my_sample_lib)  # Add this line

Modifique o main.cpp com o seguinte conteúdo:

#include "my_sample_lib.h"  // Replace #include <fmt/core.h> with "my_sample_lib.h"

int main()
{
    greet("vcpkg!");  // Replace fmt::print("Hello World!\n) with this line
    return 0;
}

Configure, compile e execute o aplicativo.

1. Configure a compilação usando o CMake:

cmake --preset=default

2. Compile o projeto:

cmake --build build

3. Execute a aplicação:

./build/HelloWorld

O caminho para o executável do seu projeto pode ser diferente, por exemplo: ./build/Debug/HelloWorld.exe.

Hello vcpkg!

Próximos passos

Agora que o foi empacotado vcpkg-sample-library como porta, a próxima etapa é adicioná-lo ao registro com curadoria vcpkg. Consulte Adicionando portas ao registro vcpkg.

Para obter mais informações, consulte:

• Portos
• Guia do mantenedor