CLion IDE setup¶
This guide describes how to set up Drake in the JetBrains CLion IDE.
It is assumed that
Using CLion with CMake¶
(We recommend using Bazel rather than CMake; see instructions below. CAUTION: the Bazel plugin does not necessarily work with the latest CLion. We have tested it up to CLion 2016.3.5 and it does not currently work with CLion 2017.1.)
- Go to https://www.jetbrains.com/clion/download/. Download the latest version of CLion. For OSX, choose the version with bundled custom JDK.
- Install CLion. Exact steps depend on your platform, but it’s straightforward. Just using defaults for everything is fine. You now have a 30-day trial version of CLion. Either try it out as is, or get a free academic license here.
Setting up Drake in CLion¶
We’ll set up CLion to build Drake only. The dependencies will just be built
from the command line. It is assumed Drake was cloned into a
directory as described in the installation instructions.
- Build Drake from the command line.
- In the Welcome to CLion screen, click
Import Project from Sources. Or from the menu
File > Import Project...
- Browse and select
drake-distro/drakeand click OK.
- When asked whether to overwrite the existing
CMakeLists.txt, just click
- Go to CLion Preferences (on OSX,
CLion-EAP > Preferences, on Ubuntu,
File > Settings...). Note that this preferences window comprises both global settings and project-specific settings (as noted by the text ‘for current project’ on some of the preference pages).
- Browse to
Build, Execution, Deployment > CMake.
CMake Options, fill in
- [This step only for Ubuntu 14.04 - Trusty]. Under
CMake Optionsexpand the tab
Pass system environment. Add the following environment variables. (You can copy these from this documentation one at a time and click on the
pastebutton at the right of the environment variables dialog.)
- Click OK. CLion will take about a minute to reload the CMake Project. If everything is in order, there should be no errors or warnings. For fun, check out the cache pane in the CMake tool window (the CMake icon in the lower left corner of the workspace); it’s pretty handy.
- If CLion asks you about unregistered VCS roots, you can just add them.
To build Drake (and only Drake, this assumes that dependencies were already built!):
- Go to Run > Edit Configurations.
- Select ‘Build All’ and click OK.
- Click Run > Build (or use the keyboard shortcut).
Note that it’s possible to select any CMake target you want from the Edit Configurations menu. This can come in very handy when you want to quickly iterate on a e.g. a specific executable without building all of Drake all the time.
Running a C++ executable¶
- Go to Run > Run...
- Click an executable, or start typing to find your favorite executable and hit enter.
Debugging .mex functions in OSX¶
- Go to Run > Edit Configurations
- Click the + in the top left corner to create a new Run/Debug Configuration.
- Name it Matlab
- Use All targets as the Target
- For Executable, click on the drop-down menu, scroll all the way down and click Select Other...
- Browse to your Matlab executable. For OSX you can just use Applications/MATLAB_R2014a.app or something similar.
- As the working directory, use
- Under Environment Variables, add a variable GRB_LICENSE_FILE and set it to the absolute path of your Gurobi license file. If you don’t do this, Gurobi will not be able to find the license file since Gurobi relies on either the GRB_LICENSE_FILE or the HOME environment variable (if the license file is in the default location) to find it.
- Leave everything else as is. Click OK to save the Run/Debug Configuration.
- Click Run > Debug Matlab.
- Once CLion is done building and you’re in the Debug pane, click the Debugger tab and then the LLDB subtab.
- Enter the following:
process handle -p true -n false -s false SIGSEGV SIGBUS(taken from http://www.mathworks.com/help/matlab/matlab_external/debugging-on-mac-platforms.html) and hit enter.
- Click Resume Program (play button) twice. Matlab should start up. Once it’s started, you can run whatever Matlab code you like. You can set breakpoints in the C++ code in CLion, and if that code is called from Matlab and the breakpoint is hit, you’ll be able to step through in CLion and inspect variables.
Note: if Matlab asks for activation, you’ll need to copy the license (.lic) file from ~/.matlab/R2014b_licenses (or whatever version of Matlab you have) to the licenses subfolder of your Matlab installation (e.g. /Applications/MATLAB_R2014b.app/licenses). If the licenses subfolder does not exist, create it.
Using CLion with Bazel¶
(See note above about CLion versions compatible with Bazel.)
First, install Bazel and build Drake with Bazel, following the Drake Bazel instructions.
A Note About Environment Variables¶
CLion forwards environment variables to the processes it launches, including
the Bazel client and server. We have a number of Bazel repository rules that
consult environment variables, especially
PATH, to locate external
dependencies. Therefore, some care is necessary to make sure CLion is launched
with the environment you actually want!
Ubuntu users will generally get good behavior by default, because
installs binaries in reasonable, standard paths, and because most CLion launch
mechanisms will have already sourced the
.bashrc. Do be careful that
ccache is not on your
PATH, though. If you launch CLion with
PATH, and then CLion launches a Bazel server, you’ll need to quit
CLion, kill the Bazel server, and run
bazel clean to recover.
OS X users will get broken behavior by default. When you run an OS X app
graphically, the parent process is launchd (PID 1), which provides its own
standard environment variables to the child process. In particular, it provides
PATH that does not include
/usr/local/bin, where most Homebrew
executables are installed. Consequently, the Bazel build will fail to find
Homebrew dependencies like
The simplest solution is not to launch CLion graphically. Instead, configure
your shell environment properly in
.bashrc, and launch CLion from the
If you strongly prefer clicking on buttons, you might be able to configure the
launchd environment using
launchctl, but this process is finicky. We
have no reliable recipe for it yet.
Installing the Bazel Plugin¶
To use Bazel in CLion, you must install a plugin supplied by Google. The plugin
requires CLion 2016.3 or later. To install the plugin, open
File > Settings, select
Plugins, and press the
button. Locate and install the
CLion with Bazel plugin. You will be
prompted to restart CLion.
Setting up Drake in CLion¶
CLion will invoke Bazel to build Drake, including the external dependencies specified in the WORKSPACE file.
File > Import Bazel Project
- Select Workspace: Use an existing Bazel workspace, and provide the path to
- (Sometimes) Select Bazel Executable: If prompted, specify the path to your Bazel executable. The default is probably correct.
- Select Project View: choose “Import from workspace”, and
select the file
- Project View: Pick a
project data directoryof your choice for the CLion project files. It must not be a subdirectory of
- (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, building symbols, and compiling Drake. This will take several minutes.
Building and Running Targets¶
To build all of Drake with default Bazel options, select
Bazel > 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 Bazel
Target expression specifies the actual code (library, binary,
and/or test) that you want to run. To learn more about target expressions, see
the Bazel manual.
Once you’ve created a configuration, you can launch it from the
To run a specific target in the debugger, create a configuration as above,
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, select
Bazel > Sync Project With BUILD Files.
CLion provides a user interface for Git, which you can enable in the
menu. It automatically detects all Git roots within the workspace. This will
bazel-drake-distro, which is a Bazel-internal detail. Bazel edits
the contents of that directory for its own purposes, and those changes will
spuriously appear in the CLion UI as changes that need to be committed. To make
bazel-drake-distro, enable Git integration under the
tab, then go to
File > Settings. Select the
Version Control menu item
directly (not one of the subtopics displayed when that item is expanded). You
will see a list of all the Git root directories. Look for
on that list and select it. On the right hand side are
- to remove the spurious root directory. After that you should be
able to go to
VCS > Commit Changes and there should be no changes seen.
Integrating External Tools with CLion¶
Code formatter settings¶
- Make sure you have installed
clang-format(see Tools for Code Style Compliance)
- Go to File > Settings > Tools > External Tools
- Add an entry for clang-format with
- Parameters (whole file):
- Parameters (current selection only):
-lines $SelectionStartLine$:$SelectionEndLine$ -i $FileName$
- Working directory :
Choose one or the other of the parameter settings. Now you can run this (manually) on any file using Tools > External Tools in the drop down menu. You can also add a keyboard shortcut.
You can also set the coding style 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
Integrating Cpplint in CLion¶
This will give you the ability to execute
cpplint on a single file or the full
project and have the result presented in the CLion console with each warning
a clickable hyperlink.
(These instructions assume you are using CLion with Bazel, as you should be. They are slightly different for CMake project organization.)
Creating the External Tools¶
Cpplint on Single File¶
Open the Settings dialog (
Click the + sign to add a new tool.
Add the following values in the following fields:
Apply cpplint to the current file.
Working directory: <empty> (CLion may set this; if so leave it.)
Make sure that only the following Options are checked (the
Synchronize files after executionis unnecessary because cpplint is a read-only operation):
Click the + sign to add a filter.
Add the following values in the following fields (and click “OK):
Convert file/line references into clickable links.
Regular expression to match output:
CppLint on Full Project¶
Repeat the steps from creating the single-file version with the following differences:
Set the fields as follows:
Apply cpplint to the entire project.
Parameters: <empty> Working directory: <empty> (CLion may set this; if so leave it.)
Continue on with steps 5 to the end.
The external tools you’ve created can be exercised in one of several ways, depending on whether you’re doing a single-file or full-project operation.
To check a single file, select the file that you want to be worked on to be “active”. This can be done by clicking on the file so the cursor lies in the file, or by clicking on the file’s tab. The path to the active file will be displayed in the title bar.
Once the file is “active”, the
Cpplint File External Tool can be invoked
in two ways:
- Right-click on the document (or tab) and select
Cpplint File, or
- in the menu bar, select
To check the whole project, in the menu bar, select
External Tools >
Cpplint Project. Alternatively, this can also be
done through the right-click context menu.