Source installation (OS X, Ubuntu)¶
Optional: Setting up the MATLAB Compiler¶
Make sure that the MATLAB executable is in your path. (e.g., typing
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.
We recommend that you setup SSH access to Github.com to avoid needing to type your password each time you access it. The following instructions assume you have uploaded your public SSH key to your Github account.
git clone email@example.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).
git clone command will configure Drake’s primary repository as a
origin. We recommend that you configure your fork of Drake’s
primary repository as the
origin remote and Drake’s primary repository as
upstream remote. This can be done by executing the following commands:
cd drake-distro git remote set-url origin firstname.lastname@example.org:[your github user name]/drake.git git remote add upstream email@example.com:RobotLocomotion/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:
See supported configurations for the configurations and platforms that Drake officially supports. All else being equal, we would recommend developers use Ubuntu Xenial.
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:
To build with
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
cmake command does not specify a build type, so drake will be built
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
In addition to the build mode, Drake has many other build options. You can view
drake-distro/CMakeLists.txt. The build options typically start with
“WITH_”. The options can be included in the above
cmake command by adding
-D flags. You can also specify them using a text-based GUI by
cd drake-distro/build ccmake ..
To get details about the actual compiler and linker commands, execute:
cd drake-distro/build make VERBOSE=true
Build with Ninja¶
First, confirm that Ninja is installed on your system:
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
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
drake/build.ninja, or run
ninja -v for a verbose build.
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 using ROS Catkin place build artifacts in Catkin’s
and place externally-visible build artifacts in Catkin’s
install space. When
official Drake/ROS installation instructions,
these spaces are typically
Identifying the Build System Used¶
If you encounter an existing from-source installation of Drake and aren’t sure
whether it was built using
Ninja,  look
drake-distro/build. If there is a file called
Makefile, Drake was
Make. If there is a file called
rules.ninja, Drake was built
|||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¶
How to Clean Your Workspace¶
First save, commit, and push all of your work. The following commands are destructive.
If you’re using
cd drake-distro rm -rf build rm -rf externals git clean -fdx git reset --hard HEAD
If you’re using ROS Catkin, simply execute:
cd drake_catkin_workspace catkin clean
Test Your Installation¶
Start MATLAB, then at the MATLAB prompt do:
cd drake-distro/drake addpath_drake
cd into the examples directories and try some things out. Here are a few
fun ones to get you started:
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
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
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.