MAVLINKHUD

The Waf Build System

Executive Summary

ArduPilot uses Waf, a Python-based build automation tool, to manage the compilation of its massive codebase. Unlike Make or CMake, Waf scripts are valid Python programs, allowing for complex logic during the build process.

The wscript in the root directory is the entry point. It handles board configuration, feature selection (via ap_config.h), and task scheduling.

Theory & Concepts

1. Configuration vs. Build

  • Configure: ./waf configure --board=CubeOrange
    • This step scans your system for compilers (arm-none-eabi-gcc), checks dependencies, and generates a build/CubeOrange/ap_config.h file containing #define macros for the specific board.
  • Build: ./waf copter
    • This step compiles the code using the configuration generated in the previous step.

2. The ap_config.h Mechanism

Instead of passing thousands of flags to the compiler (e.g., -DHAL_OSD_ENABLED=1), Waf generates a single header file ap_config.h that is included in every C++ file. This ensures consistent feature flags across the entire build.

Codebase Investigation

1. The Root wscript

Located in wscript.

  • Initialization: The init() function loads the environment and sets up the build context.
  • Options: The options() function defines command-line flags like --enable-scripting, --debug-symbols, and --disable-watchdog.
  • Board Selection: cfg.get_board().configure(cfg) calls the board-specific configuration logic found in Tools/ardupilotwaf/boards.py.

2. Feature Selection

The wscript dynamically enables/disables features based on board capabilities (flash size, memory).

if cfg.options.enable_scripting:
    cfg.env.ENABLE_SCRIPTING = True

This directly maps to #define AP_SCRIPTING_ENABLED 1 in ap_config.h.

Source Code Reference

Practical Guide: Useful Waf Commands

1. Debugging

  • ./waf configure --board=sitl --debug --debug-symbols
    • Disables optimizations (-O0) and adds debug symbols (-g), essential for GDB stepping.

2. Uploading

  • ./waf copter --upload
    • Compiles and immediately attempts to upload the firmware to a connected board via USB.

3. Cleaning

  • ./waf clean
    • Removes build artifacts. Essential if you switch branches or change fundamental defines in hwdef.dat.