10. 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.
10.1. Goals#
The system should meet the following goals:
The install location of artefacts should be the same as in previous build systems
Easy build configuration of BSPs through configuration options
Enable the BSP build configuration to be placed in a version control system (e.g. no local paths)
Fast builds (also on Windows)
Easy to maintain, e.g. add/remove a BSP, add/change/remove configuration options, add/remove a library, add/remove an object to/from a library, add/remove tests
Reusable build specifications (e.g. generate documentation for BSP options for the user manual)
Validation of built artefacts (e.g. ensure that the objects are built as specified using the DWARF debug information)
Support building of BSPs external to the project
Customization of the build (e.g. build only a subset of the RTEMS functions)
Support alternative compilers such as clang instead of GCC
Ability to unit test the build system
Version control system friendly change sets (e.g. most changes are line based in text files)
Configurable things which depend on the host computer environment such as paths
to tools are intended to be passed as command line options to the waf
command line tool. Configurable things which define what is built and how the
artefacts are configured are intended to be placed in configuration files that
can be configuration controlled. The waf
build script file called
wscript
should know nothing about the layout of the sources. What is built
and how it is built should be completely defined by the user configuration and
the build specification items.
10.2. Overview#
For an overview of the build system, see the BSP Build System chapter of the RTEMS User Manual.
10.3. Commands#
This section explains how the Build Item Type items determine what
the following waf
commands do.
10.3.1. BSP List#
In the ./waf bsplist
command, the BSP list is generated from the
Build BSP Item Type items.
10.3.2. BSP Defaults#
In the ./waf bspdefaults
command, the BSP defaults are generated from the
Build BSP Item Type and Build Option Item Type items.
Build specification items contribute to the command through the
do_defaults()
method in the wscript
.
10.3.3. Configure#
In the ./waf configure
command, the build specification items contribute to
the command through the prepare_configure()
and do_configure()
methods
in the wscript
.
10.3.4. Build, Clean, and Install#
In the ./waf
, ./waf clean
, and ./waf install
commands, the build
specification items contribute to the commands through the prepare_build()
and do_build()
methods in the wscript
.
10.4. UID Naming Conventions#
Use the following patterns for UID names:
- abi
Use the name
abi
for the GCC-specific ABI flags item of a BSP family. Each BSP family should have exactly one Build Option Item Type item which defines the GCC-specific ABI flags for all base BSPs of the family. For an architecture named arch and a BSP family named family, the file path isspec/build/bsps/arch/family/abi.yml
.- abiclang
Use the name
abiclang
for the clang-specific ABI flags item of a BSP family. Each BSP family may have at most one Build Option Item Type item which defines the clang-specific ABI flags for all base BSPs of the family. For an architecture named arch and a BSP family named family, the file path isspec/build/bsps/arch/family/abiclang.yml
.- bsp*
Use the prefix
bsp
for base BSPs.- cfg*
Use the prefix
cfg
forconfig.h
header options.- grp*
Use the prefix
grp
for groups.- lib*
Use the prefix
lib
for libraries.- linkcmds*
Use the prefix
linkcmds
for linker command files.- obj*
Use the prefix
obj
for objects. Useobjmpci
for objects which are enabled byRTEMS_MULTIPROCESSING
,objnet
for objects which are enabled byRTEMS_NETWORKING
,objnetnosmp
for objects which are enabled byRTEMS_NETWORKING
and notRTEMS_SMP
, andobjsmp
for objects which are enabled byRTEMS_SMP
.
- opt*
Use the prefix
opt
for options. Useoptclock*
for options which have something to do with the clock driver,optconsole*
for options which have something to do with the console driver,optirq*
for options which have something to do with interrupt processing,optmem*
for options which have something to do with the memory configuration, map, settings, etc., andoptosc*
for options which have something to do with oscillators.
- start
Use the name
start
for BSP start file items. Each architecture or BSP family should have a Build Start File Item Type item which builds the start file of a BSP. For an architecture named arch and a BSP family named family, the file path isspec/build/bsps/arch/start.yml
orspec/build/bsps/arch/family/start.yml
. It is preferable to have a shared start file for the architecture instead of a start file for each BSP family.- tst*
Use the prefix
tst
for test states.
10.5. Build Specification Items#
Specification items of refinements of the Build Item Type are used
by the wscript
to determine what it should do. The wscript
does not
provide default values. All values are defined by specification items. The
entry point to what is built are the Build BSP Item Type items and
the top-level Build Group Item Type item. The user configuration
defines which BSPs are built. The top-level group defaults to /grp
and can
be changed by the --rtems-top-level
command line option given to the waf
configure
command.
The top-level group is a trade-off between the specification complexity and a strict dependency definition. Dependencies are normally explicit though the item links. However, using only explicit dependencies would make the specification quite complex, see Fig. 10.1. The top-level group and explicit Build BSP Item Type items reduce the specification complexity since they use a priori knowledge of global build dependencies, see Fig. 10.2 for an example. This approach makes the build system easier, but less general.
10.6. How-To#
This section presents how to do common maintenance tasks in the build system.
10.6.1. Find the Right Item#
You find all build specification items in the RTEMS sources under the
spec/build
directory. You can use the grep
command line tool to search
in the build specification items.
10.6.2. Create a BSP Architecture#
Let arch be the name of the architecture. You can add the new BSP architecture with:
$ mkdir spec/build/bsps/arch
For a new architecture try to use a shared start file which can be used by all BSPs of the architecture. Add a Build Start File Item Type item for it:
$ vi spec/build/bsps/arch/start.yml
10.6.3. Create a BSP Family#
Let family be the BSP family name and arch the name of the architecture. You can add the new BSP family with:
$ mkdir spec/build/bsps/arch/family
Add a Build Option Item Type item for the ABI flags of the BSP family:
$ vi spec/build/bsps/arch/family/abi.yml
Define the ABI flags for each base BSP of the family. The ${ABI_FLAGS}
are
used for the ${ASFLAGS}
, ${CFLAGS}
, ${CXXFLAGS}
, and ${LDFLAGS}
build environment variables. Please have a look at the following example which
shows the GCC-specific ABI flags item of the sparc/leon3
BSP family:
SPDX-License-Identifier: CC-BY-SA-4.0 OR BSD-2-Clause
actions:
- get-string: null
- split: null
- env-append: null
build-type: option
copyrights:
- Copyright (C) 2020 embedded brains GmbH & Co. KG
default:
- -mcpu=leon3
default-by-variant:
- value:
- -mcpu=leon3
- -mfix-ut700
variants:
- sparc/ut700
- value:
- -mcpu=leon
- -mfix-ut699
variants:
- sparc/ut699
- value:
- -mcpu=leon3
- -mfix-gr712rc
variants:
- sparc/gr712rc
description: |
ABI flags
enabled-by: gcc
links: []
name: ABI_FLAGS
type: build
If the architecture has no shared start file, then add a Build Start File Item Type item for the new BSP family:
$ vi spec/build/bsps/arch/family/start.yml
10.6.4. Add a Base BSP to a BSP Family#
Let family be the BSP family name, arch the name of the architecture, and new the name of the new base BSP. You can add the new base BSP with:
$ vi spec/build/bsps/arch/family/bspnew.yml
Define the attributes of your new base BSP according to Build BSP Item Type.
In case the BSP family has no group, then create a group if it is likely that the BSP family will contain more than one base BSP (see Extend a BSP Family with a Group).
If the BSP family has a group, then link the new base BSP to the group with:
$ vi spec/build/bsps/arch/familiy/grp.yml
Add a link using a relative UID to the new base BSP item:
links:
- role: build-dependency
uid: bspnew
10.6.5. Add a BSP Option#
Let family be the BSP family name, arch the name of the architecture, and new the name of the new BSP option. You can add the new BSP option with:
$ vi spec/build/bsps/arch/family/optnew.yml
Define the attributes of your new BSP option according to Build Option Item Type. Link the option item to the corresponding group or BSP item using a relative UID:
links:
- role: build-dependency
uid: optnew
10.6.6. Extend a BSP Family with a Group#
Let family be the BSP family name and arch the name of the architecture. If you want to have more than one base BSP in a BSP family, then you have to use a group item (see Build Group Item Type). Add the group item named grp to the family with:
$ vi spec/build/bsps/arch/family/grp.yml
Define the attributes of your new group according to Build Group Item Type and move the links of the existing base BSP item to the group item. Add a link to obj.
Add an objects item named obj to the family with:
$ vi spec/build/bsps/arch/family/obj.yml
Define the attributes of your new objects item according to
Build Objects Item Type and move the cflags
, cppflags
,
includes
, install
and source
attribute values of the
existing base BSP item to the objects item.
10.6.7. Add a Test Program#
Let collection be the name of a test program collection and new the name of the new test program. You can add the new test program with:
$ vi spec/build/testsuites/collection/new.yml
Define the attributes of your new test program according to Build Test Program Item Type.
Edit corresponding group item of the test program collection:
$ vi spec/build/testsuites/collection/grp.yml
Add a link to the new test program item using a relative UID:
links:
- role: build-dependency
uid: new
10.6.8. Add a Library#
Let new be the name of the new library. You can add the new library with:
$ vi spec/build/cpukit/libnew.yml
Define the attributes of your new library according to Build Library Item Type.
Edit corresponding group item:
$ vi spec/build/cpukit/grp.yml
Add a link to the new library item using a relative UID:
links:
- role: build-dependency
uid: libnew
10.6.9. Add an Object#
Build objects logically separate relatively independent segments of functionality (for example a device driver, an architecture-dependent feature, etc.). Let new be the name of the new object. You can add the new object with:
$ vi spec/build/cpukit/objnew.yml
Define the attributes of your new object according to Build Objects Item Type.
Edit corresponding group item:
$ vi spec/build/cpukit/grp.yml
Add a link to the new objects item using a relative UID:
links:
- role: build-dependency
uid: objnew