Usage

The goal of this section is to explain how to use ADE on a project that provides an ADE configuration. See Setup for more information.

ADE Home

ADE needs a directory on the host which will be mounted as the user’s home directory within the container. It will be populated with dotfiles and must be different than the user’s home directory on the host. In case you use ADE for multiple projects it is recommended to use dedicated ADE home directories for each project.

ADE will look for a directory containing a file named .adehome starting with the current working directory and continuing with the parent directories to identify the ADE home directory to be mounted.

mkdir adehome
cd adehome
touch .adehome

Quick start

To start ade, an .aderc file is needed. For an example, see the Autoware.Auto project. For instructions to create an .aderc file for a project, see Setup.

When ade is run for the first time, it will first prompt for an authentication token, and then download all the Docker images configured in the .aderc file

$ cd adehome/path/to/.aderc
$ ade start --update
...
ADE startup completed.
$ ade enter
ade$ <= Note that the prompt changes

CLI

ade

ADE Development Environment.

ade [GLOBAL_OPTIONS] COMMAND [OPTIONS] -- [ARGS]...

Options

--version
--rc <rc>

Specify a different ADE configuration file. The file should be in adehome or its subdirectories. [default: .aderc]

--name <name>

Specify a custome name for the ADE instance [default: ade]

start

Start environment from within ADE project.

DOCKER_RUN_ARGS are passed directly to docker run. See https://docs.docker.com/engine/reference/commandline/run/ and Custom docker run/exec arguments for more information.

ade start [OPTIONS] -- DOCKER_RUN_ARGS

Options

--update, --no-update

Pull docker registries for updates. Using –update will imply –force.

--enter, --no-enter

Enter environment after starting.

-f, --force, --no-force

Force restart of running environment.

--select <select>

Select image tags to be used instead of configured defaults. Valid image tags are git tags and branches. To select one for a specific image use IMAGE:TAG (e.g. ade:ftr123) and only TAG to select it for all images for which it exists (e.g. release-42).

Arguments

-- DOCKER_RUN_ARGS

Optional argument(s)

enter

Enter environment, running optional command CMD.

DOCKER_EXEC_ARGS are passed directly to docker exec. See https://docs.docker.com/engine/reference/commandline/exec/ and Custom docker run/exec arguments for more information.

To enter a specific ADE instance, set the ADE_NAME environment variable or the global option --name. By default, ade enter will enter the ade environment.

If the specified environment is not running, select among the available environments from an interactive prompt.

ade enter [OPTIONS] [CMD] -- DOCKER_EXEC_ARGS

Options

-u, --user <user>

Enter ade as given user (e.g. root) instead of default

Arguments

CMD

Optional argument

-- DOCKER_EXEC_ARGS

Optional argument(s)

Environment variables

ADE_ENTER_CMD

Provide a default for CMD

stop

Stop ade environment.

ade stop [OPTIONS]

save

Save configuration and images of running ADE into DIRECTORY.

ade save [OPTIONS] DIRECTORY

Arguments

DIRECTORY

Required argument

load

Load images from DIRECTORY.

ade load [OPTIONS] DIRECTORY

Arguments

DIRECTORY

Required argument

update-cli

Update ade command-line interface.

ade update-cli [OPTIONS]

Options

--finish-update <finish_update>

Used internally by update mechanism

Environment Variables

It is also possible to configure the default behavior of ade using environment variables and the .aderc file. For more information, see Configuring ADE with environment variables and The .aderc File.

Option Precedence

The value of each ade option is taken from the following sources in order of highest to lowest precedence:

  1. Command line options (CLI)

  2. Environment Variables

  3. Values in The .aderc File

  4. Default values (if any)

For example::

$ export ADE_RC=/path/to/rc
$ ade --rc /path/to/other_rc start  # --rc overrides ADE_RC
$ export ADE_NAME="ade2"
$ ade start  # starts 'ade2' with configurations from /path/to/rc
$ ade --rc /path/to/other_rc start  # starts 'ade2' with configurations from /path/to/other_rc

Note that in the last command the ADE_NAME environment variable takes precedence over the ADE_NAME specified in the aderc file, because even though the aderc file is specified via the command line, the --rc option only becomes relevant after checking options directly specified in command line options or via an environemnt variables.

For example::

$ ADE_NAME='envvar' ade --name 'ade_opt' --rc /path/to/rc start  # starts 'ade_opt'
$ ADE_NAME='envvar' ade --rc /path/to/rc start  # starts 'envvar'
$ ade --rc /path/to/rc start  # starts 'ADE_NAME' from '/path/to/rc'
$ ade start  # starts 'ade'

Note that arguments to the ADE commands are additive. Specifically, arguments passed to ade start will be appended to the values in ADE_DOCKER_RUN_ARGS, and arguments passed to ade enter will be appended to the values in ADE_DOCKER_EXEC_ARGS.

Cleanup

Over time, unused Docker images, containers, and volumes will clutter the machine’s hard drive. ADE does not store anything valuable inside the Docker containers, so it is possible to use native Docker commands to clean up. Anything valuable that needs to persist should be placed in ade-home, which is stored on the host and mounted in ADE.

To get an overview of Docker’s disk usage, run:

$ docker system df
TYPE                TOTAL               ACTIVE              SIZE                RECLAIMABLE
Images              13                  11                  14.03GB             916.9MB (6%)
Containers          11                  0                   2.311MB             2.311MB (100%)
Local Volumes       17                  15                  5.411GB             17.8MB (0%)
Build Cache         0                   0                   0B                  0B

Docker provides a cleanup command that will remove everything that is unused. To properly determine what is unused, make sure that all Docker containers you want to keep are running. To avoid having to re-download ADE images, run ade start. Once you are certain that everything you want to keep is in use, run:

$ docker system prune -a --volumes

Debugging

To see the native Docker commands and other commands ade is executing, set the ECHO variable before running ade, e.g.

$ ECHO=1 ade start

Starting multiple ADE instances

When working on multiple projects with ADE configurations, it is desired to keep an instance of ADE running for each project. To run multiple instance, use the ADE_NAME environment variable to switch between the two instances.

Let’s say that there are two projects minimal-ade and AutowareAuto, cloned in ade-home:

Note

It is recommended to keep separate ADE homes for each project; however, nothing prevents using the same ADE home for two projects.

Start the ADE instance for minimal-ade:

$ cd ~/ade-home/minimal-ade
$ export ADE_NAME=minimal
$ ade start

Then start the ADE instance for AutowareAuto:

$ cd ~/ade-home/AutowareAuto
$ export ADE_NAME=autoware
$ ade start

Now, in a new terminal, it is possible to select the ADE instance by setting ADE_NAME:

$ cd ~/ade-home
$ export ADE_NAME=minimal
$ ade enter
minimal$ # minimal ADE prompt

If ADE_NAME is not defined, the default name ade is used for a new environment.

In case the specified ADE is not found, ade enter offers an interactive prompt to select among the running environments. Press Enter to select the environment offered in brackets, or type minimal and press Enter to choose the other option:

$ cd ~/ade-home
$ ade enter
ERROR: An ADE instance named ade is not running.
Select one of {'autoware, minimal'} [autoware]:
Set ADE_NAME to suppress this prompt.
Entering autoware with following images:
...
Note

The host name in the ADE container will match ADE_NAME, indicating the current ADE instance

Similarly, specific ADE instances can be stopped:

$ cd ~/ade-home
$ export ADE_NAME=autoware
$ ade stop
Stopping autoware
...

Limitations

Starting multiple ADE works well when using the default network configuration; however, ADE instances may conflict if they use custom network configurations: