Creating CMake Linux projects with Visual Studio

This tutorial shows how to create, build and debug a simple CMake-based project with Visual Studio and use the Advanced CMake Project Subsystem to automatically update the CMakeLists.txt files when editing the project.

Before you begin, make sure that VisualGDB 5.3 or later is installed.

  1. Start Visual Studio and open the “New Project” dialog. Select the Linux Project Wizard from VisualGDB folder:01-newprj
  2. On the first wizard page ensure that “Create a new project” is selected and then select the “Use CMake” and check the “Use the advanced CMake Project Subsystem” checkbox:02-type
  3. On the next page select the Linux computer you want to target and press “Next”. If you have not configured the connection to that computer with VisualGDB yet, follow the generic Linux tutorial to set it up.03-machine
  4. On the next page specify how should the Linux machine access the source code. The easiest way would be to proceed with the default settings of uploading the modified sources to the Linux machine:04-copyYou can also configure VisualGDB to store the sources directly on the Linux machine and access them via SSH. Follow this tutorial for more details.
  5. Once the project is created, press Ctrl-Shift-B to build your solution:05-project
  6. Set a breakpoint in main() and press F5 to ensure that you can debug the project:06-debug
  7. Now we will show how to manage project targets and edit various settings using the GUI. First we will create another executable target. Right-click on the .vgdbcmake node in Solution Explorer and select Add->New Item. Then pick “Executable” and add “/subdir” to the location:07-anotherexe
  8. VisualGDB will automatically create the “subdir” folder, put a CMakeLists.txt file there and reference it from the main CMakeLists file. Copy the contents of the main .cpp file to the new target’s file (optionally replacing the hello message) and build the project:08-hello2
  9. Add another source file to the new target:09-newsrc
  10. This time add “subdir2” to the source file path:10-anothersource
  11. Each CMake target under the VisualGDB CMake Project can have an independent set of properties. Debug-related properties like command-line arguments will be stored in the project file itself. Build-related properties like include directories will be automatically saved to CMakeLists.txt files. Open the VS Project Properties (alt-Enter) for the main target and set the command-line arguments to a non-empty value:11-args
  12. Right-click on the main target and select Debug->Start a new instance to begin debugging it:12-debug
  13. See how VisualGDB starts the selected target and how the command-line arguments match the ones set via Target Settings:  13-debug
  14. Open Visual Studio Properties for the project itself (.vgdbcmake node). You can use the settings in the “Sorting/Grouping” category to control how VisualGDB groups the sources or targets. E.g. try setting the “Group Sources By Types” to “False”:14-nogroup
  15. See how the “Source Files” nodes have disappeared and the sources are shown directly under the target nodes:nodirs
  16. Now we will show how CMake handles subprojects. Open the CMakeLists.txt file from the subdirectory and add the following line there:


  17. Save the CMakeLists file and look at the Solution Explorer. See how it now shows 2 project nodes, one for each project() statement:subproj2
  18. If a CMake project includes another project, CMake would normally report the targets of the included project (a.k.a. inner project) twice – once as a part of the including (a.k.a. outer) project and once as a part of the including project. As this is not very convenient, VisualGDB automatically hides redundant target instances. You can control how filtering works using the “Hide Redundant Targets” setting in the VS settings for the .vgdbcmake project:16-hidemodesIf HideInnerProjectTargets is selected, all targets will be shown as if they were defined in the outer project (i.e. as if there were no nested project() statements). If HideOuterProjectTargets is selected, VisualGDB will show the targets inside the inner project nodes.
  19. Unlike MSBuild projects, CMake projects won’t automatically detect whether they are out-of-date unless you attempt an actual build, so trying to debug a project will always result in a prompt to build it:check
  20. You can change this behavior by turning on the “Rely on CMake up-to-date Check” setting and reloading the project:17-uptodateHowever beware that CMake often mistakingly considers large projects outdated even if they aren’t, so this mechanism may not always work. You can use the View->Output->VisualGDB CMake Output pane to view the diagnostic output from CMake.
  21. If your CMake project contains multiple targets in multiple directories, you can limit the build to selected directories only by right-clicking on the target nodes and selecting “Build Target”:18-buildtargetNote that if the same directory contains multiple targets, the “Build Target” command will build all targets in that directory.
  22. Now we will show how to edit the target properties. Open Visual Studio Project Properties for one of the targets and set the Warning Level to Pedantic:19-warnings
  23. See how VisualGDB automatically inserted the target_compile_options() statement into the corresponding CMakeLists file:20-edited
  24. Finally we will show how to configure various global settings for your VisualGDB CMake Project. Right-click on the project node and select “VisualGDB Project Properties”:21-vgdbprops
  25. You can use the VisualGDB Project Properties window to configure various settings (e.g. IntelliSense, static code analysis or debug/deployment settings):22-dbgsettings