Tutorial: Empacotar uma biblioteca com vcpkg

Artigo
07/22/2024

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

Observação

No Windows, este tutorial usa o MSVC do Visual Studio como o compilador para desenvolvimento em C++.

1 - Configurar o vcpkg

Clonar o repositório

A primeira etapa é 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 selecionadas 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 trabalharem juntas. 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.
Executar o script de bootstrap

Agora que você clonou o repositório vcpkg, navegue até o vcpkg diretório e execute o script de bootstrap:
```
cd vcpkg && bootstrap-vcpkg.bat
```
```
cd vcpkg; .\bootstrap-vcpkg.bat
```
```
cd vcpkg && ./bootstrap-vcpkg.sh
```
O script de bootstrap executa verificações de pré-requisitos e baixa o executável vcpkg.

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

2 - Configure a variável de `VCPKG_ROOT` 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

Observação

A configuração de variáveis de ambiente usando o export comando afeta apenas a sessão atual do shell. Para tornar essa alteração permanente entre as sessões, adicione o export comando ao script de perfil do shell (por exemplo, ~/.bashrc ou ~/.zshrc).

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

Observação

Definir variáveis de ambiente dessa maneira afeta apenas a sessão de terminal atual. Para tornar essas alterações permanentes em todas as sessões, defina-as por meio do painel Variáveis de Ambiente do Sistema do Windows.

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

Observação

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

3 - Configure a sobreposição personalizada

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

4 - Configure 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",
  "homepage": "https://github.com/microsoft/vcpkg-docs/tree/cmake-sample-lib",
  "description": "A sample C++ library designed to serve as a foundational example for a tutorial on packaging libraries with vcpkg.",
  "license": "MIT",
  "dependencies": [
    {
      "name" : "vcpkg-cmake",
      "host" : true
    },
    {
      "name" : "vcpkg-cmake-config",
      "host" : true
    },
    "fmt"
  ]
}

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 compilar, 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 de vcpkg-cmake, que fornece funções e macros do CMake comumente usadas em portas vcpkg.
host: true: especifica que é uma dependência de host, o que significa que vcpkg-cmake é necessária para criar o pacote, mas não para usá-lo.
name: vcpkg-cmake-config: Especifica uma dependência de vcpkg-cmake-config, que auxilia no uso de scripts de configuração do CMake.
fmt: Especifica uma dependência de tempo de execução na fmt biblioteca. Este meio fmt é necessário para construir e usar o pacote.

Para obter mais informações sobre vcpkg.jsono , consulte a seguinte documentação 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)

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

Para obter mais diretrizes, consulte Manipulando arquivos de uso

Por fim, 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 Microsoft/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 "${SOURCE_PATH}/LICENSE" DESTINATION "${CURRENT_PACKAGES_DIR}/share/${PORT}" RENAME copyright)
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" "${CURRENT_PACKAGES_DIR}/share/${PORT}/usage" COPYONLY)

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 Microsoft/vcpkg-docs: O repositório GitHub que contém o código-fonte.
- REF "${VERSION}": A versão do código-fonte a ser baixada.
- 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 do repositório.
vcpkg_cmake_configure: configura o projeto usando o 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 o vcpkg.
file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include"): Exclui o diretório de inclusão da instalação de depuração para evitar sobreposição.
file(INSTALL "${SOURCE_PATH}/LICENSE" DESTINATION ...): Instala o arquivo LICENSE no diretório de compartilhamento do pacote e o renomeia para copyright.
configure_file("${CMAKE_CURRENT_LIST_DIR}/usage" ...): Copia um arquivo de instruções de uso para o diretório de compartilhamento do pacote.

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

5 - Atualização do SHA512 para `portfile.cmake`

Correr:

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

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

Expected hash: 00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
Actual hash: 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417

Copie o "Hash real" 4202125968a01219deeee14b81e1d476dab18d968425ba36d640816b0b3db6168f8ccf4120ba20526e9930c8c7294e64d43900ad2aef9d5f28175210d0c3a417e substitua o SHA512 portfile.cmake valor no 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/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 corretamente as compilações e links da biblioteca, 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.

Modifique 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 use 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.

Configure a compilação usando o CMake:

cmake --preset=default

Compile o projeto:

cmake --build build

Execute o aplicativo:

./build/HelloWorld

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

Hello vcpkg!

Próximas etapas

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

Para saber mais, veja:

Compartilhar via

Tutorial: Empacotar uma biblioteca com vcpkg

Pré-requisitos

1 - Configurar o vcpkg

2 - Configure a variável de `VCPKG_ROOT` ambiente

3 - Configure a sobreposição personalizada

4 - Configure os arquivos de porta

5 - Atualização do SHA512 para `portfile.cmake`

6 - Verifique a compilação da porta

Próximas etapas

Recursos adicionais

Compartilhar via

Tutorial: Empacotar uma biblioteca com vcpkg

Pré-requisitos

1 - Configurar o vcpkg

2 - Configure a variável de VCPKG_ROOT ambiente

3 - Configure a sobreposição personalizada

4 - Configure os arquivos de porta

5 - Atualização do SHA512 para portfile.cmake

6 - Verifique a compilação da porta

Próximas etapas

Recursos adicionais

2 - Configure a variável de `VCPKG_ROOT` ambiente

5 - Atualização do SHA512 para `portfile.cmake`