Partilhar via

vcpkg em projetos CMake

O vcpkg oferece integração perfeita com o CMake para disponibilizar pacotes instalados em seus projetos automaticamente. O mecanismo pelo qual o vcpkg se integra é através da disponibilização de um ficheiro de cadeia de ferramentas CMake.

A 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.). Esta pesquisa acontece dentro da project() função na sua CMakeLists.txt.

Para personalizar o processo de seleção da cadeia de ferramentas, o CMake suporta o uso de scripts personalizados da linguagem CMake, conhecidos como arquivos da cadeia de ferramentas. Um arquivo da cadeia de ferramentas é especificado definindo a CMAKE_TOOLCHAIN_FILE variável. O CMake avalia o conteúdo do script da 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 a cadeia de ferramentas vcpkg (<vcpkg-root>/scripts/buildsystems/vcpkg.cmake), vcpkg aproveita o mecanismo de arquivo da cadeia de ferramentas para injetar código para integrar com funções CMake integradas 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 de forma apropriada para disponibilizar os pacotes instalados através das find_package()funções , find_library()e find_path() .

No modo manifesto, para além do anteriormente mencionado, a cadeia de ferramentas deteta arquivos de manifesto (vcpkg.json arquivos) e executa 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 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 CMake.

CMAKE_TOOLCHAIN_FILE

Observação

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

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

Recomendamos o uso de Predefinições CMake para especificar o seu arquivo toolchain. Por exemplo, se tiveres definido a VCPKG_ROOT variável de ambiente, podes usar o seguinte CMakePresets.json e passar --preset debug na 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, você pode usá-lo CMakeUserPresets.json e adicioná-lo ao seu .gitignore arquivo.

{
  "version": 2,
  "configurePresets": [
    {
      "name": "default",
      "inherits": "debug",
      "environment": {
        "VCPKG_ROOT": "<path to vcpkg>"
      }
    }
  ]
}

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 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 IDE

Visual Studio / Visual Studio Código

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). 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 ficheiros da cadeia de ferramentas

Para combinar o ficheiro da cadeia de ferramentas do vcpkg com outro ficheiro da cadeia de ferramentas, pode definir a variável de cache CMake VCPKG_CHAINLOAD_TOOLCHAIN_FILE:

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 a cadeia de ferramentas vcpkg no final do arquivo primário da cadeia 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 da sua cadeia 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 triplete personalizado (que pode compartilhar sua cadeia de ferramentas)**

Referência de configurações

Todas as variáveis que afetam o vcpkg devem ser definidas antes da primeira diretiva project(), tal como num mapa CMakePresets.json, via linha de comandos ou declarações "cacheVariables".

VCPKG_TARGET_TRIPLET

Esta configuração controla o triplete de que vcpkg irá instalar e consumir bibliotecas.

Se desconfigurado, o vcpkg detetará automaticamente um triplete padrão apropriado de acordo com as configurações atuais do compilador. Se você alterar essa variável CMake, deverá excluir o cache e reconfigurá-lo.

VCPKG_HOST_TRIPLET

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

Se desconfigurado, o vcpkg detetará automaticamente um triplete nativo apropriado (x64-windows, x64-osx, x64-linux).

Consulte também Dependências de 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

Esta variável força 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 é detetado, defina isto para OFF.

VCPKG_MANIFEST_DIR

Esta variável especifica uma pasta alternativa contendo 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 o vcpkg será executado automaticamente para instalar suas dependências durante a etapa de configuração.

O padrão ON é se VCPKG_MANIFEST_MODE é 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á automaticamente inicializado 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 durante a instalação a partir do manifesto.

Por exemplo, as funcionalidades podem ser usadas por projetos para controlar a compilaçã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" ]
    }
  }
}

Esta configuração pode ser controlada diretamente por CMake Presets 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 em VCPKG_MANIFEST_FEATURES. Se definido como ON, os recursos padrão não serão ativados automaticamente.

O padrão é OFF.

VCPKG_INSTALL_OPTIONS

Esta 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

Advertência

Esta caraterística foi preterida. Em vez disso, use portas de sobreposição vazias.

Essa variável controla se o vcpkg adicionará em vez de antepor os seus caminhos a CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH e CMAKE_FIND_ROOT_PATH, de modo que as bibliotecas/pacotes do vcpkg sejam encontrados após as bibliotecas/pacotes do sistema e da cadeia de ferramentas.

O padrão é OFF.

VCPKG_FEATURE_FLAGS

Essa variável pode ser definida como uma lista de sinalizadores de recursos para passar para a ferramenta vcpkg durante a instalação automática para aceitar o comportamento experimental.

Consulte a opção de linha de --feature-flags= comando para obter mais informações.

VCPKG_TRACE_FIND_PACKAGE

Quando definido como ON, Imprima todas as chamadas para find_package. As chamadas aninhadas (por exemplo, via find_dependency) são recuadas de acordo com a profundidade de aninhamento.

VCPKG_LOCK_FIND_PACKAGE_<Pkg>

Quando essa opção é definida, chamadas não aninhadas para find_package são necessárias (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=ON) ou desabilitadas (VCPKG_LOCK_FIND_PACKAGE_<Pkg>=OFF).

Esta variável é uma ferramenta para controlar dependências diretas e recursos relacionados em portas vcpkg que usam o sistema de compilação CMake. Ele pode ser usado com vcpkg_check_features e evita efeitos não intencionais em dependências transitivas.