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.
RIOT_MAKEFILES_GLOBAL_PRE: files parsed before the body of
RIOT_MAKEFILES_GLOBAL_POST: files parsed after the body of
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.
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:
DEBUG_ADAPTER_IDfor some BOARD values
When developing and working with multiple boards the default
PORT configuration for a particular board might not apply anymore so
PORT will need to be specified whenever calling
make term/test. This can also happen if multiple
DEBUGGERS/PROGRAMMERS are present so
DEBUG_ADAPTER_ID will also need to be passed. Keeping track of this will become annoying.
One way of handling this is to use
udev rules to define
SYMLINKS between the boards serial port (
riot/tty-<board-name>) and the actual serial port (dev/ttyACM* or other). With this we can query the rest of the boards serial
dev information (
PORT, etc.) to always flash and open a terminal on the correct port.
udevadm info /dev/ttyACM0 to query the udev database for information on device on port
udevadm info --attribute-walk --name /dev/ttyACM0 for more detailed output when the first level of information isn't enough
udevadm control --reload-rules
PORTare symlinked to /dev/riot/tty-
makefile.prethat will query the real
RIOT_MAKEFILES_GLOBAL_PREas an environment variable or on each
note: if set as an environment variable it would be a good idea to add a variable to enable/disable it, e.g:
The above procedure works fine when handling different boards, but not multiple times the same board, e.g: multiple
An option for this would be to add an identifier of that board to the mapped
riot/tty-*, there are multiple ways of handling this but in the end it means having a way to identify every copy.
Another way would be to map the
DEBUG_ADAPTER_ID in the name:
But it will require to know in advance the serial number of each board you want to use. Another option would be to add some kind of numbering and defining multiple symlinks for each board. e.g. for
Then, when flashing, the number can be specified and the parsing adapted:
In the end, this would be the same as using the serial, but a simple number might be easier to handle.
Udev only parses SUBSYSTEM and one parent. For others, we will rely on ENV variables defined by 60-serial.rules
So the current filename should be higher than 60-serial.rules
If for some reason re-writing the serial is needed there is a windows tool: https://remoteqth.com/wiki/index.php?page=How+to+set+usb+device+SerialNumber
This is a simpler approach to the above mentioned issue. The solution here only uses a makefile script for selecting the debugger and serial port. No administrative privileges (e.g. to configure Udev) are required.
One of the limitations of the solution described here is that it currently doesn't work with multiple boards of the same type. This limitation is a limitation of the script and not of the mechanism used, it is possible to adapt the script to support multiple boards of the same type. This modification is left as an exercise to the reader.
The following Make snippet is used:
The array of board serial numbers has to be edited to match your local boards. The serial numbers used here is the USB device serial number as reported by the debugger hardware. With the
make list-ttys it is reported as the 'serial':
When the above make snippet is included as
RIOT_MAKEFILES_GLOBAL_PRE, the serial number of the USB device is automatically set if the used board is included in the script. This will then ensure that the board debugger is used for flashing and the board serial device is used when starting the serial console.
It supports command line parameters to filter by vendor name, model name, serial number, or driver. In addition, the
--most-recent argument will only print the most recently added interface (out of those matching the filtering by vendor, model, etc.). The
--format path argument will result in only the device path being printed for convenient use in scripts.
MOST_RECENT_PORT=1 as environment variable or as parameter to make will result in the most recently connected board being preferred over the default PORT for the selected board.
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
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
For more configuration and usage details, see in the file defining the targets
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.