apollo_build_and_test_explained.md

Apollo Build and Test Explained

This document focuses on how to build and test Apollo in different ways.

Pre-requisites

You are supposed to have followed Apollo Software Installation Guide. Make sure you are in Apollo development Docker container before you proceed.

Overview

Apollo uses Bazel as its underlying build system. Bazel is an open-source build and test tool with a human-readable, high-level build language suitable for medium and large projects. Basically, the better you know about Bazel, the better you know about Apollo Build.

Building Apollo

Subcommands in apollo.sh

Let's first take a look at the usage of apollo.sh.

From this message, we can see subcommands that starts with "build_", like build_dbg, build_cpu, and build_opt_gpu, etc. As you may figure out, they are all variants for their basic form: apollo.sh build.

Building Apollo using apollo.sh build

You can use ./apollo.sh build to build individual modules, or the whole Apollo project.

Type the following command to build, say, Cyber RT:

bash apollo.sh build cyber

To build the whole Planning module (all targets under the modules/planning directory):

bash apollo.sh build planning

To build everything,

bash apollo.sh build

For simplicty, Apollo 6.0 introduces the notion of bash apollo.sh build [module] to replace the notion of build_cyber, build_planning, etc in previous Apollo releases.

Variants of apollo.sh build

There are mainly four variants of apollo.sh build, namely, build_dbg, build_opt, build_cpu and build_gpu.

You may ask, what's the differences among them?

Good question. Let me try to make this clear.

Debug v.s. Optimized Build: build_dbg/build_opt

By default, Apollo uses the fastbuild compilation mode . So when you type bash apollo.sh build planning, you are indicating Bazel to run:

bazel build [other options] -c fastbuild //modules/planning/...

for you.

When you type bash apollo.sh build_dbg planning, you are running

bazel build [other options] --config=dbg //modules/planning/...

Please note that --config=dbg implies -c dbg, as can be seen from the following section from tools/bazelrc:

build:dbg -c dbg
build:opt -c opt

Now you can understand the build_opt variant. Basically,

bash apollo.sh build_opt cyber

means

bazel build [other options] -c opt //cyber/...

CPU v.s. GPU Build: build_cpu/build_gpu

By now, you can easily figure out that build_cpu and build_gpu are just another form of running

bazel build --config=cpu

and

bazel build --config=gpu

respectively under the hood.

However, things are a bit complicated compared to the build_dbg/build_gpu case.

Here is a snapshot showing the log messages on my screen when running apollo.sh build:

There are three USE_GPU: USE_GPU_HOST, USE_GPU_TARGET and USE_GPU.

• USE_GPU_HOST is an environment variable determined by docker/scripts/dev_start.sh to pass to Apollo Docker container, which indicates whether the host machine (where Docker is running) is GPU capable.
• USE_GPU_TARGET is an environment variable determined by scripts/apollo.bashrc inside Docker container to indicate whether the container is GPU capable.
• USE_GPU is a variable indicating whether to perform CPU build or GPU build.

When you type bash apollo.sh build --config=cpu or apollo.sh build --config=gpu, the build script will check the GPU capability of the Docker container and determines whether the build you specified can succeed.

If you didn't specify whether to perform CPU or GPU build, the build script will determine it automatically according to GPU capability of your Docker environment.

It's OK to run CPU build in a GPU capable Apollo container, whereas running GPU build in a CPU-only container will fail.

By design, --config=cpu and --config=gpu are mutually exclusive. You should specify at most one of them when running apollo.sh build.

Optimized GPU Build with build_opt_gpu

build_opt_gpu is just the combination of build_opt and build_gpu.

bash apollo.sh build_opt_gpu

is equivalent to

bazel build --config=opt --config=gpu //...

Running Unit Tests: apollo.sh test

Since bazel test inherits all options from bazel build (Ref: Bazel Docs:Test Options), the discussions above are applicable to apollo.sh test.

# Each of the following pairs are basically equivalent:

# Run unit tests under the `cyber` directory
bash apollo.sh test cyber
bazel test [--config=cpu|--config=gpu] //cyber/...

# Run unit tests for all in CPU mode
bash apollo.sh test --config=cpu
bazel test --config=cpu //...

# Run unit tests for the Planning module in GPU mode
bash apollo.sh test --config=gpu planning
bazel test --config=gpu //modules/planning/...

Actually, apollo.sh test is equivalent to

bazel test --config=unit_test

All the cpplint targets was excluded, since there is an independent apollo.sh lint command.

Running Code Coverage using apollo.sh coverage

Since bazel coverage inherits all options from bazel test(See Bazel Docs: Coverage Options), all the discussions about apollo.sh test applies to apollo.sh coverage.

Build/Test/Coverage: An Insider's View

Under the hood, apollo.sh build/test/coverage makes use of scripts/apollo_build.sh, scripts/apollo_test.sh, and scripts/apollo_coverage.sh respectively.

If you are familiar with Bazel, you can build/test any fine-grained target(s). For example,

bazel test -c dbg //cyber/common:file_test
bazel build --config=opt //modules/dreamview/backend
bazel test --config=gpu  //modules/localization/...