mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2025-12-16 10:03:50 +01:00
86 lines
3.6 KiB
Plaintext
86 lines
3.6 KiB
Plaintext
---
|
|
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.
|