Configurar e compilar com as predefinições do CMake no Visual Studio

Artigo
06/09/2023

CMake dá suporte a dois arquivos que permitem aos usuários especificar as opções comuns de configuração, compilação e teste e compartilhá-las com outras pessoas: CMakePresets.json e CMakeUserPresets.json. Use esses arquivos para conduzir o CMake no Visual Studio e Visual Studio Code, em um pipeline de CI (integração contínua) e na linha de comando.

CMakePresets.json é para salvar builds em todo o projeto. CMakeUserPresets.json é para os desenvolvedores salvarem seus próprios builds locais. Ambos os arquivos têm suporte no Visual Studio 2019 versão 16.10 ou posterior.

Este artigo contém informações sobre a integração de CMakePresets.json com o Visual Studio. Seguem alguns links úteis:

Para obter mais informações sobre o formato de CMakePresets.json, consulte a documentação oficial do CMake.
Para obter mais informações sobre os mapas de fornecedores da Microsoft e expansão de macro, consulte CMakePresets.json e CMakeUserPresets.json mapas de fornecedores da Microsoft.
Para obter mais informações sobre como usar CMakePresets.json no Visual Studio Code, consulte Configurar e compilar com predefinições do CMake.

Recomendamos CMakePresets.json como uma alternativa a CMakeSettings.json. O Visual Studio nunca lê deCMakePresets.json e CMakeSettings.json ao mesmo tempo. Para habilitar ou desabilitar a integração de CMakePresets.json no Visual Studio, consulte Habilitar CMakePresets.json no Visual Studio 2019.

CMake e versões de `CMakePresets.json` com suporte

As versões com suporte CMakePresets.json e CMakeUserPresets.json de esquema dependem da sua versão do Visual Studio:

Visual Studio 2019 versão 16.10 e versões posteriores dão suporte às versões de esquema 2 e 3.
O Visual Studio 2022 versão 17.4 versão prévia 1 adiciona suporte para a versão 4 do esquema.
O Visual Studio 2022 versão 17.5 versão prévia 1 adiciona suporte para a versão 5 do esquema.

Você pode atualizar a versão alterando o campo "version" no objeto raiz. Para obter um exemplo e mais informações, consulte CMakePresets.jsonformato.

O CMake versão 3.20 ou posterior é necessário quando você está invocando o CMake com CMakePresets.json da linha de comando. No entanto, o Visual Studio lê e avalia CMakePresets.json e CMakeUserPresets.json sozinho e não invoca o CMake diretamente com a opção --preset. Portanto, a versão 3.20 ou posterior do CMake não é estritamente necessária quando você está compilando com CMakePresets.json dentro do Visual Studio.

É recomendável usar o CMake versão 3.14 ou posterior.

Habilitar a integração do `CMakePresets.json` no Visual Studio

A integração de CMakePresets.json não está habilitada por padrão no Visual Studio. Você pode habilitá-la em Tools>Options>CMake>General:

Captura de tela mostrando 'Sempre usar CMakePresets.json' selecionado.

Importante

Feche e reabra a pasta no Visual Studio para ativar a integração.

Em algumas versões mais antigas do Visual Studio, Tools>Options>CMake>General tem apenas uma única opção para habilitar a integração de CMakePresets.json:

Captura de tela de uma versão mais antiga do Visual Studio. Há uma caixa de seleção chamada 'Usar C Make Presets .json para orientar a configuração, compilação e teste do CMake'.

A tabela a seguir indica quando CMakePresets.json é usado em vez de CMakeSettings.json para impulsionar a configuração e o build do CMake no Visual Studio 2022 e no Visual Studio 2019 versão 16.10 e posterior. Se nenhum arquivo de configuração estiver presente, serão usadas as Predefinições de Configuração padrão.

Na tabela, "Opções de>Ferramentas habilitadas" significa que Usar CMakePresets.json para conduzir a configuração, compilação e teste do CMake está selecionada em Opções de>Ferramentas>CMake>Geral.

Arquivos de configuração	Opções de ferramentas > desabilitadas	Opções de ferramentas > habilitadas
Nenhum arquivo de configuração presente	`CMakeSettings.json`	`CMakePresets.json`
`CMakeSettings.json` presente	`CMakeSettings.json`	`CMakePresets.json`
`CMakePresets.json` presente	`CMakePresets.json`	`CMakePresets.json`
Ambos os arquivos de configuração presentes	`CMakePresets.json`	`CMakePresets.json`

Modificar notificações automáticas de configuração e cache

Por padrão, o Visual Studio invoca automaticamente configure a cada vez que o sistema de destino ativo ou a predefinição configurar for alterado. Você pode modificar esse comportamento selecionando Nunca executar a etapa de configuração automaticamente em Tools>Options>CMake>General. Você também pode desabilitar todas as notificações de cache do CMake (barras de ouro) desmarcando Mostrar notificações de cache do CMake.

Predefinições de Configuração padrão

Se não houver nenhum arquivo CMakePresets.json ou CMakeUserPresets.json, ou se CMakePresets.json ou CMakeUserPresets.json for inválido, o Visual Studio voltará as seguintes Predefinições de Configuração padrão:

Exemplo do Windows

{
  "name": "windows-default",
  "displayName": "Windows x64 Debug",
  "description": "Sets Ninja generator, compilers, x64 architecture, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "architecture": {
    "value": "x64",
    "strategy": "external"
  },
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Windows" ]
    }
  }
},

Exemplo do Linux

{
  "name": "linux-default",
  "displayName": "Linux Debug",
  "description": "Sets Ninja generator, compilers, build and install directory, debug build type",
  "generator": "Ninja",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Debug",
    "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}"
  },
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": [ "Linux" ]
    },
    "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": {
      "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}"
   }
  }
}

Se você tentar abrir ou modificar um arquivo CMakePresets.json que não existe, o Visual Studio criará automaticamente um arquivo CMakePresets.json com as Predefinições de Configuração padrão na raiz do projeto.

Configurar e compilar

Na barra de ferramentas do Visual Studio, há listas suspensas para os Sistemas de Destino, Configurar Predefinições e Predefinições de Build quando CMakePresets.json a integração está habilitada:

Captura de tela mostrando as listas suspensas para o sistema de destino definido como Computador Local, configuração definida como windows-arm64 e predefinição de build definida como padrão.

Selecionar um sistema de destino

A lista suspensa à esquerda indica o Sistema de Destino ativo. É o sistema no qual o CMake será invocado para configurar e compilar o projeto. Esta lista suspensa inclui seu computador local, todas as conexões SSH no Gerenciador de Conexões por nome do host e todas as instalações do Subsistema do Windows para Linux (WSL) que o Visual Studio pode encontrar:

Captura de tela da lista suspensa do sistema de destino

No exemplo anterior:

192.168.0.5 é um sistema Linux remoto que foi adicionado ao Gerenciador de Conexões.
ubuntu2004 e debian são instalações do WSL.

Selecione Gerenciar Conexões para abrir o Gerenciador de Conexões.

Selecione uma Predefinição de Configuração

A lista suspensa no meio indica a Predefinição de Configuração ativa. É o valor de configurePreset que é usado quando o CMake é invocado para gerar o sistema de build do projeto. Essa lista suspensa inclui a união de Predefinições de Configuração não ocultas definidas em CMakePresets.json e CMakeUserPresets.json.

O Visual Studio usa o valor de hostOS no Mapa de fornecedores de configurações do Microsoft Visual Studio para ocultar Configurar Predefinições que não se aplicam ao sistema de destino ativo. Para obter mais informações, consulte a entrada de hostOS na tabela no Mapa de fornecedores de configurações do Visual Studio.

Selecione Gerenciar Configurações para abrir o arquivo CMakePresets.json localizado na raiz do projeto. CMakePresets.json será criado se ainda não existir.

Selecione uma Predefinição de Build

A lista suspensa à direita indica a Predefinição de Build ativa. É o valor de buildPreset usado quando o CMake é invocado para compilar o projeto. Essa lista suspensa inclui a união de Predefinições de Build não ocultas definidas em CMakePresets.json e CMakeUserPresets.json.

Todas as Predefinições de Build são necessárias para especificar um valor associado de configurePreset. O Visual Studio oculta Predefinições de Build que não se aplicam à Predefinição de Configuração ativa. Para obter mais informações, consulte a lista de Predefinições de Build.

Se não houver Predefinições de Build associadas à Predefinição de Configuração ativa, o Visual Studio listará a Predefinição de Build padrão. A Predefinição de Build padrão é equivalente a passar cmake --build sem outros argumentos da linha de comando.

Configurar

O Visual Studio automaticamente tenta configurar o projeto quando detecta que o cache do CMake está desatualizado. Para invocar manualmente a configuração, selecione Project> Configure <project-name> no menu principal. É o mesmo que executar cmake --preset <configurePreset> na linha de comando, onde <configurePreset> é o nome da Predefinição de Configuração ativa.

Para desabilitar a geração automática de cache, consulte Notificações automáticas de configuração e cache.

Compilação

Para compilar o projeto inteiro, selecione Compilar>Compilar Tudo no menu principal. É o mesmo que executar cmake --build --preset <buildPreset> na linha de comando, onde <buildPreset> é o nome da Predefinição de Build ativa.

Para compilar um único destino, alterne para a Exibição de destinos do CMake no Gerenciador de Soluções. Em seguida, clique com o botão direito do mouse em qualquer destino e selecione Compilar no menu de atalho.

Observação

O Visual Studio 2019 não dá suporte à opção buildPresets.targets de compilar um subconjunto de destinos especificado em CMakePresets.json.

Executar CTest

CMakePresets.json dá suporte a duas opções de menu no Visual Studio 2019:

Teste>Executar CTests para <nome do projeto> invoca o CTest e executa todos os testes associados à Predefinição de Configuração ativa e à Predefinição de Build, sem outros argumentos passados para o CTest.
Teste>Executar Predefinição de Teste para <configurePreset> expande-se para mostrar todas as Predefinições de Teste associadas com a Predefinição de Configuração ativa. Selecionar uma única Predefinição de Teste é o mesmo que executar ctest --preset <testPreset> da linha de comando, onde <testPreset> é o nome da Predefinição de Teste selecionada. Essa opção estará indisponível se nenhuma Predefinição de Teste for definida para a Predefinição de Configuração ativa.

No Visual Studio 2019, o Gerenciador de Testes não está integrado ao CMakePresets.json.

Adicionar novas predefinições

No Visual Studio 2019, todos os comandos e modelos predefinidos modificam CMakePresets.json. Você pode adicionar novas predefinições de nível de usuário editando CMakeUserPresets.jsondiretamente.

Use uma barra para frente (/) para caminhos dentro de CMakePresets.json e CMakeUserPresets.json.

Adicionar novas Predefinições de Configuração

Para adicionar uma nova Predefinição de Configuração a CMakePresets.json, no Gerenciador de Soluções, clique com o botão direito do mouse em CMakePresets.json, em Exibição de Pasta e selecione Adicionar Configuração no menu de atalho. A caixa de diálogo para selecionar um modelo para Predefinição de Configuração é exibida:

Captura de tela da caixa de diálogo Adicionar predefinição de configuração ao arquivo JSON. Ele contém entradas como Linux Debug, macOS Debug, x64 Debug e assim por diante.

Selecione o modelo de Depuração do Windows x64 para configurar nos sistemas Windows. Selecione o modelo de Depuração do Linux para configurar em sistemas WSL e Linux remotos. Para obter mais informações sobre como editar CMakePresets.json, consulte Editar predefinições.

O modelo selecionado será adicionado a CMakePresets.json se ele existir. Caso contrário, o modelo será copiado para um novo arquivo CMakePresets.json.

Adicionar novas Predefinições de Build e Predefinições de Teste

O Visual Studio 2019 não oferece modelos para novas Predefinições de Build e Predefinições de Teste. Você pode adicionar Predefinições de Build e Predefinições de Teste editando CMakePresets.jsondiretamente. Para obter mais informações, consulte a lista de Predefinições de Build, a lista de Predefinições de Testeou um arquivoCMakePresets.json de exemplo.

Editar predefinições

A documentação oficial do CMake é o melhor recurso para editar Predefinições de Configuração, de Build e de Teste. As informações a seguir são um subconjunto da documentação do CMake que é especialmente relevante para os desenvolvedores do Visual Studio.

Selecione seus compiladores

Você pode definir compiladores C e C++ usando cacheVariables.CMAKE_C_COMPILER e cacheVariables.CMAKE_CXX_COMPILER em uma Predefinição de Configuração. É equivalente a passar -D CMAKE_C_COMPILER=<value> e -D CMAKE_CXX_COMPILER=<value> ao CMake da linha de comando. Para obter mais informações, consulte CMAKE_<LANG>_COMPILER.

Use os exemplos a seguir para compilar com cl.exe e clang-cl.exe do Visual Studio. As ferramentas Clang C++ para componentes do Windows devem ser instaladas para compilar com clang-cl.

Compilar com cl.exe:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "cl",
  "CMAKE_CXX_COMPILER": "cl"
},

Compilar com clang:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "clang-cl",
  "CMAKE_CXX_COMPILER": "clang-cl"
},

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Se você usar Visual Studio 16 2019 ou Visual Studio 17 2022 como gerador, poderá usar a Predefinição de Configuração toolset para especificar o conjunto de ferramentas do ClangCL:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
},

"toolset": "ClangCL",

"vendor": {
  "microsoft.com/VisualStudioSettings/CMake/1.0": {
    "intelliSenseMode": "windows-clang-x64"
  }
}

Para obter mais informações sobre geradores que dão suporte à especificação de toolset, consulte CMAKE_GENERATOR_TOOLSET na documentação do CMake.

Importante

No Visual Studio 2019, será necessário especificar explicitamente um modo IntelliSense Clang ao compilar com clang ou clang-cl.

Para reproduzir esses builds fora do Visual Studio, consulte Executar CMake na linha de comando ou em um pipeline de CI.

Para compilar no Linux ou sem o conjunto de ferramentas do Visual C++, especifique o nome de um compilador na instância PATH ou uma variável de ambiente que seja avaliada como o caminho completo de um compilador. Os caminhos completos são desencorajados para que o arquivo possa permanecer compartilhável. Uma predefinição que é compilada com o GCC versão 8 pode ter esta aparência:

"cacheVariables": {
  "CMAKE_BUILD_TYPE": "Debug",
  "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}",
  "CMAKE_C_COMPILER": "gcc-8",
  "CMAKE_CXX_COMPILER": "g++-8"
},

Você também pode definir compiladores com um arquivo de cadeia de ferramentas do CMake. Os arquivos de cadeia de ferramentas podem ser definidos com cacheVariables.CMAKE_TOOLCHAIN_FILE, o que é equivalente a passar -D CMAKE_TOOLCHAIN_FILE=<value> para CMake da linha de comando. Um arquivo de cadeia de ferramentas do CMake é usado com mais frequência para compilação cruzada. Para obter mais informações sobre como criar arquivos de cadeia de ferramentas do CMake, consulte Cadeias de ferramentas do CMake.

Selecionar o gerador

Os modelos de Predefinir Configurar do Windows e do Linux especificam o Ninja como o gerador padrão. Outros geradores comuns são os Geradores do Visual Studio no Windows e Unix Makefiles no Linux e no macOS. Você pode especificar um novo gerador com a opção generator em uma Predefinição Configurar. É equivalente a passar -G ao CMake da linha de comando.

Defina architecture.strategy e toolset.strategy como set quando estiver criando com um Gerador do Visual Studio. Para saber mais, consulte Geradores do CMake.

Selecionar o tipo de configuração

Você pode definir o tipo de configuração (Debug ou Release) para geradores de configuração única usando cacheVariables.CMAKE_BUILD_TYPE. É equivalente a passar -D CMAKE_BUILD_TYPE=<value> ao CMake da linha de comando. Para obter mais informações, consulte CMAKE_BUILD_TYPE.

Selecione a arquitetura de destino e host ao compilar com o conjunto de ferramentas do Visual C++

Você pode definir a arquitetura de destino (x64, Win32, ARM64 ou ARM) usando architecture.value. É equivalente a passar -A ao CMake da linha de comando. Para obter mais informações, consulte Seleção de Plataforma.

Observação

Atualmente, os Geradores do Visual Studio esperam que a sintaxe Win32 e os geradores de linha de comando (como Ninja) esperem a sintaxe x86 quando você estiver compilando para x86.

Você pode definir a arquitetura do host (x64 ou x86) e o conjunto de ferramentas usando toolset.value. É equivalente a passar -T ao CMake da linha de comando. Para obter mais informações, consulte Seleção de Conjunto de ferramentas.

Os valores architecture.strategy e toolset.strategy informam ao CMake como lidar com os campos da arquitetura e do conjunto de ferramentas. set significa que o CMake definirá o respectivo valor e external significa que o CMake não definirá o respectivo valor.

É recomendável usar set com geradores de IDE, como o Gerador do Visual Studio. Use external com geradores de linha de comando como Ninja. Esses valores permitem que fornecedores como o Visual Studio proporcionem o ambiente necessário antes que o CMake seja invocado. Para obter mais informações sobre campos de arquitetura e conjunto de ferramentas, consulte a lista de Configurações Predefinições.

Caso não deseje criar um ambiente, poderá definir architecture.strategy como external e architecture.value como unspecified. Talvez você ache útil não criar um ambiente por qualquer um desses motivos:

Você usa um conjunto de ferramentas diferente do MSVC.
Você usa uma cadeia de ferramentas personalizada, como em cenários inseridos.
Você não precisa de um ambiente específico para compilar.

Para obter uma lista completa de geradores de IDE que dão suporte ao campo de arquitetura, consulte CMAKE_GENERATOR_PLATFORM. Para obter uma lista completa de geradores de IDE que dão suporte ao campo de conjunto de ferramentas, consulte CMAKE_GENERATOR_TOOLSET.

Use exemplos a seguir para direcionar o ARM64 com o gerador Ninja ou para direcionar o Win32 (x86) com o gerador do Visual Studio 16 2019:

"generator": "Ninja",
"architecture": {
    "strategy": "external",
    "value": "arm64"
},

"generator": "Visual Studio 16 2019",
"architecture": {
    "strategy": "set",
     "value": "Win32"
},

Definir e referenciar variáveis de ambiente

É possível definir variáveis de ambiente usando o mapa do ambiente. As variáveis de ambiente são herdadas por meio do campo inherits, mas você pode substituí-las como desejar.

Um ambiente predefinido é a união do próprio ambiente e o ambiente de todos os seus pais. Se várias predefinições inherits fornecerem valores conflitantes para a mesma variável, a predefinição anterior na lista inherits será preferencial. Você pode remover a definição de uma variável herdada de outra predefinição definindo-a como null.

As variáveis de ambiente definidas em uma Predefinição de Configuração também fluem automaticamente para Predefinições de Build e Predefinições de Teste associadas, a menos que inheritConfigureEnvironment esteja definida como false. Para obter mais informações, consulte a lista de Configurar Predefinições.

Você pode fazer referência a variáveis de ambiente usando a sintaxe $env{<variable-name>} e $penv{<variable-name>}. Para obter mais informações, consulte Expansão de Macro.

Configurar o IntelliSense para um compilador cruzado

Por padrão, o Visual Studio usa o modo IntelliSense que corresponde ao conjunto de ferramentas e à arquitetura de destino especificados. Se você estiver fazendo uma compilação cruzada, talvez seja necessário especificar manualmente o modo IntelliSense correto usando a opção intelliSenseMode no Mapa de fornecedores de configurações do Visual Studio. Para obter mais informações, consulte a entrada de intelliSenseMode na tabela no Mapa de fornecedores de configurações do Visual Studio.

Configurar e compilar em um sistema remoto ou no Subsistema do Windows para Linux

Com o suporte a CMakePresets.json no Visual Studio, você pode configurar e compilar facilmente seu projeto em sistemas Windows, WSL e remotos. As etapas para configurar e compilar seu projeto no Windows, em um sistema remoto ou no WSL são as mesmas. No entanto, alguns comportamentos são específicos para o desenvolvimento remoto.

Comportamento de `${sourceDir}` em cenários de cópia remota

Em cenários locais (incluindo o WSL1), ${sourceDir} avalia o caminho para o diretório de origem do projeto que está aberto no Visual Studio. Em cenários de cópia remota, ${sourceDir} avalia como o caminho para o diretório de origem do projeto no Sistema de Destino e não para o diretório de origem do projeto no computador local.

O valor de sourceDir no Mapa de fornecedores de configurações remotas do Visual Studio determina o diretório de origem do projeto no Sistema de Destino (padrão para $env{HOME}/.vs/$ms{projectDirName}). Para obter mais informações, consulte a entrada de sourceDir na tabela no Mapa de fornecedores de configurações do Visual Studio.

Pasta local para saída remota

Cenários de cópia remota exigem um diretório local para copiar alguns arquivos remotos, como arquivos de resposta da API de Arquivo do CMake ou arquivos de build, se copyBuildOutput no Mapa de fornecedores de configurações remotas do Visual Studio estiver definido como true. Esses arquivos são copiados automaticamente para <local-source-directory>/out/<remote-connection-ID>/build/${presetName}.

Invocando a mesma Predefinição Configurar no Windows e no WSL1

Você receberá um erro se tentar usar a mesma Predefinição Configurar no Windows e no WSL1. O Windows e o WSL1 usam o sistema de arquivos do Windows, portanto, o CMake tentará usar o mesmo diretório de saída (binaryDir) para as árvores de compilação do Windows e do WSL1.

Se quiser usar a mesma Predefinição Configurar com o Windows e o conjunto de ferramentas WSL1, crie uma segunda Predefinição Configurar herdada da predefinição original e especifique um novo valor para binaryDir. No exemplo a seguir, windows-preset pode ser usado no Windows e base-preset pode ser usado no WSL1:

{
  "name": "windows-preset",
  "inherits": "base-preset",
  "binaryDir": "${sourceDir}/out/build/${presetName}",
  "vendor": {
    "microsoft.com/VisualStudioSettings/CMake/1.0": {
      "hostOS": "Windows"
    }
  }
}

Observação

No Visual Studio 2019, há suporte apenas para o conjunto de ferramentas WSL1. Você verá esse comportamento sempre que invocar configure no Windows e no WSL.

Habilitar integração vcpkg

O Vcpkg ajuda a gerenciar bibliotecas C e C++ no Windows, Linux e macOS. Um arquivo de cadeia de ferramentas vcpkg (vcpkg.cmake) deve ser passado para o CMake para habilitar a integração vcpkg. Para obter mais informações, confira a documentação do vcpkg.

O Visual Studio não passa mais o arquivo de cadeia de ferramentas do vcpkg para o CMake automaticamente quando a integração CMakePresets.json está habilitada. Essa alteração elimina o comportamento específico do Visual Studio e garante que você possa reproduzir a compilação da linha de comando.

Em vez disso, defina o caminho para vcpkg.cmake usando a variável de ambiente VCPKG_ROOT em CMakePresets.json:

"cacheVariables": {
   "CMAKE_TOOLCHAIN_FILE": {
      "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake",
       "type": "FILEPATH"
    }
 },

VCPKG_ROOT deve ser definido como a raiz da instalação do vcpkg. Para obter mais informações, consulte Variáveis de ambiente do vcpkg.

Se você já usa um arquivo de cadeia de ferramentas do CMake e quiser habilitar a integração vcpkg, consulte Usando vários arquivos de cadeia de ferramentas. Siga essas instruções para usar um arquivo de conjunto de ferramentas externo com um projeto usando vcpkg.

Substituição de variável em `launch.vs.json` e `tasks.vs.json`

CMakePresets.json dá suporte à substituição de variável em launch.vs.json e tasks.vs.json. Estas são algumas considerações:

Variáveis de ambiente definidas na Predefinição de Configuração ativa fluem automaticamente para configurações de launch.vs.json e tasks.vs.json. Você pode remover a definição de variáveis de ambiente individuais em launch.vs.json e tasks.vs.json definindo-as como null. O exemplo a seguir define o valor da variável DEBUG_LOGGING_LEVEL como null em launch.vs.json: "env": { "DEBUG_LOGGING_LEVEL": null }.
Os valores de chave definidos na Predefinição de Configuração ativa estão disponíveis para consumo em launch.vs.json e tasks.vs.json com a sintaxe ${cmake.<KEY-NAME>}. Por exemplo, use ${cmake.binaryDir} para fazer referência ao diretório de saída da Predefinição de Configuração ativa.
Variáveis de ambiente individuais definidas no mapa de ambiente da Predefinição de Configuração ativa estão disponíveis para consumo em launch.vs.json e tasks.vs.json por meio da sintaxe ${env.<VARIABLE-NAME>}.

Atualize seus arquivos launch.vs.json e task.vs.json para referenciar a sintaxe de CMakePresets.json em vez da sintaxe de CMakeSettings.json. Macros que fazem referência à sintaxe antiga CMakeSettings.json quando CMakePresets.json é o arquivo de configuração ativo está programado para substituição em uma versão futura. Por exemplo, referencie o diretório de saída da Predefinição Configurar ativa com ${cmake.binaryDir}, em vez de ${cmake.buildRoot}, porque CMakePresets.json usa a sintaxe de binaryDir.

Solucionar problemas

Se as coisas não funcionarem conforme o esperado, você poderá tentar algumas etapas de solução de problemas.

Se CMakePresets.json ou CMakeUserPresets.json for inválido, o Visual Studio retornará seu comportamento padrão e mostrará apenas as Predefinições de Configuração padrão. O Visual Studio IntelliSense pode ajudá-lo a capturar muitos desses erros JSON, mas não saberá se você está fazendo referência a uma predefinição com inherits ou configurePreset pelo nome errado.

Para verificar se os arquivos predefinidos são válidos, execute cmake --list-presets na linha de comando na raiz do diretório do projeto. (Necessário o CMake 3.20 ou posterior). Se um dos arquivos for inválido, você receberá o seguinte erro:

CMake Error: Could not read presets from
C:/Users/<user>/source/repos/<project-name>: JSON parse error

Outras etapas de solução de problemas incluem:

Excluir o cache e reconfigurar o projeto (CMake: Excluir Cache e Configurar>Projeto <project-name>).
Fechar e reabrir a pasta no Visual Studio (Pasta de Fechamento>de Arquivo).
Excluir a pasta .vs na raiz do projeto.

Se você identificou um problema, a melhor maneira de reportá-lo é selecionar o botão Enviar Comentários no canto superior direito do Visual Studio.

Habilitar o registro em log para conexões remotas

Você pode habilitar o registro em log para conexões remotas se estiver com problemas para conectar ou copiar arquivos a um sistema remoto. Para obter mais informações, consulte Registrando em log para conexões remotas.

Habilitar AddressSanitizer para Windows e Linux

O Visual Studio dá suporte ao AddressSanitizer (ASAN), um detector de erros de memória de runtime C e C++, para o desenvolvimento do Windows e do Linux. A opção addressSanitizerEnabled em CMakeSettings.json habilita o AddressSanitizer. CMakePresets.json não dá suporte a esse comportamento.

Em vez disso, habilite e desabilite o AddressSanitizer definindo os sinalizadores de compilador e vinculador necessários por conta própria. Defini-los remove o comportamento específico do Visual Studio e garante que o mesmo arquivo CMakePresets.json possa reproduzir a compilação da linha de comando.

Você pode adicionar o exemplo para CMakeLists.txt a seguir para habilitar ou desabilitar o AddressSanitizer para um destino:

option(ASAN_ENABLED "Build this target with AddressSanitizer" ON)

if(ASAN_ENABLED)
  if(MSVC)
    target_compile_options(<target> PUBLIC /fsanitize=address)
  else()
    target_compile_options(<target> PUBLIC -fsanitize=address <additional-options>)
    target_link_options(<target> PUBLIC -fsanitize=address)
  endif()
endif()

O bloco <additional-options> lista outros sinalizadores de compilação, como "-fno-omit-frame-pointer". Para obter mais informações sobre AddressSanitizer para Linux, consulte Usando AddressSanitizer. Para obter mais informações sobre como usar AddressSanitizer com MSVC, consulte Use AddressSanitizer de um prompt de comando do desenvolvedor.

Passe sinalizadores de runtime para AddressSanitizer usando o campo ASAN_OPTIONS em launch.vs.json. ASAN_OPTIONS assume o padrão como detect_leaks=0 quando nenhuma outra opção de runtime é especificada porque o LeakSanitizer não tem suporte no Visual Studio.

Executar o CMake na linha de comando ou em um pipeline de CI

Você pode usar os mesmos arquivos CMakePresets.json e CMakeUserPresets.json para invocar o CMake no Visual Studio e na linha de comando. A documentação CMake e CTest são os melhores recursos para invocar CMake e CTest com --preset. É necessário o CMake versão 3.20 ou posterior.

Fornecer o ambiente ao compilar com geradores de linha de comando no Windows

Cabe ao usuário configurar o ambiente antes que o CMake seja invocado na compilação com um gerador de linha de comando. Se você fizer a compilação com o Ninja e o conjunto de ferramentas do Visual C++ no Windows, defina o ambiente antes que o CMake seja chamado para gerar o sistema de compilação. Você pode fazer isso chamando vcvarsall.bat com o argumento architecture. O argumento architecture especifica o host e a arquitetura de destino a ser usada. Para obter mais informações, confira vcvarsallSintaxe. Se você compilar no Linux ou no Windows com um Gerador do Visual Studio, não precisará seguir esta etapa.

É a mesma etapa que o Visual Studio faz por você quando o IDE invoca o CMake. O Visual Studio analisa a Predefinição de Configuração ativa para o host e a arquitetura de destino especificada por toolset e architecture. Em seguida, o Visual Studio cria o ambiente especificado de vcvarsall.bat. Ao compilar a partir da linha de comando do Windows com o Ninja, você precisará fazer esta etapa por conta própria.

vcvarsall.bat é instalado com as Ferramentas de Build para Visual Studio. Por padrão, o vcvarsall.bat é instalado em C:\Program Files (x86)\Microsoft Visual Studio\2019\<edition>\VC\Auxiliary\Build. Você pode adicionar vcvarsall.bat em PATH se usar o fluxo de trabalho de linha de comando com frequência.

Exemplo de fluxo de trabalho de linha de comando

Você pode usar os comandos a seguir para configurar e criar um projeto do CMake que usa o Ninja para direcionar o ARM64 com ferramentas de build x64. É necessário o CMake versão 3.20 ou posterior. Execute estes comandos no diretório em que o arquivo CMakePresets.json está localizado:

/path/to/vcvarsall.bat x64_arm64 
cmake --list-presets=all .
cmake --preset <configurePreset-name>
cmake --build --preset <buildPreset-name>

Arquivo de exemplo `CMakePresets.json`

O arquivo CMakePresets.json em box2d-lite contém exemplos de Predefinições de Configuração, Predefinições de Build e Predefinições de Teste. Para obter mais informações sobre este exemplo, confira a apresentação Uma Introdução ao CMakePresets.json. Você pode ver outro exemplo no projeto DirectXTK, que mostra muitos destinos de build na seção configurePresets.

Próximas etapas

Saiba mais sobre como configurar e depurar projetos do CMake no Visual Studio:

Projetos do CMake no Visual Studio
Personalizar as configurações de compilação do CMake
Configurar sessões de depuração do CMake
Referência de configuração predefinida do CMake

Compartilhar via

Configurar e compilar com as predefinições do CMake no Visual Studio

CMake e versões de CMakePresets.json com suporte

Habilitar a integração do CMakePresets.json no Visual Studio

Modificar notificações automáticas de configuração e cache

Predefinições de Configuração padrão

Exemplo do Windows

Exemplo do Linux

Configurar e compilar

Selecionar um sistema de destino

Selecione uma Predefinição de Configuração

Selecione uma Predefinição de Build

Configurar

Compilação

Executar CTest

Adicionar novas predefinições

Adicionar novas Predefinições de Configuração

Adicionar novas Predefinições de Build e Predefinições de Teste

Editar predefinições

Selecione seus compiladores

Selecionar o gerador

Selecionar o tipo de configuração

Selecione a arquitetura de destino e host ao compilar com o conjunto de ferramentas do Visual C++

Definir e referenciar variáveis de ambiente

Configurar o IntelliSense para um compilador cruzado

Configurar e compilar em um sistema remoto ou no Subsistema do Windows para Linux

Comportamento de ${sourceDir} em cenários de cópia remota

Pasta local para saída remota

Invocando a mesma Predefinição Configurar no Windows e no WSL1

Habilitar integração vcpkg

Substituição de variável em launch.vs.json e tasks.vs.json

Solucionar problemas

Habilitar o registro em log para conexões remotas

Habilitar AddressSanitizer para Windows e Linux

Executar o CMake na linha de comando ou em um pipeline de CI

Fornecer o ambiente ao compilar com geradores de linha de comando no Windows

Exemplo de fluxo de trabalho de linha de comando

Arquivo de exemplo CMakePresets.json

Próximas etapas

Comentários

Recursos adicionais

CMake e versões de `CMakePresets.json` com suporte

Habilitar a integração do `CMakePresets.json` no Visual Studio

Comportamento de `${sourceDir}` em cenários de cópia remota

Substituição de variável em `launch.vs.json` e `tasks.vs.json`

Arquivo de exemplo `CMakePresets.json`