|
modm API documentation
|
lbuild module: modm:build:scons
SCons is a software construction build system written in Python. For a better embedded experience, we've extended it with modm-specific build tools.
This module generates two files:
modm/SConscript file: configures all required SCons tools with the right settings (also using information from the modm:build module) to compile the modm library.SConstruct file: configures additional, optional tools and sets up all the relevant SCons functions for your target.The SConscript file is self contained and does not depend on anything outside of the modm/ directory. This allows it to be combined with SConscript of other projects without clashing.
In fact, if you look at your generated SConstruct file, you'll notice that it doesn't contain a lot of logic or specific data, it is only meant for calling the right SCons tool with the right arguments.
We do not intend to serve every possible use-case with this module. If you need something special, write your own SConstruct file, maybe starting by modifying ours. It is intentionally BSD-licensed so that you do not have to publish your changes to it.
Remember to set modm:build:scons:include_sconstruct to False, so that your custom SConstruct does not get overwritten by lbuild build. See the instructions inside our generated default SConstruct file.
This module generates these SCons methods depending on the target.
Defaults to scons build size.
You can add these arguments to any of the SCons commands:
verbose=1: gives a more verbose output, so you can, for example, check what options the compiler is called with.profile=release: Compile project with the release profile options (default).profile=debug: Compile project with the debug profile options.For a description of the release and debug profiles, see the modm:build module documentation.
profile=debug to all commands, especially scons program profile=debug and scons debug profile=debug!Some SCons commands take a firmware={GNU Build ID or path/to/firmware.elf} argument that specifies which firmware to use for the command. It is useful in combination with the scons artifact command to preserve a specific firmware version for later.
Compiles your application into an executable.
Example for a STM32 target:
Cleans the build artifacts.
Displays the static Flash and RAM consumption of your target.
Example for a STM32 target with 16MB external heap:
Writes the executable onto your target via Avrdude or OpenOCD. This is a convenience wrapper around the programming options and methods defined in the modm:build module. (* only AVR and ARM Cortex-M targets)
Example for a STM32 target:
Writes all fuses onto your target connected to avrdude. See the modm:platform:core module for how to define the fuse values. (* only AVR targets)
Writes the executable onto your target via Device Firmware Update (DFU) over USB. A DFU bootloader is available on many STM32 microcontrollers and can be accessed by pressing the BOOT0-Button during startup.
Some DFU devices require additional delay to re-enumerate, which you can specify with the delay parameter (default is 5 seconds). (* only ARM Cortex-M targets)
Black Magic Probe is convenient tool to convert cheap USB ST-LINK V2 clones to a fully functional GDB compatible debug adaptor for ARM Cortex microcontrollers. GDB can directly communicate with the debug adaptor making debugging easy and accessible. (* only ARM Cortex-M targets)
Black Magic Probe creates two serial devices, the first being the GDB interface and the second a plain serial adaptor for debugging purposes.
You can let the tool guess the port or explicitly specify it:
Writes the executable onto your target connected to a remote backend process running on your own computer (host=":3333") or somewhere else. You can also connect to JLink (host=":2331") or Black Magic Probe (host="/dev/tty.usbserial"). (* only ARM Cortex-M targets)
Writes the executable onto your target via JLink. This is a convenience wrapper around the programming options and methods defined in the modm:build module. (* only ARM Cortex-M targets)
Example for a STM32 target:
Starts an OpenOCD process to attach a remote debugger to (e.g. with scons program-remote or scons debug-remote). (* only ARM Cortex-M targets)
Starts a JLinkGDBServer process to attach a remote debugger to (e.g. with scons program-remote or scons debug-remote). (* only ARM Cortex-M targets)
Compiles and executes your program on your computer. (* only Hosted targets)
Launches OpenOCD in the background, then launches GDB in foreground with the correct executable with text-based or web-based GDBGUI UI. When GDB exits, it stops the OpenOCD process. (* only ARM Cortex-M targets)
This is just a convenience wrapper for the debug functionality defined in the modm:build module. To use GDBGUI you must have it installed via pip install gdbgui.
scons debug profile=release, and if that doesn't help, compile and scons program profile=debug and try scons debug profile=debug again.Debugs the executable via a remote OpenOCD process running on your own computer (host=":3333") or somewhere else. You can also connect to JLink (host=":2331") or Black Magic Probe (host="/dev/tty.usbserial"). (* only ARM Cortex-M targets)
Launches GDB to debug via Black Magic Probe. (* only ARM Cortex-M targets)
Launches GDB to debug via JLink. (* only ARM Cortex-M targets)
Launches GDB for post-mortem debugging with the firmware identified by the (optional) firmware={hash or filepath} argument using the data from the coredump={filepath} argument. Note that CrashDebug must be in your path, see the modm:crashcatcher module for details.
Use the scons coredump method to generate a coredump with a debugger attached, otherwise see the modm:platform:fault module for details how to generate and receive the coredump data from the device itself. (* only ARM Cortex-M targets)
Launches GDB via OpenOCD and creates a coredump.txt file containing all volatile memories and prints the GNU build ID of the firmware under debug. Note that this command does not require an ELF file, so it can be used to coredump any firmware whose ELF file is currently unavailable. You can use the GNU build ID to find the corresponding ELF file in your artifact store (see scons artifact). (* only ARM Cortex-M targets)
Creates a coredump via Black Magic Probe. (* only ARM Cortex-M targets)
Creates a coredump via JLink. (* only ARM Cortex-M targets)
Resets the executable via OpenOCD. (* only ARM Cortex-M targets)
Resets the executable via Black Magic Probe. (* only ARM Cortex-M targets)
Resets the executable via JLink. (* only ARM Cortex-M targets)
Resets the executable via a remote OpenOCD process running on your own computer (host=":3333") or somewhere else. You can also connect to JLink (host=":2331") or Black Magic Probe (host="/dev/tty.usbserial"). (* only ARM Cortex-M targets)
Configures OpenOCD in tracing mode to output ITM channel 0 on SWO pin and displays the serial output stream. (* only ARM Cortex-M targets)
See the modm:platform:itm module for details how to use the ITM as a logging output.
Outputs the ITM channel via JLinkSWOViewer. Note that JLink auto-detects the CPU frequency. (* only ARM Cortex-M targets)
Configures OpenOCD in RTT mode to output the chosen channel (default 0) via a simple telnet client. Disconnect with Ctrl+D. (* only ARM Cortex-M targets)
See the modm:platform:rtt module for details how to use RTT for data transfer.
Configures JLink in RTT mode to output the chosen channel (default 0) via a simple telnet client. Disconnect with Ctrl+D. (* only ARM Cortex-M targets)
Generates only the static library libmodm.a without linking it to the application.
Dumps the symbol table for your executable.
Decompiles your executable into an annotated assembly listing. This is very useful for checking and learning how the compiler translates C++ into assembly instructions:
Creates a binary file of your executable.
Creates a Intel-hex file of your executable.
Creates a UF2 compatible file of your executable. UF2 is a bootloader by Microsoft.
(* only ARM Cortex-M targets)
Caches the ELF and binary file of the newest compiled executable identified by the hash of the binary file in artifacts/{hash}.elf. You can change this path with the modm:build:scons:path.artifact option.
Generates several files so that the project can be imported into Qt Creator via the .creator file importer. Note, that no compiliation or debugging features are supported, this is only meant for using the IDE as an editor.
The modm:nanopb module contains a Python generator to translate the messages defined in *.proto files by the modm:nanopb:source option into *.pb.cpp and *.pb.hpp files. This module contains a SCons wrapper tool that automatically updates the generated files when it becomes necessary:
The generated files are available as a top-level #include <protofile.pb.hpp>.
The modm:communication:xpcc:generator module contains the Python tools to translate the XPCC XML declarations into various language implementations. This module contains a SCons wrapper tool, that understands the XML dependencies and automatically updates the generated files when it becomes necessary.
The wrapper tool is automatically used when the generator module is detected, and its options are evaluated for the wrapper as follows:
The generated files are available as a top-level #include <identifiers.hpp>.
Our info SCons tool generates a set of header files containing information about the repository state.
A call to env.InfoGit(with_status={True, False}) will generate a <info_git.h> header file and add these two defines to the command line CPP options:
MODM_GIT_INFOMODM_GIT_STATUS: defined only if called with with_state=True.You can enable this by setting the modm:build:info.git option.
A call to env.InfoBuild() will generate a <info_build.h> header file and add this define to the command line CPP options:
MODM_BUILD_INFOYou can enable this by setting the modm:build:info.build option.
If the modm:build:image.source is defined as a path, it'll be searched for .pbm files to convert into C++ data files using the bitmap tool:
See the GraphicsDisplay::drawImage() method in the modm:ui:display module for how to use these generated files. The directory is added to the include search paths, so the generated files can be accessed as #include <image.hpp>.
SConstruct file!Generated with: yes in [yes, no]
If value is $cache, the cache is placed into the top-level build/ folder. You can disable CacheDir by setting an empty string.
Generated with: [] in [Path]
The artifact folder contains ELF files named by their GNU build id hash. This allows identification of firmware on the device via serial output and is useful for archiving or post-mortem debugging.
Generated with: artifacts in [Path]
1.4.2