RTEMS 4.11.2 Source Builder¶

1.1. Why Build from Source?¶

The RTEMS Source Builder is not a replacement for the binary install systems you have with commercial operating systems or open source operating system distributions. Those products and distributions are critically important and are the base that allows the RSB to work. The RTEMS Source Builder sits somewhere between you manually entering the commands to build a tool set and a tool such as yum or apt-get to install binary packages made specifically for your host operating system. Building manually or installing a binary package from a remote repository are valid and real alternatives. The RSB provides the specific service of repeatably being able to build tool sets from source code. The process leaves you with the source code used to build the tools and the ability to rebuilt it.

If you are developing a system or product that has a long shelf life or is used in a critical piece of infrastructure that has a long life cycle being able to build from source is important. It insulates the project from the fast ever changing world of the host development machines. If your tool set is binary and you have lost the ability to build it you have lost a degree of control and flexibility open source gives you. Fast moving host environments are fantastic. We have powerful multi-core computers with huge amounts of memory and state of the art operating systems to run on them however the product or project you are part of may need to be maintained well past the life time of these host. Being able to build from source an important and critical part of this process because you can move to a newer host and create an equivalent tool set.

Building from source provides you with control over the configuration of the package you are building. If all or the most important dependent parts are built from source you limit the exposure to host variations. For example the GNU C compiler (gcc) currently uses a number of 3rd party libraries internally (gmp, mpfr, etc). If your validated compiler generating code for your target processor is dynamically linked against the host’s version of these libraries any change in the host’s configuration may effect you. The changes the host’s package management system makes may be perfectly reasonable in relation to the distribution being managed however this may not extend to you and your tools. Building your tools from source and controlling the specific version of these dependent parts means you are not exposing yourself to unexpected and often difficult to resolve problems. On the other side you need to make sure your tools build and work with newer versions of the host operating system. Given the stability of standards based libraries like libc and ever improving support for standard header file locations this task is becoming easier.

The RTEMS Source Builder is designed to be audited and incorporated into a project’s verification and validation process. If your project is developing critical applications that needs to be traced from source to executable code in the target, you need to also consider the tools and how to track them.

If your IT department maintains all your computers and you do not have suitable rights to install binary packages, building from source lets you create your own tool set that you install under your home directory. Avoiding installing any extra packages as a super user is always helpful in maintaining a secure computing environment.

1.2. History¶

The RTEMS Source Builder is a stand alone tool based on another tool called the SpecBuilder written by Chris Johns. The SpecBuilder was written around 2010 for the RTEMS project to provide Chris with a way to build tools on hosts that did not support RPMs. At the time the RTEMS tools maintainer only supported spec files and these files held all the vital configuration data needed to create suitable tool sets. The available SRPM and spec files by themselves where of little use because a suitable rpm tool was needed to use them. At the time the available versions of rpm for a number of non-RPM hosts were broken and randomly maintained. The solution Chris settled on was to use the spec files and to write a Python based tool that parsed the spec file format creating a shell script that could be run to build the package. The approach proved successful and Chris was able to track the RPM version of the RTEMS tools on a non-RPM host for a number of years.

The SpecBuilder tool did not build tools or packages unrelated to the RTEMS Project where no suitable spec file was available so another tool was needed. Rather than start again Chris decided to take the parsing code for the spec file format and build a new tool called the RTEMS Source Builder.

2.1. Setup¶

Setup a development work space:

$ cd
$ mkdir -p development/rtems/src
$ cd development/rtems/src

The RTEMS Source Builder is distributed as source. It is Python code so all you need to do is download the release’s RSB tarball or clone the code directly from the RTEMS GIT repository:

$ git clone git://git.rtems.org/rtems-source-builder.git
$ cd rtems-source-builder

2.2. Checking¶

The next step is to check if your host is set up correctly. The RTEMS Source Builder provides a tool to help:

$ source-builder/sb-check
warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
error: exe: not found: (_xz) /usr/local/bin/xz    <2>
RTEMS Source Builder environment is not correctly set up
$ source-builder/sb-check
RTEMS Source Builder environment is ok   <3>

The checking tool will output a list of executable files not found if problems are detected. Locate those executable files and install them. You may also be given a list of warnings about executable files not in the expected location however the executable was located somewhere in your environment’s path. You will need to check each tool to determine if this is an issue. An executable not in the standard location may indicate it is not the host operating system’s standard tool. It maybe ok or it could be buggy, only you can determine this.

The Chapter 3 - Hosts section lists packages you should install for common host operating systems. It maybe worth checking if you have those installed.

2.3. Build Sets¶

The RTEMS tools can be built within the RTEMS Source Builder’s source tree. We recommend you do this so lets change into the RTEMS directory in the RTEMS Source Builder package:

$ cd rtems

If you are unsure how to specify the build set for the architecture you wish to build ask the tool:

$ ../source-builder/sb-set-builder --list-bsets   <1>
RTEMS Source Builder - Set Builder, v4.11.0
Examining: config
Examining: ../source-builder/config    <2>
    4.10/rtems-all.bset      <3>
    4.10/rtems-arm.bset      <4>
    4.10/rtems-autotools.bset
    4.10/rtems-avr.bset
    4.10/rtems-bfin.bset
    4.10/rtems-h8300.bset
    4.10/rtems-i386.bset
    4.10/rtems-lm32.bset
    4.10/rtems-m32c.bset
    4.10/rtems-m32r.bset
    4.10/rtems-m68k.bset
    4.10/rtems-mips.bset
    4.10/rtems-nios2.bset
    4.10/rtems-powerpc.bset
    4.10/rtems-sh.bset
    4.10/rtems-sparc.bset
    4.11/rtems-all.bset
    4.11/rtems-arm.bset
    4.11/rtems-autotools.bset
    4.11/rtems-avr.bset
    4.11/rtems-bfin.bset
    4.11/rtems-h8300.bset
    4.11/rtems-i386.bset
    4.11/rtems-lm32.bset
    4.11/rtems-m32c.bset
    4.11/rtems-m32r.bset
    4.11/rtems-m68k.bset
    4.11/rtems-microblaze.bset
    4.11/rtems-mips.bset
    4.11/rtems-moxie.bset
    4.11/rtems-nios2.bset
    4.11/rtems-powerpc.bset
    4.11/rtems-sh.bset
    4.11/rtems-sparc.bset
    4.11/rtems-sparc64.bset
    4.11/rtems-v850.bset
    4.9/rtems-all.bset
    4.9/rtems-arm.bset
    4.9/rtems-autotools.bset
    4.9/rtems-i386.bset
    4.9/rtems-m68k.bset
    4.9/rtems-mips.bset
    4.9/rtems-powerpc.bset
    4.9/rtems-sparc.bset
    gnu-tools-4.6.bset
    rtems-4.10-base.bset    <5>
    rtems-4.11-base.bset
    rtems-4.9-base.bset
    rtems-base.bset         <5>

2.4. Building¶

The quick start builds a SPARC tool set:

$ ../source-builder/sb-set-builder --log=l-sparc.txt \   <1>
      --prefix=$HOME/development/rtems/4.11 \       <2>
      4.11/rtems-sparc           <3>
Source Builder - Set Builder, v0.2.0
Build Set: 4.11/rtems-sparc
config: expat-2.1.0-1.cfg        <4>
package: expat-2.1.0-x86_64-freebsd9.1-1
building: expat-2.1.0-x86_64-freebsd9.1-1
config: tools/rtems-binutils-2.22-1.cfg        <5>
package: sparc-rtems4.11-binutils-2.22-1
building: sparc-rtems4.11-binutils-2.22-1
config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg   <6>
package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
config: tools/rtems-gdb-7.5.1-1.cfg      <7>
package: sparc-rtems4.11-gdb-7.5.1-1
building: sparc-rtems4.11-gdb-7.5.1-1
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <8>
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
cleaning: expat-2.1.0-x86_64-freebsd9.1-1     <9>
cleaning: sparc-rtems4.11-binutils-2.22-1
cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
cleaning: sparc-rtems4.11-gdb-7.5.1-1
Build Set: Time 0:13:43.616383        <10>

Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and RTEMS applications. When the build runs you will notice the tool fetch the source code from the internet. These files are cached in directies called source and patches. If you run the build again the cached files are used. This is what happened in the shown example. Archiving these directories archives the source you need to recreate the build.

The installed tools:

$ ls $HOME/development/rtems/4.11
bin         include     lib         libexec     share       sparc-rtems4.11
$ ls $HOME/development/rtems/4.11/bin
sparc-rtems4.11-addr2line       sparc-rtems4.11-cpp
sparc-rtems4.11-gcc-ar          sparc-rtems4.11-gprof
sparc-rtems4.11-objdump         sparc-rtems4.11-size
sparc-rtems4.11-ar              sparc-rtems4.11-elfedit
sparc-rtems4.11-gcc-nm          sparc-rtems4.11-ld
sparc-rtems4.11-ranlib          sparc-rtems4.11-strings
sparc-rtems4.11-as              sparc-rtems4.11-g++
sparc-rtems4.11-gcc-ranlib      sparc-rtems4.11-ld.bfd
sparc-rtems4.11-readelf         sparc-rtems4.11-strip
sparc-rtems4.11-c++             sparc-rtems4.11-gcc
sparc-rtems4.11-gcov            sparc-rtems4.11-nm
sparc-rtems4.11-run             xmlwf
sparc-rtems4.11-c++filt         sparc-rtems4.11-gcc-4.7.2
sparc-rtems4.11-gdb             sparc-rtems4.11-objcopy
sparc-rtems4.11-sis
$ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v
Using built-in specs.
COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc
COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \
libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper
Target: sparc-rtems4.11                         <1>
Configured with: ../gcc-4.7.2/configure         <2>
--prefix=/home/chris/development/rtems/4.11
--bindir=/home/chris/development/rtems/4.11/bin
--exec_prefix=/home/chris/development/rtems/4.11
--includedir=/home/chris/development/rtems/4.11/include
--libdir=/home/chris/development/rtems/4.11/lib
--libexecdir=/home/chris/development/rtems/4.11/libexec
--mandir=/home/chris/development/rtems/4.11/share/man
--infodir=/home/chris/development/rtems/4.11/share/info
--datadir=/home/chris/development/rtems/4.11/share
--build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11
--disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib
--with-system-zlib --disable-nls --without-included-gettext
--disable-win32-registry --enable-version-specific-runtime-libs --disable-lto
--enable-threads --enable-plugin --enable-newlib-io-c99-formats
--enable-newlib-iconv --enable-languages=c,c++
Thread model: rtems             <3>
gcc version 4.7.2 20120920      <4>
 (RTEMS 4.11 RSB cb12e4875c203f794a5cd4b3de36101ff9a88403)-1 newlib 2.0.0) (GCC)

2.5. Deployment¶

If you wish to create and distribute your build or you want to archive a build you can create a tar file. We term this deploying a build. This is a more advanced method for binary packaging and installing of tools.

By default the RTEMS Source Builder installs the built packages directly and optionally it can also create a build set tar file or a package tar file per package built. The normal and default behaviour is to let the RTEMS Source Builder install the tools. The source will be downloaded, built, installed and cleaned up.

The tar files are created with the full build prefix present and if you follow the examples given in this documentation the path is absolute. This can cause problems if you are installing on a host you do not have super user or administrator rights on because the prefix path may references part you do not have write access too and tar will not extract the files. You can use the --strip-components option in tar if your host tar application supports it to remove the parts you do not have write access too or you may need to unpack the tar file somewhere and copy the file tree from the level you have write access from. Embedding the full prefix path in the tar files lets you know what the prefix is and is recommended. For example if /home/chris/development/rtems/4.11 is the prefix used you cannot change directory to the root (/) and untar the file because the /home is root access only. To install a tar file you have downloaded into your new machine’s Downloads directory in your home directoty you would enter:

$ cd /somewhere
$ tar --strip-components=3 -xjf \
      $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2

A build set tar file is created by adding --bset-tar-file option to the sb-set-builder command:

$ ../source-builder/sb-set-builder --log=l-sparc.txt \
         --prefix=$HOME/development/rtems/4.11 \
         --bset-tar-file \     <1>
         4.11/rtems-sparc
Source Builder - Set Builder, v0.2.0
Build Set: 4.11/rtems-sparc
config: expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-freebsd9.1-1
building: expat-2.1.0-x86_64-freebsd9.1-1
config: tools/rtems-binutils-2.22-1.cfg
package: sparc-rtems4.11-binutils-2.22-1
building: sparc-rtems4.11-binutils-2.22-1
config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
config: tools/rtems-gdb-7.5.1-1.cfg
package: sparc-rtems4.11-gdb-7.5.1-1
building: sparc-rtems4.11-gdb-7.5.1-1
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2      <3>
cleaning: expat-2.1.0-x86_64-freebsd9.1-1
cleaning: sparc-rtems4.11-binutils-2.22-1
cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
cleaning: sparc-rtems4.11-gdb-7.5.1-1
Build Set: Time 0:15:25.92873

You can also suppress installing the files using the --no-install option. This is useful if your prefix is not accessiable, for example when building Canadian cross compiled tool sets:

$ ../source-builder/sb-set-builder --log=l-sparc.txt \
            --prefix=$HOME/development/rtems/4.11 \
            --bset-tar-file \
            --no-install \      <1>
            4.11/rtems-sparc
Source Builder - Set Builder, v0.2.0
Build Set: 4.11/rtems-sparc
config: expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-freebsd9.1-1
building: expat-2.1.0-x86_64-freebsd9.1-1
config: tools/rtems-binutils-2.22-1.cfg
package: sparc-rtems4.11-binutils-2.22-1
building: sparc-rtems4.11-binutils-2.22-1
config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
config: tools/rtems-gdb-7.5.1-1.cfg
package: sparc-rtems4.11-gdb-7.5.1-1
building: sparc-rtems4.11-gdb-7.5.1-1
tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2    <2>
cleaning: expat-2.1.0-x86_64-freebsd9.1-1
cleaning: sparc-rtems4.11-binutils-2.22-1
cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
cleaning: sparc-rtems4.11-gdb-7.5.1-1
Build Set: Time 0:14:11.721274
$ ls tar
rtems-4.11-sparc-rtems4.11-1.tar.bz2

A package tar file can be created by adding the --pkg-tar-files to the sb-set-builder command. This creates a tar file per package built in the build set:

$ ../source-builder/sb-set-builder --log=l-sparc.txt \
        --prefix=$HOME/development/rtems/4.11 \
        --bset-tar-file \
        --pkg-tar-files \        <1>
        --no-install 4.11/rtems-sparc
Source Builder - Set Builder, v0.2.0
Build Set: 4.11/rtems-sparc
config: expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-freebsd9.1-1
building: expat-2.1.0-x86_64-freebsd9.1-1
config: tools/rtems-binutils-2.22-1.cfg
package: sparc-rtems4.11-binutils-2.22-1
building: sparc-rtems4.11-binutils-2.22-1
config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
config: tools/rtems-gdb-7.5.1-1.cfg
package: sparc-rtems4.11-gdb-7.5.1-1
building: sparc-rtems4.11-gdb-7.5.1-1
tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
cleaning: expat-2.1.0-x86_64-freebsd9.1-1
cleaning: sparc-rtems4.11-binutils-2.22-1
cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
cleaning: sparc-rtems4.11-gdb-7.5.1-1
Build Set: Time 0:14:37.658460
$ ls tar
expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2

2.6. Controlling the Build¶

Build sets can be controlled via the command line to enable and disable various features. There is no definitive list of build options that can be listed because they are implemented with the configuration scripts. The best way to find what is available is to grep the configuration files. for with and without.

Following are currentlt available:

--without-rtems

Do not build RTEMS when building an RTEMS build set.

--without-cxx

Do not build a C++ compiler.

--with-objc

Attempt to build a C++ compiler.

--with-fortran

Attempt to build a Fortran compiler.

3.1. Linux¶

A number of different Linux distrubutions are known to work. The following have been tested and report as working.

# pacman -S base-devel gdb xz unzip ncurses git zlib

# pacman -R texinfo
$ yaourt -S texinfo-legacy
# ln -s /usr/bin/makeinfo-4.13a /usr/bin/makeinfo

# yum install autoconf automake binutils gcc gcc-c++ gdb make patch \
bison flex xz unzip ncurses-devel texinfo zlib-devel python-devel git

# yum install ncurses-devel python-devel git bison gcc cvs gcc-c++ \
     flex texinfo patch perl-Text-ParseWords zlib-devel

$ sudo apt-get install autoconf automake bison flex binutils gcc g++ gdb \
texinfo unzip ncurses-dev python-dev git

$ sudo apt-get build-dep binutils gcc g++ gdb unzip git
$ sudo apt-get install python2.7-dev

# sudo apt-get install zlib1g-dev

3.2. FreeBSD¶

The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3 and 11 64bit version. You need to install some ports. They are:

# cd /usr/ports
# portinstall --batch lang/python27

If you wish to build Windows (mingw32) tools please install the following ports:

# cd /usr/ports
# portinstall --batch devel/mingw32-binutils devel/mingw32-gcc
# portinstall --batch devel/mingw32-zlib devel/mingw32-pthreads

The +zlip+ and +pthreads+ ports for MinGW32 are used for builiding a Windows QEMU.

If you are on FreeBSD 10.0 and you have pkgng installed you can use ‘pkg install’ rather than ‘portinstall’.

3.3. NetBSD¶

The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add are:

# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/gmake-3.82nb7.tgz
# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/devel/bison-2.7.1.tgz
# pkg_add ftp://ftp.netbsd.org/pub/pkgsrc/packages/NetBSD/i386/6.1/archivers/xz-5.0.4.tgz

3.4. MacOS¶

The RTEMS Source Builder has been tested on Mountain Lion. You will need to install the Xcode app using the App Store tool, run Xcode and install the Developers Tools package within Xcode.

3.5. Windows¶

Windows tool sets are supported. The tools are native Windows executable which means they do not need an emulation layer to run once built. The tools understand and use standard Windows paths and integrate easily into Windows IDE environments because they understand and use standard Windows paths. Native Windows tools have proven over time to be stable and reliable with good performance. If you are a Windows user or you are required to use Windows you can still develop RTEMS application as easily as a Unix operating system. Some debugging experiences may vary and if this is an issue please raised the topic on the RTEMS Users mailing list.

Building the tools or some other packages may require a Unix or POSIX type shell. There are a few options, Cygwin and MSYS2. I recommend MSYS2.

$ pacman -S git cvs bison make texinfo patch unzip diffutils tar \
         mingw64/mingw-w64-x86_64-gcc mingw64/mingw-w64-x86_64-binutils

chris@cygthing ~/development/rtems/src/rtems-source-builder/rtems
$ ../source-builder/sb-set-builder --log=l-arm.txt --prefix=$HOME/development/rtems/4.10 4.10/rtems-arm
RTEMS Source Builder - Set Builder, v0.2
Build Set: 4.10/rtems-arm
config: expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-w64-mingw32-1
building: expat-2.1.0-x86_64-w64-mingw32-1
reporting: expat-2.1.0-1.cfg -> expat-2.1.0-x86_64-w64-mingw32-1.html
config: tools/rtems-binutils-2.20.1-1.cfg
package: arm-rtems4.10-binutils-2.20.1-1   <1>
building: arm-rtems4.10-binutils-2.20.1-1
package: (Cxc) arm-rtems4.10-binutils-2.20.1-1   <2>
building: (Cxc) arm-rtems4.10-binutils-2.20.1-1
reporting: tools/rtems-binutils-2.20.1-1.cfg ->
arm-rtems4.10-binutils-2.20.1-1.html
config: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg
package: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
building: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
package: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
building: (Cxc) arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
reporting: tools/rtems-gcc-4.4.7-newlib-1.18.0-1.cfg ->
arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1.html
config: tools/rtems-gdb-7.3.1-1.cfg
package: arm-rtems4.10-gdb-7.3.1-1
building: arm-rtems4.10-gdb-7.3.1-1
reporting: tools/rtems-gdb-7.3.1-1.cfg -> arm-rtems4.10-gdb-7.3.1-1.html
config: tools/rtems-kernel-4.10.2.cfg
package: arm-rtems4.10-kernel-4.10.2-1
building: arm-rtems4.10-kernel-4.10.2-1
reporting: tools/rtems-kernel-4.10.2.cfg -> arm-rtems4.10-kernel-4.10.2-1.html
installing: expat-2.1.0-x86_64-w64-mingw32-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
installing: arm-rtems4.10-binutils-2.20.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10 <3>
installing: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
installing: arm-rtems4.10-gdb-7.3.1-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
installing: arm-rtems4.10-kernel-4.10.2-1 -> /cygdrive/c/Users/chris/development/rtems/4.10
cleaning: expat-2.1.0-x86_64-w64-mingw32-1
cleaning: arm-rtems4.10-binutils-2.20.1-1
cleaning: arm-rtems4.10-gcc-4.4.7-newlib-1.18.0-1
cleaning: arm-rtems4.10-gdb-7.3.1-1
cleaning: arm-rtems4.10-kernel-4.10.2-1
Build Set: Time 10:09:42.810547   <4>

4.1. Bare Metal¶

The RSB contains a ‘bare’ configuration tree and you can use this to add packages you use on the hosts. For example ‘qemu’ is supported on a range of hosts. RTEMS tools live in the rtems/config directory tree. RTEMS packages include tools for use on your host computer as well as packages you can build and run on RTEMS.

The bare metal support for GNU Tool chains. An example is the lang/gcc491 build set. You need to provide a target via the command line --target option and this is in the standard 2 or 3 tuple form. For example for an ARM compiler you would use arm-eabi or ``arm-eabihf`, and for SPARC you would use sparc-elf:

$ cd rtems-source-builder/bare
$ ../source-builder/sb-set-builder --log=log_arm_eabihf \
    --prefix=$HOME/development/bare --target=arm-eabihf lang/gcc491
RTEMS Source Builder - Set Builder, v0.3.0
Build Set: lang/gcc491
config: devel/expat-2.1.0-1.cfg
package: expat-2.1.0-x86_64-apple-darwin13.2.0-1
building: expat-2.1.0-x86_64-apple-darwin13.2.0-1
config: devel/binutils-2.24-1.cfg
package: arm-eabihf-binutils-2.24-1
building: arm-eabihf-binutils-2.24-1
config: devel/gcc-4.9.1-newlib-2.1.0-1.cfg
package: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
building: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
config: devel/gdb-7.7-1.cfg
package: arm-eabihf-gdb-7.7-1
building: arm-eabihf-gdb-7.7-1
installing: expat-2.1.0-x86_64-apple-darwin13.2.0-1 -> /Users/chris/development/bare
installing: arm-eabihf-binutils-2.24-1 -> /Users/chris/development/bare
installing: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1 -> /Users/chris/development/bare
installing: arm-eabihf-gdb-7.7-1 -> /Users/chris/development/bare
cleaning: expat-2.1.0-x86_64-apple-darwin13.2.0-1
cleaning: arm-eabihf-binutils-2.24-1
cleaning: arm-eabihf-gcc-4.9.1-newlib-2.1.0-1
cleaning: arm-eabihf-gdb-7.7-1

4.2. RTEMS¶

The RTEMS Configurations found in the rtems directory. The configurations are grouped by RTEMS version. In RTEMS the tools are specific to a specific version because of variations between Newlib and RTEMS. Restructuring in RTEMS and Newlib sometimes moves libc functionality between these two parts and this makes existing tools incompatible with RTEMS.

RTEMS allows architectures to have different tool versions and patches. The large number of architectures RTEMS supports can make it difficult to get a common stable version of all the packages. An architecture may require a recent GCC because an existing bug has been fixed, however the more recent version may have a bug in other architecture. Architecture specific patches should be limited to the architecture it relates to. The patch may fix a problem on the effect architecture however it could introduce a problem in another architecture. Limit exposure limits any possible crosstalk between architectures.

If you are building a released version of RTEMS the release RTEMS tar file will be downloaded and built as part of the build process. If you are building a tool set for use with the development branch of RTEMS, the development branch will be cloned directly from the RTEMS GIT repository and built.

When building RTEMS within the RTEMS Source Builder it needs a suitable working autoconf and automake. These packages need to built and installed in their prefix in order for them to work. The RTEMS Source Builder installs all packages only after they have been built so if you host does not have a recent enough version of autoconf and automake you first need to build them and install them then build your tool set. The commands are:

$ ../source-builder/sb-set-builder --log=l-4.11-at.txt \
   --prefix=$HOME/development/rtems/4.11 4.11/rtems-autotools
$ export PATH=~/development/rtems/4.11/bin:$PATH    <1>
$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
   --prefix=$HOME/development/rtems/4.11 4.11/rtems-sparc

If this is your first time building the tools and RTEMS it pays to add the --dry-run option. This will run through all the configuration files and if any checks fail you will see this quickly rather than waiting for until the build fails a check.

To build snapshots for testing purposes you use the available macro maps passing them on the command line using the --macros option. For RTEMS these are held in config/snapshots directory. The following builds newlib from CVS:

$ ../source-builder/sb-set-builder --log=l-4.11-sparc.txt \
   --prefix=$HOME/development/rtems/4.11 \
   --macros=snapshots/newlib-head.mc \
   4.11/rtems-sparc

and the following uses the version control heads for binutils, gcc, newlib, gdb and RTEMS:

$ ../source-builder/sb-set-builder --log=l-heads-sparc.txt \
   --prefix=$HOME/development/rtems/4.11-head \
   --macros=snapshots/binutils-gcc-newlib-gdb-head.mc \
   4.11/rtems-sparc

4.3. Patches¶

Packages being built by the RSB need patches from time to time and the RSB supports patching upstream packages. The patches are held in a seperate directory called patches relative to the configuration directory you are building. For example %{_topdir}/patches:%{_sbdir}/patches. Patches are declared in the configuration files in a similar manner to the package’s source so please refer to the %source documentation. Patches, like the source, are to be made publically available for configurations that live in the RSB package and are downloaded on demand.

If a package has a patch management tool it is recommended you reference the package’s patch management tools directly. If the RSB does not support the specific patch manage tool please contact the mailing list to see if support can be added.

Patches for packages developed by the RTEMS project can be placed in the RTEMS Tools Git repository. The tools directory in the repository has various places a patch can live. The tree is broken down in RTEMS releases and then tools within that release. If the package is not specific to any release the patch can be added closer to the top under the package’s name. Patches to fix specific tool related issues for a specific architecture should be grouped under the specific architecture and only applied when building that architecture avoiding a patch breaking an uneffected architecture.

Patches in the RTEMS Tools repository need to be submitted to the upstream project. It should not be a clearing house for patches that will not be accepted upstream.

Patches are added to a component’s name and in the %prep: section the patches can be set up, meaning they are applied to source. The patches are applied in the order they are added. If there is a dependency make sure you order the patches correctly when you add them. You can add any number of patches and the RSB will handle them efficently.

Patches can have options. These are added before the patch URL. If no options are provided the patch’s setup default options are used.

Patches can be declared in build set up files.

This examples shows how to declare a patch for gdb in the lm32 architecture:

%patch add <1> gdb <2> %{rtems_gdb_patches}/lm32/gdb-sim-lm32uart.diff <3>

Patches require a checksum to avoid a warning. The %hash directive can be used to add a checksum for a patch that is used to verify the patch:

%hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>

The patches are applied when a patch setup command is issued in the %prep: section. All patches in the group are applied. To apply the GDB patch above use:

%patch setup <1> gdb <2> -p1 <3>

Architecture specific patches live in the architecture build set file isolating the patch to that specific architecture. If a patch is common to a tool it resides in the RTEMS tools configuration file. Do not place patches for tools in the source-builder/config template configuration files.

To test a patch simply copy it to your local patches directory. The RSB will see the patch is present and will not attempt to download it. Once you are happy with the patch submit it to the project and a core developer will review it and add it to the RTEMS Tools git repository. For example, to test a local patch for newlib, add the following two lines to the .cfg file in rtems/config/tools/ that is included by the bset you use:

%patch add newlib file://0001-this-is-a-newlib-patch.patch   <1>
%hash md5 0001-this-is-a-newlib-patch.diff 77d070878112783292461bd6e7db17fb <2>

5.1. Cross Building¶

Cross building is where the _build_ machine and _host_ are different. The _build_ machine runs the RSB and the _host_ machine is where the output from the build runs. An example is building a package such as NTP for RTEMS on your development machine.

To build the NTP package for RTEMS you enter the RSB command:

$ ../source-builder/sb-set-builder \
   --log=log_ntp_arm.txt \
   --prefix=$HOME/development/rtems/4.11 \  <1>
   --host=arm-rtems4.11 \  <2>
   --with-rtems-bsp=xilinx_zynq_zc706 \  <3>
   4.11/net/ntp

5.2. Canadian Cross Building¶

A Canadian cross builds are where the build, host and target machines all differ. For example building an RTEMS compiler for an ARM processor that runs on Windows is built using a Linux machine. The process is controlled by setting the build triplet to the host you are building, the host triplet to the host the tools will run on and the target to the RTEMS architecture you require. The tools needed by the RSB are:

• Build host C and C++ compiler
• Host C and C++ cross compiler

The RTEMS Source Builder requires you provide the build host C and C++ compiler and the final host C and C++ cross-compiler. The RSB will build the build host RTEMS compiler and the final host RTEMS C and C++ compiler, the output of this process.

The Host C and C++ compiler is a cross-compiler that builds executables for the host you want the tools for. You need to provide these tools. For Windows a number of Unix operating systems provide MinGW tool sets as packages.

The RSB will build an RTEMS tool set for the build host. This is needed when building the final host’s RTEMS compiler as it needs to build RTEMS runtime code such as libc on the build host.

TIP: Make sure the host’s cross-compiler tools are in your path before run the RSB build command.

TIP: Canadian Cross built tools will not run on the machine being used to build them so you should provide the --bset-tar-files and --no-install options. The option to not install the files lets you provide a prefix that does not exist or you cannot access.

To perform a cross build add --host= to the command line. For example to build a MinGW tool set on FreeBSD for Windows add --host=mingw32 if the cross compiler is mingw32-gcc:

$ ../source-builder/sb-set-builder --host=mingw32 \
   --log=l-mingw32-4.11-sparc.txt \
   --prefix=$HOME/development/rtems/4.11 \
   4.11/rtems-sparc

If you are on a Linux Fedora build host with the MinGW packages installed the command line is:

$ ../source-builder/sb-set-builder --host=i686-w64-mingw32 \
   --log=l-mingw32-4.11-sparc.txt \
   --prefix=$HOME/development/rtems/4.11 \
   4.11/rtems-sparc

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.

7.1. Source and Patches¶

The RTEMS Source Builder provides a flexible way to manage source. Source and patches are declare in configurations file using the source and patch directives. These are a single line containing a Universal Resource Location or URL and can contain macros and shell expansions. The Chapter 7 Section 8.2 - %prep section details the source and patch directives

The URL can reference remote and local source and patch resources. The following schemes are provided:

http:

Remote access using the HTTP protocol.

https:

Remote access using the Secure HTTP protocol.

ftp:

Remote access using the FTP protocol.

git:

Remote access to a GIT repository.

pm:

Remote access to a patch management repository.

file:

Local access to an existing source directory.

%source set<1> gcc<2> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2

%define stlink_version 3494c11
%source set stlink https://api.github.com/repos/texane/stlink/texane-stlink-%{stlink_version}.tar.gz

%source set gcc git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard

%source set newlib cvs://pserver:anoncvs@sourceware.org/cvs/src?module=newlib?src-prefix=src

7.2. Macros and Defaults¶

The RTEMS Source Builder uses tables of macros read in when the tool runs. The initial global set of macros is called the defaults. These values are read from a file called defaults.mc and modified to suite your host. This host specific adaption lets the Source Builder handle differences in the build hosts.

Build set and configuration files can define new values updating and extending the global macro table. For example builds are given a release number. This is typically a single number at the end of the package name. For example:

%define release 1

Once defined if can be accessed in a build set or package configuration file with:

%{release}

The sb-defaults command lists the defaults for your host. I will not include the output of this command because of its size:

$ ../source-builder/sb-defaults

A nested build set is given a separate copy of the global macro maps. Changes in one change set are not seen in other build sets. That same happens with configuration files unless inline includes are used. Inline includes are seen as part of the same build set and configuration and changes are global to that build set and configuration.

Name Type Attribute String

# Comments
[my-special-map] <1>
_host:  none, override, 'abc-xyz'
multiline: none, override, '''First line,
second line,
and finally the last line'''

%select my-special-map

# <1>
# Build all tool parts from version control head.
#
%include %{_configdir}/snapshots/binutils-head.mc
%include %{_configdir}/snapshots/gcc-head.mc
%include %{_configdir}/snapshots/newlib-head.mc
%include %{_configdir}/snapshots/gdb-head.mc

7.3. Report Mailing¶

The build reports can be mailed to a specific email address to logging and monitoring. Mailing requires a number of parameters to function. These are:

• To mail address
• From mail address
• SMTP host

The to mail address is taken from the macro %{_mail_tools_to} and the default is rtems-tooltestresults at rtems.org. You can override the default with a personal or user macro file or via the command line option --mail-to.

The from mail address is taken from:

• GIT configuration
• User .mailrc file
• Command line

If you have configured an email and name in git it will be used used. If you do not a check is made for a .mailrc file. The environment variable MAILRC is used if present else your home directory is check. If found the file is scanned for the from setting:

set from="Foo Bar <foo@bar>"

You can also support a from address on the command line with the --mail-from option.

The SMTP host is taken from the macro %{_mail_smtp_host} and the default is localhost. You can override the default with a personal or user macro file or via the command line option --smtp-host.

7.4. Build Set Files¶

Build set files lets you list the packages in the build set you are defining and have a file extension of .bset. Build sets can define macro variables, inline include other files and reference other build set or package configuration files.

Defining macros is performed with the %define macro:

%define _target m32r-rtems4.11

Inline including another file with the %include macro continues processing with the specified file returning to carry on from just after the include point:

%include rtems-4.11-base.bset

This includes the RTEMS 4.11 base set of defines and checks. The configuration paths as defined by _configdir are scanned. The file extension is optional.

You reference build set or package configuration files by placing the file name on a single line:

tools/rtems-binutils-2.22-1

The _configdir path is scanned for tools/rtems-binutils-2.22-1.bset or tools/rtems-binutils-2.22-1.cfg. Build set files take precedent over package configuration files. If tools/rtems-binutils-2.22-1 is a build set a new instance of the build set processor is created and if the file is a package configuration the package is built with the package builder. This all happens once the build set file has finished being scanned.

7.5. Configuration Control¶

The RTEMS Souce Builder is designed to fit within most verification and validation processes. All of the RTEMS Source Builder is source code. The Python code is source and comes with a commercial friendly license. All configuration data is text and can be read or parsed with standard text based tools.

File naming provides configuration management. A specific version of a package is captured in a specific set of configuration files. The top level configuration file referenced in a build set or passed to the sb-builder command relates to a specific configuration of the package being built. For example the RTEMS configuration file rtems-gcc-4.7.2-newlib-2.0.0-1.cfg creates an RTEMS GCC and Newlib package where the GCC version is 4.7.2, the Newlib version is 2.0.0, plus any RTEMS specific patches that related to this version. The configuration defines the version numbers of the various parts that make up this package:

%define gcc_version    4.7.2
%define newlib_version 2.0.0
%define mpfr_version   3.0.1
%define mpc_version    0.8.2
%define gmp_version    5.0.5

The package build options, if there are any are also defined:

%define with_threads 1
%define with_plugin  0
%define with_iconv   1

The generic configuration may provide defaults in case options are not specified. The patches this specific version of the package requires can be included:

Patch0: gcc-4.7.2-rtems4.11-20121026.diff

Finally including the GCC 4.7 configuration script:

%include %{_configdir}/gcc-4.7-1.cfg

The gcc-4.7-1.cfg file is a generic script to build a GCC 4.7 compiler with Newlib. It is not specific to RTEMS. A bare no operating system tool set can be built with this file.

The -1 part of the file names is a revision. The GCC 4.7 script maybe revised to fix a problem and if this fix effects an existing script the file is copied and given a -2 revision number. Any dependent scripts referencing the earlier revision number will not be effected by the change. This locks down a specific configuration over time.

7.6. Personal Configurations¶

The RSB supports personal configurations. You can view the RTEMS support in the rtems directory as a private configuration tree that resides within the RSB source. There is also the bare set of configurations. You can create your own configurations away from the RSB source tree yet use all that the RSB provides.

To create a private configuration change to a suitable directory:

$ cd ~/work
$ mkdir test
$ cd test
$ mkdir config

and create a config directory. Here you can add a new configuration or build set file. The section ‘Adding New Configurations’ details how to add a new confguration.

7.7. New Configurations¶

This section describes how to add a new configuration to the RSB. We will add a configuration to build the Device Tree Compiler. The Device Tree Compiler or DTC is part of the Flattened Device Tree project and compiles Device Tree Source (DTS) files into Device Tree Blobs (DTB). DTB files can be loaded by operating systems and used to locate the various resources such as base addresses of devices or interrupt numbers allocated to devices. The Device Tree Compiler source code can be downloaded from http://www.jdl.com/software. The DTC is supported in the RSB and you can find the configuration files under the bare/config tree. I suggest you have a brief look over these files.

#
# DTC 1.x.x Version 1.
#
# This configuration file configure's, make's and install's DTC.
#

%if %{release} == %{nil}
%define release 1
%endif

Name:      dtc-%{dtc_version}-%{_host}-%{release}
Summary:   Device Tree Compiler v%{dtc_version} for target %{_target} on host %{_host}
Version:   %{dtc_version}
Release:   %{release}
URL:           http://www.jdl.com/software/
BuildRoot: %{_tmppath}/%{name}-root-%(%{__id_u} -n)

#
# Source
#
%source set dtc http://www.jdl.com/software/dtc-v%{dtc_version}.tgz

#
# Prepare the source code.
#
%prep
  build_top=$(pwd)

  %source setup dtc -q -n dtc-v%{dtc_version}
  %patch setup dtc -p1

  cd ${build_top}

%build
  build_top=$(pwd)

  cd dtc-v%{dtc_version}

  %{build_build_flags}

  %{__make} PREFIX=%{_prefix}

  cd ${build_top}

%install
  build_top=$(pwd)

  %{__rmdir} -rf $SB_BUILD_ROOT

  cd dtc-v%{dtc_version}
  %{__make} DESTDIR=$SB_BUILD_ROOT PREFIX=%{_prefix} install

  cd ${build_top}

$  ../source-builder/sb-builder --prefix=/usr/local \
     --log=log_dtc devel/dtc-1.2.0
RTEMS Source Builder, Package Builder v0.2.0
config: devel/dtc-1.2.0
package: dtc-1.2.0-x86_64-freebsd9.1-1
download: http://www.jdl.com/software/dtc-v1.2.0.tgz -> sources/dtc-v1.2.0.tgz
building: dtc-1.2.0-x86_64-freebsd9.1-1
$ ls tar
dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2

#
# Build the DTC.
#

%define release 1

devel/dtc-1.2.0.cfg

$ ../source-builder/sb-set-builder --prefix=/usr/local --log=log_dtc \
   --trace --bset-tar-file --no-install dtc
RTEMS Source Builder - Set Builder, v0.2.0
Build Set: dtc
config: devel/dtc-1.2.0.cfg
package: dtc-1.2.0-x86_64-freebsd9.1-1
building: dtc-1.2.0-x86_64-freebsd9.1-1
tarball: tar/x86_64-freebsd9.1-dtc-set.tar.bz2
cleaning: dtc-1.2.0-x86_64-freebsd9.1-1
Build Set: Time 0:00:02.865758
$ ls tar
dtc-1.2.0-x86_64-freebsd9.1-1.tar.bz2   x86_64-freebsd9.1-dtc-set.tar.bz2

7.8. Scripting¶

Configuration files specify how to build a package. Configuration files are scripts and have a .cfg file extension. The script format is based loosely on the RPM spec file format however the use and purpose in this tool does not compare with the functionality and therefore the important features of the spec format RPM needs and uses.

The script language is implemented in terms of macros. The built-in list is:

%{}:

Macro expansion with conditional logic.

%():

Shell expansion.

%prep:

The source preparation shell commands.

%build:

The build shell commands.

%install:

The package install shell commands.

%clean:

The package clean shell commands.

%include:

Inline include another configuration file.

%name:

The name of the package.

%summary:

A brief package description. Useful when reporting about a build.

%release:

The package release. A number that is the release as built by this tool.

%version:

The package’s version string.

%buildarch:

The build architecture.

%source:

Define a source code package. This macro has a number appended.

%patch:

Define a patch. This macro has a is number appended.

%hash:

Define a checksum for a source or patch file.

%echo:

Print the following string as a message.

%warning:

Print the following string as a warning and continue.

%error:

Print the following string as an error and exit.

%select:

Select the macro map. If there is no map nothing is reported.

%define:

Define a macro. Macros cannot be redefined, you must first undefine it.

%undefine:

Undefine a macro.

%if:

Start a conditional logic block that ends with a %endif.

%ifn:

Inverted start of a conditional logic block.

%ifarch:

Test the architecture against the following string.

%ifnarch:

Inverted test of the architecture

%ifos:

Test the host operating system.

%else:

Start the else conditional logic block.

%endfi:

End the conditional logic block.

%bconf_with:

Test the build condition with setting. This is the --with-* command line option.

%bconf_without:

Test the build condition without setting. This is the --without-* command line option.

              <1>                <2>      <3>
%source setup gcc -q -c -T -n %{name}-%{version}

%source set gdb http://ftp.gnu.org/gnu/gdb/gdb-%{gdb_version}.tar.bz2

%source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-code-%{gcc_version}.tar.bz2
%source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-g++-%{gcc_version}.tar.bz2
%source setup gcc -q -T -D -n gcc-%{gcc_version}

%source set gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
%source set newlib ftp://sourceware.org/pub/newlib/newlib-%{newlib_version}.tar.gz
%source set mpfr http://www.mpfr.org/mpfr-%{mpfr_version}/mpfr-%{mpfr_version}.tar.bz2
%source set mpc http://www.multiprecision.org/mpc/download/mpc-%{mpc_version}.tar.gz
%source set gmp ftp://ftp.gnu.org/gnu/gmp/gmp-%{gmp_version}.tar.bz2

%source setup gcc -q -n gcc-%{gcc_version}
%source setup newlib -q -D -n newlib-%{newlib_version}
%source setup mpfr -q -D -n mpfr-%{mpfr_version}
%source setup mpc -q -D -n mpc-%{mpc_version}
%source setup gmp -q -D -n gmp-%{gmp_version}

%patch add gdb %{rtems_gdb_patches}/gdb-sim-arange-inline.diff
%patch add gdb -p0 <1> %{rtems_gdb_patches}/gdb-sim-cgen-inline.diff

%patch setup gdb -p1 <1>

%build
  export PATH="%{_bindir}:${PATH}" <1>

  cd texane-stlink-%{stlink_version} <2>

  ./autogen.sh <3>

%if "%{_build}" != "%{_host}"
  CFLAGS_FOR_BUILD="-g -O2 -Wall" \ <4>
%endif
  CPPFLAGS="-I $SB_TMPPREFIX/include/libusb-1.0" \ <5>
  CFLAGS="$SB_OPT_FLAGS" \
  LDFLAGS="-L $SB_TMPPREFIX/lib" \
  ./configure \ <6>
    --build=%{_build} --host=%{_host} \
    --verbose \
    --prefix=%{_prefix} --bindir=%{_bindir} \
    --exec-prefix=%{_exec_prefix} \
    --includedir=%{_includedir} --libdir=%{_libdir} \
    --mandir=%{_mandir} --infodir=%{_infodir}

  %{__make} %{?_smp_mflags} all <7>

  cd ..

%install
  export PATH="%{_bindir}:${PATH}" <1>
  rm -rf $SB_BUILD_ROOT <2>

  cd texane-stlink-%{stlink_version} <3>
  %{__make} DESTDIR=$SB_BUILD_ROOT install <4>

  cd ..

%include %{_configdir}/gcc-4.7-1.cfg

Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release}

Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}

%define release 1

Version: %{gcc_version}

%source set gcc <1> ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2

%source add gcc ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/g++-%{gcc_version}.tar.bz2

%source gcc setup -q -T -D -n %{name}-%{version}

%patch add gcc <1>  gcc-4.7.2-rtems4.11-20121026.diff
%patch add gcc -p0 <2>  gcc-4.7.2-rtems4.11-20121101.diff

  %patch setup gcc <1>  -p1 <2>

1. The patch group.

2. The default option used to apply the patch.

%hash md5 <1> net-snmp-%{net_snmp_version}.tar.gz <2> 7db683faba037249837b226f64d566d4 <3>

%select gcc-4.8-snapshot <1>
%define one_plus_one 2 <2>

%define foo bar
%define one_plus_one 2
%define one <1>

%if ${foo}
 %warning The test passes, must not be empty or is non-zero
%else
 %error The test fails, must be empty or zero
%endif

%if ! ${foo}
 %warning The test passes, must be empty or zero
%else
 %error The test fails, must not be empty or is non-zero
%endif

%define one 1
%if ${one} == 1
 %warning The test passes
%else
 %error The test fails
%endif

%if ${nothing} == %{nil}
 %warning The test passes
%else
 %error The test fails

#
# Check a value not being equal.
#
%define one 1
%if ${one} != 2
 %warning The test passes
%else
 %error The test fails
%endif
#
# Check if a macro is set.
#
%if ${something} != %{nil}
  %warning The test passes
%else
 %error The test fails
%endif

%ifn %{defined foo}
 %define foo bar
%endif

8.1. Checker (sb-check)¶

This commands checks your system is set up correctly. Most options are ignored:

$ ../source-builder/sb-check --help
sb-check: [options] [args]
RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
Options and arguments:
--force                : Force the build to proceed
--quiet                : Quiet output (not used)
--trace                : Trace the execution
--dry-run              : Do everything but actually run the build
--warn-all             : Generate warnings
--no-clean             : Do not clean up the build tree
--always-clean         : Always clean the build tree, even with an error
--jobs                 : Run with specified number of jobs, default: num CPUs.
--host                 : Set the host triplet
--build                : Set the build triplet
--target               : Set the target triplet
--prefix path          : Tools build prefix, ie where they are installed
--topdir path          : Top of the build tree, default is $PWD
--configdir path       : Path to the configuration directory, default: ./config
--builddir path        : Path to the build directory, default: ./build
--sourcedir path       : Path to the source directory, default: ./source
--tmppath path         : Path to the temp directory, default: ./tmp
--macros file[,[file]  : Macro format files to load after the defaults
--log file             : Log file where all build out is written too
--url url[,url]        : URL to look for source
--no-download          : Disable the source downloader
--targetcflags flags   : List of C flags for the target code
--targetcxxflags flags : List of C++ flags for the target code
--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
--with-<label>         : Add the --with-<label> to the build
--without-<label>      : Add the --without-<label> to the build
--regression           : Set --no-install, --keep-going and --always-clean
$ ../source-builder/sb-check
RTEMS Source Builder - Check, v0.2.0
Environment is ok

8.2. Defaults (sb-defaults)¶

This commands outputs and the default macros for your when given no arguments. Most options are ignored:

$ ../source-builder/sb-defaults --help
sb-defaults: [options] [args]
RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
Options and arguments:
--force                : Force the build to proceed
--quiet                : Quiet output (not used)
--trace                : Trace the execution
--dry-run              : Do everything but actually run the build
--warn-all             : Generate warnings
--no-clean             : Do not clean up the build tree
--always-clean         : Always clean the build tree, even with an error
--jobs                 : Run with specified number of jobs, default: num CPUs.
--host                 : Set the host triplet
--build                : Set the build triplet
--target               : Set the target triplet
--prefix path          : Tools build prefix, ie where they are installed
--topdir path          : Top of the build tree, default is $PWD
--configdir path       : Path to the configuration directory, default: ./config
--builddir path        : Path to the build directory, default: ./build
--sourcedir path       : Path to the source directory, default: ./source
--tmppath path         : Path to the temp directory, default: ./tmp
--macros file[,[file]  : Macro format files to load after the defaults
--log file             : Log file where all build out is written too
--url url[,url]        : URL to look for source
--no-download          : Disable the source downloader
--targetcflags flags   : List of C flags for the target code
--targetcxxflags flags : List of C++ flags for the target code
--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
--with-<label>         : Add the --with-<label> to the build
--without-<label>      : Add the --without-<label> to the build
--regression           : Set --no-install, --keep-going and --always-clean

8.3. Set Builder (sb-set-builder)¶

This command builds a set:

$ ../source-builder/sb-set-builder --help
RTEMS Source Builder, an RTEMS Tools Project (c) 2012-2013 Chris Johns
Options and arguments:
--force                : Force the build to proceed
--quiet                : Quiet output (not used)
--trace                : Trace the execution
--dry-run              : Do everything but actually run the build
--warn-all             : Generate warnings
--no-clean             : Do not clean up the build tree
--always-clean         : Always clean the build tree, even with an error
--regression           : Set --no-install, --keep-going and --always-clean
---jobs                 : Run with specified number of jobs, default: num CPUs.
--host                 : Set the host triplet
--build                : Set the build triplet
--target               : Set the target triplet
--prefix path          : Tools build prefix, ie where they are installed
--topdir path          : Top of the build tree, default is $PWD
--configdir path       : Path to the configuration directory, default: ./config
--builddir path        : Path to the build directory, default: ./build
--sourcedir path       : Path to the source directory, default: ./source
--tmppath path         : Path to the temp directory, default: ./tmp
--macros file[,[file]  : Macro format files to load after the defaults
--log file             : Log file where all build out is written too
--url url[,url]        : URL to look for source
--no-download          : Disable the source downloader
--no-install           : Do not install the packages to the prefix
--targetcflags flags   : List of C flags for the target code
--targetcxxflags flags : List of C++ flags for the target code
--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
--with-<label>         : Add the --with-<label> to the build
--without-<label>      : Add the --without-<label> to the build
--mail-from            : Email address the report is from.
--mail-to              : Email address to send the email too.
--mail                 : Send email report or results.
--smtp-host            : SMTP host to send via.
--no-report            : Do not create a package report.
--report-format        : The report format (text, html, asciidoc).
--bset-tar-file        : Create a build set tar file
--pkg-tar-files        : Create package tar files
--list-bsets           : List available build sets
--list-configs         : List available configurations
--list-deps            : List the dependent files.

The arguments are a list of build sets to build.

Options:

--force:

Force the build to proceed even if the host check fails. Typically this happens if executable files are found in the path at a different location to the host defaults.

--trace:

Trace enable printing of debug information to stdout. It is really only of use to RTEMS Source Builder’s developers.

--dry-run:

Do everything but actually run the build commands. This is useful when checking a new configuration parses cleanly.

--warn-all:

Generate warnings.

--no-clean:

Do not clean up the build tree during the cleaning phase of the build. This leaves the source and the build output on disk so you can make changes, or amend or generate new patches. It also allows you to review configure type output such as config.log.

--always-clean:

Clean away the results of a build even if the build fails. This is normally used with --keep-going when regression testing to see which build sets fail to build. It keeps the disk usage down.

--jobs:

Control the number of jobs make is given. The jobs can be none for only 1 job, half so the number of jobs is half the number of detected cores, a fraction such as 0.25 so the number of jobs is a quarter of the number of detected cores and a number such as 25 which forces the number of jobs to that number.

--host:

Set the host triplet value. Be careful with this option.

--build:

Set the build triplet. Be careful with this option.

--target:

Set the target triplet. Be careful with this option. This is useful if you have a generic configuration script that can work for a range of architectures.

--prefix path:

Tools build prefix, ie where they are installed.

--topdir path:

Top of the build tree, that is the current directory you are in.

--configdir path:

Path to the configuration directory. This overrides the built in defaults.

--builddir path:

Path to the build directory. This overrides the default of +build+.

--sourcedir path:

Path to the source directory. This overrides the default of +source+.

--tmppath path:

Path to the temporary directory. This overrides the default of +tmp+.

--macros files:

Macro files to load. The configuration directory path is searched.

--log file:

Log all the output from the build process. The output is directed to +stdout+ if no log file is provided.

--url url:

URL to look for source when downloading. This is can be comma separate list.

--no-download:

Disable downloading of source and patches. If the source is not found an error is raised.

--targetcflags flags:

List of C flags for the target code. This allows for specific local customisation when testing new variations.

--targetcxxflags flags:

List of C++ flags for the target code. This allows for specific local customisation when testing new variations.

--libstdcxxflags flags:

List of C++ flags to build the target libstdc++ code. This allows for specific local customisation when testing new variations.

--with-<label>:

Add the --with-<label> to the build. This can be tested for in a script with the %bconf_with macro.

--without-<label>:

Add the --without-<label> to the build. This can be tested for in a script with the %bconf_without macro.

--mail-from:

Set the from mail address if report mailing is enabled.

--mail-to:

Set the to mail address if report mailing is enabled. The report is mailed to this address.

--mail:

Mail the build report to the mail to address.

--smtp-host:

The SMTP host to use to send the email. The default is localhost.

--no-report:

Do not create a report format.

--report-format format:

The report format can be text or html. The default is html.

--keep-going:

Do not stop on error. This is useful if your build sets performs a large number of testing related builds and there are errors.

--always-clean:

Always clean the build tree even with a failure.

--no-install:

Do not install the packages to the prefix. Use this if you are only after the tar files.

--regression:

A convenience option which is the same as --no-install, --keep-going and --always-clean.

--bset-tar-file:

Create a build set tar file. This is a single tar file of all the packages in the build set.

--pkg-tar-files:

Create package tar files. A tar file will be created for each package built in a build set.

--list-bsets:

List available build sets.

--list-configs:

List available configurations.

--list-deps:

Print a list of dependent files used by a build set. Dependent files have a dep[?]` prefix where ``? is a number. The files are listed alphabetically.

8.4. Set Builder (sb-builder)¶

This command builds a configuration as described in a configuration file. Configuration files have the extension of .cfg:

$ ./source-builder/sb-builder --help
sb-builder: [options] [args]
RTEMS Source Builder, an RTEMS Tools Project (c) 2012 Chris Johns
Options and arguments:
--force                : Force the build to proceed
--quiet                : Quiet output (not used)
--trace                : Trace the execution
--dry-run              : Do everything but actually run the build
--warn-all             : Generate warnings
--no-clean             : Do not clean up the build tree
--always-clean         : Always clean the build tree, even with an error
--jobs                 : Run with specified number of jobs, default: num CPUs.
--host                 : Set the host triplet
--build                : Set the build triplet
--target               : Set the target triplet
--prefix path          : Tools build prefix, ie where they are installed
--topdir path          : Top of the build tree, default is $PWD
--configdir path       : Path to the configuration directory, default: ./config
--builddir path        : Path to the build directory, default: ./build
--sourcedir path       : Path to the source directory, default: ./source
--tmppath path         : Path to the temp directory, default: ./tmp
--macros file[,[file]  : Macro format files to load after the defaults
--log file             : Log file where all build out is written too
--url url[,url]        : URL to look for source
--targetcflags flags   : List of C flags for the target code
--targetcxxflags flags : List of C++ flags for the target code
--libstdcxxflags flags : List of C++ flags to build the target libstdc++ code
--with-<label>         : Add the --with-<label> to the build
--without-<label>      : Add the --without-<label> to the build
--list-configs         : List available configurations