Source installation (OS X, Ubuntu)¶

Optional: Setting up the MATLAB Compiler¶

Make sure that the MATLAB executable is in your path. (e.g., typing matlab
at the system command line should start an instance of MATLAB). For example, on Mac you might consider sudo ln -s /Applications/MATLAB_R2014a.app/bin/matlab /usr/bin/matlab, or you can actually add the MATLAB/bin directory to your system path.

Getting Drake¶

Now run:

git clone git@github.com:RobotLocomotion/drake.git drake-distro


Note: the build process may encounter problems if you have unusual characters like parentheses in the absolute path to the drake-distro directory (see #394).

The above git clone command will configure Drake’s primary repository as a remote called origin. We recommend that you configure your fork of Drake’s primary repository as the origin remote and Drake’s primary repository as the upstream remote. This can be done by executing the following commands:

cd drake-distro
git remote set-url origin git@github.com:[your github user name]/drake.git
git remote set-url --push upstream no_push


Mandatory platform specific instructions¶

Before running the build, you must follow some one-time platform-specific setup steps:

Build the collection¶

There are three ways to build Drake:

For instructions on how to switch build systems, see this subsection.

Make support is more mature, but Ninja is faster, more modern, and will receive more investment from the Drake development team going forward.

Build with Make¶

First, confirm that Make is installed on your system by executing:

make --version


To build with Make, execute:

cd drake-distro
mkdir build
cd build
cmake ..
make


Do NOT use sudo. Just make is sufficient, and will prevent problems later. Feel free to use make -j if your platform supports it. Note that the above cmake command does not specify a build type, so drake will be built with Release by default. If you wish to build with a different build type, change the cmake command to cmake .. -DCMAKE_BUILD_TYPE:STRING=Debug to build with build type “Debug”. Alternative build modes include “RelWithDebInfo” and “Release”. They differ in terms of the amount of debug symbols included in the resulting binaries and how efficiently the code executes.

In addition to the build mode, Drake has many other build options. You can view them in drake-distro/CMakeLists.txt. The build options typically start with “WITH_”. The options can be included in the above cmake command by adding additional -D flags. You can also specify them using a text-based GUI by executing:

cd drake-distro/build
ccmake ..


cd drake-distro/build
make VERBOSE=true


Build with Ninja¶

First, confirm that Ninja is installed on your system:

ninja --version


Drake uses CMake to generate Ninja files within an out-of-source build directory. You can configure CMake options by passing them at the cmake command line with -D, or in a GUI by running ccmake instead of cmake. For instance, the following sequence of commands generates Ninja files, and then runs the Ninja build.

cd drake-distro
mkdir build
cd build
cmake .. -G Ninja
ninja


Ninja can rebuild Drake from within drake-distro/build/drake/ without rebuilding the entire super-build. It can also build specific targets. Tab-completion is supported.

cd drake-distro/build/drake
ninja


To review the raw shell commands, compiler flags, and linker flags that CMake generated, consult build.ninja and drake/build.ninja, or run ninja -v for a verbose build.

See:

Locations of Build and Install Directories¶

This section contains information about where Drake’s build artifacts are located. They assume you are following the official from-source build instructions given above. The locations will differ if you’re building Drake using an alternative method, e.g., completely out of source.

Builds based on Make and Ninja place build artifacts in drake-distro/build/. Externally visible build artifacts are placed in drake-distro/build/install.

Builds using ROS Catkin place build artifacts in Catkin’s development space and place externally-visible build artifacts in Catkin’s install space. When following the official Drake/ROS installation instructions, these spaces are typically drake_catkin_workspace/devel and drake_catkin_workspace/install, respectively.

Identifying the Build System Used¶

If you encounter an existing from-source installation of Drake and aren’t sure whether it was built using Make or Ninja, [1] look in drake-distro/build. If there is a file called Makefile, Drake was built using Make. If there is a file called rules.ninja, Drake was built using Ninja.

 [1] ROS Catkin is not listed since you should immediately know if Drake was compiled using ROS Catkin based on whether it is located in a ROS workspace. Once compiled using Catkin, do not attempt to switch build systems.

How to Switch Build Systems¶

To switch between using make vs. ninja, first clean your workspace. Then follow the original build instructions using the desired build system.

First save, commit, and push all of your work. The following commands are destructive.

If you’re using make or ninja, execute:

cd drake-distro
rm -rf build
rm -rf externals
git clean -fdx


If you’re using ROS Catkin, simply execute:

cd drake_catkin_workspace
catkin clean


Start MATLAB, then at the MATLAB prompt do:

cd drake-distro/drake


Then cd into the examples directories and try some things out. Here are a few fun ones to get you started:

• runLQR in the examples/CartPole directory
• runLQR in the examples/Quadrotor2D directory
• RimlessWheelPlant.run() in the examples/RimlessWheel directory
• StateMachineControl.run() in the examples/PlanarMonopodHopper directory

To run some unit tests, execute the following:

cd drake-distro/build/drake
ctest -VV


For more details on how to run Drake’s unit tests, see the instructions here: Detailed Notes on Drake’s Unit Tests.

If you have problems, please check the Frequently Asked Questions. If the solution is not there, or if you discover something missing from our installation instructions or lists of prerequisites, then please file an issue and label it as installation.

Using SNOPT as an external¶

Drake includes support for SNOPT, but is not able to redistribute it directly. To use SNOPT with Drake, you must have access to its private GitHub repository, and you must set up a GitHub SSH key on your machine. Follow the instructions in the GitHub documentation.

This capability is meant for members of MIT Robot Locomotion Group and close collaborators with whom RLG shares licenses.

Using Gurobi as an external¶

Before building Drake with Gurobi, create an account and obtain a license on Gurobi’s website. Download Gurobi 6.0.5, and set the GUROBI_DISTRO environment variable to the absolute path to the downloaded file. Consult Gurobi’s documentation to activate your license; exact procedures depend on license type. Once activated, place your Gurobi license file gurobi.lic in your home directory.

Then enable the CMake option WITH_GUROBI in the Drake superbuild, and proceed to build Drake as usual.

Stay up to date¶

To work on the bleeding edge, do:

cd drake-distro
git checkout master
git pull upstream master
cd build
make


This is especially useful if you are ready to contribute your work back to the main repository with a pull request.

Bazel support¶

Drake is adding support for the Bazel build system.

Troubleshooting¶

If you’re unable to launch drake-visualizer due to a “No module named vtkCommonCorePython” error, see this FAQ.