Working with CMake

CMake is popular advanced cross-platform build system. It has its own format of build files (called CMakeLists.txt) which is platform independent. These files are converted to platform dependent files in turn (e.g. makefiles, Visual Studio projects, and other available formats). You can find more information on the CMake website: http://cmake.org/overview.

WinGDB aims at providing comprehensive integration with CMake, offering many features to augment standard CMake work flow:

New project wizard creating Visual Studio workplace project from specified CMake project (sources and CMake lists).
Advanced editor features for CMakeLists files (IntelliSense, outlining, cross-probing CMakeLists errors, and more).
CMake projects are directly buildable and debuggable on remote Unix machine under Visual Studio.
Easy, contextual access to CMake documentation (help on commands, variables and properties).
Simple changes to the project (adding, renaming and removing files) in Visual Studio can be reflected back to the CMakeLists file.

Configuring WinGDB for CMake

In order to use WinGDB with CMake, the CMake install location must be known to WinGDB. In most cases WinGDB is able to determine this location automatically. However, CMake must be installed with Windows Installer (a .msi file) to allow that. If the CMake installation was just unpacked to some directory, then you must specify the location explicitly in WinGDB/Preferences/General/CMake installation path field.

There is also WinGDB/Preferences/General/Enable CMake integration field, which should be set to Yes to enable CMake features in WinGDB.

Opening CMake project in Visual Studio

If you already have a project with CMakeLists.txt files, you have two possibilities on how to start work with WinGDB.

Click New project, find WinGDB/Standard projects category and select Visual Studio project from CMake. This will create a Visual Studio project and open it. The wizard asks for destination location first, and later for a path to your top-level CMakeLists.txt file. You can specify different directory for the VS project than the source directory -- it is actually recommended. The generated VS project will be your "workplace" project and you can throw it away without risking losing any sources. Meanwhile, your source directories remain free of platform-specific files.

Use the WinGDB/CMake/Open CMake GUI option to open CMake GUI and generate the project from there. You must manually open the project in Visual Studio in such case. Use WinGDB/Properties or WinGDB/Project configuration wizard to configure build and debugging on remote host.

If you already have a Visual Studio project generated from CMake, you can continue working with it as before. In this case also use WinGDB/Properties or WinGDB/Project configuration wizard to configure build and debugging on remote host.

Editing CMake build files

CMake build files are named by convention CMakeLists.txt. There usually is one such file in each directory of the source tree. These files are visible in Solution Explorer window in Visual Studio. You can edit them just by double clicking, as usual. WinGDB offers specialized editing features for opened CMakeLists.txt files, provided that Enable CMake integration option is turned on.

Note that CMake places the top-level CMakeLists.txt file inside the ALL_BUILD artifical project. This file configures the solution as a whole and lists particular projects inside it.

Syntax coloring in CMake list files

WinGDB provides syntax highlighting for CMakeLists.txt files. You can configure this feature by opening standard Fonts and colors dialog and setting WinGDB CMake colors.

IntelliSense in CMake list files

WinGDB also implements a whole set of IntelliSense features. Lists of available entries are displayed for commands, properties and variables.

When hovering mouse cursor over a name, a help tip appears with short description taken from CMake documentation.

There is also an option to open full help for particular command, property or variable:

Other language specific editing features also work: comment / uncomment selection, outlining, matching parenthesis highlight, detection of simple syntax errors. For CMake macros and functions, Go to definition command is also available. For included files, Open command is available.

Compiling CMake build files

In order to regenerate Visual Studio projects after changes in CMakeLists.txt file (or more of them), select the top-level CMake list file in Solution Explorer and use option Compile on it:

Should the CMake file contain errors, WinGDB will redirect them to Visual Studio console and Task List windows, so that you can click on them to jump to appopriate place in the file.

This will compile the CMake list on local machine, and possibly regenerate Visual Studio projects. In such case, Visual Studio will prompt you to reload these projects.

Configuring remote build and debugging in CMake project

WinGDB allows to build and debug CMake projects remotely, same as regular makefile projects. It needs some configuration, though. Also, both CMake and GNU make must be installed on the remote machine.

First of all, CMake project is actually equivalent to whole solution in Visual Studio. Therefore you need to configure the solution build. In order to do this, right-click on the solution node in Solution Explorer and choose WinGDB/Properties on it. Alternatively, use WinGDB/Manage properties/Persistent properties to make the options stored in disk file instead of SUO file. Go to the Solution build page and set following options:

Solution build mode must be set to Invoke top-level remote build command, as we will be running single CMake command to build the whole set of projects.
Solution build directory should be set to the target directory where build results will be stored. You can use Visual Studio variables, like $(Configuration) here (as well as in other parameters).
Solution build command runs both CMake (to generate makefile) and make to perform actual build. It should be set to value like:

cmake -DCMAKE_BUILD_TYPE=$(Configuration) ../..;make

The argument to cmake is relative path to the top-level CMakeLists.txt file, as viewed from the solution build directory described above. If the target directory is something like Debug/bin inside the project directory, then relative path pointing back to CMakeLists.txt is ../... It can be any relative path. Second command in sequence (after the semicolon) is GNU make invocation. CMake will generate makefile in the target directory, and make will build it.

Solution rebuild command is similar to the above, but should clean build results as well. Suggested value is:

cmake -DCMAKE_BUILD_TYPE=$(Configuration) ../..;make clean;make

Solution clean command only cleans the build, e.g.

cmake -DCMAKE_BUILD_TYPE=$(Configuration) ../..;make clean

An example of the configuration is shown below.

If you created the project with the template described above and used the Project configuration wizard during that process, you do not need to perform these configuration steps, as the wizard sets the data for you.

To configure debugging, follow standard procedure described in this section and sections of the manual related to your target platform. At least, you need to enter executable location in the Debug/Executable path field.

Multiplatform development with CMake

CMake support in WinGDB integrates seamlessly with other mechanisms, including Systems. In order to develop for Windows and Linux simultaneously, just create two systems, named e.g. Windows and GCC. For Windows system, set Intercept standard IDE commands to No. It will ensure that Visual Studio project will be built and debugged locally. For GCC system, enter configuration settings as described above and set Intercept standard IDE commands to Yes. Now you can just switch between local Windows and remote Linux development with just two clicks, using the System selector box.

Updating CMake list files automatically

When you add, remove or rename files in the project using the Solution Explorer, WinGDB can automatically update corresponding CMakeLists.txt file. The list file must list the sources explicitly to make the updating possible. Updating can also be enabled or disabled in project properties. To control this, open WinGDB / Properties (or Persistent properties) on the solution, go to Automated flow page and set Update CMakeList on files change. to the desired value.

If your CMake project is complex and it enumerates sources by some other way than directly listing them in a command, update will not be performed.

You can also set control updating per project instead of entire solution, although it is usually not the most convenient option. However, if updating does not behave as you expected, it is woth checking whether it were not accidentally disabled in project settings (as project settings override ones inherited from the solution).

Table of Contents