Skip to content

Commit

Permalink
[doc] Completely revamp installation instructions (#15953)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jwnimmer-tri
jwnimmer-tri authored Oct 24, 2021
1 parent fbfd773 commit 5cb3f68
Show file tree
Hide file tree
Showing 46 changed files with 482 additions and 318 deletions.
64 changes: 64 additions & 0 deletions doc/_pages/apt.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: Installation via APT (Ubuntu)
---

# APT Packages

Drake publishes pre-compiled binaries as APT packages (``*.deb``) for the
Ubuntu 18.04 (Bionic) and Ubuntu 20.04 (Focal) operating systems. Refer to
[Supported Configurations](/installation.html#supported-configurations)
for additional compatibility details.

To learn about other installation methods, refer to
[Installation and Quickstart](/installation.html).

Drake binary releases incorporate a pre-compiled version of
[SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
[Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
Thanks to Philip E. Gill and Elizabeth Wong for their kind support.

## Stable Releases

To add the Drake APT repository to your machine and install the `drake-dev` package,
please do the following in order:

If you are using a [minimal](https://wiki.ubuntu.com/Minimal) cloud or
container image, you may need to install the following packages:

```bash
sudo apt-get update
sudo apt-get install --no-install-recommends \
ca-certificates gnupg lsb-release wget
```

Download a copy of the Drake GPG signing key and add it to an APT trusted keychain:

```bash
wget -qO- https://drake-apt.csail.mit.edu/drake.asc | gpg --dearmor - \
| sudo tee /etc/apt/trusted.gpg.d/drake.gpg >/dev/null
```

Add the Drake repository to your APT sources list:

```bash
echo "deb [arch=amd64] https://drake-apt.csail.mit.edu/$(lsb_release -cs) $(lsb_release -cs) main" \
| sudo tee /etc/apt/sources.list.d/drake.list >/dev/null
```

Update your local APT package index and install the `drake-dev` package:

```bash
sudo apt-get update
sudo apt-get install --no-install-recommends drake-dev
```

Most content installs to `/opt/drake`, so setting the following environment
variables may be useful:

```bash
export LD_LIBRARY_PATH="/opt/drake/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
export PATH="/opt/drake/bin${PATH:+:${PATH}}"
export PYTHONPATH="/opt/drake/lib/python$(python3 -c 'import sys; print("{0}.{1}".format(*sys.version_info))')/site-packages${PYTHONPATH:+:${PYTHONPATH}}"
```

Refer to [Quickstart](/installation.html#quickstart) for next steps.
36 changes: 1 addition & 35 deletions doc/_pages/developers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,34 +57,9 @@ of artifacts distributed with this website.
* [Detailed Notes on Drake's Unit Tests](/unit_testing_instructions.html)
* [Downstream Testing (Drake as a Dependency)](/downstream_testing.html)


# Supported Configurations

The following table shows the configurations and platforms that Drake
officially supports. Supported configurations are tested in continuous
integration. All other configurations are provided on a best-effort basis.

Drake requires a compiler running in C++17 mode.

| Operating System | Bazel | CMake | C/C++ Compiler | Java | Python |
|----------------------------------|-------|-------|--------------------------------|-------------------------------|--------|
| Ubuntu 18.04 LTS (Bionic Beaver) | 4.2 | 3.10 | GCC 7.5 (default) or Clang 9 | OpenJDK 11 | 3.6 |
| Ubuntu 20.04 LTS (Focal Fossa) | 4.2 | 3.16 | GCC 9.3 (default) or Clang 9 | OpenJDK 11 | 3.8 |
| macOS Catalina (10.15) | 4.2 | 3.19 | Apple LLVM 12.0.0 (Xcode 12.4) | AdoptOpenJDK 15 (HotSpot JVM) | 3.9 |
| macOS Big Sur (11) | 4.2 | 3.19 | Apple LLVM 12.0.0 (Xcode 12.4) | AdoptOpenJDK 15 (HotSpot JVM) | 3.9 |

CPython is the only Python implementation supported. On Ubuntu, amd64
(i.e., x86_64) is the only supported architecture. On macOS, x86_64 is the only
supported architecture and running Drake under Rosetta 2 emulation on arm64 is
not supported. Plans for any future arm64 support on macOS and/or Ubuntu are
discussed in [issue #13514](https://github.com/RobotLocomotion/drake/issues/13514).

Drake Ubuntu builds assume support for Intel's AVX2 and FMA instructions,
introduced with the Haswell architecture in 2013 with substantial performance
improvements in the Broadwell architecture in 2014. Drake is compiled with
`-march=broadwell` to exploit these instructions (that also works for Haswell
machines). Drake can be used on older machines if necessary by building from
source with that flag removed.
Refer to [Source Installation](/from_source.html#supported-configurations).

## Configuration Management Non-Determinism

Expand All @@ -105,15 +80,6 @@ If you have tried and are unable to configure your system by
[following the instructions](/from_source.html) please do not hesitate
to [ask for help](/getting_help.html).

## Binary Packages

The binary releases of Drake are built with GCC 7.5 on Ubuntu 18.04 (Bionic),
GCC 9.3 on Ubuntu 20.04 (Focal), and Apple LLVM 12.0.0 on macOS Catalina
(10.15).

The links for these packages are listed in
[Binary installation](/from_binary.html).

# Issue Tracking

* [GitHub Issue Management](/issues.html)
Expand Down
61 changes: 50 additions & 11 deletions doc/_pages/docker.md
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,60 @@
---
title: Using the Drake Docker Images From Docker Hub
title: Installation via Docker
---

Drake's continuous integration has nightly jobs that publish the binary
archives that are described in the [Nightly releases](/from_binary.html#nightly-releases) section. The Ubuntu
18.04 (Bionic) binary archive is also used to publish a Docker image on
[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake). You can see the
available Docker images here:
# Docker Hub

[https://hub.docker.com/r/robotlocomotion/drake/tags](https://hub.docker.com/r/robotlocomotion/drake/tags)
Drake publishes pre-compiled binaries as Docker images on
[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake). Refer to
[Supported Configurations](/installation.html#supported-configurations)
for additional compatibility details.

The [latest](https://hub.docker.com/r/robotlocomotion/drake/tags?name=latest)
image can be pulled from Docker Hub as follows:
To learn about other installation methods, refer to
[Installation and Quickstart](/installation.html).

Drake binary releases incorporate a pre-compiled version of
[SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
[Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
Thanks to Philip E. Gill and Elizabeth Wong for their kind support.

## Stable Releases

The latest stable image can be pulled from
[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake)
as follows:

```
docker pull robotlocomotion/drake:X.Y.Z
```

Refer to [Release Notes](/release_notes/release_notes.html) for a list of
published X.Y.Z version numbers.

The docker tags for Drake's stable releases are spelled like:

* ``bionic-X.Y.Z`` for the Ubuntu 18.04 image of Drake vX.Y.Z.
* ``focal-X.Y.Z`` for the Ubuntu 20.04 image of Drake vX.Y.Z.
* ``X.Y.Z`` is a synonym for one of the above, currently bionic-X.Y.Z.

Refer to [Quickstart](/installation.html#quickstart) for next steps.

## Nightly Releases

The latest nightly image can be pulled from
[Docker Hub](https://hub.docker.com/r/robotlocomotion/drake)
as follows:

```
docker pull robotlocomotion/drake:latest
```

Docker images based on the Ubuntu 20.04 (Focal) binary archive are not
available.
The docker tags for Drake's nightly releases are spelled like:

* ``bionic-YYYYMMDD`` for the Ubuntu 18.04 image of Drake as of date YYYY-MM-DD.
* ``bionic`` is a synonym for the most recent ``bionic-YYYYMMDD``.
* ``focal-YYYYMMDD`` for the Ubuntu 20.04 image of Drake as of date YYYY-MM-DD.
* ``focal`` is a synonym for the most recent ``focal-YYYYMMDD``.
* ``YYYYMMDD`` is a synonym for one of the above, currently ``bionic-YYYYMMDD``.
* ``latest`` is a synonym for the most recent ``YYYYMMDD``.

Refer to [Quickstart](/installation.html#quickstart) for next steps.
142 changes: 61 additions & 81 deletions doc/_pages/from_binary.md
View file
Original file line number Diff line number Diff line change
@@ -1,111 +1,91 @@
---
title: Binary installation (macOS, Ubuntu)
title: Installation via Direct Download
---

# Nightly Releases
# Binary Packages

Binary packages of Drake for Ubuntu 18.04 (Bionic), Ubuntu 20.04 (Focal) and
Mac are generated nightly and are tagged ``latest`` or by ``yyyymmdd``. Latest
releases are available to download at:

* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz)

Releases for specific days are available as follows:
`https://drake-packages.csail.mit.edu/drake/nightly/drake-yyyymmdd-bionic|focal|mac.tar.gz`
Drake publishes pre-compiled binaries as binary downloads (``*.tar.gz``)
for all supported operating systems. Refer to
[Supported Configurations](/installation.html#supported-configurations)
for compatibility details.

For example: [https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-bionic.tar.gz)


Note that Drake no longer supports Ubuntu 16.04 (Xenial), but older packages are available here:

* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-xenial.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-xenial.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-xenial.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-20191026-xenial.tar.gz)

Individual packages are archived two years from their date of creation.

Note that for release v0.30.0 and later, Ubuntu binaries require support for
Intel's AVX2 and FMA instruction sets which were introduced with the Haswell
architecture in 2013 with substantial performance improvements in the Broadwell
architecture in 2014. Drake is compiled with `-march=broadwell` to exploit these
instructions (that also works for Haswell machines). Drake can be used on older
machines if necessary by building from source with that flag removed.

For the compilers used to produce these releases, see
[Binary Packages](/developers.html#binary-packages).
To learn about other installation methods, refer to
[Installation and Quickstart](/installation.html).

Drake binary releases incorporate a pre-compiled version of
[SNOPT](https://ccom.ucsd.edu/~optimizers/solvers/snopt/) as part of the
[Mathematical Program toolbox](https://drake.mit.edu/doxygen_cxx/group__solvers.html).
Thanks to Philip E. Gill and Elizabeth Wong for their kind support.

## Stable Releases

Binary packages of Drake for Ubuntu 18.04 (Bionic), Ubuntu 20.04 (Focal) and
Mac are available to download as attachments from Drake's GitHub
[releases](https://github.com/RobotLocomotion/drake/releases) page.

The most recent release is
[v0.35.0](https://github.com/RobotLocomotion/drake/releases/tag/v0.35.0):

## Example Usage
* [https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-bionic.tar.gz](https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-bionic.tar.gz)
* [https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-focal.tar.gz](https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-focal.tar.gz)
* [https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-mac.tar.gz](https://github.com/RobotLocomotion/drake/releases/download/v0.35.0/drake-20211021-mac.tar.gz)

An example of how to use the nightly binaries is shown in this
[example CMake project](https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_cmake_installed).
### Use as a C++ library

## Binary Installation for Python
For an example of using a Drake ``*.tar.gz`` image from a CMake project, refer
to the
[drake_cmake_installed](https://github.com/RobotLocomotion/drake-external-examples/tree/main/drake_cmake_installed)
example.

To use Python bindings, see [Binary Installation for Python](/python_bindings.html#installation).
### Use as a Python library

## Docker Images
In most cases, we suggest using our [pip releases](/pip.html), because that
will be more convenient than manually downloading. However, if you need both
C++ and Python API support, then pip will not work. This section shows
how to incorporate a manual download into a
[virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)
directory. In the example below, we will name that directory ``env``, but you
can choose any name.

You may also use binary releases in Docker images. See
[Using the Drake Docker Images From Docker Hub](/docker.html)
for more information.
Download the binary release ``*.tar.gz`` file, using one of the links above.
In the example below, we'll use ``drake.tar.gz`` to refer to it, but your
download will have a more version-specific filename.

## Experimental Packages
Create and activate the envionment:

Drake maintainers may build "experimental" packages on demand using Jenkins by
following [these instructions](/jenkins.html#building-binary-packages-on-demand).
```bash
mkdir -p env
tar -xvzf drake.tar.gz -C env --strip-components=1
python3 -m virtualenv -p python3 env --system-site-packages
source env/bin/activate
```

## Historical Note
Install dependencies within the environment:

Older releases were built around substantial MATLAB support, and are
described on [release notes page](/release_notes/older_releases.html).
```bash
env/share/drake/setup/install_prereqs
````

# APT Packages for Monthly Tagged Releases
(On Ubuntu, the script might ask to be run under ``sudo``.)

APT packages are currently available for the Ubuntu 18.04 (Bionic) and
Ubuntu 20.04 (Focal) operating systems on x86 64-bit architectures.
Refer to [Quickstart](/installation.html#quickstart) for next steps.

## To Install the Packages
## Nightly Releases

To add the Drake APT repository to your machine and install the `drake-dev` package,
please do the following in order:
Binary packages of Drake for Ubuntu 18.04 (Bionic), Ubuntu 20.04 (Focal) and
Mac are generated nightly and are available to download at:

1. If you are using a [minimal](https://wiki.ubuntu.com/Minimal) cloud or
container image, you may need to install the following packages:
```bash
sudo apt-get update
sudo apt-get install --no-install-recommends \
ca-certificates gnupg lsb-release wget
```
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-focal.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz)

2. Download a copy of the Drake GPG signing key and add it to an APT trusted keychain:
```bash
wget -qO- https://drake-apt.csail.mit.edu/drake.asc | gpg --dearmor - \
| sudo tee /etc/apt/trusted.gpg.d/drake.gpg >/dev/null
```
Older packages for specific dates are available by replacing ``latest`` with an
8-digit date, e.g., ``20200102`` for January 2nd, 2020.

3. Add the Drake repository to your APT sources list:
```bash
echo "deb [arch=amd64] https://drake-apt.csail.mit.edu/$(lsb_release -cs) $(lsb_release -cs) main" \
| sudo tee /etc/apt/sources.list.d/drake.list >/dev/null
```
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-bionic.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-bionic.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-focal.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-focal.tar.gz)
* [https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-mac.tar.gz](https://drake-packages.csail.mit.edu/drake/nightly/drake-YYYYMMDD-mac.tar.gz)

4. Update your local APT package index and install the `drake-dev` package:
```bash
sudo apt-get update
sudo apt-get install --no-install-recommends drake-dev
```
Individual packages are archived two years from their date of creation.

Most content installs to `/opt/drake`, so setting the following environment
variables may be useful:
```bash
export LD_LIBRARY_PATH="/opt/drake/lib${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}"
export PATH="/opt/drake/bin${PATH:+:${PATH}}"
export PYTHONPATH="/opt/drake/lib/python$(python3 -c 'import sys; print("{0}.{1}".format(*sys.version_info))')/site-packages${PYTHONPATH:+:${PYTHONPATH}}"
```
The installation instructions are identical to stable releases as shown above.
Loading

0 comments on commit 5cb3f68

Please sign in to comment.