Personalizar as configurações de build do CMake

O Visual Studio usa um arquivo de configuração do CMake para acionar a geração e o build no CMake. CMakePresets.json tem suporte do Visual Studio 2019 versão 16.10 ou posterior e é o arquivo de configuração do CMake recomendado. CMakePresets.json tem suporte diretamente pelo CMake e pode ser usado para impulsionar a geração e o build do CMake do Visual Studio, do VS Code, em um pipeline de Integração Contínua e na linha de comando no Windows, Linux e Mac. Para mais informações sobre CMakePresets.json, confira Configurar e compilar com as predefinições do CMake.

Se você mantiver projetos que usam um arquivo CMakeSettings.json para a configuração de build do CMake, o Visual Studio 2019 e versões posteriores fornecerão um editor de configurações do CMake. O editor permite que você adicione configurações do CMake e personalize suas configurações facilmente. A intenção é ser uma alternativa mais simples para editar manualmente o arquivo CMakeSettings.json. Porém, se você preferir editar o arquivo diretamente, selecione o link Editar JSON no canto superior direito do editor.

Para abrir o editor de configurações CMake, clique na lista suspensa Configuração na barra de ferramentas principal e escolha Gerenciar Configurações.

Agora você vê o Editor de Configurações com as configurações instaladas à esquerda.

O painel esquerdo mostra as configurações instaladas (x86-Debug). O painel direito mostra as configurações da configuração selecionada. As configurações incluem o nome da configuração, o tipo de configuração (definido como Debug), o conjunto de ferramentas (definido como msvc_x86), o arquivo CMake toolchain (vazio), a raiz build (contém ${env:USERPROFILE}\CMakeBuilds\${workspaceHash}\build\${name}), os argumentos de comando CMake (vazio) e os argumentos de comando build (-v).

O Visual Studio fornece uma configuração x64-Debug por padrão. Você pode adicionar mais configurações escolhendo o sinal de adição verde. As configurações exibidas no editor podem variar de acordo com a configuração selecionada.

As opções escolhidas no editor são gravadas em um arquivo chamado CMakeSettings.json. Esse arquivo fornece argumentos de linha de comando e variáveis de ambiente que são passadas para o CMake quando você compila os projetos. O Visual Studio nunca modifica CMakeLists.txt automaticamente; usando o CMakeSettings.json, você pode personalizar o build por meio do Visual Studio, deixando os arquivos de projeto do CMake inalterados para que outras pessoas em sua equipe possam consumi-los com as ferramentas que estiverem usando.

Configurações Gerais do CMake

As seguintes configurações estão disponíveis sob o título Geral:

Nome da configuração

Corresponde à configuração name. Esse nome aparece na lista suspensa de configuração do C++. Use a macro ${name} para compor outros valores de propriedade, como caminhos.

Tipo de configuração

Corresponde à configuração configurationType. Define o tipo de configuração de build para o gerador selecionado. Os valores atualmente suportados são Debug, MinSizeRel, Release e RelWithDebInfo. Ele mapeia para CMAKE_BUILD_TYPE.

Conjunto de Ferramentas

Corresponde à configuração inheritedEnvironments. Define o ambiente do compilador usado para compilar a configuração selecionada. Os valores compatíveis dependem do tipo de configuração. Para criar um ambiente personalizado, escolha Editar JSON no canto superior direito do Editor de Configurações e edite o arquivo CMakeSettings.json diretamente.

Arquivo de cadeia de ferramentas do CMake

Caminho para o arquivo de cadeia de ferramentas do CMake. Esse caminho é passado para o CMake como "-DCMAKE_TOOLCHAIN_FILE = <filepath>". Os arquivos de cadeia de ferramentas especificam locais de compiladores e utilitários de cadeia de ferramentas e outras informações relacionadas à plataforma e ao compilador de destino. Por padrão, o Visual Studio usará o arquivo de cadeia de ferramentas vcpkg se essa configuração não for especificada.

Raiz de build

Corresponde a buildRoot. Mapeia para CMAKE_BINARY_DIR e especifica onde criar o cache do CMake. A pasta especificada será criado se ela não existir.

Argumentos de comando

As seguintes configurações estão disponíveis sob o título Argumentos de comando:

Argumentos de comando do CMake

Corresponde a cmakeCommandArgs. Especifica mais opções de linha de comando passadas para o CMake.

Argumentos de comando de build

Corresponde a buildCommandArgs. Especifica mais opções a serem passadas para o sistema de build subjacente. Por exemplo, passar -v ao usar o gerador Ninja força o Ninja a emitir linhas de comando de saída.

Argumentos de comando do CTest

Corresponde a ctestCommandArgs. Especifica mais opções de linha de comando a serem passadas para o CTest ao executar testes.

Configurações gerais para builds remotos

Para configurações como o Linux que usam builds remotos, as seguintes configurações também estão disponíveis:

Argumentos de comando rsync

Opções de linha de comando extras passadas para rsync, uma ferramenta rápida e versátil de cópia de arquivo.

Variáveis e cache do CMake

Essas configurações permitem definir as variáveis do CMake e salvá-las no CMakeSettings.json. Elas serão passadas para o CMake no tempo de compilação e substituirão todos os valores no arquivo CMakeLists.txt. Use esta seção da mesma forma que usaria a CMakeGUI para exibir uma lista de todas as variáveis do CMake disponíveis para edição. Escolha o botão Salvar e gerar cache para exibir uma lista de todas as variáveis do CMake disponíveis para edição, incluindo variáveis avançadas (de acordo com a CMakeGUI). Filtre a lista por nome da variável.

Corresponde a variáveis. Contém um par nome-valor das variáveis do CMake passadas como -D name=value para o CMake. Se as instruções de build do projeto do CMake especificam a adição de variáveis diretamente ao arquivo de cache CMake, é recomendável que você as adicione aqui.

Configurações avançadas

Gerador do CMake

Corresponde ao gerador. Mapeia para a opção CMake -G e especifica o gerador CMake a ser usado. Essa propriedade também pode ser usada como uma macro, ${generator}, ao compor outros valores de propriedade. No momento, o Visual Studio dá suporte aos seguintes geradores do CMake:

• "Ninja"
• "UNIX Makefiles"
• "Visual Studio 16 2019"
• "Visual Studio 16 2019 Win64"
• "Visual Studio 16 2019 ARM"
• "Visual Studio 15 2017"
• "Visual Studio 15 2017 Win64"
• "Visual Studio 15 2017 ARM"
• "Visual Studio 14 2015"
• "Visual Studio 14 2015 Win64"
• "Visual Studio 14 2015 ARM"

Como o Ninja é criado para velocidades rápidas de builds em vez de flexibilidade e função, ele está definido como padrão. No entanto, alguns projetos CMake podem não conseguir compilar corretamente usando o Ninja. Se isso ocorrer, instrua o CMake a gerar um projeto do Visual Studio em vez disso.

Modo do IntelliSense

O modo IntelliSense usado pelo mecanismo IntelliSense. Se nenhum modo for selecionado, o Visual Studio herdará o modo do conjunto de ferramentas especificado.

Diretório de instalação

O diretório no qual o CMake instala os destinos. Mapeia para CMAKE_INSTALL_PREFIX.

Executável do CMake

O caminho completo para o executável do programa do CMake, incluindo o nome de arquivo e a extensão. Ele permite que você use uma versão personalizada do CMake com o Visual Studio. Para builds remotos, especifique a localização do CMake no computador remoto.

Para configurações como o Linux que usam builds remotos, as seguintes configurações também estão disponíveis:

Raiz remota de CMakeLists.txt

O diretório no computador remoto que contém o arquivo raiz de CMakeLists.txt.

Raiz de instalação remota

O diretório no computador remoto no qual o CMake instala os destinos. Mapeia para CMAKE_INSTALL_PREFIX.

Origens de cópia remota

Especifica se os arquivos de origem devem ser copiados para o computador remoto e permite que você especifique se deseja usar o rsync ou o sftp.

Editar o CMakeSettings.json diretamente

Edite também o CMakeSettings.json diretamente para criar configurações personalizadas. O Editor de Configurações tem um botão Editar JSON no canto superior direito que abre o arquivo para edição.

O seguinte exemplo mostra uma configuração de exemplo, que pode ser usada como ponto de partida:

    {
      "name": "x86-Debug",
      "generator": "Ninja",
      "configurationType": "Debug",
      "inheritEnvironments": [ "msvc_x86" ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    },

O JSON IntelliSense ajuda a editar o arquivo CMakeSettings.json:

O editor de JSON também informa quando você escolhe configurações incompatíveis.

Para obter mais informações sobre cada uma das propriedades no arquivo, confira Referência de esquema de CMakeSettings.json.

Confira também

Projetos do CMake no Visual Studio
Configurar um projeto do Linux CMake
Conectar-se ao computador Linux remoto
Configurar sessões de depuração do CMake
Implantar, executar e depurar o projeto do Linux
Referência de configuração predefinida do CMake