New templates for debugging CMake projects on remote systems and WSL in Visual Studio 2019

Erika Sweet

We heard your feedback that it can be difficult to configure debugging sessions on remote Linux systems or the Windows Subsystem for Linux (WSL). In Visual Studio 2019 version 16.6 Preview 2 we introduced a new debugging template to simplify debugging with gdb.

  • All your existing debug configurations (of type cppdbg) will continue to work as expected.
  • The new template of type cppgdb will be used by default whenever you add a new Linux or WSL debug configuration.
  • You can read a full description of the new schema by checking out our updated documentation: Keep reading for an overview of the new template and a remote debugging FAQ.
  • Note: In Visual Studio 2019 version 16.6 Preview 2 you will need to manually set the configuration type to cppgdb. This bug has been fixed in Preview 3.

The new cppgdb template

We heard your feedback that the old debug configurations were too verbose, too confusing, and not well documented. The new cppgdb configuration has been simplified and looks like this:

  "type": "cppgdb",
  "name": "My custom debug configuration",
  "project": "CMakeLists.txt",
  "projectTarget": "DemoApp.exe",
  "comment": "Learn how to configure remote debugging. See here for more info",
  "debuggerConfiguration": "gdb",
  "args": [],
  "env": {}

The new setting debuggerConfiguration indicates which set of debugging default values to use. In Visual Studio 2019 version 16.6 the only valid option is gdb.

There are more optional settings that can be added and configured for your debugging scenario like gdbPath (path to gdb), cwd (path to the working directory where the program is run), and preDebugCommand (a new setting that allows a Linux command to run before starting the debugger). A full list of these settings and their default values are listed in our documentation.

Coming next: first-class support for gdbserver

In Visual Studio 2019 version 16.5 or later you can manually configure launch.vs.json to debug CMake projects with gdbserver. In an upcoming release of Visual Studio we will be adding first-class support for gdbserver to the new cppgdb template. This will allow you to select gdbserver via the debuggerConfiguration setting and easily customize things like the path to gdbserver or the local path to gdb.

Remote debugging scenarios FAQ

There are a few frequently asked questions we receive about debugging on Linux and WSL. A selection of these are called out and answered with examples below.

How do I pass arguments to the program being debugged?

Command-line arguments passed on startup to the program being debugged are configured with the args array. Example:

"args": ["arg1", "arg2"],

How do I set environment variables? Do I need to re-set the environment variables I set in CMakeSettings.json?

In Visual Studio 2019 version 16.5 or later debug targets are automatically launched with the environment specified in CMakeSettings.json. You can reference an environment variable defined in CMakeSettings.json (e.g. for path construction) with the syntax “${env.VARIABLE_NAME}”. You can also unset a variable defined in CMakeSettings.json by setting it to null.

The following example passes a new environment variable (DISPLAY) to the program being debugged and unsets an environment variable (DEBUG_LOGGING_LEVEL) that is specified in CMakeSettings.json.

"env": {
        "DISPLAY": "1.0",
        "DEBUG_LOGGING_LEVEL": null

Note: Old Linux/WSL configurations of type cppdbg depend on the “environment” syntax. This alternative syntax is defined in our documentation.

I want to separate the system I am building on from the system I am debugging on. How do I do this?

Your build system (either a WSL installation or a remote system) is defined in CMakeSettings.json. Your remote debug system is defined by the key remoteMachineName in launch.vs.json.

By default, the value of remoteMachineName in launch.vs.json is synchronized with your build system. This setting only needs to be changed when specifying a new debug system. The easiest way to change the value of remoteMachineName in launch.vs.json is to use IntelliSense (ctrl + space) to view a list of all established remote connections.

IntelliSense in launch.vs.json prompts you with all of your existing connections defined in the Connection Manager.

There are several other (optional) deployment settings that can be used to configure the separation of build and debug listed in our documentation.

I want to interact directly with the underlying debugger. Can I do this?

Visual Studio allows you to execute custom gdb commands via the Command Window. To do so,

  • View > Other Windows > Command Window
  • Run: Debug.MIDebugExec insert-your-gdb-command-here

I’m debugging with gdb or gdbserver and something isn’t working. How can I troubleshoot? 

You can enable logging to see what commands we are sending to gdb, what output gdb is returning, and how long each command took.

  • View > Other Windows > Command Window
  • Run: Debug.MIDebugLog (/On[:<filename>] | /Off) [/OutputWindow]


  • /On[:] – Turn on MIEngine logging. Optionally specify a file to contain the log. Either the file must be supplied, or the “/OutputWindow” option must appear.
  • /Off — Turn off MIEngine logging. If logging to a file, the file is closed.
  • /OutputWindow — Log to the “Debug” pane in the output Window.

Give us your feedback

Download Visual Studio 2019 version 16.6 Preview 2 today and give it a try. We’d love to hear from you to help us prioritize and build the right features for you. We can be reached via the comments below, Developer Community, email (, and Twitter (@VisualC and @erikasweet_). The best way to file a bug or suggest a feature is via Developer Community.


Discussion is closed. Login to edit/delete existing comments.

  • M.Mohyuddin Zubair 0

    hello, I like your article it’s most relevant with my education its very help full for new Software developers and their Skills

  • Cem PAYZIN 0

    Hi Erika,

    I am not sure if I am asking this question on proper channel, however i have been using VS2019 16.5 to develop Linux apps. I prefer debug on test on WSL and then compile and deploy to remote Linux. However i could not figure out how to sync WSL headers so intellisense works. Remote linux boxes downloads intellisense headers and no issue with them.

    Please let me know if you can help me out on this.


    • Erika SweetMicrosoft employee 0

      Hi Cam, can you open an issue on Developer Community? You can do this from inside Visual Studio via the “Send Feedback” button in the top right-hand corner of the IDE. You can also search for “Report a Problem” in the search bar.

      IntelliSense for WSL should work the same as it does for remote systems – if that’s not working for you then we will be happy to take a look!

Feedback usabilla icon