diff --git a/doc/guides/build-system/build_system.mdx b/doc/guides/build-system/build_system.mdx index b853e71a7d..5431a4f0f7 100644 --- a/doc/guides/build-system/build_system.mdx +++ b/doc/guides/build-system/build_system.mdx @@ -13,7 +13,7 @@ Makefile providing at least the following variables: * `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 +Additionally, it has to include the `Makefile.include`, located in RIOT's root directory: ```make title="a minimal application Makefile" @@ -32,27 +32,54 @@ platform, using the sample Makefile, by invoking make like this: 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. Neither this variable nor -the targets `flash` and `term` are mandatory for the native port. +`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 the additional +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 +`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. +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. - -Learn more about the build system in the -[Wiki](https://github.com/RIOT-OS/RIOT/wiki/The-Make-Build-System)