Projetos do CMake no Visual Studio

O CMake é uma ferramenta multiplataforma de código aberto para definir processos de build que são executados em várias plataformas. Esse artigo pressupõe que você esteja familiarizado com CMake. Para obter mais informações sobre CMake, confira a documentação do CMake. O tutorial do CMake é um bom ponto de partida para saber mais.

Observação

O CMake foi integrado progressivamente ao Visual Studio nas últimas versões. Para ver a documentação da sua versão preferencial do Visual Studio, use o controle seletor de Versão. Ele é encontrado na parte superior da tabela de conteúdo nesta página.

O suporte nativo do Visual Studio para o CMake permite editar, compilar e depurar projetos do CMake no Windows, no Subsistema do Windows para Linux (WSL) e em sistemas remotos da mesma instância do Visual Studio. Os arquivos de projeto do CMake (como CMakeLists.txt) são consumidos diretamente pelo Visual Studio para fins de IntelliSense e navegação. cmake.exe é invocado diretamente pelo Visual Studio para configuração e build do CMake.

Instalação

As ferramentas do CMake de C++ para Windows são instaladas como parte das cargas de trabalho Desenvolvimento para área de trabalho com C++ e Desenvolvimento de Linux com C++. Tanto as ferramentas do CMake de C++ para Windows quanto o Desenvolvimento de Linux com C++ são necessários para o desenvolvimento de CMake multiplataforma.

No instalador, o desenvolvimento da área de trabalho com lista suspensa do C++ está selecionado e a opção de ferramentas C Make do C++ para Windows está selecionada.

Para obter mais informações, confira Instalar a carga de trabalho do Linux em C++ no Visual Studio.

Integração de IDE

Quando você abrir uma pasta contendo um arquivo CMakeLists.txt, acontecerá o seguinte.

A caixa de diálogo oferece estas opções: clonar um repositório, abrir um projeto ou uma solução, abrir uma pasta local ou criar um projeto. Abrir uma pasta local é chamado na captura de tela.

• O Visual Studio adiciona itens do CMake ao menu Projeto, com comandos para exibição e edição de scripts do CMake.

• O Gerenciador de Soluções exibe a estrutura de pastas e os arquivos.

• O Visual Studio executa o CMake e gera o arquivo de cache do CMake (CMakeCache.txt) para a configuração padrão. A linha de comando do CMake é exibida na Janela de Saída, juntamente com outra saída do CMake.

• Em segundo plano, o Visual Studio começa a indexar os arquivos de origem para habilitar o IntelliSense, as informações de navegação, a refatoração e assim por diante. Conforme você trabalha, o Visual Studio monitora as alterações feitas no editor e também em disco para manter seu índice em sincronia com as fontes.

Observação

Começando no Visual Studio 2022 versão 17.1 Versão Prévia 2, se o CMakeLists.txt de nível superior existir em uma subpasta e não na raiz do workspace, será solicitado q você habilite ou não a integração do CMake. Para obter mais informações, consulte Ativação parcial do CMake.

Quando a geração de cache do CMake tiver êxito, você também poderá exibir seus projetos organizados logicamente por destino. Escolha o botão Selecionar Exibição na barra de ferramentas do Gerenciador de Soluções. Na lista em Gerenciador de Soluções - Exibições, selecione Exibição de Destinos do CMake e pressione Enter para abrir a exibição de destinos:

Escolha o botão Mostrar Todos os Arquivos na parte superior do Gerenciador de Soluções para ver toda a saída gerada pelo CMake nas pastas out/build/<config>.

Use o arquivo CMakeLists.txt em cada pasta de projeto da mesma forma que você faria em qualquer projeto do CMake. Você pode especificar arquivos de origem, localizar bibliotecas, definir opções de compilador e vinculador e especificar outras informações relacionadas ao sistema de build. Para saber mais sobre os serviços de linguagem do CMake fornecidos pelo Visual Studio, consulte Editando arquivos CMakeLists.txt.

O Visual Studio usa um arquivo de configuração do CMake para acionar a geração e o build de cache no CMake. Para saber mais, confira Configurando projetos do CMake e Compilando projetos do CMake.

Para passar argumentos para um executável em tempo de depuração, você poderá usar outro arquivo chamado launch.vs.json. Para obter mais informações sobre como depurar projetos do CMake multiplataforma no Visual Studio, consulte Depurando projetos do CMake.

A maioria dos recursos de linguagem do Visual Studio e do C++ tem suporte de projetos do CMake no Visual Studio. Os exemplos incluem:

• Editar e Continuar para projetos do CMake
• Integração do Incredibuild para projetos do CMake
• Suporte do AddressSanitizer para projetos do CMake
• Suporte para Clang/LLVM

Observação

Para outros tipos de projetos Open Folder, um arquivo JSON CppProperties.json adicional é usado. Esse arquivo não é relevante para projetos do CMake.

Configurando projetos do CMake

A etapa de configuração do CMake gera o sistema de build do projeto. É equivalente a invocar cmake.exe da linha de comando. Para obter mais informações sobre a etapa de configuração do CMake, consulte a documentaçã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. CMakeSettings.json está disponível para clientes que usam uma versão anterior do Visual Studio. Para saber mais sobre CMakeSettings.json, confira Personalizar configurações de build do CMake.

Quando você faz alterações significativas no arquivo de configuração do CMake ou em um arquivo CMakeLists.txt, o Visual Studio executa automaticamente a etapa de configuração do CMake. Você pode invocar a etapa de configuração manualmente: selecione Projeto > Configurar Cache na barra de ferramentas. Você também pode alterar as preferências de configuração em Ferramentas>Opções>CMake>Geral.

As configurações do CMake são chamadas. Mostrar que as notificações de cache do C Make estão selecionadas. Em 'Quando o cache está desatualizado:', a opção "Nunca executar a etapa de configuração automaticamente" está selecionada.

Se a etapa de configuração for concluída sem erros, as informações disponíveis acionarão os serviços de linguagem e IntelliSense do C++. Elas também são usadas em operações de build e depuração.

Você pode, ainda, abrir um cache de CMake existente no Visual Studio. Para saber mais, confira Abrir um cache existente.

Personalizar comentários e notificações de configuração

Por padrão, a maioria das mensagens de configuração é suprimida, a menos que haja um erro. Para ver todas as mensagens, selecioneFerramentas>Opções>CMake>Habilitar saída de diagnóstico de CMake detalhada.

Você também pode desabilitar todas as notificações de cache do CMake (barras douradas) desmarcando Mostrar notificações de cache do CMake.

Solução de problemas de erros do cache do CMake

Caso precise de mais informações sobre o estado do cache do CMake para diagnosticar um problema, abra o menu principal do Projeto ou o menu de contexto de CMakeLists.txt no Gerenciador de Soluções para executar um destes comandos:

• View CMakeCache.txt abre o arquivo CMakeCache.txt do diretório de build no editor. As edições feitas aqui em CMakeCache.txt são apagadas se você limpar o cache. Para fazer alterações que persistem após você limpar o cache, consulte Personalizar configurações do CMake ou Configurar e compilar com predefinições do CMake.

• Delete Cache and Reconfigure exclui o diretório de build e reconfigura de um cache limpo.

• Configure Cache força a execução da etapa de geração, mesmo quando o Visual Studio considera o ambiente atualizado.

Compilando projetos do CMake

A etapa de build do CMake cria uma árvore binária de projeto já gerada. É equivalente a invocar cmake --build da linha de comando. Para obter mais informações sobre a etapa de build do CMake, consulte a documentação do CMake.

Para compilar um projeto do CMake, você tem estas opções:

1. Na barra de ferramentas, localize a lista suspensa Item de Inicialização. Selecione o destino de sua preferência e pressione F5 ou escolha o botão Executar na barra de ferramentas. O projeto será compilado automaticamente pela primeira vez, assim como uma solução do Visual Studio.

2. Clique com o botão direito do mouse no destino do CMake com a Exibição de Destinos do CMake ativa no Gerenciador de Soluções e selecione Compilar no menu de contexto.

3. No menu principal, selecione Compilar > Compilar Tudo. Verifique se um destino do CMake já está selecionado na lista suspensa Item de Inicialização na barra de ferramentas.

Como se esperaria, os resultados do build são mostrados na Janela de Saída e na Lista de Erros.

Os avisos de build do CMake sobre conversões que podem resultar em perda de dados, como a conversão de um float em um inteiro, são visíveis. :::image-end:::

Editar as configurações de build

O Visual Studio usa um arquivo de configuração do CMake para acionar builds no CMake. Os arquivos de configuração do CMake encapsulam opções de build, como opções de ferramentas de build nativas e variáveis de ambiente. Se CMakePresets.json for o arquivo de configuração ativo, consulte Configurar e compilar com predefinições do CMake. Se CMakeSettings.json for o arquivo de configuração ativo, consulte Personalizar as configurações de build do CMake. CMakePresets.json está disponível no Visual Studio 2019 versão 16.10 ou posterior e é o arquivo de configuração do CMake recomendado.

Depurando projetos do CMake

Todos os destinos de CMake executáveis são mostrados na lista suspensa Item de Inicialização na barra de ferramentas. Para iniciar a depuração, selecione um e pressione o botão Depurar > Iniciar Depuração na barra de ferramentas. Em um projeto do CMake, a opção "Documento atual" só é válida para arquivos .cpp.

A lista suspensa tem estas opções: Mostrar/Ocultar destinos de depuração, documento atual, exemplos (que está realçada), box2d_tests e samples-noGUI.

Os comandos Depurar ou F5 primeiro compilam o projeto se as alterações foram feitas desde o build anterior. Alterações no arquivo de configuração do CMake (CMakePresets.json ou CMakeSettings.json) ou CMakeLists.txt fazem com que o cache do CMake seja regenerado.

Você pode personalizar uma sessão de depuração do CMake configurando propriedades no arquivo launch.vs.json. Para personalizar as configurações de depuração de um destino específico, selecione o destino na lista suspensa Item de Inicialização e pressione Depurar > Configurações de Depuração e Inicialização para o <destino ativo>. Para obter mais informações sobre as sessões de depuração do CMake, consulte Configurar sessões de depuração do CMake.

Apenas Meu Código para projetos do CMake

Quando você compila para Windows usando o compilador do MSVC, os projetos do CMake têm suporte para depuração Apenas Meu Código. Para alterar a configuração Apenas Meu Código, acesse Ferramentas>Opções>Depuração>Geral. Para obter mais informações sobre a depuração Apenas Meu Código, confira Depurar apenas o código do usuário com Apenas Meu Código.

Editar e Continuar para projetos do CMake

Quando você compila para o Windows com o compilador MSVC, os projetos do CMake têm suporte para Editar e Continuar. Adicione o código a seguir ao arquivo CMakeLists.txt para habilitar Editar e Continuar. Para obter mais informações sobre Editar e Continuar, confira Configurar Editar e Continuar (C#, VB, C++).

if(MSVC)
  target_compile_options(<target> PUBLIC "/ZI")
  target_link_options(<target> PUBLIC "/INCREMENTAL")
endif()

Anexar a um projeto do CMake em execução no Linux

O Visual Studio permite depurar um processo em execução em um sistema Linux remoto ou no WSL e depurá-lo com o depurador GDB. Para começar, selecione Depurar>Anexar ao Processo..., defina o Tipo de conexão como SSH e selecione o Destino de conexão na lista de conexões no Gerenciador de Conexões. Selecione um processo na lista de processos disponíveis e pressione Anexar. O GDB precisa estar instalado no computador Linux. Para obter mais informações sobre conexões SSH, consulte o Gerenciador de Conexões

As seguintes opções estão disponíveis na caixa de diálogo: Tipo de conexão (definido como SSH), o destino da conexão (definido como demo@ 172. 20. 60. 6) e uma lista de processos disponíveis aos quais você pode anexar."

Ativação parcial do CMake

No Visual Studio 2022 versão 17.1 e posterior, a funcionalidade do CMake não será habilitada automaticamente se a pasta raiz não contiver um arquivo CMakeLists.txt. Em vez disso, uma caixa de diálogo questionará se você deseja habilitar a funcionalidade do CMake para o projeto. Se você recusar, a geração de cache do CMake não será iniciada e as configurações do CMake (de CMakeSettings.json ou CMakePresets.json) não aparecerão na lista suspensa de configuração. Se você aceitar, será levado a um arquivo de configuração no nível do workspace, CMakeWorkspaceSettings.json, (armazenado no diretório .vs) para especificar as pastas para as quais deseja habilitar o CMake. (Essas pastas contêm seus arquivos CMakeLists.txt raiz).

As propriedades aceitas são:

Propriedade	Descrição
enableCMake	Habilite a integração do Visual Studio para este workspace.
sourceDirectory	Uma cadeia de caracteres ou uma matriz de cadeias de caracteres especificando o diretório ou diretórios com CMakeLists.txt. Macros (como ${workspaceRoot}) são permitidas. Os caminhos relativos são baseados na raiz do workspace. Diretórios fora do workspace atual serão ignorados.

Você pode acessar CMakeWorkspaceSettings.json por meio do comando de menu Projeto>Configurações do Workspace do CMake a qualquer momento, mesmo que a funcionalidade do CMake esteja desabilitada.

Abrir um cache existente

Quando você abre um arquivo de cache do CMake (CMakeCache.txt), o Visual Studio não tenta gerenciar o cache e a árvore de build para você. Suas ferramentas personalizadas ou preferenciais têm controle completo sobre como o CMake configura o projeto.

Você pode adicionar um cache do CMake existente a um projeto aberto. Isso é feito da mesma maneira que você adicionaria uma nova configuração. Para saber mais, consulte nossa postagem no blog sobre como abrir um cache existente no Visual Studio.

Observação

A experiência de cache existente padrão depende de cmake-server, que foi removido do CMake na versão 3.20. Para continuar usando a funcionalidade de cache existente no Visual Studio 2019 versão 16.10 e posterior, siga uma destas etapas:

• Instale manualmente o CMake versão 3.19 ou inferior. Em seguida, defina a propriedade cmakeExecutable na configuração de cache existente para usar essa versão do CMake.
• Na configuração de cache existente, defina a propriedade cacheGenerationCommand para permitir que o Visual Studio solicite os arquivos de API baseados em arquivo do CMake necessários. Para obter mais informações sobre essa propriedade, consulte a Referência de CMakeSettings.json.
• Use um arquivo de consulta para solicitar os arquivos de API baseados em arquivo do CMake ao gerar o cache antes que ele seja aberto no Visual Studio. Para obter instruções sobre o arquivo de consulta, consulte a próxima seção, Solução de problemas de cache avançado do CMake.

Solução de problemas de cache avançado do CMake

O Visual Studio usa a API baseada em arquivo do CMake (nas versões 3.14 e posteriores) para preencher o editor com informações específicas à estrutura do projeto. Para obter mais informações, consulte a postagem no blog da equipe do C++ sobre workspaces com várias raízes e API baseada em arquivo.

Antes de gerar o cache do CMake, suas ferramentas personalizadas ou preferenciais podem precisar criar um arquivo de consulta chamado .cmake/api/v1/query/client-MicrosoftVS/query.json na pasta de saída do build (a pasta que contém CMakeCache.txt). O arquivo de consulta deve ter este conteúdo:

{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]}

Quando suas ferramentas personalizadas ou preferenciais geram o cache, o CMake coloca arquivos em .cmake/api/v1/response que o Visual Studio usa para popular o editor com informações específicas da estrutura do projeto.

Editando arquivos CMakeLists.txt

Para editar um arquivo CMakeLists.txt, clique com o botão direito do mouse no arquivo no Gerenciador de Soluções e escolha Abrir. Se você fizer alterações no arquivo, uma barra de status amarela será exibida e informará que o IntelliSense será atualizado. Isso lhe dá a chance de cancelar a operação de atualização. Para obter informações sobre CMakeLists.txt, consulte a documentação do CMake.

Ele contém o projeto de linhas (hello-cmake), add_subdirectory (testes), add_executable (hello hello.cpp) e instalação (TARGETS hello DESTINATION hello/bin). Uma mensagem na parte superior da janela diz que as informações do C++ do IntelliSense serão atualizadas depois que o C Make terminar de gerar o cache.

Assim que você salva o arquivo, a etapa de configuração é executada novamente de forma automática e exibe as informações na janela de Saída. Os erros e avisos são mostrados na Lista de Erros ou na janela de Saída. Clique duas vezes em um erro na Lista de Erros para navegar até a linha incorreta em CMakeLists.txt.

Uma mensagem de erro do C Make na linha 3 de CMakeLists.txt está realçada. Os detalhes são de que o C Make não conseguiu localizar um arquivo de configuração de pacote fornecido pelo sqlite3. C Make procurou por ele em CMAKE_MODULE_PATH mas não conseguiu encontrá-lo. A sugestão é adicionar o prefixo de instalação 'sqlite3' para CMAKE_PREFIX_PATH ou definir sqlite3_DIR a um diretório que contém sqlite3Config.cmake e/ou sqlitet3-config.cmake.

Serviços de linguagem para CMake

Os serviços de linguagem para o CMake estão disponíveis no Visual Studio 2019 versão 16.5 ou posterior. Eles dão suporte a recursos de navegação de código como Ir para Definição, Espiar Definição e Localizar Todas as Referências para variáveis, funções e destino do CMake em arquivos de script do CMake. Para obter mais informações, consulte Navegação de código para scripts do CMake.

Os resultados de onde SUPERTUX_SOURCES_CXX são encontrados são mostrados. Por exemplo, em list(SORT SSUPERTUX_SOURCES_CXX), file(GLOB SUPERTUX_SOURCES_CXX) e assim por diante.

Manipulação de projetos do CMake

A manipulação de projetos do CMake está disponível no Visual Studio 2019 versão 16.5 ou posterior. A manipulação de projetos permite que você adicione, remova e renomeie arquivos de origem e destinos em seus projetos do CMake sem editar manualmente seus scripts do CMake. Quando você adicionar ou remover arquivos do Gerenciador de Soluções, o Visual Studio editará automaticamente seu projeto do CMake. Pode haver mais de um lugar em que faz sentido adicionar ou remover uma referência a um script do CMake. Nesse caso, o Visual Studio pergunta onde você deseja fazer a alteração e exibe uma visualização das alterações propostas. Para obter instruções passo a passo, consulte Adicionar, remover e renomear arquivos e destinos em projetos do CMake.

Um modo de exibição de árvore mostra CMakeLists.txt, em que estão dois itens: add_executable e set. Set está marcado. A janela de visualização mostra onde as alterações serão feitas. O conjunto de linhas (PROJECT_SRC "CmakeProject4.cpp" "CMakeProject4.h" mostra "Demo.cpp" realçado antes do parêntese de fechamento. Você pode usar o botão aplicar para aceitar a alteração ou pressionar cancelar.

IntelliSense para projetos do CMake

Por padrão, o Visual Studio usa o modo IntelliSense que corresponde à arquitetura de compilador e de destino especificada pela configuração ativa do CMake.

Se CMakePresets.json for seu arquivo de configuração do CMake ativo, você poderá especificar opções do IntelliSense usando intelliSenseMode e intelliSenseOptions no mapa de fornecedores de Configurações do Visual Studio. Para obter mais informações, consulte a Referência do mapa de fornecedores de Configurações do Visual Studio.

Se CMakeSettings.json for o arquivo de configuração do CMake ativo, você poderá especificar as opções do IntelliSense usando intelliSenseMode em CMakeSettings.json. Para obter mais informações, confira a referência do CMakeSettings.json.

Configurar o IntelliSense com arquivos de cadeia de ferramentas do CMake

No Visual Studio 2019 versão 16.9 e posterior, o Visual Studio configura automaticamente o IntelliSense em projetos do CMake com base em variáveis do CMake quando você usa um arquivo de cadeia de ferramentas do CMake. Para obter mais informações, consulte Configurar o IntelliSense com arquivos de cadeia de ferramentas do CMake.

Integração de vcpkg

Os projetos do CMake abertos no Visual Studio integram-se ao vcpkg, um gerenciador de dependências de C/C++ multiplataforma. Antes de usar o vcpkg com o Visual Studio, você precisa executar vcpkg integrate install. Para obter instruções e mais informações sobre vcpkg, consulte:

• Instalar e usar pacotes com o CMake no Visual Studio
• vcpkg em projetos do CMake

Se CMakeSettings.json for o arquivo de configuração ativo, o Visual Studio passará automaticamente o arquivo de cadeia de ferramentas do vcpkg (vcpkg.cmake) para o CMake. Esse comportamento é desabilitado automaticamente quando você especifica qualquer outra cadeia de ferramentas nas Configurações do CMake.

Se CMakePresets.json for o arquivo de configuração ativo, você precisará definir o caminho como vcpkg.cmake em CMakePresets.json. É recomendável usar a variável de ambiente VCPKG_ROOT em vez de um caminho absoluto para manter o arquivo compartilhável. Para obter mais informações, consulte Habilitar a integração de vcpkg com predefinições do CMake. CMakePresets.json está disponível no Visual Studio 2019 versão 16.10 ou posterior e é o arquivo de configuração do CMake recomendado.

Executar CMake na linha de comando

Se CMakePresets.json for o arquivo de configuração do CMake ativo, você poderá reproduzir facilmente builds locais fora do Visual Studio. Para obter mais informações, consulte Executar o CMake na linha de comando ou em um pipeline de CI. CMakePresets.json tem suporte no Visual Studio 2019 versão 16.10 ou posterior e é o arquivo de configuração do CMake recomendado.

Se CMakeSettings.json for o arquivo de configuração do CMake ativo, você precisará passar manualmente os argumentos codificados no arquivo CMakeSettings.json para o CMake. Se tiver instalado o CMake do Instalador do Visual Studio, será possível executá-lo na linha de comando seguindo estas etapas:

1. Execute o arquivo vsdevcmd.bat apropriado (x86/x64). Para obter mais informações, consulte Compilando na linha de comando.

2. Alterne para sua pasta de saída.

3. Execute o CMake para compilar ou configurar o aplicativo.

Confira também

Tutorial: Criar projetos multiplataforma do C++ no Visual Studio
Configurar um projeto do Linux CMake
Conectar-se ao computador Linux remoto
Personalizar as configurações de compilação do CMake
CMakeSettings.json referência de esquema
Configurar sessões de depuração do CMake
Implantar, executar e depurar o projeto do Linux
Referência de configuração predefinida do CMake
vcpkg em projetos do CMake
Instalar e usar pacotes com o CMake no Visual Studio