EVERY SETUP STEP IN THIS DOCUMENT IS CRITICAL TO GET CLION WORKING PROPERLY.Read carefully, and do not skip anything.
The Bazel plugin for CLion does not support macOS, perhttps://github.com/bazelbuild/intellij/issues/109
I like including the Fedora version in the container in the port so that I can have multiple versions at the same time and don't have to remove lines in /.ssh/knownhosts on container upgrades. NB: Due to container limitations, interactive sessions won't work. Exit the toolbox. You can now run the server with a toolbox run sudo /usr/sbin/sshd.
This guide describes how to set up Drake in the JetBrains CLion IDE on Ubuntu.
First, you must install Bazel and build Drake with Bazel, followingthe Drake Bazel instructions.
To use Drake with CLion, your Drake checkout must be named drake
.
- I'll be showing you one of the many methods of installing Clion on a fedora workstation and get you up and coding in a matter of minutes. Here is a quick run down of the installation steps: Get the CLion archive.
- Step-by-step - CLion IDE Fedora 34 Installation Guide. Posted by just now. Step-by-step - CLion IDE Fedora 34 Installation Guide.
Installing CLion
- Go to https://www.jetbrains.com/clion/download/. Look for 'Other versions'and download the appropriate version of CLion (see below).
- Install CLion. Exact steps depend on your platform, but it'sstraightforward. Just using defaults for everything is fine. You now have a30-day trial version of CLion. Either try it out as is, or get a freeacademic license here.
The most recent versions that we have tested for compatibility are:
- Ubuntu 18.04
- Bazel 3.0.0 (6 April 2020)
- CLion 2019.3.6 (5 May 2020) with:
- Bazel plugin 2020.06.01.1.0 (15 June 2020).
Many versions of the above (Bazel / CLion / Bazel plugin) are not compatiblewith each other. We strongly suggest using only the versions shown above, whenworking with Drake.
Upgrading CLion
Users upgrading from a previous version of CLion should do the following:
- To have your Unity launcher CLion icon point to the correct version,run
locate jetbrains-clion.desktop
and edit the located file. If morethan one file is located, you may want to consolidate to a single launch filein your user directory, typically~/.local/share/applications
. - Uninstall the previous version of the Bazel plugin and update to the latestversion. See Installing the Bazel Plugin.
Note: It is not necessary to import your project into a new CLion project.Overwriting the old project is appropriate.
Installing the Bazel Plugin
To use Bazel in CLion, you must install a plugin supplied by Google. Toinstall the plugin, open Settings
(either Welcome > Configure >Settings
or File > Settings
), select Plugins
, and press the Browserepositories
button. Locate and install the Bazel
plugin. You will beprompted to restart CLion.
To use Drake in CLion you must use Drake's bazel wrapper.Open Settings > Bazel Settings
. For Bazel binary location
select thepath to drake/tools/clion/bazel_wrapper
from any recent Drake source tree(it doesn't have to match the current project open in CLion).
Setting up Drake in CLion
CLion will invoke Bazel to build Drake, including the external dependenciesspecified in the WORKSPACE file.
File > Import Bazel Project
- Select Workspace: Use an existing Bazel workspace, and provide the path toyour
drake
directory. - Select Project View: choose 'Import project view file', andselect the file
drake/.bazelproject
- Project View: Pick a
project data directory
of your choice for theCLion project files. It must not be a subdirectory ofdrake
. - (Advanced) Project View: If you only wish to develop a subset of Drake,you can specify only those files and targets in the project view file.Most users should leave it as-is.
- Click 'Finish'. CLion will begin ingesting the Drake source, buildingsymbols, and compiling Drake. This will take several minutes.
Building and Running Targets
To build all of Drake with default Bazel options, selectBazel > Build > Compile Project
.
To build or run a specific target go to Run > Edit Configurations
. Click+
to create a new Bazel command. Specify the configuration name and Bazeloptions. The Target expression
specifies the actual code (library, binary,and/or test) that you want to run. To learn more about target expressions, seethe Bazel manual.Once you've created a configuration, you can launch it from the Run
menu.
To run a specific target in the debugger, create a configuration as above,using the bazel run
command. Then launch it from Run > Debug
.
Keeping CLion Up-to-Date with the Bazel Build
Changes to BUILD files can add or remove source files from the Bazel build.To propagate those changes into the CLion project structure, selectBazel > Sync Project With BUILD Files
.
Git Integration
CLion provides a user interface for Git, which you can enable in the VCS
menu. It automatically detects all Git roots within the workspace. This willinclude bazel-drake
, which is a Bazel-internal detail. Bazel editsthe contents of that directory for its own purposes, and those changes willspuriously appear in the CLion UI as changes that need to be committed. To makeCLion ignore bazel-drake
, enable Git integration under the VCS
tab, then go to File > Settings
. Select the Version Control
menu itemdirectly (not one of the subtopics displayed when that item is expanded). Youwill see a list of all the Git root directories. Look for bazel-drake
on that list and select it. On the right hand side are +
and -
buttons;click -
to remove the spurious root directory. After that you should beable to go to VCS > Commit Changes
and there should be no changes seen.
CLion provides a mechanism for invoking external binaries/scripts/etc. withparameters derived from the CLion GUI. Below, we outline a number of commontools to aid with compliance with the Drake style guide. The work to createa new external tool is the same in all cases; only the specific tool settingsdiffer from tool to tool. We'll outline the general work here and provideper-tool details below. The GUI description applies to version 2018.1.6 andmay be slightly different in previous versions.
- Open the Settings dialog (
File
>Settings
) orAlt+Ctrl+S
. - Navigate to
Tools
>External Tools
. - Click the + sign to add a newtool.
- Set the appropriate fields in the
Edit Tool
. See the following tools fordetails. - Click
Ok
.
There are several ways to use an External Tool. One is to right-click on afile and select External Tools
> Tool Name
. Another is to selectTools
> External Tools
> Tool Name
. For tools that operate on aselected file, make sure that file is 'active' by clicking on it. TheTool Name
will be the value set in the Name
field outlined below.
Formatting files
You can use clang format to modify the formatting of your file in the GUI. We'llintroduce three variants:
- Apply clang-format to a whole file.
- Apply clang-format to selected lines.
- Apply clang-format to correct
#include
ordering.
These tools modify the selected file. There is a synchronization issue withCLion such that the modification may not be immediately apparent. When in doubt,select away from the target file and back; this will cause the file to refreshand you can confirm that the file has been modified as expected.
First, make sure you have installed clang-format-9
(see Tools for Code Style Compliance).
Clang format selected file
Open the Edit Tool
for external tools as outlined above and enter thefollowing values for the fields:
- Name:
Clang Format Full File
- Description:
Apply clang-format to the active file
- Program:
clang-format-9
- Arguments:
-i $FileName$
- Working directory:
$FileDir$
- Advanced Options: Uncheck
Open console for tool output
Leave the checkbox options in their default state.
Clang format selected lines
Open the Edit Tool
for external tools as outlined above and enter thefollowing values for the fields:
Clion Fedora Men
- Name:
Clang Format Selected Lines
- Description:
Apply clang-format to the selected lines
- Program:
clang-format-9
- Arguments:
-lines $SelectionStartLine$:$SelectionEndLine$ -i $FileName$
- Working directory:
$FileDir$
- Advanced Options: Uncheck
Open console for tool output
Leave the checkbox options in their default state.
Correct #include ordering
Open the Edit Tool
for external tools as outlined above and enter thefollowing values for the fields:
- Name:
Clang Format Include Ordering
- Description:
Runs the clang format for correcting includes on the current file
- Program:
bazel
- Arguments:
run //tools/lint:clang-format-includes -- $FilePath$
- Working directory:
$Projectpath$
- Advanced Options: Uncheck
Open console for tool output
Leave the checkbox options in their default state.
'Linting' files
'Linting' refers to using tools to find aspects of code which don't conformto specified coding practices. You can apply Drake's linting tools in CLion tofind such issues. We'll define two tools:
- General linting (via cpplint) which captures most of the Drake style guide.
- Drake extended linting which captures aspects of the Drake style guide notcaptured by the general linting tool. This includes detecting out-of-order
#include
directives.
These tools produce reports. In some cases, the reports can be automaticallyconverted into clickable links so that you can click on a message and be takento the file and line indicated in the message. The configuration instructionsinclude the details of how to configure these clickable links.
You can also set the general coding style for CLion through the following steps
- Go to
File
>Settings
>Editor
>Code Style
- On the right panel, Go to
Default Options
>Right margin (columns)
:Set it to 80 - Go to
File
>Settings
>Editor
>Code Style
>C/C++
- On the right panel, choose
Set from
>Predefined Style
>Google
Lint selected file for google style guide
Open the Edit Tool
for external tools as outlined above and enter thefollowing values for the fields:
- Name:
Cpplint File
- Description:
Apply cpplint to the current file
- Program:
bazel
- Arguments:
run @styleguide//:cpplint -- --output=eclipse $FilePath$
- Working directory:
$Projectpath$
- Advanced Options: Confirm
Open console for tool output
is checked
To configure the clickable links, enter the following string in the AdvancedOptions
> Output filters
window:
$FILE_PATH$:$LINE$
Lint selected file for Drake style addenda
This tool is a supplement to the google style cpplint. It tests for additionalstyle requirements which are otherwise missed by the general tool. The primaryreason to run this is to confirm that the order of the #include
statementsis correct.
Open the Edit Tool
for external tools as outlined above and enter thefollowing values for the fields:
- Name:
Drake Lint File
- Description:
Apply drake lint to the current file
- Program:
bazel
- Arguments:
run //tools/lint:drakelint -- $FilePath$
- Working directory:
$Projectpath$
- Advanced Options: Confirm
Open console for tool output
is checked
In the event of finding a lint problem (e.g., out-of-order include files), theCLion output will contain a single clickable link. This link is only thefirst error encountered in the include section; there may be more. The linkmerely provides a hint to the developer to see the problem area. Rather thanfixing by hand, we strongly recommend executing the Clang Format IncludeOrdering
external tool on the file.
Alternative linting configuration
The linting tools have been configured to use the bazel system. The advantage indoing so is that it guarantees that the tools are built prior to being used.However, bazel only allows one instance of bazel to run at a time. For example,if building Drake in a command-line window, it would be impossible to lint filesat the same time.
The work around is to change the configurations to execute the binariesdirectly. This approach generally works but will fail if the corresponding bazeltargets have not been built. The tools would need to be built prior toexecution.
With this warning in place, you can make the following modifications to thelinting tools to be able to lint and compile simultaneously.
Google style guide linting
Change the following fields in the instructions given above:
- Program:
bazel-bin/external/styleguide/cpplint_binary
- Arguments:
--output=eclipse $FilePath$
Building the google styleguide lint tool:
bazel build @styleguide//:cpplint
Drake style addenda
Change the following fields in the instructions given above:
- Program:
bazel-bin/tools/lint/drakelint
- Arguments:
$FilePath$
Building the drake addenda lint tool:
bazel build //tools/lint:drakelint
Apparently CLion (or perhaps the Bazel plugin) has a certain amount ofauto-configuration of run/debug targets. It appears to hinge on the presence ofthe gtest.h header in source files. This is convenient, but only furthermystifies the process of debugging a non-gtest program. This section explainshow to configure debugging support for arbitrary programs in a Drake/CLionproject.
This section assumes all of the Drake-recommended installation andconfiguration is done.
Get the bazel target string
Find the source file of the program in the file tree view. Right-click on thefile, and select 'Copy BUILD Target String'. This will put the Bazel targetname into the clipboard.
Clion Fedora Cap
Start a run configuration
In the event of finding a lint problem (e.g., out-of-order include files), theCLion output will contain a single clickable link. This link is only thefirst error encountered in the include section; there may be more. The linkmerely provides a hint to the developer to see the problem area. Rather thanfixing by hand, we strongly recommend executing the Clang Format IncludeOrdering
external tool on the file.
Alternative linting configuration
The linting tools have been configured to use the bazel system. The advantage indoing so is that it guarantees that the tools are built prior to being used.However, bazel only allows one instance of bazel to run at a time. For example,if building Drake in a command-line window, it would be impossible to lint filesat the same time.
The work around is to change the configurations to execute the binariesdirectly. This approach generally works but will fail if the corresponding bazeltargets have not been built. The tools would need to be built prior toexecution.
With this warning in place, you can make the following modifications to thelinting tools to be able to lint and compile simultaneously.
Google style guide linting
Change the following fields in the instructions given above:
- Program:
bazel-bin/external/styleguide/cpplint_binary
- Arguments:
--output=eclipse $FilePath$
Building the google styleguide lint tool:
bazel build @styleguide//:cpplint
Drake style addenda
Change the following fields in the instructions given above:
- Program:
bazel-bin/tools/lint/drakelint
- Arguments:
$FilePath$
Building the drake addenda lint tool:
bazel build //tools/lint:drakelint
Apparently CLion (or perhaps the Bazel plugin) has a certain amount ofauto-configuration of run/debug targets. It appears to hinge on the presence ofthe gtest.h header in source files. This is convenient, but only furthermystifies the process of debugging a non-gtest program. This section explainshow to configure debugging support for arbitrary programs in a Drake/CLionproject.
This section assumes all of the Drake-recommended installation andconfiguration is done.
Get the bazel target string
Find the source file of the program in the file tree view. Right-click on thefile, and select 'Copy BUILD Target String'. This will put the Bazel targetname into the clipboard.
Clion Fedora Cap
Start a run configuration
From the top menu, select 'Run/Edit Configurations…'. Select the '+' at theupper left of the dialog to add a new configuration. From the list, select'Bazel Command'.
Clion Fedora Hat
Fill in the configuration
Now it's time to fill in the new blank configuration. Give it a name, thenselect the '+' at the right side to add the target expression. Once the editbox appears, paste the contents of the clipboard there. Hit 'Enter' or 'Tab' toconfirm the setting; a port number value should appear in the 'Port number'field below. In 'Bazel command', select either 'run' (for an arbitraryprogram), or 'test' (for a Bazel test target). Everything else can be left atdefault values. Click OK to finish.
Launch the debugger
At this point, the top menu 'Run' should have entries to run or debug the newconfiguration. Select the debug entry there, or use the controls at the upperright to launch the debugger.
Hello fellow developers. I'll be showing you one of the many methods of installing Clion on a fedora workstation and get you up and coding in a matter of minutes.
Here is a quick run down of the installation steps:
- Get the CLion archive
- Extract the files
- Place extracted CLion folder in an easily accessible location
- Create a launcher
Lets begin!
Download CLion: CLion – Download
Extract the archive with your favorite tool. I will demonstrate this with two tools: the builtin Archive Manager from Fedora and the terminal tool tar.
Terminal
Note: Please be mindful of the archive name and version. It may be different from my version.
Terminal Extraction
Built-In Archive Manager (Simple!)
Save the file wherever you want. Some of my colleagues at work create a .clion folder in their home directory; I much prefer to create a folder in the home directory named Tools then move the extracted folder there. I move lots of tools to the directory such as GitKranken, Eclipse, QT, etc…
Clion Fedora
Okay. The extraction is complete now we need to move the folder. You can do this in the Terminal or the UI cut and paste the extracted clion folder into Tools directory and you are done. The terminal method is posted bellow.
CLion Download Page
Now comes the fun part adding a launcher icon to the gnome menu. It is much easier to do this with the terminal then using an editor like gedit or something else. I'll be using vim to create the Clion.desktop file and add the necessary entries to have the CLion icon visible on the gnome menu.
Here is what you should write in the CLion.desktop file:
Note: Replace the {username} with your fedora username
Clion Fedora Hats
Now just press the Super key and start typing CLion.
You may need to logout/reboot your system in order form the changes to take effect.
Gnome CLion Icon
If you have any questions or suggestion please leave a comment bellow. Best of luck and happy coding!