Add a new "Basic use" section so people don't get overhauled with build
instructions. They can read about the more advanced commands once they
are able to use the basic ones.
While at it, update the instructions to use the waf wrapper.
Ardupilot is gradually moving from the make-based build system to
[Waf](https://waf.io/).
[Waf](https://waf.io/). You can read the [Waf Book](https://waf.io/book/) if
you want to learn more about Waf.
To keep access to Waf convenient, use the following alias from the
root ardupilot directory:
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 `sitl`).
```bash
alias waf="$PWD/modules/waf/waf-light"
```
## Basic usage ##
You can also define the alias or create a function in your shell rc file (e.g.
`~/.bashrc`).
There are several commands in the build system for advanced usages, but here we
list some basic and more used commands as example.
You can read the [Waf Book](https://waf.io/book/) if you want to learn more
about Waf.
* **Build ArduCopter**
## Calling waf ##
Here we use minlure as an example of Linux board. Other boards can be used
and the next section shows how to get a list of available boards.
Waf should always be called from the ardupilot's root directory.
```sh
./waf configure --board minlure
./waf copter
```
Differently from the make-based build, with Waf there's a configure step
to choose the board to be used (default is `sitl`):
The first command should be called only once or when you want to change a
configuration option. One configuration often used is the `--board` option to
switch from one board to another one. For example we could switch to
Pixhawk and build again:
```bash
# Configure the Linux board
waf configure --board=linux
```
```sh
./waf configure --board px4-v2
./waf copter
```
Waf build system is composed of commands. For example, the above command
(`configure`) is for configuring the build. Consequently, in order to build, a
"build" command is issued, thus `waf build`. That is the default command, so
calling just `waf` is enough:
* **List available boards**
```bash
# Build programs from bin group
waf
# Waf also accepts '-j' option to parallelize the build.
waf -j8
```
It's possible to get a list of supported boards on ArduPilot with the command
below
To clean things up, use the `clean` or `distclean` command:
```sh
./waf list_boards
```bash
# Clean the build products, but keep configure information
waf clean
```
# Clean everything, will need to call configure again
waf distclean
```
* **Clean the build**
Commands `clean` and `distclean` can be used to clean the objects produced by
the build. The first keeps the `configure` information, cleaning only the
objects for the current board. The second cleans everything for every board,
including the saved `configure` information.
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 `--upload` option in order to upload the binary built
to a connected board. This option is supported by Pixhawk. The command below
uses the `--targets` option that is explained in the next item.
```sh
./waf --targets bin/arducopter-quad --upload
```
Currently Linux boards don't support the upload option, but there's an
install command, which will install to a certain directory. This can be
used by distributors to create .deb, .rpm or other package types:
```sh
./waf copter
DESTDIR=/my/temporary/location ./waf install
```
* **Use different targets**
The build commands in the items above use `copter` as argument. This
builds all binaries that fall under the "copter" group. See the
section [Advanced usage](#advanced-usage) below for more details regarding
groups.
This shows a list of all possible targets:
```
./waf list
```
For example, to build only a single binary:
```
# Quad frame of ArduCopter
./waf --targets bin/arducopter-quad
Using git to clean the files also work fine.
# unit test of our math functions
./waf --targets tests/test_math
```
To list the task generator names that can be used for the option `--targets`,
use the `list`command:
* **Other options**
It's possible to see all available commands and options:
```
./waf -h
```
Also, take a look on the [Advanced section](#advanced-usage) below.
## Advanced usage ##
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
particular build.
```bash
waf list
# Configure the Linux board
./waf configure --board=linux
```
Consequently, in order to build, a "build" command is issued, thus `waf build`.
That is the default command, so calling just `waf` is enough:
```bash
# Build programs from bin group
./waf
# Waf also accepts '-j' option to parallelize the build.
./waf -j8
```
## Program groups ##
By default waf tries to parallelize the build automatically to all processors
so the `-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
the build.
### Program groups ###
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.
@ -70,7 +147,7 @@ to one main group.
@@ -70,7 +147,7 @@ to one main group.
There's a special group, called "all", that comprises all programs.
### Main groups ###
#### Main groups ####
The main groups form a partition of all programs. Besides separating the
programs logically, they also define where they are built.
@ -94,20 +171,20 @@ main group the program belongs to. For example, for a linux build, arduplane,
@@ -94,20 +171,20 @@ main group the program belongs to. For example, for a linux build, arduplane,
which belongs to the main group "bin", will be located at
`build/linux/bin/arduplane`.
### Main products groups ###
#### 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 products groups are:
The main product groups are:
- antennatracker
- copter
- plane
- rover
## Building a program group ##
#### 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
Lucas De Marchi
9 years ago