Advanced CMake Project Structure

This page describes the Advanced CMake Projects and outlines their differences from the regular VC++-based projects.

Overview

Unlike the MSBuild-based projects, Advanced CMake projects are completely independent from the regular Visual C++ Project Subsystem and are fully managed by VisualGDB. This enables a much deeper integration with the underlying build tools and also allows having multiple targets (e.g. executables or libraries) per project:

Structure

A typical Advanced CMake project consists of the following parts:

  • One or more CMakeLists.txt files (and *.cmake files included from them) that actually describe the project structure (targets, files, build settings, etc.).
  • The .vgdbcmake file that contains VisualGDB-level settings (e.g. how to transfer source files to the target, or how to debug the project).

The project structure (targets, source files, etc) are not duplicated in the .vgdbsettings file. Instead, they are queried directly from CMake and rendered in Solution Explorer. Using Solution Explorer to add new files, or change any settings will directly update the necessary statements in CMakeLists.txt:

Settings

The Advanced CMake Projects have 4 types of settings shown below:

Settings What covers How to edit
VisualGDB Project Properties File transfer settings, most debugging settings, custom steps, IntelliSense. Select “VisualGDB Project Properties” in the project’s context menu.
VS Project Properties for the project Sorting/grouping of targets and other nodes in Solution Explorer. Select “Properties” in the project‘s context menu or press Alt+Enter.
VS Project Properties for a specific target Include directories, preprocessor macros, CFLAGS, target-specific debug and deployment settings. Select “Properties” in the target‘s context menu or press Alt+Enter.
VS Project Properties for a specific file Include directories, preprocessor macros, CFLAGS for a specific file. These settings override target-level settings. Select “Properties” in the file‘s context menu or press Alt+Enter.

Managing Targets

You can add new targets to the project by selecting Add->New Item in the project’s context menu:Selecting the same command in the target’s menu will add source files to the target instead.

Underlying Build Tools

CMake relies on external tools (such as GNU Make) to find outdated files and do the actual build. VisualGDB supports 2 build tools for the CMake projects:

  • GNU Make
  • Ninja

You can switch between the build tools via VisualGDB Project Properties:We recommend using Ninja instead of GNU Make, if your project and target supports its. Ninja works much faster on multi-core systems and is better integrated with the “project is out-of-date” check.

Debugging CMake Scripts

VisualGDB supports debugging CMake scripts by stepping into them (with breakpoints, watches and other regular debug functionality). You can start a CMake debug session by selecting “Launch CMake Debugger” in the project’s context menu:

Troubleshooting Build Problems

If building a project with VisualGDB results in strange errors that don’t appear when building it manually, you can extract the exact command lines used by VisualGDB to configure and build the project:First, reload the project via Solution Explorer. Then check the VisualGDB Build window. If it shows both configuration and build logs, make sure you select Configuration. Finally, locate the build command line and dump it into a batch file. Repeat last step for the build command line to dump it to another batch file.

Running the configuration and build .bat files manually will result in the same behavior as you observe with VisualGDB. If it is still different from the manual build, try modifying the batch files to 100% match the original build command.

If you discover that the project requires some environment variables or CMake Definitions that were not specified when importing it into VisualGDB, you can add them via VisualGDB Project Properties -> CMake Project Settings as shown below: