22title : Source Installation
33---
44
5+ # New Users
6+
7+ For first-time users, we strongly suggest using one of the pre-compiled binaries
8+ described on our [ installation] ( /installation.html ) page. This page explains how
9+ to build Drake form source, which is somewhat more challenging.
10+
511# Supported Configurations
612
713The following table shows the configurations and platforms that Drake
@@ -39,113 +45,67 @@ setup steps.
3945
4046⁽³⁾ Drake requires a compiler running in C++20 (or greater) mode.
4147
42- # Getting Drake
43-
44- Run:
45-
46- ```
47- git clone --filter=blob:none https://github.com/RobotLocomotion/drake.git
48- ```
49-
50- Note: we suggest you keep the default clone directory name (`` drake `` ) and not
51- rename it (such as `` drake2 `` ). The CLion integration will suffer if the
52- checkout directory is not named `` drake `` . (See [ CLion IDE setup] ( clion.html ) for details.)
53-
54- Note: the build process may encounter problems if you have unusual characters
55- like parentheses in the absolute path to the drake directory
56- (see [ #394 ] ( https://github.com/RobotLocomotion/drake/issues/394 ) ).
57-
58- ## Using a fork of Drake
59-
60- The above `` git clone `` command will configure Drake's primary repository as a
61- remote called `` origin `` . If you plan to fork Drake for development, we
62- recommend that you configure your fork of Drake's primary repository as the
63- `` origin `` remote and Drake's primary repository as the `` upstream ``
64- remote. This can be done by executing the following commands:
65-
66- ```
67- cd drake
68- git remote set-url origin git@github.com:[your github user name]/drake.git
69- git remote add upstream https://github.com/RobotLocomotion/drake.git
70- git remote set-url --push upstream no_push
71- ```
72-
73- We recommend that you
74- [ setup SSH access to github.com] ( https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/ )
75- to avoid needing to type your password each time you access it.
76-
77- # Mandatory platform-specific instructions
78-
79- Before running the build, you must follow some one-time platform-specific
80- setup steps.
81-
82- * Ubuntu:*
83-
84- ```
85- sudo ./setup/ubuntu/install_prereqs.sh
86- ```
87-
88- * macOS:*
89-
90- We assume that you have already installed Xcode
91- ([ from the Mac App Store] ( https://itunes.apple.com/us/app/xcode/id497799835 ) ).
92-
93- After that, run:
48+ # Building with CMake
9449
95- ```
96- ./setup/mac/install_prereqs.sh
97- ```
98-
99- # Build with Bazel
100-
101- For instructions, jump to
102- [ Developing Drake using Bazel] ( /bazel.html#developing-drake-using-bazel ) ,
103- or check out the full details at:
50+ For sample projects that show how to import Drake as a CMake external project
51+ (either by building Drake from source, or by downloading a pre-compiled Drake
52+ release) please see our gallery of
53+ [ drake-external-examples] ( https://github.com/RobotLocomotion/drake-external-examples ) .
10454
105- * [ Bazel build system ] ( /bazel.html )
55+ Otherwise, you can run a build from source by hand like this:
10656
107- ## Building the Python Bindings
57+ ``` bash
58+ # Get the sources.
59+ git clone --filter=blob:none https://github.com/RobotLocomotion/drake.git
10860
109- To use the Python bindings from Drake externally, we recommend using CMake .
110- As an example:
61+ # Install the build dependencies .
62+ drake/setup/install_prereqs
11163
112- ``` bash
113- git clone https://github.com/RobotLocomotion/drake.git
64+ # Build and install using standard CMake commands.
11465mkdir drake-build
11566cd drake-build
11667cmake ../drake
11768make install
11869```
11970
120- Note that a concurrency limit passed to ` make ` (e.g., ` make -j 2 ` ) has almost no
121- effect on the Drake build. You might need to add a bazel configuration dotfile
122- to your home directory if your build is running out of memory. See the
123- [ troubleshooting] ( /troubleshooting.html#build-oom ) page for details.
71+ To change the build options, you can run one of the standard CMake GUIs (e.g.,
72+ ` ccmake ` or ` cmake-gui ` ) or specify command-line options with ` -D ` .
12473
125- Be aware that repeatedly running ` make install ` will install the recompiled
126- version of Drake * on top of* the prior version. This will lead to disaster
127- unless the set of installed filenames is exactly the same (because old files
128- will be hanging around polluting your PYTHONPATH). It is safe if you are merely
129- tweaking a source code file and repeatedly installing, without any changes to
130- the build system. For any kind of larger change (e.g., upgrading to a newer
131- Drake), we strongly advise that you delete the prior tree (within the ` install `
132- sub-directory) before running ` make ` .
74+ ## Drake-specific CMake options
13375
134- Please note the additional CMake options which affect the Python bindings:
76+ These options can be set using ` -DFOO=bar ` on the CMake command line, or in one
77+ of the CMake GUIs.
13578
136- * `` -DWITH_GUROBI={ON, [OFF]} `` - Build with Gurobi enabled.
137- * `` -DWITH_MOSEK={ON, [OFF]} `` - Build with MOSEK™ enabled.
138- * `` -DWITH_SNOPT={ON, [OFF]} `` - Build with SNOPT enabled.
79+ Adjusting open-source dependencies:
13980
140- `` {...} `` means a list of options, and the option surrounded by `` [...] `` is
141- the default option. An example of building `` pydrake `` with both Gurobi and
142- MOSEK™, without building tests:
81+ * WITH_USER_EIGEN (default OFF). When ON, uses ` find_package(Eigen3) `
82+ to locate a user-provided ` Eigen3::Eigen ` library
83+ instead of hard-coding to the operating system version.
84+ * WITH_USER_FMT (default OFF). When ON, uses ` find_package(fmt) `
85+ to locate a user-provided ` fmt::fmt ` library
86+ instead of hard-coding to the operating system version.
87+ * WITH_USER_SPDLOG (default OFF). When ON, uses ` find_package(spdlog) `
88+ to locate a user-provided ` spdlog::spdlog ` library
89+ instead of hard-coding to the operating system version.
14390
144- ``` bash
145- cmake -DWITH_GUROBI=ON -DWITH_MOSEK=ON ../drake
146- ```
91+ Adjusting closed-source (commercial) software dependencies:
92+
93+ * WITH_GUROBI (default OFF). When ON, enables the ` GurobiSolver ` in the build.
94+ * If Gurobi is not installed to its standard location, you must also specify
95+ ` export GUROBI_HOME=${...GUROBI_UNZIP_PATH...}/linux64 ` in your terminal
96+ so that ` find_package(Gurobi) ` will be able to find it.
97+ * WITH_MOSEK (default OFF). When ON, enables the ` MosekSolver ` in the build.
98+ * WITH_SNOPT (default OFF). When ON, enables the ` SnoptSolver ` in the build.
99+ * SNOPT_PATH (no default). When WITH_SNOPT is ON, this must be set to a SNOPT
100+ archive path, e.g. ` /home/user/Downloads/snopt7.4.tar.gz ` .
101+ * WITH_ROBOTLOMOTION_SNOPT (default OFF). When ON, enables the ` SnoptSolver `
102+ in the build, using a hard-coded and access-controlled download of SNOPT.
103+ This option is only valid for MIT- or TRI-affiliated Drake developers.
147104
148- You will also need to have your `` PYTHONPATH `` configured correctly.
105+ ## Running the Python Bindings after a CMake install
106+
107+ To run the installed copy of ` pydrake ` , you will also need to have your
108+ `` PYTHONPATH `` configured correctly.
149109
150110* Ubuntu 22.04 (Jammy):*
151111
@@ -167,3 +127,25 @@ export PYTHONPATH=${PWD}/install/lib/python3.12/site-packages:${PYTHONPATH}
167127cd drake-build
168128export PYTHONPATH=${PWD} /install/lib/python3.12/site-packages:${PYTHONPATH}
169129```
130+
131+ ## Caveats
132+
133+ Note that a concurrency limit passed to ` make ` (e.g., ` make -j 2 ` ) for a Drake
134+ build has almost no effect. You might need to add a bazel configuration dotfile
135+ to your home directory if your build is running out of memory. See the
136+ [ troubleshooting] ( /troubleshooting.html#build-oom ) page for details.
137+
138+ Be aware that repeatedly running ` make install ` will install the recompiled
139+ version of Drake * on top of* the prior version. This will lead to disaster
140+ unless the set of installed filenames is exactly the same (because old files
141+ will be hanging around, e.g., polluting your PYTHONPATH). It is safe if you are
142+ merely tweaking a source code file and repeatedly installing, without any
143+ changes to the build system. For any kind of larger change (e.g., upgrading to a
144+ newer Drake), we strongly advise that you delete the prior tree (within the
145+ ` install ` sub-directory) before running ` make ` .
146+
147+ # Making changes to Drake
148+
149+ Drake developers use Bazel (not CMake) for development. Refer to our [ Bazel
150+ instructions] ( /bazel.html ) for details. Bazel is only used for development;
151+ there is no way to _ install_ Drake from Bazel.
0 commit comments