Separate RSB Configurations

Tools Source Builder
1

Separate RSB Configurations

This topic discusses how to create a custom tools configuration you can own and manage without having to have it merged into the RTEMS Project. There are good reasons to do this:

  1. The configuration is for custom hardware no one will gain access too
  2. The target is subject to export restrictions
  3. The configuration does things the RTEMS project does not want merged into the main project. An example is tracking HEAD on a branch in a Git repository
  4. Your project wants to own and configuration manage a specific tool set configuration
  5. The source for the tools is not publicly available
  6. You are developing something to finally be submitted to the project

The RTEMS Deployment tool is a working example of a repository with separate RSB configurations. This tool has separate configurations that support specific user or organization builds and it combines those configurations into a tool that packages the tools, kernel, networking and third party packages into a package format specific hosts support without burdening the RSB with this detail. You could consider the RSB as a Swiss Arm Knife for building tools. The RSB is a toolbox of commands and options and it can cut if they are not used correctly. It can lack some guards to aid you.

Separate configurations can be used with different versions of the RSB. We try to maintain the interfaces used so you can use a configuration with RTEMS 6, 7 or later. You could think of separate configurations as being orthogonal to the RSB.

The topic assumes:

  1. Your host can build tools
  2. The tools you want to build do in fact build
  3. You have a copy of the RSB you want to use

Create a Configuration

Create a Workspace

Create a directory on your build host computer and change into it. Create a config directory:

mkdir config

Create a Build Set

I will use the existing AMD Microzed configuration file from RTEMS Deployment. We will start by building the tools for the ARM architecture.

Create an amd directory to hold this build set:

mkdir config/amd

Create the build set file config/amd/avnet-microzed.bset with the following configuration:

#
# ARM Tools
#
%{rtems_version}/rtems-arm

Test the Build

Now we have an initial configuration or build set so lets test it. The trick here is to use an absolute path to the RSB. The RSB will quietly determine where it is located and from that it can find it’s internal configurations or config directories.

/opt/work/chris/rtems/rsb/rtems-source-builder.git/source-builder/sb-set-builder \
  --prefix=/opt/work/chris/rtems/amd \
  --log=microzed.txt \
  amd/avnet-microzed

I am using a copy of the RSB from git. The specific version used depends on the branch I have checked out. Lets say it is main and HEAD so RTEMS 7.

The tools are built and installed into /opt/work/chris/rtems/amd which is a personal area on the host I can test and play with. For a company or organisation you may want a common install path all developers use, either networked on installed on each machine. The path can also contain versioning details.

You can check the configuration by adding --dry-run to the RSB’s set builder command line. Adding --trace will add a lot of pretty horrible but useful trace detail to the log.

Vertical Software Stack

The Executable section of the RTEMS User Manual explains a vertical software stack. The RSB supports vertical stacks with build sets.

Building the RTEMS Kernel

I will add a kernel build to our build set. Edit the avnet-microzed.bset to be:

#
# Avnet Microzed (Xilinx Zynq)
#
%{rtems_version}/rtems-arm
%{rtems_version}/rtems-kernel

Yes the comment changed to show we are now being specific about a Microzed.

Running the same command as before will rebuild the tools and an RTEMS kernel. The kernel will have the default set of options.

If you have a configuration INI file you can add it. For our Microzed we want to have an SMP build and the default options has SMP disabled. Add an INI file called config/amd/avnet-microzed.ini containing:

[DEFAULT]
RTEMS_POSIX_API = True

#
# Microzed BSP configuration
#
[arm/xilinx_zynq_microzed]
RTEMS_SMP = True

Now edit the build set file to be:

#
# Avnet Microzed (Xilinx Zynq)
#
%{rtems_version}/rtems-arm
%define with_rtems_bsp_config config/amd/avnet-microzed.ini
%{rtems_version}/rtems-kernel

Running the same build set command will now create a set of tools and an SMP kernel for the Microzed.

Building LibBSD

Adding LibBSD to the build is a simple edit to add the existing LibBSD build set file the RSB contains. Edit the build set file to be:

#
# Avnet Microzed (Xilinx Zynq)
#
%{rtems_version}/rtems-arm
%define with_rtems_bsp_config config/amd/avnet-microzed.ini
%{rtems_version}/rtems-kernel
%{rtems_version}/rtems-libbsd

Again use the same build set command and this time you will have a set of tools, a kernel and the LibBSD network stack.

It is important to note the order in the build set file demotes the dependencies in the build. The kernel needs a set of tools and the network stack needs the tools and a kernel.

Third Party Packages

Our final edit to this configuration is add some third party packages that are built as libraries and installed. The packages added are:

  1. RTEMS Net Services. This provides a range networking services common to all networking stacks RTEMS supports, for example NTP.
  2. YAML C++ library
  3. Civetweb Web server (awesome package)
#
# Avnet Microzed (Xilinx Zynq)
#
%{rtems_version}/rtems-arm
%define with_rtems_bsp_config config/amd/avnet-microzed.ini
%{rtems_version}/rtems-kernel
%{rtems_version}/rtems-libbsd
net/net-services
devel/yaml-cpp
www/civetweb

With this build set you can build SMP networked applications for a Microzed that support NTP, a web server and in C++ you can use YAML.

Packaging

The RSB builds each package and installs it internally in a staging area. Nothing is installed under the --prefix option path until all the pieces are successfully built. If you add --no-install nothing will be installed under the prefix path which may seem a waste of time. However if you add the --bset-tar-file the RSB will create a tar file of the contents installed under the prefix without doing an install. The combination lets you build a package of tools, a kernel, network and third party packages for your company or organisation you can distrubute.

Advances Configurations

I will not go into this here at this point in time. The config directory is effectively joined to the RSB configurations and all config directories are searched. If you need a specific configuration file you can copy them to your config tree. You can copy in existing build set files and then edit them to reference your custom configuration files (`.cfg). You can sit at a high level like this topic shows using existing build sets and configurations or you can add more. Feel free to add custom build sets and configurations that digging deeper into the RSB giving you more accurate and specific control.

1 Like