{"id":28300,"date":"2021-07-14T18:58:54","date_gmt":"2021-07-14T18:58:54","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cppblog\/?p=28300"},"modified":"2021-11-22T22:20:37","modified_gmt":"2021-11-22T22:20:37","slug":"build-and-debug-c-with-wsl-2-distributions-and-visual-studio-2022","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cppblog\/build-and-debug-c-with-wsl-2-distributions-and-visual-studio-2022\/","title":{"rendered":"Build and Debug C++ with WSL 2 Distributions and Visual Studio 2022"},"content":{"rendered":"<p><div  class=\"d-flex justify-content-center\"><a class=\"cta_button_link btn-primary mb-24\" href=\"https:\/\/aka.ms\/vs2022preview\" target=\"_blank\">Download Visual Studio 2022 Preview<\/a><\/div>\nVisual Studio 2022 introduces a native WSL 2 toolset for C++ development. This toolset is available now in <a href=\"https:\/\/visualstudio.microsoft.com\/vs\/preview\/vs2022\/\">Visual Studio 2022 version 17.0 Preview 2<\/a>. WSL 2 is the new, recommended version of the <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/wsl\/about\">Windows Subsystem for Linux (WSL)<\/a> architecture that provides better Linux file system performance, GUI support, and full system call compatibility. Visual Studio\u2019s WSL 2 toolset allows you to build and debug C++ code on WSL 2 distros from Visual Studio without ever adding an SSH connection. You can already build and debug C++ code on WSL 1 distros using the <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/c-with-visual-studio-2019-and-windows-subsystem-for-linux-wsl\/\">native WSL 1 toolset<\/a> introduced in Visual Studio 2019 version 16.1.<\/p>\n<div style=\"text-align: center;\"><iframe src=\"\/\/www.youtube.com\/embed\/IKI2w75aAow\" width=\"560\" height=\"314\" allowfullscreen=\"allowfullscreen\"><\/iframe><\/div>\n<p>&nbsp;<\/p>\n<p>Visual Studio\u2019s WSL 2 toolset supports both CMake and MSBuild-based Linux projects. However, CMake is our recommendation for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems.<\/p>\n<h4>How does the WSL 2 toolset work?<\/h4>\n<p>Our C++ cross-platform support in Visual Studio assumes that all source files originate in the Windows file system. When targeting a WSL 2 distro, Visual Studio will execute a local rsync copy to copy files from the Windows file system to the WSL file system. This local rsync copy will occur automatically when Visual Studio detects that you are using a WSL 2 distro and will require no user intervention. See <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/wsl\/compare-versions\">Comparing WSL 1 and WSL 2<\/a> to learn more about the differences between WSL 1 and WSL 2.<\/p>\n<p>Continue reading for a step-by-step guide on getting started with CMake and WSL 2 and an overview of our MSBuild-based WSL 2 support.<\/p>\n<h4>Cross-platform CMake development with a WSL 2 distro<\/h4>\n<p>The WSL 2 toolset is supported by our CMake Presets integration in Visual Studio. You can learn more about CMake Presets in our <a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/cmake-presets-integration-in-visual-studio-and-visual-studio-code\/\">announcement blog post<\/a> and <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/cmake-presets-vs?view=msvc-160\">documentation<\/a>. Follow the instructions below to build and debug a CMake project on a WSL 2 distro.<\/p>\n<p>1. Install WSL and a WSL 2 distro with the <a href=\"https:\/\/docs.microsoft.com\/en-us\/windows\/wsl\/install-win10\">Windows Subsystem for Linux Installation Guide for Windows 10<\/a>.<\/p>\n<p>2. Install the required build tools on your WSL 2 distro. You will need a C++ compiler, gdb, CMake, an underlying build system generator, rsync, and zip. You can install these dependencies on distros that use apt with the following commands:<\/p>\n<div style=\"text-align: center;\">\n<pre class=\"prettyprint\">sudo apt update\r\nsudo apt install g++ gdb make ninja-build rsync zip<\/pre>\n<\/div>\n<p>In this tutorial I\u2019ll use GCC and Ninja on Ubuntu. I will install a recent version of CMake using Visual Studio\u2019s CMake binary deployment in step 9.<\/p>\n<p>3. Open a CMake project in Visual Studio 2022 version 17.0 Preview 2 or later. Visual Studio defines a CMake project as a folder with a CMakeLists.txt file at the project root. You can either clone a CMake repository (like <a href=\"https:\/\/github.com\/esweet431\/bullet3\">bullet3<\/a>), open a local CMake project, or create a new CMake project with the CMake Project template. In this tutorial I\u2019m going to create a new CMake project with the CMake Project template.\n<a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/get-started.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28301\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/get-started.png\" alt=\"The &quot;Get started&quot; menu in the Visual Studio Installer. Options are &quot;Clone a repository&quot;, &quot;Open a project or solution&quot;, &quot;Open a local folder&quot;, or &quot;Create a new project&quot;.\" width=\"384\" height=\"417\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/get-started.png 384w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/get-started-276x300.png 276w\" sizes=\"(max-width: 384px) 100vw, 384px\" \/><\/a>\n4. Enable Visual Studio\u2019s CMake Presets integration. You can add a CMakePresets.json file to the root of the project or enable the integration globally in <strong>Tools &gt; Options &gt; CMake &gt; General<\/strong>. You must close and reopen the folder in Visual Studio to activate the integration. See <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/cmake-presets-vs?view=msvc-160#enable-cmakepresetsjson-integration-in-visual-studio-2019\">Enable CMake Presets integration<\/a> for more information.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/enable-cmakepresets.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28302\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/enable-cmakepresets.png\" alt=\"An image of the checkbox to enable CMake Presets integration in Tools &gt; Options &gt; CMake &gt; General in Visual Studio. The option to &quot;Prefer using CMake Presets for CMake configure, build, and test&quot; is checked and highlighted red.\" width=\"732\" height=\"248\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/enable-cmakepresets.png 732w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/enable-cmakepresets-300x102.png 300w\" sizes=\"(max-width: 732px) 100vw, 732px\" \/><\/a><\/p>\n<p>5. You should now see three dropdowns across the menu bar. Use the dropdown on the left to select your active Target System. This is the system where CMake will be invoked to configure and build the project. Visual Studio queries for WSL installations with <strong>wsl -l -v<\/strong>. In the example below, my Target System is <strong>WSL2: Ubuntu-20.04.<\/strong><\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/target-system.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28303\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/target-system.png\" alt=\"An image of the Target System dropdown in Visual Studio. The options are &quot;Local Machine&quot;, &quot;172.26.1.64&quot;, &quot;WSL2: Ubuntu-20.04&quot; and &quot;WSL1: Debian&quot;. &quot;WSL2: Ubuntu-20.04&quot; is selected.\" width=\"737\" height=\"165\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/target-system.png 737w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/target-system-300x67.png 300w\" sizes=\"(max-width: 737px) 100vw, 737px\" \/><\/a><\/p>\n<p>Note: If Visual Studio starts to configure your project automatically, read step 9 to manage CMake binary deployment and then return to step 6. See <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/cmake-presets-vs?view=msvc-160#modify-automatic-configuration-and-cache-notifications\">Modify automatic configuration and cache notifications<\/a> to customize this behavior.<\/p>\n<p>6. Use the dropdown in the middle to select your active Configure Preset. Configure Presets tell Visual Studio how to invoke CMake and generate the underlying build system. In the example in Step 5 (above), my active Configure Preset is the <strong>linux-default<\/strong> Preset created by Visual Studio. If you want to create a custom Configure Preset, select <strong>Manage Configurations\u2026<\/strong>. See <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/cmake-presets-vs?view=msvc-160#select-a-configure-preset\">Select a Configure Preset<\/a> and <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/cmake-presets-vs?view=msvc-160#edit-presets\">Edit Presets<\/a> for more information.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/manage-configs.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28304\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/manage-configs.png\" alt=\"An image of the Configure Preset dropdown. The only option is &quot;linux-default&quot;, which is selected.\" width=\"210\" height=\"92\" \/><\/a><\/p>\n<p>7. Use the dropdown on the right to select your active Build Preset. Build Presets tell Visual Studio how to invoke build. In the example in Step 5 (above), my active Build Preset is the <strong>Default <\/strong>Preset created by Visual Studio. See <a href=\"https:\/\/docs.microsoft.com\/en-us\/cpp\/build\/cmake-presets-vs?view=msvc-160#select-a-build-preset\">Select a Build Preset<\/a> for more information.<\/p>\n<p>8. Configure the project on WSL 2. If project generation does not start automatically, then you can manually invoke configure with <strong>Project &gt; Configure &lt;project-name&gt;<\/strong>.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/manual-generation.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28305\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/manual-generation.png\" alt=\"An image of the Project menu in Visual Studio. &quot;Configure CMakeProject&quot; is selected.\" width=\"307\" height=\"223\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/manual-generation.png 307w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/manual-generation-300x218.png 300w\" sizes=\"(max-width: 307px) 100vw, 307px\" \/><\/a><\/p>\n<p>9. If you do not have a supported version of CMake installed on your WSL 2 distro, then Visual Studio will prompt you to deploy a recent version of CMake. Select \u201cYes\u201d to deploy CMake binaries to your WSL 2 distro.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/binary-deployment.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28306\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/binary-deployment.png\" alt=\"Image binary deployment\" width=\"757\" height=\"95\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/binary-deployment.png 757w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/binary-deployment-300x38.png 300w\" sizes=\"(max-width: 757px) 100vw, 757px\" \/><\/a><\/p>\n<p>10. Confirm that the configure step has completed and that you can see the <strong>CMake generation finished<\/strong> message in the CMake pane of the Output Window. Note that build files are written to a directory in the WSL 2 distro\u2019s file system.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/output.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28307\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/output.png\" alt=\"The CMake pane of the Output Window is open in Visual Studio. The last line of output reads &quot;CMake generation finished.&quot;\" width=\"1118\" height=\"309\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/output.png 1118w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/output-300x83.png 300w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/output-1024x283.png 1024w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/output-768x212.png 768w\" sizes=\"(max-width: 1118px) 100vw, 1118px\" \/><\/a><\/p>\n<p>11. Select the active debug target. The debug dropdown menu lists all the CMake targets available to the project.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debug-drop.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28308\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debug-drop.png\" alt=\"An image of the debug dropdown menu in Visual Studio. The CMake target &quot;CMakeProject&quot; is selected.\" width=\"300\" height=\"144\" \/><\/a><\/p>\n<p>12. Set a breakpoint. Expand the project subfolder in the Solution Explorer and in the .cpp file set a breakpoint in main(). You can also navigate to CMake Targets View by selecting the View Picker button in the Solution Explorer.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/targets-view.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28309\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/targets-view.png\" alt=\"Image targets view\" width=\"356\" height=\"137\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/targets-view.png 356w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/targets-view-300x115.png 300w\" sizes=\"(max-width: 356px) 100vw, 356px\" \/><\/a><\/p>\n<p>13. Now click \u201cStart\u201d (Debug &gt; Start) or press F5. Your project will build, the executable will launch on your WSL 2 distro, and you will hit your breakpoint. You can see the output of your program (in this case, \u201cHello CMake.\u201d) in the Linux Console Window.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debugging.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28310\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debugging.png\" alt=\"CMakeProject.cpp is open and running under the debugger. A breakpoint is set and hit at line 11. The Linux Console Window is open and reads &quot;Hello CMake.&quot;\" width=\"1170\" height=\"832\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debugging.png 1170w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debugging-300x213.png 300w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debugging-1024x728.png 1024w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/debugging-768x546.png 768w\" sizes=\"(max-width: 1170px) 100vw, 1170px\" \/><\/a><\/p>\n<h4>MSBuild-based Linux development with a WSL 2 distro<\/h4>\n<p>CMake is our recommendation for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems. If you are already using a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in <strong>Property Pages &gt; General &gt; Platform Toolset<\/strong>.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/msbuild.png\"><img decoding=\"async\" class=\"aligncenter size-full wp-image-28311\" src=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/msbuild.png\" alt=\"Property Pages are open in a MSBuild-based Linux project. The &quot;Platform Toolset&quot; option is selected, and &quot;WSL2 Toolset&quot; is the selected value.\" width=\"558\" height=\"162\" srcset=\"https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/msbuild.png 558w, https:\/\/devblogs.microsoft.com\/cppblog\/wp-content\/uploads\/sites\/9\/2021\/07\/msbuild-300x87.png 300w\" sizes=\"(max-width: 558px) 100vw, 558px\" \/><\/a><\/p>\n<h4>Talk to us!<\/h4>\n<p>Our native WSL 2 toolset and CMake Presets integration are still in preview. We\u2019ll continue to address your feedback in future releases of Visual Studio. The best way to file a bug or suggest a feature is with the <strong>Send Feedback<\/strong> button in the upper right-hand corner of the IDE. See <a href=\"https:\/\/docs.microsoft.com\/en-us\/visualstudio\/ide\/feedback-options?view=vs-2019#:~:text=In%20Visual%20Studio%2C%20choose%20the%20feedback%20icon%20in,information%2C%20see%20Suggest%20a%20feature%20for%20Visual%20Studio.\">Visual Studio feedback options<\/a> for more information.<\/p>\n<p>We\u2019d love to learn how your team is adopting our support for WSL 2. If you have feedback or a success story to share, you can contact us at vcpplinux-support@microsoft.com. You can also reach us on Twitter (<a href=\"https:\/\/twitter.com\/visualc\">@VisualC<\/a>).<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Visual Studio 2022 introduces a native WSL 2 toolset for C++ development. This toolset is available now in Visual Studio 2022 version 17.0 Preview 2. WSL 2 is the new, recommended version of the Windows Subsystem for Linux (WSL) architecture that provides better Linux file system performance, GUI support, and full system call compatibility. Visual [&hellip;]<\/p>\n","protected":false},"author":2953,"featured_media":28313,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[270,1,266,279,230],"tags":[],"class_list":["post-28300","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-announcement","category-cplusplus","category-cmake","category-linux","category-new-feature"],"acf":[],"blog_post_summary":"<p>Visual Studio 2022 introduces a native WSL 2 toolset for C++ development. This toolset is available now in Visual Studio 2022 version 17.0 Preview 2. WSL 2 is the new, recommended version of the Windows Subsystem for Linux (WSL) architecture that provides better Linux file system performance, GUI support, and full system call compatibility. Visual [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/28300","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=28300"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/posts\/28300\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media\/28313"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/media?parent=28300"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/categories?post=28300"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cppblog\/wp-json\/wp\/v2\/tags?post=28300"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}