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 is spec/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 is spec/build/bsps/arch/family/abiclang.yml.

bsp*

Use the prefix bsp for base BSPs.

cfg*

Use the prefix cfg for config.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. Use

objmpci for objects which are enabled by RTEMS_MULTIPROCESSING,
objnet for objects which are enabled by RTEMS_NETWORKING,
objnetnosmp for objects which are enabled by RTEMS_NETWORKING and not RTEMS_SMP, and
objsmp for objects which are enabled by RTEMS_SMP.

opt*

Use the prefix opt for options. Use

optclock* 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., and
optosc* 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 is spec/build/bsps/arch/start.yml or spec/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.

_images/bld-deps.png — Fig. 10.1 Example with Explicit Item Links¶

This example shows how build item dependencies are specified explicitly by item links. In this example, a user wants to build a group of tests. Each test program has a dependency on the standard RTEMS libraries. The first issue is that the `librtemsbsp.a` needs dependencies to all base BSP variants (more than 100). The dependencies are the values of the `links` attribute in the library item files. External BSPs would have to modify the library item files. This is quite undesirable. The second issue is that the source files of the `librtemscpu.a` need a dependency to the ABI compiler flags specified by each BSP. The third issue is that each BSP has to define its own `bspopts.h` configuration header item.

_images/bld-deps2.png — Fig. 10.2 Example with Implicit Ordering Rules¶

This example shows how build item dependencies are specified by dedicated BSP items, a top-level group, and ordered item links. The BSP is configured after the top-level group item and built before the top-level group item (defined by `wscript` source code). The library group is configured and built before the test group as specified by the item link order in the top-level group. The BSP options are processed before the results are written to the configuration header `bspopts.h` as defined by the BSP item link order.

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¶

_images/bld-bsp.png — Fig. 10.3 This example shows a BSP family named *family* in the architecture *arch* which consists of only one base BSP named *xyz*. The BSP sources and installation information is contained in the `spec:/build/bsps/arch/family/bspxyz` BSP item. The items linked by the BSP item are shown using relative UIDs.¶

_images/bld-bsp2.png — Fig. 10.4 This example shows a BSP family named *family* in the architecture *arch* which consists of three base BSPs named *rst*, *uvw*, and *xyz*. The BSP sources and installation information is contained in the *obj* objects item. The group *grp* defines the main BSP constituents. The base BSP items `spec:/build/bsps/arch/family/bsprst`, `spec:/build/bsps/arch/family/bspuvw`, and `spec:/build/bsps/arch/family/bspxyz` just define the name of the base BSP and set a link to the group item. The base BSP and BSP family names can be used for example in the `default-by-variant` attribute of Build Option Item Type items. The items linked by the BSP items are shown using relative UIDs.¶

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