Advanced CMake Project Structure

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

Contents

Overview
Structure
Settings
Managing Targets
Underlying Build Tools
Debugging CMake Scripts
Troubleshooting Build Problems
Customizing Solution Explorer View
Using Virtual Folders
Defining Conditional Settings

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:

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 shown in cyan 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:

Customizing Solution Explorer View

You can customize the way items are shown in Solution Explorer by opening VS properties for the project-level node (with CMake icon) in Solution Explorer:There you can set the following options:

• Combine Trivial Folder Nodes. If grouping by paths is enabled, VisualGDB will combine multiple folder nodes where possible. E.g. if the “level2” folder only contains a “level3” subfolder and no files inside “level2”, both nodes will be merged into “level2/level3“:
• Follow CMake Source Groups. If enabled, VisualGDB will rely on CMake-reported source groups instead of built-in groups like “Source Files” or “Header Files“. CMake source groups can be defined via the source_group() statement.
• Group Sources by Paths. If enabled, VisualGDB will automatically group file nodes in Solution Explorer by their paths relative to the main source directory of each target. If disabled, all files will appear together as if they were located in the same directory:
• Group Sources by Types. If enabled, VisualGDB will show files of different types (e.g. Source Files vs. Header Files) separately:Note that this setting does not affect built-in nodes like Embedded Resources or Linker Scripts.
• Group Targets by Paths. If enabled, VisualGDB will automatically group targets (executables and libraries) based on the directory path where they are defined, relatively to the top-level CMakeLists.txt file. If disabled, VisualGDB will show all targets as if they were defined in the same directory:
• Sort Sources/Targets by Name. If enabled, VisualGDB will sort all source files/targets in Solution Explorer alphabetically. If disabled, it will show them in the order reported by CMake.

Using Virtual Folders

You can create virtual target/source folders in Solution Explorer using context menu commands in the Add menu:After the folder is created, you can drag targets or sources into it, and VisualGDB will remember it next time you open the project. The mappings between the target/source paths and virtual folders are stored in the .vgdbcmake files.

Defining Conditional Settings

You can change various target settings (e.g. add preprocessor macros) via VS Properties window for the target. However, it will affect all configurations and platforms:Note that each time you change these settings, VisualGDB will create or update a statement in one of the CMakeLists.txt files. You can make this statement conditional by wrapping it in if()/endif() commands:E.g. the following code will add the MYMACRO definition to debug configuration only:

if ("${CMAKE_BUILD_TYPE}" STREQUAL "DEBUG")
target_compile_definitions(LinuxProject10 PRIVATE MYMACRO)
endif()

Note that the VS Properties windows will show conditionally defined settings together with the unconditional ones.