Personalizar as configurações de compilação 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 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 construir 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.

O Visual Studio 2017 fornece várias configurações do CMake que definem como o CMake é invocado para criar o cache do CMake para determinado projeto. Para adicionar uma nova configuração, selecione a lista suspensa na barra de ferramentas de configuração e escolha Gerenciar Configurações:

Você pode escolher na lista de configurações predefinidas:

Na primeira vez que você seleciona uma configuração, o Visual Studio cria um arquivo CMakeSettings.json na pasta raiz do seu projeto. Esse arquivo é usado para recriar o arquivo de cache do CMake, por exemplo, após uma operação de Limpeza.

Para adicionar outra configuração, clique com o botão direito do mouse CMakeSettings.json e escolha Adicionar Configuração.

Você também pode editar o arquivo usando o Editor de Configurações do CMake. Clique com o botão direito do mouse em CMakeSettings.json no Gerenciador de Soluções e escolha Editar Configurações do CMake. Ou selecione Gerenciar Configurações na lista suspensa de configurações na parte superior da janela do editor.

Edite também o CMakeSettings.json diretamente para criar configurações personalizadas. 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:

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