6. RTEMS 3rd Party Packages¶

6.1. Vertical Integration¶

The RSB supports horizontal integration with support for multiple architectures. Adding packages to the RSB as libraries is vertical integration. Building the GCC tool chain requires you build an assembler before you build a compiler. The same can be done for 3rd party libraries, you can crate build sets that stack library dependences vertically to create a stack.

6.2. Building¶

To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP installed. The set builder command line requires you provide the tools path, the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix needs to be the same as the prefix used to build RTEMS.

To build Net-SNMP the command is:

$ cd rtems-source-builder/rtems
$ ../source-builder/sb-set-builder --log=log_sis_net_snmp \
    --prefix=$HOME/development/rtems/bsps/4.11 \
    --with-tools=$HOME/development/rtems/4.11 \
    --host=sparc-rtems4.11 --with-rtems-bsp=sis 4.11/net-mgmt/net-snmp
RTEMS Source Builder - Set Builder, v0.3.0
Build Set: 4.11/net-mgmt/net-snmp
config: net-mgmt/net-snmp-5.7.2.1-1.cfg
package: net-snmp-5.7.2.1-sparc-rtems4.11-1
building: net-snmp-5.7.2.1-sparc-rtems4.11-1
installing: net-snmp-5.7.2.1-sparc-rtems4.11-1 -> /Users/chris/development/rtems/bsps/4.11
cleaning: net-snmp-5.7.2.1-sparc-rtems4.11-1
Build Set: Time 0:01:10.651926

6.3. Adding¶

Adding a package requires you first build it manually by downloading the source for the package and building it for RTEMS using the command line of a standard shell. If the package has not been ported to RTEMS you will need to port it and this may require you asking questions on the package’s user or development support lists as well as RTEMS’s developers list. Your porting effort may end up with a patch. RTEMS requires a patch be submitted upstream to the project’s community as well as RTEMS so it can be added to the RTEMS Tools git repository. A patch in the RTEMS Tools git reposiitory can then be referenced by an RSB configuration file.

A package may create executables, for example NTP normally creates executables such as ntdp, ntpupdate, or ntpdc. These executables can be useful when testing the package however they are of limited use by RTEMS users because they cannot be directly linked into a user application. Users need to link to the functions in these executables or even the executable as a function placed in libraries. If the package does not export the code in a suitable manner please contact the project’s commuinity and see if you can work them to provide a way for the code to be exported. This may be difficult because exporting internal headers and functions opens the project up to API compatibility issues they did not have before. In the simplest case attempting to get the code into a static library with a single call entry point exported in a header would give RTEMS user’s access to the package’s main functionality.

A package requires 3 files to be created:

• The first file is the RTEMS build set file and it resides in the rtems/config/%{rtems_version} path in a directory tree based on the FreeBSD ports collection. For the NTP package and RTEMS 4.11 this is rtems/config/4.11/net/ntp.bset. If you do not know the FreeBSD port path for the package you are adding please ask. The build set file references a specific configuration file therefore linking the RTEMS version to a specific version of the package you are adding. Updating the package to a new version requires changing the build set to the new configuration file.
• The second file is an RTEMS version specific configuration file and it includes the RSB RTEMS BSP support. These configuration files reside in the rtems/config tree again under the FreeBSD port’s path name. For example the NTP package is found in the net directory of the FreeBSD ports tree so the NTP configuration path is rtems/config/net/ntp-4.2.6p5-1.cfg for that specific version. The configuration file name typically provides version specific references and the RTEMS build set file references a specific version. This configuration file references the build configuration file held in the common configuration file tree.
• The build configuration. This is a common script that builds the package. It resides in the source-builder/config directory and typically has the packages’s name with the major version number. If the build script does not change for each major version number a common base script can be created and included by each major version configuration script. The gcc compiler configuration is an example. This approach lets you branch a version if something changes that is not backwards compatible. It is important to keep existing versions building. The build configuration should be able to build a package for the build host as well as RTEMS as the RSB abstracts the RTEMS specific parts. See Chapter 7 - Configuration for more details.

6.4. BSP Support¶

The RSB provides support to help build packages for RTEMS. RTEMS applications can be viewed as statically linked executables operating in a single address space. As a result only the static libraries a package builds are required and these libraries need to be ABI compatible with the RTEMS kernel and application code meaning compiler ABI flags cannot be mixed when building code. The 3rd party package need to use the same compiler flags as the BSP used to build RTEMS.

The RSB provides the configuration file rtems/config/rtems-bsp.cfg to support building 3rd party packages and you need to include this file in your RTEMS version specific configuration file. For example the Net-SNMP configuration file rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg:

#
# NetSNMP 5.7.2.1
#
%if %{release} == %{nil}
 %define release 1    <1>
%endif

%include %{_configdir}/rtems-bsp.cfg   <2>

#
# NetSNMP Version
#
%define net_snmp_version 5.7.2.1   <3>

#
# We need some special flags to build this version.
#
%define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0

#
# Patch for RTEMS support.
#
%patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>

#
# NetSNMP Build configuration
#
%include %{_configdir}/net-snmp-5-1.cfg   <6>

The RSB RTEMS BSP support file rtems/config/rtems-bsp.cfg checks to make sure standard command line options are provided. These include --host and --with-rtems-bsp. If the --with-tools command line option is not given the ${_prefix} is used:

%if %{_host} == %{nil} <1>
 %error No RTEMS target specified: --host=host
%endif

%ifn %{defined with_rtems_bsp} <2>
 %error No RTEMS BSP specified: --with-rtems-bsp=bsp
%endif

%ifn %{defined with_tools} <3>
 %define with_tools %{_prefix}
%endif

#
# Set the path to the tools.
#
%{path prepend %{with_tools}/bin} <4>

RTEMS exports the build flags used in pkgconfig (.pc) files and the RSB can read and manage them even when there is no pkgconfig support installed on your build machine. Using this support we can obtain a BSP’s configuration and set some standard macros variables (rtems/config/rtems-bsp.cfg):

%{pkgconfig prefix %{_prefix}/lib/pkgconfig} <1>
%{pkgconfig crosscompile yes} <2>
%{pkgconfig filter-flags yes} <3>

#
# The RTEMS BSP Flags
#
%define rtems_bsp           %{with_rtems_bsp}
%define rtems_bsp_ccflags   %{pkgconfig ccflags %{_host}-%{rtems_bsp}} <4>
%define rtems_bsp_cflags    %{pkgconfig cflags  %{_host}-%{rtems_bsp}}
%define rtems_bsp_ldflags   %{pkgconfig ldflags %{_host}-%{rtems_bsp}}
%define rtems_bsp_libs      %{pkgconfig libs    %{_host}-%{rtems_bsp}}

The flags obtain by pkgconfig and given a rtems_bsp_ prefix and we uses these to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd party library your host computer is the _build_ machine and RTEMS is the _host_ machine therefore we set the host variables (rtems/config/rtems-bsp.cfg):

%define host_cflags  %{rtems_bsp_cflags}
%define host_ldflags %{rtems_bsp_ldflags}
%define host_libs    %{rtems_bsp_libs}

Finally we provide all the paths you may require when configuring a package. Packages by default consider the _prefix the base and install various files under this tree. The package you are building is specific to a BSP and so needs to install into the specific BSP path under the _prefix. This allows more than BSP build of this package to be install under the same _prefix at the same time (rtems/config/rtems-bsp.cfg):

%define rtems_bsp_prefix  %{_prefix}/%{_host}/%{rtems_bsp} <1>
%define _exec_prefix      %{rtems_bsp_prefix}
%define _bindir           %{_exec_prefix}/bin
%define _sbindir          %{_exec_prefix}/sbin
%define _libexecdir       %{_exec_prefix}/libexec
%define _datarootdir      %{_exec_prefix}/share
%define _datadir          %{_datarootdir}
%define _sysconfdir       %{_exec_prefix}/etc
%define _sharedstatedir   %{_exec_prefix}/com
%define _localstatedir    %{_exec_prefix}/var
%define _includedir       %{_libdir}/include
%define _lib              lib
%define _libdir           %{_exec_prefix}/%{_lib}
%define _libexecdir       %{_exec_prefix}/libexec
%define _mandir           %{_datarootdir}/man
%define _infodir          %{_datarootdir}/info
%define _localedir        %{_datarootdir}/locale
%define _localedir        %{_datadir}/locale
%define _localstatedir    %{_exec_prefix}/var

When you configure a package you can reference these paths and the RSB will provide sensible default or in this case map them to the BSP (source-builder/config/ntp-4-1.cfg):

../${source_dir_ntp}/configure \ <1>
  --host=%{_host} \
  --prefix=%{_prefix} \
  --bindir=%{_bindir} \
  --exec_prefix=%{_exec_prefix} \
  --includedir=%{_includedir} \
  --libdir=%{_libdir} \
  --libexecdir=%{_libexecdir} \
  --mandir=%{_mandir} \
  --infodir=%{_infodir} \
  --datadir=%{_datadir} \
  --disable-ipv6 \
  --disable-HOPFPCI

6.5. RTEMS BSP Configuration¶

To build a package for RTEMS you need to build it with the matching BSP configuration. A BSP can be built with specific flags that require all code being used needs to be built with the same flags.