---
title: The Build System
description: Learn how the build system in RIOT works
---

RIOT uses [GNU make](https://www.gnu.org/software/make/) as build system. The
simplest way to compile and link an application with RIOT, is to set up a
Makefile providing at least the following variables:

 * `APPLICATION`: should contain the (unique) name of your application
 * `BOARD`: specifies the platform the application should be built for by
   default
 * `RIOTBASE`: specifies the path to your copy of the RIOT repository (note,
   that you may want to use `$(CURDIR)` here, to give a relative path)

Additionally, it has to include the `Makefile.include`, located in RIOT's root
directory:

```make title="a minimal application Makefile"
APPLICATION = mini-makefile
BOARD ?= native
RIOTBASE ?= $(CURDIR)/../RIOT

include $(RIOTBASE)/Makefile.include
```

You can use Make's `?=` operator in order to allow overwriting
variables from the command line. For example, you can easily specify the target
platform, using the sample Makefile, by invoking make like this:

```shell
make BOARD=iotlab-m3
```

## Makefile targets

Besides typical targets like `clean`, `all`, or `doc`, RIOT provides the
special targets `flash` and `term` to invoke the configured flashing and
terminal tools for the specified platform. These targets use the variable
`PORT` for the serial communication to the device, which defaults to
`/dev/ttyACM0` and `/dev/tty.usbmodem*` on Linux and macOS, respectively.
([source](https://github.com/RIOT-OS/RIOT/blob/master/makefiles/tools/serial.inc.mk#L37-L38)).
Setting `MOST_RECENT_PORT=1` enables a more sophisticated serial port selection
algorithm, which selects the most recently connected serial port whose metadata
matches the board's known properties.

For the native port, `PORT` has a special meaning: it is used to identify the
tap interface if the `netdev_tap` module is used. The target `debug` can be
used to invoke a debugger on some platforms. For the native port additional
targets such as `all-valgrind` and `valgrind` exist. Refer to
`cpu/native/README.md` for additional information.

The make target `help` lists all available targets, of which
[the zsh completion script](https://github.com/RIOT-OS/RIOT/blob/master/dist/tools/zsh-completion/zsh-riot.zsh#L96-L126)
offers a short description.

Notable targets include `info-*` targets which provide further information about
the build system. As such, `info-modules` list all (recursively) included modules
in the build, and `info-build` shows more details about the build: among others,
include paths, a list of included Makefiles, and the `CFLAGS` used for the build.

## Build System Internals

### Basic

RIOT uses a recursive Makefile system. The starting point for these structure
is typically the Makefile within the application's Makefile. Among other
variables it sets the path to the RIOT repository as `RIOTBASE`.

### Makefiles

There is a number of special Makefiles in RIOT:

- `Makefile.include` in RIOT module directories: appends target-specific
information to variables like `INCLUDES`, setting the include paths, etc.
- `Makefile.include` in `RIOTBASE`: Part of the internal build system architecture
and should be included in an application's `Makefile` as the last line.
- `Makefile.base`: Meant for inclusion as the last line in a RIOT module's
`Makefile`.
- `Makefile.dep` serves to define dependencies for RIOT modules.
- `makefiles/vars.inc.mk`: All RIOT specific variables used in the Make build
system are listed and briefly explained in Makefile.vars.

Unless specified otherwise, make will create an elf-file as well as an Intel
hex file in the `bin` folder of your application directory.