kaspar/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-12-14 17:13:50 +01:00
Code Releases Activity

Merge pull request #21573 from AnnsAnns/doxygen_deprecation

Browse Source 
doc: Deprecate doxygen guides and sync changes
This commit is contained in:
crasbe 2025-07-21 20:35:32 +00:00 committed by GitHub
commit 20c7f5d0e2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 222 additions and 905 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

211
doc/doxygen/src/advanced-build-system-tricks.md
View File

@ -1,211 +1,6 @@
Advanced build system tricks {#advanced-build-system-tricks}
============================
[TOC]
Introduction {#introduction}
============
This page describes some build systems tricks that can help developers but are
not part of the standard workflow.
They are low level commands that should not be taken as part of a stable API
but better have a documentation than only having a description in the build
system code.
Customize the build system {#customize-build-system}
==========================
+ `RIOT_MAKEFILES_GLOBAL_PRE`: files parsed before the body of
`$RIOTBASE/Makefile.include`
+ `RIOT_MAKEFILES_GLOBAL_POST`: files parsed after the body of
`$RIOTBASE/Makefile.include`
The variables are a list of files that will be included by
`$RIOTBASE/Makefile.include`.
They will be handled as relative to the application directory if the path is
relative.
Usage
-----
You can configure your own files that will be parsed by the build system main
`Makefile.include` file before or after its main body, examples usages can be:
* Globally overwrite a variable, like `TERMPROG`
* Specify a hard written `PORT` / `DEBUG_ADAPTER_ID` for some BOARD values
* Define your custom targets
* Override default targets
Speed-up builds with ccache {#ccache}
===========================
[`ccache`](https://ccache.samba.org/) is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again.
Usually, the initial build takes a little (5% - 20%) longer, but repeated builds are up to ten times faster.
Using `ccache` is safe, as `ccache` tries very hard to not mess up things and falls back to a normal compile if it cannot ensure correct output.
There's one drawback: without further tweaking, `gcc` stops emitting colored output.
Setup
-----
- Install using the package manager of your distribution, e.g., on Ubuntu or Debian:
~~~~~~~~~~~~~~~~~~~
# sudo apt-get install ccache
~~~~~~~~~~~~~~~~~~~
- Set `CCACHE` variable to `ccache`:
~~~~~~~~~~~~~~~~~~~
# export CCACHE=ccache
~~~~~~~~~~~~~~~~~~~
- (Optionally) add the above export line to your `~/.profile`
Result
------
Build without `ccache`:
~~~~~~~~~~~~~~~~~~~
[kaspar@booze default (master)]$ time BOARD=samr21-xpro make clean all
Building application "default" for "samr21-xpro" with MCU "samd21".
[...]
text data bss dec hex filename
37016 180 6008 43204 a8c4 /home/kaspar/src/riot/examples/basic/default/bin/samr21-xpro/default.elf
real 0m12.321s
user 0m10.317s
sys 0m1.170s
[kaspar@booze default (master)]$
~~~~~~~~~~~~~~~~~~~
First build with `ccache` enabled:
~~~~~~~~~~~~~~~~~~~
[kaspar@booze default (master)]$ time BOARD=samr21-xpro make clean all
Building application "default" for "samr21-xpro" with MCU "samd21".
[...]
text data bss dec hex filename
37016 180 6008 43204 a8c4 /home/kaspar/src/riot/examples/basic/default/bin/samr21-xpro/default.elf
real 0m15.462s
user 0m12.410s
sys 0m1.597s
[kaspar@booze default (master)]$
~~~~~~~~~~~~~~~~~~~
Subsequent build with `ccache` enabled:
~~~~~~~~~~~~~~~~~~~
[kaspar@booze default (master)]$ time BOARD=samr21-xpro make clean all
Building application "default" for "samr21-xpro" with MCU "samd21".
[...]
text data bss dec hex filename
37016 180 6008 43204 a8c4 /home/kaspar/src/riot/examples/basic/default/bin/samr21-xpro/default.elf
real 0m2.157s
user 0m1.213s
sys 0m0.327s
[kaspar@booze default (master)]$
~~~~~~~~~~~~~~~~~~~
Analyze dependency resolution {#analyze-depedency-resolution}
=============================
When refactoring dependency handling or modifying variables used for dependency
resolution, one may want to evaluate the impact on the existing applications.
This describe some debug targets to dump variables used during dependency
resolution.
To analyze one board and application run the following commands in an
application directory.
Generate the variables dump with the normal dependency resolution to a
`dependencies_info_board_name` file:
~~~~~~~~~~~~~~~~~~~
BOARD=board_name make dependency-debug
~~~~~~~~~~~~~~~~~~~
Or with the "quick" version used by murdock to know supported boards
(this is an incomplete resolution, details in `makefiles/dependencies_debug.inc.mk`)
to a `dependencies_info-boards-supported_board_name` file:
~~~~~~~~~~~~~~~~~~~
BOARDS=board_name DEPENDENCY_DEBUG=1 make info-boards-supported
~~~~~~~~~~~~~~~~~~~
For more configuration and usage details, see in the file defining the targets
`makefiles/dependencies_debug.inc.mk`
To do a repository wide analysis, you can use the script
`dist/tools/buildsystem_sanity_check/save_all_dependencies_resolution_variables.sh`
that will generate the output for all boards and applications.
It currently take around 2 hours on an 8 cores machine with ssd.
Generate Makefile.ci content {#generate-makefileci}
============================
Most applications and tests include a `Makefile.ci` to indicate which boards can
not compile the application or test. The content for these files can be
generated via the script in
~~~~~~~~~~~~~~~~~~~
make -C $APPLICATION_DIRECTORY generate-Makefile.ci
~~~~~~~~~~~~~~~~~~~
This will compile and link the application for every board available and record
the result in the Makefile.ci. This requires the toolchain for every target to
be available. The target supports using docker via the `BUILD_IN_DOCKER=1`
variable.
Out of Tree Cache Directory {#out-of-tree-cache-dir}
===========================
By exporting the `BUILD_DIR` environment variable, a custom build / clone cache
directory can be created. This can be particularly useful when working with
multiple git work trees or clones of the RIOT repository.
Comparing Build Sizes {#comparing-build-sizes}
=====================
There is a make target for build size comparison. It will automatically check
all the boards compiled in the `NEWBIN` and `OLDBIN` and compare them.
For boards that do not have a complementary partner, a warning is generated.
You can use it like that:
~~~~~~~~~~~~~~~~~~~
$ cd RIOT/test/test_something
$ git checkout master
$ BINDIRBASE=master-bin BOARD=native64 make all
$ git checkout my-branch
$ BINDIRBASE=my-branch-bin BOARD=native64 make all
$ OLDBIN=master-bin NEWBIN=my-branch-bin make info-buildsizes-diff
text data bss dec BOARD/BINDIRBASE
0 0 0 0 native64 **← this line contains the diff**
57356 1532 96769 155657 master-bin
57356 1532 96769 155657 my-branch-bin
...
~~~~~~~~~~~~~~~~~~~
Check it out, the output contains colors. ;)
RIOT-aware Completion in zsh {#zsh-completion-for-riot}
============================
For zsh users a RIOT-aware completion is provided in
`dist/tools/zsh-completion`. Refer to the `README.md` in there for more details
and installation instructions.
@deprecated See [Advanced Build System Tricks](https://guide.riot-os.org/build-system/advanced_build_system_tricks/)
on the RIOT Guide Site for the latest information.
This page will be removed after release 2025.11.

127
doc/doxygen/src/build-in-docker.md
View File

@ -1,125 +1,6 @@
# Build In Docker {#build-in-docker}
Some parts of RIOT's build process can be performed inside a Docker container,
which comes with the necessary compilers and toolchains and is fully managed by
the build system. It can be enabled by passing `BUILD_IN_DOCKER=1` to make.
```shell
$ BUILD_IN_DOCKER=1 make
```
If your user does not have permissions to access the Docker daemon:
```shell
$ BUILD_IN_DOCKER=1 DOCKER="sudo docker" make
```
to always use Docker for building, set `BUILD_IN_DOCKER=1` (and if necessary
`DOCKER="sudo docker"`) in the environment:
```console
$ export BUILD_IN_DOCKER=1
```
## Targets ran in Docker: DOCKER_MAKECMDGOALS_POSSIBLE
Currently only build related targets are ran in the docker container, the exact
list is under `DOCKER_MAKECMDGOALS_POSSIBLE` variable.
## Environment Variables: DOCKER_ENV_VARS
When building in docker one might want for the command ran in docker to inherit
variables that might have been set in the command line. e.g.:
```shell
BOARD=samr21-xpro USEMODULE=xtimer make -C examples/basic/hello-world
```
In `docker.ink.mk` the origin of a variable listed in `DOCKER_ENV_VARS` is checked
and if the origin is `environment` or `command` (for make command-line argument)
then those variables will be passed to the docker container.
You can also set in `DOCKER_ENV_VARS` in the environment to add variables to the
list, e.g.:
```shell
DOCKER_ENV_VARS=BEER_TYPE BEER_TYPE="imperial stout" BUILD_IN_DOCKER=1 make -C examples/basic/hello-world/
docker run --rm -t -u "$(id -u)" \
...
-e 'BEER_TYPE=imperial stout' \
-w '/data/riotbuild/riotbase/examples/basic/hello-world/' \
'riot/riotbuild:latest' make
```
Your application Makefile can also extend `DOCKER_ENV_VARS`.
### Directly Define Environment Variables: DOCKER_ENVIRONMENT_CMDLINE
`DOCKER_ENVIRONMENT_CMDLINE` can be used to add variables directly to the environment
but will need to be prefixed with `-e` (see [option-summary]).
e.g.:
```
DOCKER_ENVIRONMENT_CMDLINE='-e BEER_TYPE="imperial stout"' BUILD_IN_DOCKER=1 make -C examples/basic/hello-world/
docker run --rm -t -u "$(id -u)" \
...
-e 'BEER_TYPE=imperial stout' \
-w '/data/riotbuild/riotbase/examples/basic/hello-world/' \
'riot/riotbuild:latest' make
```
## Command Line Variables: DOCKER_OVERRIDE_CMDLINE
Command line arguments are variables that are passed after `make` e.g.
`make target FOO=bar`, but different to environment variables a variable defined
through the command line will take precedence over all assignments of `FOO` within
the makefile (same effect as adding `-e` for environment variables, see
[option-summary] for more details.
To pass variables overriding the command-line to docker `DOCKER_OVERRIDE_CMDLINE`
may be used:
```shell
DOCKER_OVERRIDE_CMDLINE="BEER_TYPE='imperial stout'" BUILD_IN_DOCKER=1 make -C examples/basic/hello-world/ RIOT_CI_BUILD=1
Launching build container using image "riot/riotbuild:latest".
sudo docker run --rm -t -u "$(id -u)" \
...
-w '/data/riotbuild/riotbase/examples/basic/hello-world/' \
'riot/riotbuild:latest' make BEER_TYPE='imperial stout' 'RIOT_CI_BUILD=1'
```
### Redefined or Overridden Variables: DOCKER_ENV_VARS_ALWAYS
There is a corner case for the handling of `DOCKER_ENV_VARS`. If a variable is
redefined (`+=`, `=`, `:=`) or overridden then the origin of the variable will be changed
to `file` and there is no way of detecting in Make how it was set.
If this happens after `docker.ink.mk` this is not an issue, but for all variables
susceptible to be defined in the application `Makefile` this is indeed the case.
A subset of these variables, namely variables relating to dependency resolution
are therefore unconditionally passed to docker. The complete list can be found
under `DOCKER_ENV_VARS_ALWAYS`.
#### CFLAGS
CFLAGS are not automatically passed to docker because they might contain spaces,
'"' or other characters that will require escaping. The solution is to pass it with
`DOCKER_ENVIRONMENT_CMDLINE` and escape every character as required.
e.g: if wanting to override STRING_WITH_SPACES
```
# normal build
CFLAGS=-DSTRING_WITH_SPACES='\"with space\" make
# in docker
DOCKER_ENVIRONMENT_CMDLINE='-e CFLAGS=-DSTRING_WITH_SPACES=\'\\\"with\ space\\\"\'' \
BUILD_IN_DOCKER=1 make
```
Alternatively, it is often easier to define the CFLAGS in the Makefile which gets
evaluated inside the Docker image again), conditional on a less complex environment
variable that gets added to `DOCKER_ENV_VARS` in the Makefile.
[option-summary]: https://www.gnu.org/software/make/manual/html_node/Options-Summary.html
@deprecated This page is deprecated.
See [Build in Docker](https://guide.riot-os.org/build-system/build-in-docker/)
on the RIOT Guide Site for the latest information.
This page will be removed after release 2025.11.

218
doc/doxygen/src/build-system-basics.md
View File

@ -1,217 +1,5 @@
# Build System Basics {#build-system-basics}
# BOARD, CPU & FEATURES {#board-cpu-features}
## FEATURES {#features}
### What is a FEATURE?
A `FEATURE` is a mean of specifying valid/invalid dependencies and configurations.
Whenever a `FEATURE` is used there should be at some level a hardware requirement,
whether this is a _radio_, a _bus_ of a specific core architecture.
This is not a hard line, in some cases the line can be harder to establish than
others. There are complicated cases like `netif` since a network interface could
be fully implemented in software as a loop-back.
It's also important to note that a `FEATURE` does not mean there is a `MODULE`
with the same name. There could be many implementations for the same `FEATURE`.
The fact that many `FEATURES` translate directly into a `MODULE` is only by
convenience.
e.g.
# all periph features correspond to a periph submodule
USEMODULE += $(filter periph_%,$(FEATURES_USED))
### Providing a FEATURE
For a `FEATURE` to be provided by a `board` it must meet 2 criteria, and for
`periph_%` and other _hw_ (hardware) related `FEATURES` it must follow a 3rd criteria.
- Needs the "hardware" or BSP support (toolchain, build system, flasher, etc.)
- e.g.: `stm32l152re` has an SPI peripheral
`riotboot` needs to be able to link and flash at an offset
- Needs support in RIOT, an implementation of an api to interact with the _hw_
- e.g.: `cpu/stm32_common/periph/spi.c` is implemented for `stm32l1`
`riotboot` needs an implementation of `cpu_jump_to_image`
- Wiring between the _cpu/soc_(system on a chip) a _bus_ and other _cpu_/_hw_ components.
- e.g.: `nucleo-l152re/include/periph_conf.h` specified wiring between `PORT_Ax`
and `SPI1`
### All the FEATURES_%
- `FEATURES_PROVIDED` are available hardware (including BSP) features
(e.g.:`periph_hwrng`, `periph_uart`) or characteristics (e.g:`arch_32bits`) of
a board.
- `FEATURES_CONFLICT` are a series of `FEATURES` that can't be used at the same
time for a particular `BOARD`.
- `FEATURES_REQUIRED` are `FEATURES` that are needed by a `MODULE` or `APPLICATION`
to work.
- `FEATURES_OPTIONAL` are "nice to have" `FEATURES`, not needed but useful. If
available they are always included.
- `FEATURES_REQUIRED_ANY` are `FEATURES` of which (at least) one of
is needed by a `MODULE` or `APPLICATION`. Alternatives are separated by
a pipe (`|`) in order of preference, e.g.:
`FEATURES_REQUIRED_ANY += arch_avr8|arch_native` if both are provide then
`arch_avr8` will be used.
- `FEATURES_BLACKLIST` are `FEATURES` that can't be used by a `MODULE` or `APPLICATION`.
They are usually used for _hw_ characteristics like `arch_` to easily resolve
unsupported configurations for a group.
- `FEATURES_USED` are the final list of `FEATURES` that will be used by an `APPLICATION`
### Where to define FEATURES_%
- `FEATURES_PROVIDED`, `FEATURES_CONFLICT` and `FEATURES_CONFLICT_MSG ` are
defined in `Makefile.features`
- `FEATURES_REQUIRED`, `FEATURES_OPTIONAL`, `FEATURES_REQUIRED_ANY`,
and `FEATURES_BLACKLIST` are defined by the application `Makefile`
(`examples/%/Makefile`, `tests/%/Makefile`, etc.) or in `Makefile.dep`
## CPU/CPU_MODEL {#cpu}
`CPU` and `CPU_MODEL` refer to the _soc_ or _mcu_ (microcontroller)
present in a `BOARD`. The variables `CPU`, `CPU_FAM`, etc. are just arbitrary groupings
to avoid code duplication. How this grouping is done depends on every implementation
and the way each manufacturer groups there products.
These variables allows declaring the `FEATURES` that the _mcu/soc_ provides as well
as resolving dependencies.
`FEATURES` provided by a `CPU/CPU_MODEL` should not depend on the wiring of a
specific `BOARD` but be intrinsic to the _soc/mcu_.
A `CPU/CPU_MODEL` might support `FEATURES` that will depend on the `BOARD` wiring,
e.g.: bus (`uart`, `spi`) mappings. In this cases the `FEATURE` should be provided
by the `BOARD.`
## BOARD {#board}
In RIOTs build-system, a `BOARD` is a grouping of:
- _soc/mcu_ (`CPU/CPU_MODEL`)
- e.g.: `b-l072z-lrwan1` `stm32l072cz`
- _sensor/actuators_ (buttons and leds included) (`drivers`)
- e.g.: `b-l072z-lrwan1` leds and buttons
- _radios_, _ethernet_, etc. devices (`drivers`)
- e.g.: `b-l072z-lrwan1` `sx1276`
- _programming/debugging_ tools
- e.g.: `b-l072z-lrwan1` `stlink`
- configuration mapping cpu support capabilities to availability
- e.g.: `b-l072z-lrwan1` `periph_conf.h`, `gpio_params`
A `board` can have all the required `FEATURES` to interact with a radio or
sensor/actuator, but it doesn't necessarily provide that `FEATURE`.
e.g.:
- `samr21-xpro` provides a `at86rf233` radio as well as the necessary
`periph_*` features.
- `nucleo-*` provide all `periph_*` features to use `sx1272`, and
even a default configuration for the `SX1272MB2xA` shield, but not
doesn't provide the radio.
If a `board` in `$(RIOTBASE)/boards` is connected to a radio shield, sensors,
actuators, etc. then it is a different `board` than the one provided by default.
Whenever you need to have a device mapping (in linux-arm, it would require
a different device tree), then it is a different board and would need a
different `board/periph_conf`.
A `nucleo-*` with a `SX1272MB2xA` is a different board in RIOT sense.
_note_: if `devicetree` is implemented this concept will change.
# Variables declaration guidelines {#variable-declaration-guidelines}
This page contains basic guidelines about `make` variable declaration, it
summarizes some of the pros and cons as well as specifies good and bad patterns
in our build system. You might want to refer to `gnu make` documentation
regarding these subjects.
## Avoid unnecessary export
```
export OUTPUT = $(shell some-command)
```
Exporting a variable means it will be evaluated on every `target` call, which
slows down the build system. Always avoid exporting a variable if unneeded.
If an export is actually needed by a `sub-make` then export the variable only for
the needed targets using `target-export-variables` (more in
`makefiles/utils/variables.mk`).
Exported variables ("global variable") are hard to remove, specially when badly
documented. If no one knows why it's there and no one knows where it can be used
then no one knows if it's safe to remove since it's present for every target.
This is why global variables need clear documentation.
[gnumake doc](https://www.gnu.org/software/make/manual/html_node/Variables_002fRecursion.html)
## Use memoized for variables referencing a function or command
### recursively expanded variable:
~~~~~~~~~~~~~~~~
OUTPUT = $(shell some-command $(ANOTHER_VARIABLE))
~~~~~~~~~~~~~~~~
- When using `=` the value of the variable is only declared, but not set,
therefore the variable will only be evaluated when expanded (used) somewhere
in the makefile. If `$(OUTPUT)` is never expanded, `some-command`
is never executed and `ANOTHER_VARIABLE` not expanded.
- All variables or functions referenced by the declared variable will will be
evaluated every time the variable is expanded.
In the example `some-command` is executed every time `OUTPUT` is expanded, same for
`ANOTHER_VARIABLE`. If `some-command` is slow this introduced unneeded overhead.
- If the variable expansion doesn't involve evaluating a function the overhead
is none.
### simply expanded variable:
~~~~~~~~~~~~~~~~
OUTPUT := $(shell some-command $(ANOTHER_VARIABLE))
~~~~~~~~~~~~~~~~
- When using `:=` the value is only expanded once, expanding any reference to
other variables or functions. If `OUTPUT` is always used at least once and
evaluates a costly function (`some command`) then use `:=`.
- When using `:=` the variable will be evaluated even if not needed, which
introduces unnecessary delay, in particular `some command` or functions
evaluated by `ANOTHER_VARIABLE` are slow.
It can also cause a failure in a worst-case scenario (think what happens if a
tool is defined with `:=` but you don't have the tool and you don't need it either).
- The values of variables declared with `:=` depend on the order of definition.
### memoized:
~~~~~~~~~~~~~~~~
OUTPUT = $(call memoized,OUTPUT,$(shell some-command))
~~~~~~~~~~~~~~~~
- `memoized` is a RIOT defined function that combines characteristics from
both `=` and `:=`.
The variable expansion will be deferred until its first usage, but further
usage will consider it as a simply expanded variable, so it will use the already
evaluated value. In the example `some-command` would be executed once or not
at all (more in `makefiles/utils/variables.mk`).
[gnumake doc](https://www.gnu.org/software/make/manual/html_node/Flavors.html)
## Additional documentation
- Deferred vs. simple expansion: http://make.mad-scientist.net/deferred-simple-variable-expansion/
- Tracking issue: [#10850](https://github.com/RIOT-OS/RIOT/issues/10850)
@deprecated See [Build System Basics](https://guide.riot-os.org/build-system/build_system_basics/)
on the RIOT Guide Site for the latest information.
This page will be removed after release 2025.11.

2
doc/doxygen/src/dev-best-practices.md
View File

@ -3,7 +3,7 @@
[TOC]
* Use the [methodology](#methodology) described below.
* Use [`ccache`](@ref ccache) to speedup compilation
* Use [`ccache`](https://guide.riot-os.org/build-system/advanced_build_system_tricks/#speed-up-builds-with-ccache) to speedup compilation
## Coding "Dos" and "Don'ts": {#coding-dos-and-donts}

332
doc/doxygen/src/getting-started.md
View File

@ -3,284 +3,17 @@ Getting started {#getting-started}
[TOC]
Downloading RIOT code {#downloading-riot-code}
=====================
You can obtain the latest RIOT code from
our [Github](https://github.com/RIOT-OS/) repository either by
[downloading the latest tarball](https://github.com/RIOT-OS/RIOT/releases) or
by cloning the [git repository](https://github.com/RIOT-OS/RIOT).
In order to clone the RIOT repository, you need the
[Git revision control system](http://git-scm.com/) and run the following
command:
~~~~~~~~ {.sh}
git clone https://github.com/RIOT-OS/RIOT.git
~~~~~~~~
Compiling RIOT {#compiling-riot}
==============
Required Software for Development {#setting-up-a-toolchain}
-----------------------------------------------------------
A set of common tools and a toolchain for the hardware you target needs to be installed first.
### Choosing an Operating System for the Development PC
#### Linux
Most of the RIOT OS developers are using Linux on their development PCs, so
you can expect the most streamlined experience here.
Not all distributions have packages for cross-compilation for microcontrollers
and non-x86 platforms such as ARM.
Ubuntu works well for cross-development, Fedora for example does not provide
the necessary packages.
However, with most distributions, you can use the
[RIOT Docker container](@ref build-in-docker) as an alternative.
Other POSIX-compliant OSes such as the various BSD flavours
will also be fine - however, we rely on users to report bugs regarding tooling incompatibilities
here. So expect occasional issues for the development branch and please help testing during the
feature freeze period, if you develop on macOS or BSD.
#### Windows
Windows users can refer to [this guide][dev-setup-windows] to setup the
development environment on Windows which guides through the process of
setting up the
[Windows Subsystem for Linux (WSL)](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux).
[dev-setup-windows]: https://guide.riot-os.org/getting-started/install-wsl/
#### MacOS
Native development on macOS machines is not officially supported.
Some packages can be found in the homebrew repositories, but the installation
is not trivial, especially for different microcontroller platforms.
As an alternative, the [RIOT Docker Container](@ref build-in-docker) can be used
or a virtual machine running Linux. The latter option has a significant
performance reduction compared to Docker.
### Common Tools
The following tools are required or useful regardless of the architecture and board you are
developing for:
* Essential system development tools (GNU Make GCC, standard C library headers)
* git
* GDB in the multiarch variant (alternatively: install for each architecture you target the
corresponding GDB package)
* unzip or p7zip
* wget or curl
* python3
* pyserial (linux distro package often named python3-serial or py3-serial)
* psutil (python3-psutil or py3-psutil)
* Doxygen for building the documentation
@note For each architecture a default tool for flashing and on-chip debugging is listed below - in
most cases OpenOCD. However, some boards use different tools, e.g. because a bootloader is
installed that allows flashing via the serial interface. Check the board documentation for any
details on this. If that documentation contains no info about a flashing tool, the default
tool for its architecture is used.
For example, in Ubuntu the above tools can be installed with the following command:
sudo apt install git gcc-arm-none-eabi make gcc-multilib libstdc++-arm-none-eabi-newlib\
openocd gdb-multiarch doxygen wget unzip python3-serial python3-psutil
@details Running `BOARD=<INSERT_TARGET_BOARD_HERE> make info-programmers-supported` in your
application folder lists the programmers supported by RIOT for the given board.
### Architecture: ARM7 and ARM Cortex M*
* GCC, binutils, and newlib for `arm-none-eabi`
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* OpenOCD for debugging/flashing (most boards)
* Some boards use UF2 based bootloaders, which require auto-mounting to work with `make flash`
* Some boards default to using J-Link for flashing/debugging. Either install that or export
`PROGRAMMER=openocd` to just use OpenOCD instead
* installation instructions can be found [here](https://github.com/RIOT-OS/RIOT/wiki/OpenOCD)
* Optional: picolibc for `arm-none-eabi` to link against picolibc instead of newlib
* Optional: clang to build with `TOOLCHAIN=llvm`
* Optional: GDB multiarch for debugging
* If no multiarch package is available, use GDB for `arm-none-eabi` instead
### Architecture: Xtensa
#### ESP32
* @ref esp32_toolchain "Toolchain for ESP32"
* [esptool](https://github.com/espressif/esptool) for flashing
* Optional: OpenOCD and GDB (multiarch version) for @ref esp32_jtag_debugging "debugging via JTAG"
#### ESP8266
* @ref esp8266_toolchain "Toolchain for ESP8266"
* [esptool](https://github.com/espressif/esptool) for flashing
* Optional: GDB (multiarch version) for @ref esp8266_esp_gdbstub "debugging via the gdbstub"
interface for the ESP8266
### Architecture: AVR
* GCC and binutils for AVR and avrlibc
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* avrdude for flashing
* Optional: AVaRICE and GDB (multiarch version) for debugging
### Architecture: RISC-V
* GCC, binutils, and newlib for RISC-V (target triple should start with `riscv` and end with
`-none-elf` or `-unknown-elf`. Note that most packages are multilib, e.g. `riscv64-unknown-elf`
will likely work fine for 32 bit RISC-V boards)
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* OpenOCD for debugging/flashing (some new boards might require a patched version of OpenOCD or a
recent build from the git sources)
* Optional: picolibc to link against picolibc instead of newlib (recommended)
* Optional: clang to build with `TOOLCHAIN=llvm`
* Optional: GDB multiarch for debugging
### Architecture: MSP430
* GCC, binutils, and newlib for MSP430
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* [mspdebug](https://github.com/dlbeer/mspdebug) for flashing/debugging
* Optional: [MSP Debug Stack](https://www.ti.com/tool/download/MSPDS-OPEN-SOURCE) for additional
board support
* Optional: GDB multiarch for debugging
### Architecture: native
* On 64 bit systems: multilib versions for your host compilers, standard C library, and development
headers
* Alternatively: Compile with `BUILD_IN_DOCKER=1`. Note that for running the executable you
still need a multilib system (or 32 bit Linux) with glibc a standard C library.
* A C library supporting the deprecated POSIX.1-2001 ucontext library (e.g. glibc, FreeBSD's libc)
* Optional: GDB for debugging. (Prefer the multiarch version, this will also work for other boards)
@deprecated See [Setup Guide](https://guide.riot-os.org/getting-started/installing/#architecture-specific-requirements) on the RIOT Guide Site for the latest information. This section will be removed after release 2025.11.
The build system {#the-build-system}
----------------
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)
@deprecated See [The Build System](https://guide.riot-os.org/build-system/build_system/) on the RIOT Guide Site for the latest information. This section will be removed after release 2025.11.
Additionally it has to include the `Makefile.include`, located in RIOT's root
directory:
~~~~~~~~ {.mk}
# 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:
~~~~~~~~ {.sh}
make BOARD=iotlab-m3
~~~~~~~~
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. Neither this variable nor
the targets `flash` and `term` are mandatory for the native port.
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 the additional
targets such as `all-valgrind` and `valgrind` exist. Refer to
`cpu/native/README.md` for additional information
Some RIOT directories contain special Makefiles like `Makefile.base`,
`Makefile.include` or `Makefile.dep`. The first one can be included into other
Makefiles to define some standard targets. The files called `Makefile.include`
are used in `boards` and `cpu` to append target specific information to
variables like `INCLUDES`, setting the include paths. `Makefile.dep` serves to
define dependencies.
Unless specified otherwise, make will create an elf-file as well as an Intel
hex file in the `bin` folder of your application directory.
Learn more about the build system in the
[Wiki](https://github.com/RIOT-OS/RIOT/wiki/The-Make-Build-System)
Building and executing an example {#building-and-executing-an-example}
---------------------------------
RIOT provides a number of examples in the `examples/` directory. Every example
has a README that documents its usage and its purpose. You can build them by
opening a shell, navigating to an example (e.g. `examples/basic/default`), and
running:
~~~~~~~~ {.sh}
make BOARD=samr21-xpro
~~~~~~~~
or
~~~~~~~~ {.sh}
make all BOARD=samr21-xpro
~~~~~~~~
To flash the application to a board just run:
~~~~~~~~ {.sh}
make flash BOARD=samr21-xpro
~~~~~~~~
You can then access the board via the serial interface:
~~~~~~~~ {.sh}
make term BOARD=samr21-xpro
~~~~~~~~
If you are using multiple boards you can use the `PORT` macro to specify the
serial interface:
~~~~~~~~ {.sh}
make term BOARD=samr21-xpro PORT=/dev/ttyACM1
~~~~~~~~
For flashing and accessing the board via the serial interface, the current user
needs to have the correct access rights on the serial device.
The easiest way to ensure this is to add the current user to the group that is
owning the serial device. For example, this can be achieved on Linux by issuing
the following line, logging out and logging in again:
~~~~~~~~ {.sh}
sudo usermod -aG $(stat --format="%G" /dev/ttyACM0) $USER
~~~~~~~~
Note that the `PORT` macro has a slightly different semantic in `native`. Here
it is used to provide the name of the TAP interface you want to use for the
virtualized networking capabilities of RIOT.
We use `pyterm` as the default terminal application. It is shipped with RIOT in
the `dist/tools/pyterm/` directory. If you choose to use another terminal
program you can set `TERMPROG` (and if need be the `TERMFLAGS`) macros:
~~~~~~~~ {.sh}
make -C examples/networking/gnrc/gnrc_networking/ term \
BOARD=samr21-xpro \
TERMPROG=gtkterm \
TERMFLAGS="-s 115200 -p /dev/ttyACM0 -e"
~~~~~~~~
You may not see the greeting
main(): This is RIOT!
when you flash the board. In this case, type `reboot` in the command line or reboot manually.
@deprecated See [Building and executing an example](https://guide.riot-os.org/getting-started/building_example/) on the RIOT Guide Site for the latest information. This section will be removed after release 2025.11.
Configuring an application {#configuring-an-application}
--------------------------
@ -308,68 +41,13 @@ present in the target platform.
Use Docker to build RIOT {#docker}
========================
[Docker](https://www.docker.com/) is a platform that allows packaging software into containers that can easily be run on any Linux that has Docker installed.
You can download a RIOT Docker container from the Docker Hub and then use that to build your project making use of all toolchains that we've preinstalled in the container.
It can be helpful to use Docker especially if you are working with ESP, since the
installation might be easier this way.
Setup {#docker-setup}
-----
### Installing docker
To use the RIOT docker build image, the Docker application needs to be installed on your system.
To install Docker, depending on your operating system, use `sudo apt-get install docker` or a variant.
The user on your computer requires permission to access and use docker. There are two ways to manage this:
- Your OS distribution may create a group called `docker`. If so, then adding yourself to that group (and logging out and in again) should grant you permission.
- Execute docker with sudo. This is in fact the most secure and recommended setup (see [here](https://docs.docker.com/install/linux/linux-postinstall/), [here](https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface), [here](https://www.projectatomic.io/blog/2015/08/why-we-dont-let-non-root-users-run-docker-in-centos-fedora-or-rhel/) and [here](https://fosterelli.co/privilege-escalation-via-docker.html)). No extra setup steps are needed. `make` should be instructed to use `sudo` by setting `DOCKER="sudo docker"` in the command line.
Usage
-----
The RIOT build system provides support for using a Docker container containing all necessary tools to build RIOT projects.
The latest image is automatically fetched from the Docker Hub, so you just have to execute the
build command like this:
(**from the directory you would normally run make, e.g. examples/basic/default**)
```console
$ make BUILD_IN_DOCKER=1
```
If your user does not have permissions to access the Docker daemon:
```console
$ make BUILD_IN_DOCKER=1 DOCKER="sudo docker"
```
to always use Docker for building, set `BUILD_IN_DOCKER=1` (and if necessary `DOCKER="sudo docker"`) in the environment:
```console
$ export BUILD_IN_DOCKER=1
```
running make without specifying `BUILD_IN_DOCKER=1` will still use Docker (because of the environment variable)
Troubleshooting {#docker-troubleshooting}
---------------
On some Ubuntu versions a make with `BUILD_IN_DOCKER=1` can't resolve the host name of for example github.com. To fix this add the file `/etc/docker/daemon.json` with the address of your DNS Server.
For more details see @ref build-in-docker.
@deprecated See [Setup Guide](https://guide.riot-os.org/getting-started/installing/) or [Build in Docker](https://guide.riot-os.org/build-system/build-in-docker/) on the RIOT Guide Site for the latest information. This section will be removed after release 2025.11.
Generating compile_commands.json e.g. for code completion in IDEs
=================================================================
A `compile_commands.json` for the selected board can be generated by running inside the application
folder the following:
```console
$ make compile-commands
```
See [Setup Guide](https://guide.riot-os.org/getting-started/installing/#using-vs-code-for-development) for a guide on how to set up VS Code for RIOT development using the `compile_commands.json` file.
This target will honor the variables controlling the build process such as `BOARD`, `TOOLCHAIN`,
`DEVELHELP`, etc. just like the usual build process. This works without actual compilation. By

30
doc/doxygen/src/mainpage.md
View File

@ -48,33 +48,15 @@ RIOT is developed by an open community that anyone is welcome to join:
[mastodon-link]: https://floss.social/@RIOT_OS
The quickest start {#the-quickest-start}
Getting Started
==================
You can run RIOT on most IoT devices, on open-access testbed hardware (e.g.
IoT-lab), and also directly as a process on your Linux or FreeBSD machine (we
call this the `native` port). Try it right now in your terminal window:
~~~~~~~{.sh}
git clone https://github.com/RIOT-OS/RIOT.git # assumption: git is pre-installed
cd RIOT
git checkout <LATEST_RELEASE>
sudo ./dist/tools/tapsetup/tapsetup # create virtual Ethernet
# interfaces to connect multiple
# RIOT instances
cd examples/basic/default/
make all
make term
~~~~~~~
To get started with RIOT, you can follow the
[Setup Guide](https://guide.riot-os.org/getting-started/installing/) on
the RIOT Guide Site. This guide will help you to set up your development
environment, build and run your first application, and configure RIOT for
your specific hardware.
... and you are in the RIOT shell!
Type `help` to discover available commands. For further information see the
[README of the `default` example](https://github.com/RIOT-OS/RIOT/tree/master/examples/basic/default).
To use RIOT directly on your embedded platform, and for more hands-on details
with RIOT, see @ref getting-started.
Before that, skimming through the next section is recommended (but not
mandatory).
Structure {#structure}
=========

105
doc/guides/build-system/advanced_build_system_tricks.md
View File

@ -23,6 +23,84 @@ You can configure your own files that will be parsed by the build system main `M
- Define your custom targets
- Override default targets
## Speed-up builds with ccache
[`ccache`](https://ccache.samba.org/) is a compiler cache. It speeds up recompilation by caching previous compilations and detecting when the same compilation is being done again.
Usually, the initial build takes a little (5% - 20%) longer, but repeated builds are up to ten times faster.
Using `ccache` is safe, as `ccache` tries very hard to not mess up things and falls back to a normal compile if it cannot ensure correct output.
There's one drawback: without further tweaking, `gcc` stops emitting colored output.
### Setup
- Install using the package manager of your distribution, e.g., on Ubuntu or Debian:
```shell
sudo apt-get install ccache
```
- Set `CCACHE` variable to `ccache`:
```shell
export CCACHE=ccache
```
- (Optionally) add the above export line to your `~/.profile`
### Result
Build without `ccache`:
```sh
[kaspar@booze default (master)]$ time BOARD=samr21-xpro make clean all
Building application "default" for "samr21-xpro" with MCU "samd21".
[...]
text data bss dec hex filename
37016 180 6008 43204 a8c4 /home/kaspar/src/riot/examples/basic/default/bin/samr21-xpro/default.elf
real 0m12.321s
user 0m10.317s
sys 0m1.170s
[kaspar@booze default (master)]$
```
First build with `ccache` enabled:
```sh
[kaspar@booze default (master)]$ time BOARD=samr21-xpro make clean all
Building application "default" for "samr21-xpro" with MCU "samd21".
[...]
text data bss dec hex filename
37016 180 6008 43204 a8c4 /home/kaspar/src/riot/examples/basic/default/bin/samr21-xpro/default.elf
real 0m15.462s
user 0m12.410s
sys 0m1.597s
[kaspar@booze default (master)]$
```
Subsequent build with `ccache` enabled:
```sh
[kaspar@booze default (master)]$ time BOARD=samr21-xpro make clean all
Building application "default" for "samr21-xpro" with MCU "samd21".
[...]
text data bss dec hex filename
37016 180 6008 43204 a8c4 /home/kaspar/src/riot/examples/basic/default/bin/samr21-xpro/default.elf
real 0m2.157s
user 0m1.213s
sys 0m0.327s
[kaspar@booze default (master)]$
```
## Analyze dependency resolution
When refactoring dependency handling or modifying variables used for dependency resolution, one may want to evaluate the impact on the existing applications. This describe some debug targets to dump variables used during dependency resolution.
@ -59,6 +137,33 @@ This will compile and link the application for every board available and record
By exporting the `BUILD_DIR` environment variable, a custom build / clone cache directory can be created. This can be particularly useful when working with multiple git work trees or clones of the RIOT repository.
## Comparing Build Sizes
There is a make target for build size comparison. It will automatically check
all the boards compiled in the `NEWBIN` and `OLDBIN` and compare them.
For boards that do not have a complementary partner, a warning is generated.
You can use it like that:
```sh
$ cd RIOT/test/test_something
$ git checkout master
$ BINDIRBASE=master-bin BOARD=native64 make all
$ git checkout my-branch
$ BINDIRBASE=my-branch-bin BOARD=native64 make all
$ OLDBIN=master-bin NEWBIN=my-branch-bin make info-buildsizes-diff
text data bss dec BOARD/BINDIRBASE
0 0 0 0 native64 **← this line contains the diff**
57356 1532 96769 155657 master-bin
57356 1532 96769 155657 my-branch-bin
...
```
Check it out, the output contains colors. ;)
## RIOT-aware Completion in zsh
For zsh users a RIOT-aware completion is provided in `dist/tools/zsh-completion`. Refer to the `README.md` in there for more details and installation instructions.

4
doc/guides/build-system/build-in-docker.md
View File

@ -84,11 +84,11 @@ To pass variables overriding the command-line to docker `DOCKER_OVERRIDE_CMDLINE
may be used:
```shell
DOCKER_OVERRIDE_CMDLINE="BEER_TYPE='imperial stout'" BUILD_IN_DOCKER=1 make -C examples/hello-world/ RIOT_CI_BUILD=1
DOCKER_OVERRIDE_CMDLINE="BEER_TYPE='imperial stout'" BUILD_IN_DOCKER=1 make -C examples/basic/hello-world/ RIOT_CI_BUILD=1
Launching build container using image "riot/riotbuild:latest".
sudo docker run --rm -t -u "$(id -u)" \
...
-w '/data/riotbuild/riotbase/examples/hello-world/' \
-w '/data/riotbuild/riotbase/examples/basic/hello-world/' \
'riot/riotbuild:latest' make BEER_TYPE='imperial stout' 'RIOT_CI_BUILD=1'
```

BIN
doc/guides/getting-started/img/06-Use_VS_Code-00.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 60 KiB

BIN
doc/guides/getting-started/img/06-Use_VS_Code-01.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 60 KiB

98
doc/guides/getting-started/installing.mdx
View File

@ -47,7 +47,7 @@ This is especially useful if you want to avoid installing the required software
Depending on the operation distribution you are using, the installation of the required software packages may vary.
##### Ubuntu
#### Ubuntu
```bash title="Ubuntu command to install required packages"
sudo apt install make gcc-multilib python3-serial wget unzip git openocd gdb-multiarch esptool podman-docker clangd clang
@ -109,8 +109,6 @@ The app should behave the same when run on real hardware.
## Using VS Code for Development
![Ubuntu terminal running `make compile-commands` in the `hello-world` app](img/06-Use_VS_Code-00.png)
- If not already open, open the terminal
- Confirm that the terminal is pointed to the folder `~/RIOT/examples/basic/hello-world`
- The blue part left of the prompt (the `$` sign in the terminal) shows
@ -120,14 +118,14 @@ The app should behave the same when run on real hardware.
- Inside `~/RIOT/examples/basic/hello-world` run the command `make compile-commands`
- The output should look like above
![Launching VS Code from Ubuntu](img/06-Use_VS_Code-01.png)
![Ubuntu terminal running `make compile-commands` in the `hello-world` app](img/06-Use_VS_Code-01.png)
- Navigate back to `~/RIOT` using the command `cd ~/RIOT`
- run `code .` to launch VS Code
- This will take a bit longer on the first launch
- Eventually, a VS Code Window should pop up that looks like this:
![VS Code as opened from WSL](img/06-Use_VS_Code-02.png)
![VS Code opened via shell](img/06-Use_VS_Code-02.png)
1. Click on "Yes, I trust the authors"
@ -192,3 +190,93 @@ Re-run `make compile-commands` when:
Congratulations! You just compiled your first RIOT application. To run RIOT
on real hardware, proceed with the next to sections.
## Architecture Specific Requirements
:::caution[Don't get lost]
If this section overwhelms you, don’t worry, you can always come back to it later.
This is only important if you want to develop for a specific architecture or board.
For now everything should work fine with the packages installed above.
You can safely skip this section if you are just getting started with RIOT
and want to try out the examples or develop for the `native` board.
:::
For each architecture a default tool for flashing and on-chip debugging is listed below - in
most cases OpenOCD. However, some boards use different tools, e.g. because a bootloader is
installed that allows flashing via the serial interface. Check the board documentation for any
details on this. If that documentation contains no info about a flashing tool, the default
tool for its architecture is used.
:::tip
Running `BOARD=<INSERT_TARGET_BOARD_HERE> make info-programmers-supported` in your
application folder lists the programmers supported by RIOT for the given board.
:::
#### Architecture: ARM7 and ARM Cortex M*
* GCC, binutils, and newlib for `arm-none-eabi`
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* OpenOCD for debugging/flashing (most boards)
* Some boards use UF2 based bootloaders, which require auto-mounting to work with `make flash`
* Some boards default to using J-Link for flashing/debugging. Either install that or export
`PROGRAMMER=openocd` to just use OpenOCD instead
* installation instructions can be found [here](https://github.com/RIOT-OS/RIOT/wiki/OpenOCD)
* Optional: picolibc for `arm-none-eabi` to link against picolibc instead of newlib
* Optional: clang to build with `TOOLCHAIN=llvm`
* Optional: GDB multiarch for debugging
* If no multiarch package is available, use GDB for `arm-none-eabi` instead
#### Architecture: Xtensa
##### ESP32
* [Toolchain for ESP32](https://doc.riot-os.org/group__cpu__esp32.html#esp32_toolchain)
* [esptool](https://github.com/espressif/esptool) for flashing
* Optional: OpenOCD and GDB (multiarch version) for [debugging via JTAG](https://doc.riot-os.org/group__cpu__esp32.html#esp32_jtag_debugging)
##### ESP8266
* [Toolchain for ESP8266](https://doc.riot-os.org/group__cpu__esp8266.html#esp8266_toolchain)
* [esptool](https://github.com/espressif/esptool) for flashing
* Optional: GDB (multiarch version) for [debugging via the gdbstub](https://doc.riot-os.org/group__cpu__esp8266.html#esp8266_esp_gdbstub)
interface for the ESP8266
#### Architecture: AVR
* GCC and binutils for AVR and avrlibc
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* avrdude for flashing
* Optional: AVaRICE and GDB (multiarch version) for debugging
#### Architecture: RISC-V
* GCC, binutils, and newlib for RISC-V (target triple should start with `riscv` and end with
`-none-elf` or `-unknown-elf`. Note that most packages are multilib, e.g. `riscv64-unknown-elf`
will likely work fine for 32 bit RISC-V boards)
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* OpenOCD for debugging/flashing (some new boards might require a patched version of OpenOCD or a
recent build from the git sources)
* Optional: picolibc to link against picolibc instead of newlib (recommended)
* Optional: clang to build with `TOOLCHAIN=llvm`
* Optional: GDB multiarch for debugging
#### Architecture: MSP430
* GCC, binutils, and newlib for MSP430
* Alternatively: Install docker and export `BUILD_IN_DOCKER=1`
* [mspdebug](https://github.com/dlbeer/mspdebug) for flashing/debugging
* Optional: [MSP Debug Stack](https://www.ti.com/tool/download/MSPDS-OPEN-SOURCE) for additional
board support
* Optional: GDB multiarch for debugging
#### Architecture: native
* On 64 bit systems: multilib versions for your host compilers, standard C library, and development
headers
* Alternatively: Compile with `BUILD_IN_DOCKER=1`. Note that for running the executable you
still need a multilib system (or 32 bit Linux) with glibc a standard C library.
* A C library supporting the deprecated POSIX.1-2001 ucontext library (e.g. glibc, FreeBSD's libc)
* Optional: GDB for debugging. (Prefer the multiarch version, this will also work for other boards)