WSL

Configure WSL

1. Download and install a WSL distribution (for instance, Ubuntu) from Microsoft Store.

   For this step, be sure to use Windows 10 with the latest “Fall Creators Update” (minimum version 1709, build 16299.15). See the official guide Install the Windows Subsystem for Linux for instructions.

   To work with WSL 2, your Windows version should be 10 build 18917 or later. Follow these instructions to switch the distributive.

   Note that CLion does not support legacy WSL, which you may have installed before upgrading your system to the build 16299.15 or later of Windows 10. In this case, you need to update your WSL distribution.

2. Run Ubuntu.

   Upon the first launch of Ubuntu, the system may prompt you to enable the Windows optional feature. In this case, you need to do the following:

   • Open Windows PowerShell as Administrator and run

     Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

   • Restart your computer.

3. Set up the WSL Ubuntu environment:

   • Install cmake, gcc, or/and clang (and optionally build-essentials package), as follows:

     sudo apt-get update
     sudo apt-get install cmake gcc clang gdb build-essential

   • Configure and run open ssh-server.

     You can set the configuration manually or by using our script(note that if your Linux distribution is different from Ubuntu, the script might need adjustments). To download and run the script, use the following command line:

     wget https://raw.githubusercontent.com/JetBrains/clion-wsl/master/ubuntu_setup_env.sh && bash ubuntu_setup_env.sh

4. Next, check the ssh connection:

   ssh username@localhost -p2222

   Port number 2222 is valid for our configuration script. If you are not using our script, the port number can be different.

Configure a WSL toolchain for your project

1. In CLion, go to Settings / Preferences | Build, Execution, Deployment | Toolchains and click to create a new toolchain. Select WSL from the Environment list. CLion automatically detects the installed distribution, or you can set the path manually.

   note

   If you specified the path to ubuntu.exe correctly, but CLion still cannot find the executable, the reason might be the WSL issue fixed in Windows 10 version 1803. You need to either update your system to the version 1803 or later, or enable the wsl.close.process.input key in the Registry (go to Help | Find Action, type Registry, and search by the key name).

2. Provide the remote credentials: click the icon and select one the SSH configurations or create a new one.

   In case of unexpected errors, try the troubleshooting instructions.

   

3. Now to start using the toolchain, do one of the following:

   • Set the WSL toolchain as default. This way, it will automatically connect to the default CMake profile.

   • Create a separate CMake profile, connect it to the WSL toolchain, and select this profile in the configurations switcher:

     

tip

In order to run Valgrind on WSL, make sure to select the CMake profile associated with the WSL toolchain. See this instruction for details.

Troubleshooting

• Make sure that two bundled plugins, FTP/SFTP Connectivity and Remote Hosts Data Access, are enabled in Settings / Preferences | Plugins.

• If you get the Credentials are not valid for this WSL distribution error when creating a toolchain, check the value of HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Lxss{ubuntu_id }\BasePath in the Windows Registry Editor (to access it, launch regedit from the Start menu). In case the value contains non-ASCII characters, use the workaround described in this issue.

• Due to the IntelliJ platform issue, there are problems with using WSL file-system which is case-sensitive and Windows file system which is not. As a workaround, you can do the following:

  • Go to Help | Edit Custom Properties menu option and specify

    idea.case.sensitive.fs=true

  • Invalidate caches and restart the IDE using File | Invalidate Caches menu option.

  tip

  If you can’t open the Edit Custom Properties popup from the Welcome screen, open any project and edit properties from Help | Edit Custom Properties main menu option.