guides/build-system: document more targets

mguetschow · crasbe · mguetschow · commit 31e2d2ff3202 · 2025-12-03T09:52:44.000+01:00
Co-authored-by: crasbe &lt;crasbe@gmail.com&gt;
diff --git 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.
+
+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
 
-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.
+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)
