vcpkg em projetos do CMake

Artigo
10/15/2024

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

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

Para personalizar o processo de seleção do conjunto de ferramentas, o CMake oferece suporte ao uso de scripts personalizados no idioma CMake, conhecidos como arquivos do conjunto de ferramentas. Um arquivo de cadeia de ferramentas é 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ê configura CMAKE_TOOLCHAIN_FILE para usar o conjunto de ferramentas vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), o vcpkg aproveita o mecanismo de arquivo do conjunto de ferramentas para injetar código para integração 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, o vcpkg define os caminhos de pesquisa do CMake adequadamente para disponibilizar os pacotes instalados por meio das find_package()funções , find_library()e find_path() .

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

Como o arquivo da cadeia de ferramentas é avaliado durante a project() chamada, todas as variáveis de nível do CMake que modificam uma configuração de 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.

Veja Instalando e Usando Pacotes Exemplo: sqlite para um exemplo totalmente trabalhado usando CMake.

`CMAKE_TOOLCHAIN_FILE`

Observação

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

Os projetos configurados para usar o arquivo de conjunto de ferramentas vcpkg (por meio da configuração CMAKE_TOOLCHAIN_FILECMake ) podem encontrar bibliotecas do vcpkg usando as funções padrão do CMake: find_package(), find_path(), e find_library().

Recomendamos usar as predefinições do CMake para especificar o arquivo da cadeia de ferramentas. Por exemplo, se você definiu a variável VCPKG_ROOTde ambiente, pode usar o seguinte CMakePresets.json e passar --preset debug a linha de configuração:

{
  "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, poderá 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 da cadeia de ferramentas 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 vinculação ao seu projeto. Para usar uma biblioteca somente de cabeçalho que 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

Visual Studio / Visual Studio Code

É recomendável usar as predefinições do 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 de Toolchains (File > Settings no Windows e Linux, CLion > Preferences no macOS) e vá para as configurações do CMake (Build, Execution, Deployment > CMake). Em 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 de cadeia de ferramentas

Para combinar o arquivo de cadeia de ferramentas do vcpkg com outro arquivo de cadeia de ferramentas, você pode definir a variável VCPKG_CHAINLOAD_TOOLCHAIN_FILEde cache do 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 conjunto de ferramentas vcpkg no final do arquivo principal do conjunto de ferramentas:

# 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 conjunto de ferramentas, 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 triplo personalizado (que pode compartilhar seu conjunto de ferramentas)**

Referência de configurações

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

`VCPKG_TARGET_TRIPLET`

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

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

`VCPKG_HOST_TRIPLET`

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

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

Consulte também Dependências do host.

`VCPKG_INSTALLED_DIR`

Essa variável define o local de 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 a vcpkg.json é detectado, defina-o como OFF.

`VCPKG_MANIFEST_DIR`

Essa variável especifica uma pasta alternativa contendo um vcpkg.json manifesto.

O padrão é ${CMAKE_SOURCE_DIR} if ${CMAKE_SOURCE_DIR}/vcpkg.json exists.

`VCPKG_MANIFEST_INSTALL`

Essa variável controla se o 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 de manifesto, o 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 amostras:

{
  "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 daqueles listados em 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 configurada 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`

Aviso

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

Essa variável controla se o vcpkg anexará 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 as bibliotecas/pacotes do conjunto de ferramentas/sistema.