{"id":25804,"date":"2020-04-03T18:27:03","date_gmt":"2020-04-03T18:27:03","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=25804"},"modified":"2020-04-07T17:06:59","modified_gmt":"2020-04-07T17:06:59","slug":"new-templates-for-debugging-cmake-projects-on-remote-systems-and-wsl-in-visual-studio-2019","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/new-templates-for-debugging-cmake-projects-on-remote-systems-and-wsl-in-visual-studio-2019\/","title":{"rendered":"New templates for debugging CMake projects on remote systems and WSL in Visual Studio 2019"},"content":{"rendered":"<p>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 <a href=\"https:\/\/visualstudio.microsoft.com\/vs\/preview\/\">Visual Studio 2019 version 16.6 Preview 2<\/a> we introduced a new debugging template to simplify debugging with gdb.<\/p>\n<ul>\n<li>All your existing debug configurations (of type <span class=\"lang:default highlight:0 decode:true crayon-inline \">cppdbg<\/span>) will continue to work as expected.<\/li>\n<li>The new template of type <span class=\"lang:default highlight:0 decode:true crayon-inline \">cppgdb<\/span> will be used by default whenever you add a <strong>new<\/strong> Linux or WSL debug configuration.<\/li>\n<li>You can read a full description of the new schema by checking out our updated documentation: <a href=\"https:\/\/aka.ms\/vslinuxdebug\">https:\/\/aka.ms\/vslinuxdebug<\/a>. Keep reading for an overview of the new template and a remote debugging FAQ.<\/li>\n<li>Note: In Visual Studio 2019 version 16.6 Preview 2 you will need to manually set the configuration type to cppgdb. This <a href=\"https:\/\/developercommunity.visualstudio.com\/content\/problem\/967036\/template-type-cppdbg-added-instead-of-cppgdb.html\">bug has been fixed in Preview 3<\/a>.<\/li>\n<\/ul>\n<h4>The new cppgdb template<\/h4>\n<p>We heard your feedback that the old debug configurations were too verbose, too confusing, and not well documented. The new <span class=\"lang:default highlight:0 decode:true crayon-inline \">cppgdb<\/span> configuration has been simplified and looks like this:<\/p>\n<pre class=\"\">{\r\n  \"type\": \"cppgdb\",\r\n  \"name\": \"My custom debug configuration\",\r\n  \"project\": \"CMakeLists.txt\",\r\n  \"projectTarget\": \"DemoApp.exe\",\r\n\u00a0 \"comment\": \"Learn how to configure remote debugging. See here for more info http:\/\/aka.ms\/vslinuxdebug\",\r\n  \"debuggerConfiguration\": \"gdb\",\r\n  \"args\": [],\r\n  \"env\": {}\r\n}<\/pre>\n<p>The new setting <strong>debuggerConfiguration<\/strong> indicates which set of debugging default values to use. In Visual Studio 2019 version 16.6 the only valid option is <strong>gdb<\/strong>.<\/p>\n<p>There are more optional settings that can be added and configured for your debugging scenario like <strong>gdbPath <\/strong>(path to gdb), <strong>cwd<\/strong> (path to the working directory where the program is run), and <strong>preDebugCommand<\/strong> (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 <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/configure-cmake-debugging-sessions?view=vs-2019#launchvsjson-reference-for-remote-projects-and-wsl\">documentation<\/a>.<\/p>\n<h4>Coming next: first-class support for gdbserver<\/h4>\n<p>In Visual Studio 2019 version 16.5 or later you can manually configure launch.vs.json to <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/debugging-linux-cmake-projects-with-gdbserver\/\">debug CMake projects with gdbserver.<\/a> In an upcoming release of Visual Studio we will be adding first-class support for <strong>gdbserver<\/strong> to the new <span class=\"lang:default highlight:0 decode:true crayon-inline \">cppgdb<\/span> template. This will allow you to select gdbserver via the <strong>debuggerConfiguration<\/strong> setting and easily customize things like the path to gdbserver or the local path to gdb.<\/p>\n<h4>Remote debugging scenarios FAQ<\/h4>\n<p>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.<\/p>\n<p><strong>How do I pass arguments to the program being debugged? <\/strong><\/p>\n<p>Command-line arguments passed on startup to the program being debugged are configured with the <strong>args<\/strong> array. Example:<\/p>\n<pre class=\"\">\"args\": [\"arg1\", \"arg2\"],<\/pre>\n<p><strong>How do I set environment variables? Do I need to re-set the environment variables I set in CMakeSettings.json? <\/strong><\/p>\n<p>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 \u201c${env.VARIABLE_NAME}\u201d. You can also unset a variable defined in CMakeSettings.json by setting it to null.<\/p>\n<p>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.<\/p>\n<pre class=\"\">\"env\": {\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"DISPLAY\": \"1.0\",\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"DEBUG_LOGGING_LEVEL\": null\r\n\u00a0\u00a0\u00a0\u00a0\u00a0 },<\/pre>\n<p>Note: Old Linux\/WSL configurations of type cppdbg depend on the \u201c<strong>environment\u201d<\/strong> syntax. This alternative syntax is defined in our <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/configure-cmake-debugging-sessions?view=vs-2019#configuration-type-cppdbg\">documentation<\/a>.<\/p>\n<p><strong>I want to separate the system I am building on from the system I am debugging on. How do I do this? <\/strong><\/p>\n<p>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 <strong>remoteMachineName<\/strong> in launch.vs.json.<\/p>\n<p>By default, the value of remoteMachineName in launch.vs.json is synchronized with your build system. This setting <strong>only needs to be changed<\/strong> 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.<\/p>\n<p><img decoding=\"async\" class=\"aligncenter size-full wp-image-25795\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/03\/remoteMachineName.png\" alt=\"IntelliSense in launch.vs.json prompts you with all of your existing connections defined in the Connection Manager.\" width=\"415\" height=\"91\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/03\/remoteMachineName.png 415w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2020\/03\/remoteMachineName-300x66.png 300w\" sizes=\"(max-width: 415px) 100vw, 415px\" \/><\/p>\n<p>There are several other (optional) deployment settings that can be used to configure the separation of build and debug listed in our <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/configure-cmake-debugging-sessions?view=vs-2019#deployment-options\">documentation<\/a>.<\/p>\n<p><strong>I want to interact directly with the underlying debugger. Can I do this?<\/strong><\/p>\n<p>Visual Studio allows you to <a href=\"https:\/\/github.com\/microsoft\/MIEngine\/wiki\/Executing-custom-gdb-lldb-commands\">execute custom gdb commands<\/a> via the Command Window. To do so,<\/p>\n<ul>\n<li>View &gt; Other Windows &gt; Command Window<\/li>\n<li>Run: Debug.MIDebugExec insert-your-gdb-command-here<\/li>\n<\/ul>\n<p><strong>I\u2019m debugging with gdb or gdbserver and something isn\u2019t working. How can I troubleshoot?\u00a0 <\/strong><\/p>\n<p>You can <a href=\"https:\/\/github.com\/microsoft\/MIEngine\/wiki\/Logging\">enable logging<\/a> to see what commands we are sending to gdb, what output gdb is returning, and how long each command took.<\/p>\n<ul>\n<li>View &gt; Other Windows &gt; Command Window<\/li>\n<li>Run: Debug.MIDebugLog (\/On[:&lt;filename&gt;] | \/Off) [\/OutputWindow]<\/li>\n<\/ul>\n<p>Options:<\/p>\n<ul>\n<li>\/On[:] \u2013 Turn on MIEngine logging. Optionally specify a file to contain the log. Either the file must be supplied, or the \u201c\/OutputWindow\u201d option must appear.<\/li>\n<li>\/Off &#8212; Turn off MIEngine logging. If logging to a file, the file is closed.<\/li>\n<li>\/OutputWindow &#8212; Log to the \u201cDebug\u201d pane in the output Window.<\/li>\n<\/ul>\n<h4>Give us your feedback<\/h4>\n<p>Download <a href=\"https:\/\/visualstudio.microsoft.com\/downloads\/\">Visual Studio 2019 version 16.6 Preview 2<\/a> today and give it a try. We\u2019d love to hear from you to help us prioritize and build the right features for you. We can be reached via the comments below,\u00a0<a href=\"https:\/\/developercommunity.visualstudio.com\/spaces\/8\/index.html\">Developer Community<\/a>, email (<a href=\"mailto:visualcpp@microsoft.com\">visualcpp@microsoft.com<\/a>), and Twitter (<a href=\"https:\/\/twitter.com\/visualc\">@VisualC<\/a> and <a href=\"https:\/\/twitter.com\/erikasweet_\">@erikasweet_<\/a>). The best way to file a bug or suggest a feature is via Developer Community.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 [&hellip;]<\/p>\n","protected":false},"author":2953,"featured_media":25795,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[270,1,266,279],"tags":[],"class_list":["post-25804","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-announcement","category-cplusplus","category-cmake","category-linux"],"acf":[],"blog_post_summary":"<p>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 [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/25804","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/users\/2953"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/comments?post=25804"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/25804\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/25795"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=25804"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=25804"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=25804"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}