Ardupilot is gradually moving from the make-based build system to Waf. The instructions below should be enough for you to build Ardupilot, but you can also read more about the build system in the Waf Book.
Waf should always be called from the ardupilot's root directory. Differently
from the make-based build, with Waf there's a configure step to choose the
board to be used (default is
There are several commands in the build system for advanced usages, but here we list some basic and more used commands as example.
Below shows how to build ArduCopter for the Pixhawk2/Cube. Many other boards are supported and the next section shows how to get a full list of them.
./waf configure --board px4-v3 ./waf copter
The first command should be called only once or when you want to change a configuration option. One configuration often used is the
--boardoption to switch from one board to another one. For example we could switch to SkyViper GPS drone and build again:
./waf configure --board skyviper-v2450 ./waf copter
If building for the bebop2 the binary must be built statically:
./waf configure --board bebop --static ./waf copter
The "arducopter" and "arducopter-heli" binaries should appear in the
List available boards
It's possible to get a list of supported boards on ArduPilot with the command below
Here are some commands to configure waf for commonly used boards:
./waf configure --board bebop --static # Bebop or Bebop2 ./waf configure --board edge # emlid edge ./waf configure --board navio2 # emlid navio2 ./waf configure --board px4-v1 # the very old two layer Pixhawk (almost none exist) ./waf configure --board px4-v2 # older Pixhawks that suffer from the 1MB flash limit issue ./waf configure --board px4-v3 # Pixhawk2/Cube and newer Pixhawks with no 1MB flash limit issue ./waf configure --board fmuv3 # Pixhawk2/Cube using ChibiOS ./waf configure --board px4-v4 # Pixracer ./waf configure --board fmuv4 # Pixracer using ChibiOS ./waf configure --board skyviper-v2450 # SkyRocket's SkyViper GPS drone using ChibiOS ./waf configure --board sitl # software-in-the-loop simulator ./waf configure --board sitl --debug # software-in-the-loop simulator with debug symbols
Clean the build
distcleancan be used to clean the objects produced by the build. The first keeps the
configureinformation, cleaning only the objects for the current board. The second cleans everything for every board, including the saved
Cleaning the build is very often not necessary and discouraged. We do incremental builds reducing the build time by orders of magnitude.
Upload or install
Build commands have a
--uploadoption in order to upload the binary built to a connected board. This option is supported by Pixhawk and Linux-based boards. The command below uses the
--targetsoption that is explained in the next item.
./waf --targets bin/arducopter --upload
For Linux boards you need first to configure the IP of the board you are going to upload to. This is done on configure phase with:
./waf configure --board <board> --rsync-dest <destination>
The commands below give a concrete example (board and destination IP will change according to the board used):
./waf configure --board navio2 --rsync-dest firstname.lastname@example.org:/ ./waf --target bin/arducopter --upload
This allows to set a destination to which the
--uploadoption will upload the binary. Under the hood it installs to a temporary location and calls
rsync <temp_install_location>/ <destination>.
On Linux boards there's also an install command, which will install to a certain directory, just like the temporary install above does. This can be used by distributors to create .deb, .rpm or other package types:
./waf copter DESTDIR=/my/temporary/location ./waf install
Use different targets
The build commands in the items above use
copteras argument. This builds all binaries that fall under the "copter" group. See the section Advanced usage below for more details regarding groups.
This shows a list of all possible targets:
For example, to build only a single binary:
# Quad frame of ArduCopter ./waf --targets bin/arducopter # unit test of our math functions ./waf --targets tests/test_math
It's possible to see all available commands and options:
Also, take a look on the Advanced section below.
This section contains some explanations on how the Waf build system works and how you can use more advanced features.
Waf build system is composed of commands. For example, the command below
configure) is for configuring the build with all the options used by this
# Configure the Linux board ./waf configure --board=linux
Consequently, in order to build, a "build" command is issued, thus
That is the default command, so calling just
waf is enough:
# Build programs from bin group ./waf # Waf also accepts '-j' option to parallelize the build. ./waf -j8
By default waf tries to parallelize the build automatically to all processors
-j option is usually not needed, unless you are using icecc (thus
you want a bigger value) or you don't want to stress your machine with
Program groups are used to represent a class of programs. They can be used to build all programs of a certain class without having to specify each program. It's possible for two groups to overlap, except when both groups are main groups. In other words, a program can belong to more than one group, but only to one main group.
There's a special group, called "all", that comprises all programs.
The main groups form a partition of all programs. Besides separating the programs logically, they also define where they are built.
The main groups are:
- bin: the main binaries, that is, ardupilot's main products - the vehicles and Antenna Tracker
- examples: programs that show how certain libraries are used or to simply test their operation
- benchmarks: requires
- tests: basically unit tests to ensure changes don't break the system's logic
All build files are placed under
the board/platform you selected during configuration. Each main program group
has a folder with its name directly under
build/<board>/. Thus, a program
will be stored in
<main_group> is the
main group the program belongs to. For example, for a linux build, arduplane,
which belongs to the main group "bin", will be located at
Main product groups
Those are groups for ardupilot's main products. They contain programs for the product they represent. Currently only the "copter" group has more than one program - one for each frame type.
The main product groups are:
Building a program group
Ardupilot adds to waf an option called
--program-group, which receives as
argument the group you want it to build. For a build command, if you don't pass
--program-group, then the group "bin" is selected by
default. The option
--program-group can be passed multiple times.
# Group bin is the default one ./waf # Build all vehicles and Antenna Tracker ./waf --program-group bin # Build all benchmarks and tests ./waf --program-group benchmarks --program-group tests
Shortcut for program groups
For less typing, you can use the group name as the command to waf. Examples:
# Build all vehicles and Antenna Tracker ./waf bin # Build all examples ./waf examples # Build arducopter binaries ./waf copter
Building a specific program
In order to build a specific program, you just need to pass its path relative
build/<board>/ to the option
# Build arducopter for quad frame ./waf --targets bin/arducopter # Build vectors unit test ./waf --targets tests/test_vectors
check builds all programs and then executes the relevant tests.
In that context, a relevant test is a program from the group "tests" that makes
one of the following statements true:
- it's the first time the test is built since the last cleanup or when the project was cloned.
- the program had to be rebuilt (due to modifications in the code or dependencies, for example)
- the test program failed in the previous check.
That is, the tests are run only if necessary. If you want waf to run all tests,
then you can use either option
--alltests or the shortcut command
# Build everything and run relevant tests ./waf check # Build everything and run all tests ./waf check --alltests # Build everything and run all tests ./waf check-all
It's possible to pass the option
--debug to the
configure command. That
will set compiler flags to store debugging information in the binaries so that
you can use them with
gdb, for example. That option might come handy when using SITL.
waf binary on root tree is actually a wrapper to the real
maintained in its own submodule. It's possible to call the latter directly via
./modules/waf/waf-light or to use an alias if you prefer typing
There's also a make wrapper called
Makefile.waf. You can use
make -f Makefile.waf help for instructions on how to use it.
Command line help
You can use
waf --help to see information about commands and options built-in
to waf as well as some quick help on those added by ardupilot.