8. BSP Build System¶
The purpose of the build system is to produce and install artefacts from the RTEMS sources such as static libraries, start files, linker command files, configuration header files, header files, test programs, package description files, and third-party build system support files for a specific BSP in a user controlled configuration.
8.1. Overview¶
The build system consists of three components which are all included in the RTEMS sources
the waf meta build system command line tool,
a wscript file used by
waf
, anda set of build specification items maintained by a text editor just like other source files.
The build system is controlled by the user through
commands passed to the
waf
command line tool,command line options passed to
waf
, andconfiguration files (e.g.
config.ini
) used bywscript
throughwaf
invocations.
Configurable things which are subject to a local installation variant such as
paths to tools are intended to be passed as command line options to the waf
command line tool. Which BSPs are built and how they are configured by means of
options is placed in configuration files (e.g. config.ini
). The
configuration files may reside anywhere in the file system and the goal is to
have it under version control by the user.
8.2. Work Flow¶
There are five steps necessary to build and install one or more BSPs.
Select which BSPs you want to build. See also Deployment and
./waf bsplist
.Write a BSP build configuration file (e.g.
config.ini
) which determines which BSPs are built and how they are configured.Run the
./waf configure
command to generate the build environment.Build the BSP artefacts with
./waf
. The build uses the build environment created by./waf configure
. The BSP build configuration file (e.g.config.ini
) is no longer used and may be deleted.Install the BSP artefacts with
./waf install
.
8.3. Commands¶
The build system is controlled by invocations of the ./waf
command line
tool instead of the well known make
. Since waf is written in Python, a
standard Python 2.7 or 3 installation without third-party packages is required
to run it. The ./waf
command line tool must be invoked in the RTEMS source
tree top-level directory.
Some commands accept the --rtems-specs
command line option. This option
specifies paths to build specification items. It is an advanced option and
there is normally no need to use it. It may be used to customize the build at
the level of the build specification. For more information see the
Build System chapter of the
RTEMS Software Engineering
guide.
8.3.1. Help¶
Use ./waf --help
to get a list of commands and options.
8.3.2. BSP List¶
The BSP list command ./waf bsplist
loads the build specification items and
generates a list of base BSPs from it. The list is sorted by architecture and
base BSP name. Which base BSPs are listed can be controlled by the
--rtems-bsps
command line option. It expects a comma-separated list of
Python regular expressions
which select the desired BSP variants. The path to the build specification
items can be specified by the --rtems-specs
command line option.
$ ./waf bsplist --rtems-bsps=sparc/
sparc/at697f
sparc/erc32
sparc/gr712rc
sparc/gr740
sparc/leon2
sparc/leon3
sparc/ut699
sparc/ut700
$ ./waf bsplist --rtems-bsps='/leon,/rv64imac$'
riscv/rv64imac
sparc/leon2
sparc/leon3
8.3.3. BSP Defaults¶
The BSP defaults command ./waf bspdefaults
loads the build specification
items and generates a list options with default values for each base BSP from
it. The list is sorted by architecture and base BSP name. Which base BSPs are
listed can be controlled by the --rtems-bsps
command line option. Default
values may depend on the selected compiler. The compiler can be specified by
the --rtems-compiler
command line option. The path to the build
specification items can be specified by the --rtems-specs
command line
option.
$ ./waf bspdefaults --rtems-bsps=gr712rc --rtems-compiler=gcc | grep ABI_FLAGS
ABI_FLAGS = -mcpu=leon3 -mfix-gr712rc
$ ./waf bspdefaults --rtems-bsps=gr712rc --rtems-compiler=clang | grep ABI_FLAGS
ABI_FLAGS = -mcpu=gr712rc
8.3.4. Configure¶
The configure command ./waf configure
loads the BSP build configuration
files and the build specification items and configures the build environment
accordingly. The configuration files can be specified by the --rtems-config
command line option. It expects a comma-separated list of paths to the
configuration files. By default, the file config.ini
is used. The paths to
RTEMS tools can be specified by the --rtems-tools
command line option. It
expects a comma-separated list of prefix paths to tools, e.g. compiler, linker,
etc. By default, the installation prefix is used for the RTEMS tools. Tools
are searched in the prefix path and also in a bin
subdirectory of the prefix
path. The path to the build specification items can be specified by the
--rtems-specs
command line option.
8.3.5. Build, Clean, and Install¶
The commands ./waf
, ./waf clean
, and ./waf install
load the build
specification items according to the specification paths stored in the build
environment. The BSP build configuration files (e.g. config.ini
) used by
the ./waf configure
command to create the build environment are not longer
used and may be deleted. The build commands perform a dependency tracking and
re-build artefacts if input sources changed. Input sources are also the build
specification.
8.4. Configuration¶
The BSP build configuration is done via INI-style configuration files. The
configuration files are consumed by the ./waf configure
command. By
default, the file config.ini
is used. You can specify other configuration
files with the --rtems-config
command line option. The configuration files
consist of sections and options (key-value pairs).
To build a particular BSP, you have to create a section with the BSP variant name.
[sparc/erc32]
This one line configuration file is sufficient to build the base BSP
sparc/erc32 with default values for all options. The base BSPs are determined
by the build specification. The ./waf bsplist
command lists all base BSPs.
You can create your own BSP names. However, in this case you have to inherit
from a base BSP. The inheritance works only within an architecture, e.g. a
riscv BSP cannot inherit options from an arm BSP.
[sparc/foobar]
INHERIT = erc32
The inheritance works recursively and must end up in a base BSP.
[sparc/foo]
INHERIT = erc32
[sparc/bar]
INHERIT = foo
A child BSP variant inherits all options from the parent BSP variant. The child BSP can override the inherited options.
You can determine the compiler used to build the BSP with the COMPILER
option.
[sparc/gr740_gcc]
INHERIT = gr740
COMPILER = gcc
[sparc/gr740_clang]
INHERIT = gr740
COMPILER = clang
Use the ./waf bspdefaults
command to get a list of all configuration
options with default values.
$ ./waf bspdefaults --rtems-bsps=sparc/erc32
[sparc/erc32]
# Flags passed to the library archiver
ARFLAGS = crD
# Warning flags passed to the C compiler
CC_WARNING_FLAGS = -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs
# Warning flags passed to the C++ compiler
CXX_WARNING_FLAGS =
# Flags passed to the linker (GNU ld)
LDFLAGS = -Wl,--gc-sections
# Enable the Ada support
__RTEMS_ADA__ = False
# Enable the RTEMS internal debug support
RTEMS_DEBUG = False
...
# Install the legacy application Makefile framework.
INSTALL_LEGACY_MAKEFILES = True
It is not recommended to blindly add all the options obtained through the
./waf bspdefaults
command to custom configuration files. The specified
options should be kept at the necessary minimum to get the desired build.
Some projects may still want to specify all options in a configuration file to
be independent of changes in the base BSP. You can review differences between
the user and base BSP values with the diff
command.
$ ./waf bspdefaults --rtems-bsps=sparc/erc32 > config.ini
$ sed -i 's/BUILD_TESTS = False/BUILD_TESTS = True/' config.ini
$ ./waf bspdefaults --rtems-bsps=sparc/erc32 | diff -u - config.ini
--- config.ini 2019-12-04 08:21:36.049335872 +0100
+++ - 2019-12-04 08:21:41.187432405 +0100
@@ -31,7 +31,7 @@
# Build the Ada test programs (may be also enabled by BUILD_TESTS)
BUILD_ADATESTS = False
# Build the test programs
-BUILD_TESTS = False
+BUILD_TESTS = True
# Build the benchmark programs (may be also enabled by BUILD_TESTS)
BUILD_BENCHMARKS = False
# Build the file system test programs (may be also enabled by
There is a special section DEFAULT
which can be used to specify default
values for all other sections of the configuration file. In the following
example configuration file, building of the tests is enabled for the
sparc/erc32 and the riscv/griscv BSP.
[DEFAULT]
BUILD_TESTS = True
[sparc/erc32]
[riscv/griscv]
8.5. Migration from Autoconf/Automake¶
The Autoconf/Automake based build system used a configure
command to
configure a single target architecture and one or more BSPs. The make
command was used to build it. The configure
command is replaced by a
./waf configure
invocation with configuration file. The make
command
is replaced by ./waf
and make install
is replaced by ./waf install
.
Here are some hints for how a configure command line can be converted to
options in the configuration file of the waf
based build system. BSP
options given at the configure command line have to be added to the BSP section
in the configuration file.
--target=${arch}-rtems6
--enable-rtembsp=${bsp}
To build a BSP add
[${arch}/${bsp}]
to the configuration file.--enable-ada
|--disable-ada
Set
__RTEMS_ADA__
toTrue
orFalse
in the BSP section of the configuration file.--enable-multiprocessing
|--disable-multiprocessing
Set
RTEMS_MULTIPROCESSING
toTrue
orFalse
in the BSP section of the configuration file.--enable-paravirt
|--disable-paravirt
Set
RTEMS_PARAVIRT
toTrue
orFalse
in the BSP section of the configuration file.--enable-profiling
|--disable-profiling
Set
RTEMS_PROFILING
toTrue
orFalse
in the BSP section of the configuration file.--enable-posix
|--disable-posix
Set
RTEMS_POSIX_API
toTrue
orFalse
in the BSP section of the configuration file.--enable-rtems-debug
|--disable-rtems-debug
Set
RTEMS_DEBUG
toTrue
orFalse
in the BSP section of the configuration file.--enable-smp
|--disable-smp
Set
RTEMS_SMP
toTrue
orFalse
in the BSP section of the configuration file.--enable-tests
|--disable-tests
Set
BUILD_TESTS
toTrue
orFalse
in the BSP section of the configuration file.--enable-tests=samples
Set
BUILD_SAMPLES
toTrue
orFalse
in the BSP section of the configuration file.
Please have a look at the following example configuration file.
# --target=sparc-rtems6 --enable-rtemsbsp=erc32
[sparc/erc32]
# --enable-ada
__RTEMS_ADA__ = True
# --enable-multiprocessing
RTEMS_MULTIPROCESSING = False
# --disable-paravirt
RTEMS_PARAVIRT = False
# --enable-profiling
RTEMS_PROFILING = True
# --disable-posix
RTEMS_POSIX_API = False
# --enable-rtems-debug
RTEMS_DEBUG = True
# --disable-smp
RTEMS_SMP = False
# --enable-tests
BUILD_TESTS = True
# BSP_POWER_DOWN_AT_FATAL_HALT=
BSP_POWER_DOWN_AT_FATAL_HALT = False