vcpkg em projetos do CMake

Artigo
01/10/2024

vcpkg oferece integração perfeita com o CMake para disponibilizar pacotes instalados em seus projetos automaticamente. O mecanismo no qual vcpkg se integra é fornecendo um arquivo CMake toolchain.

Na primeira vez que o CMake configura um projeto, ele executa rotinas de pesquisa internas para localizar uma cadeia de ferramentas viável (compilador, linker, etc.). Essa busca acontece dentro da project() função no seu CMakeLists.txt.

Para personalizar o processo de seleção do toolchain, o CMake oferece suporte ao uso de scripts personalizados da linguagem CMake, conhecidos como arquivos toolchain. Um arquivo toolchain é especificado definindo a CMAKE_TOOLCHAIN_FILE variável. O CMake avalia o conteúdo do script de cadeia de ferramentas fornecido e define definições de variáveis, caminhos para ferramentas de compilação necessárias e outros parâmetros de compilação, como sinalizadores de compilação cruzada, de acordo.

Quando você define CMAKE_TOOLCHAIN_FILE para usar o toolchain vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), vcpkg aproveita o mecanismo de arquivo toolchain para injetar código para integrar com funções internas do CMake de forma transparente para você.

Você ainda pode usar um arquivo de cadeia de ferramentas para configurar seus próprios conjuntos de ferramentas usando a VCPKG_CHAINLOAD_TOOLCHAIN_FILE variável triplet.

A integração vcpkg funciona de forma diferente dependendo do modo de operação que você está usando:

No modo clássico, vcpkg define caminhos de pesquisa CMake adequadamente para disponibilizar pacotes instalados por meio das find_package()funções , find_library()e find_path() .

No modo manifesto, além do acima, o toolchain detecta arquivos de manifesto (vcpkg.json arquivos) e é executado vcpkg install para adquirir automaticamente as dependências do projeto.

Como o arquivo toolchain é avaliado durante a project() chamada, todas as variáveis de nível CMake que modificam uma configuração vcpkg devem ser definidas antes da primeira chamada para project(). Também pode ser necessário reconfigurar seu projeto CMake se você modificar qualquer configuração vcpkg que resulte em alterações de hash ABI.

Consulte Instalando e usando pacotes Exemplo: sqlite para obter um exemplo totalmente trabalhado usando o CMake.

`CMAKE_TOOLCHAIN_FILE`

Observação

Se você definir CMAKE_TOOLCHAIN_FILE no CMakeList.txt arquivo, certifique-se de que a variável esteja definida antes de qualquer chamada para project().

Projetos configurados para usar o arquivo vcpkg toolchain (através da configuração CMAKE_TOOLCHAIN_FILECMake ) podem encontrar bibliotecas de vcpkg usando as funções padrão do CMake: find_package(), find_path()e find_library().

Recomendamos o uso de predefinições do CMake para especificar seu arquivo de cadeia de ferramentas. Por exemplo, se você tiver definido a variável VCPKG_ROOTde ambiente, poderá usar o seguinte CMakePresets.json e passar --preset debug a linha configure:

{
  "version": 2,

  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

cmake -B build -S /my/project --preset debug

Se você precisar usar um caminho absoluto para vcpkg específico para sua máquina atual, você pode usá-lo CMakeUserPresets.json e adicioná-lo ao seu .gitignore arquivo.

{
  "version": 2,

  "configurePresets": [
    {
      "name": "debug",
      "cacheVariables": {
        "CMAKE_TOOLCHAIN_FILE": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
      }
    }
  ]
}

As versões do CMake anteriores à 3.19 devem passar o arquivo toolchain na linha de comando configure:

cmake ../my/project -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

Usando bibliotecas

vcpkg suporta os mecanismos nativos do CMake para encontrar bibliotecas: find_package(), find_library()e find_path(). Ao instalar bibliotecas com suporte específico ao CMake, o vcpkg exibirá informações de uso sobre como consumir a biblioteca:

The package zlib is compatible with built-in CMake targets:

    find_package(ZLIB REQUIRED)
    target_link_libraries(main PRIVATE ZLIB::ZLIB)

O VCPKG não adiciona automaticamente nenhum caminho de inclusão ou links ao seu projeto. Para usar uma biblioteca somente de cabeçalho, você pode usar find_path() que funcionará corretamente em todas as plataformas:

# To find and use catch2
find_path(CATCH_INCLUDE_DIR NAMES catch.hpp PATH_SUFFIXES catch2)
target_include_directories(main PRIVATE ${CATCH_INCLUDE_DIR})

Integração com o IDE

Código do Visual Studio / Visual Studio

Recomendamos o uso de predefinições CMake no Visual Studio e no Visual Studio Code.

Saiba mais em Configurar e compilar com predefinições do CMake no Visual Studio e Configurar e compilar com predefinições do CMake no Visual Studio Code.

CLion

Abra as configurações do Toolchains (File > Settings no Windows e Linux, CLion > Preferences no macOS) e vá para as configurações do CMake (Build, Execution, Deployment > CMake). No CMake options, adicione a seguinte linha:

-DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake

Você deve adicionar essa linha a cada perfil separadamente.

Usando vários arquivos do Toolchain

Para combinar o arquivo toolchain do vcpkg com outro arquivo toolchain, você pode definir a variável VCPKG_CHAINLOAD_TOOLCHAIN_FILEde cache CMake :

cmake ../my/project \
   -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake \
   -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=../my/project/toolchain.cmake

Como alternativa, você pode incluir o toolchain vcpkg no final do arquivo primário do toolchain:

# MyToolchain.cmake
set(CMAKE_CXX_COMPILER ...)
set(VCPKG_TARGET_TRIPLET x64-my-custom-windows-triplet)
include(/path/to/vcpkg/scripts/buildsystems/vcpkg.cmake)

Observação

O VCPKG não aplica automaticamente as configurações do seu toolchain, como o compilador ou os sinalizadores de compilação, durante a criação de bibliotecas. Para alterar as configurações da biblioteca do vcpkg, você deve criar um arquivo triplet personalizado (que pode compartilhar seu toolchain)**

Referência de configurações

Todas as variáveis que afetam vcpkg devem ser definidas antes da primeira project() diretiva, como em um CMakePresets.jsonmapa , através da linha de "cacheVariables" comando ou set() instruções.

`VCPKG_TARGET_TRIPLET`

Essa configuração controla o triplete vcpkg que instalará e consumirá bibliotecas.

Se não estiver definido, vcpkg detectará automaticamente um triplet padrão apropriado, dadas as configurações atuais do compilador. Se você alterar essa variável CMake, deverá excluir o cache e reconfigurar.

`VCPKG_HOST_TRIPLET`

Essa variável controla para quais dependências de host triplete serão instaladas.

Se não configurado, o vcpkg detectará automaticamente um triplete nativo apropriado (x64-windows, x64-osx, x64-linux).

Consulte também Dependências do host.

`VCPKG_INSTALLED_DIR`

Essa variável define o local onde as bibliotecas serão instaladas e consumidas.

No modo de manifesto, o padrão é ${CMAKE_BINARY_DIR}/vcpkg_installed.

No modo clássico, o padrão é ${VCPKG_ROOT}/installed.

`VCPKG_MANIFEST_MODE`

Essa variável força o vcpkg a operar no modo manifesto ou no modo clássico.

O padrão é ON quando VCPKG_MANIFEST_DIR não está vazio ou ${CMAKE_SOURCE_DIR}/vcpkg.json existe.

Para desativar o modo de manifesto enquanto um vcpkg.json é detectado, defina-o como OFF.

`VCPKG_MANIFEST_DIR`

Essa variável especifica uma pasta alternativa que contém um vcpkg.json manifesto.

O padrão é ${CMAKE_SOURCE_DIR} se ${CMAKE_SOURCE_DIR}/vcpkg.json existir.

`VCPKG_MANIFEST_INSTALL`

Essa variável controla se vcpkg será executado automaticamente para instalar suas dependências durante a etapa de configuração.

O padrão é ON if VCPKG_MANIFEST_MODE is ON.

`VCPKG_BOOTSTRAP_OPTIONS`

Essa variável pode ser definida como parâmetros de comando adicionais para passar para ./bootstrap-vcpkg.

No modo manifesto, vcpkg será inicializado automaticamente se o executável não existir.

`VCPKG_OVERLAY_TRIPLETS`

Essa variável pode ser definida como uma lista de caminhos a serem passados na linha de comando como --overlay-triplets=...

`VCPKG_OVERLAY_PORTS`

Essa variável pode ser definida como uma lista de caminhos a serem passados na linha de comando como --overlay-ports=...

`VCPKG_MANIFEST_FEATURES`

Essa variável pode ser definida como uma lista de recursos a serem ativados ao instalar a partir do manifesto.

Por exemplo, os recursos podem ser usados por projetos para controlar a construção com dependências adicionais para habilitar testes ou exemplos:

{
  "name": "mylibrary",
  "version": "1.0",
  "dependencies": [ "curl" ],
  "features": {
    "samples": {
      "description": "Build Samples",
      "dependencies": [ "fltk" ]
    },
    "tests": {
      "description": "Build Tests",
      "dependencies": [ "gtest" ]
    }
  }
}

Essa configuração pode ser controlada diretamente pelas predefinições do CMake com "cacheVariables" ou indiretamente com base em outras configurações:

# CMakeLists.txt

option(BUILD_TESTING "Build tests" OFF)
if(BUILD_TESTING)
  list(APPEND VCPKG_MANIFEST_FEATURES "tests")
endif()

option(BUILD_SAMPLES "Build samples" OFF)
if(BUILD_SAMPLES)
  list(APPEND VCPKG_MANIFEST_FEATURES "samples")
endif()

project(myapp)

# ...

`VCPKG_MANIFEST_NO_DEFAULT_FEATURES`

Essa variável controla a ativação de recursos padrão além dos listados no VCPKG_MANIFEST_FEATURES. Se definido como ON, os recursos padrão não serão ativados automaticamente.

Assume o padrão de OFF.

`VCPKG_INSTALL_OPTIONS`

Essa variável pode ser definida como uma lista de parâmetros de linha de comando adicionais para passar para a ferramenta vcpkg durante a instalação automática.

`VCPKG_PREFER_SYSTEM_LIBS`

Esse recurso foi preterido. Em vez disso, use portas de sobreposição vazias.

Essa variável controla se vcpkg acrescentará em vez de preceder seus caminhos para CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH e CMAKE_FIND_ROOT_PATH para que as bibliotecas/pacotes vcpkg sejam encontrados após toolchain/system libraries/packages.