source: rtems-source-builder/doc/source-builder.txt @ ae717cb

RTEMS Source Builder
====================
:doctype: book
:toc2:
:toclevels: 5
:icons:
:numbered:

image:images/rtemswhitebg.jpg["RTEMS",width="30%"]

Chris Johns <chrisj@rtems.org>
1.4, August 2013

RTEMS Tools From Source
-----------------------

The RTEMS Source Builder is a tool to aid building packages from source used by
the RTEMS project. It helps consolidate the details you need to build a package
from source in a controlled and verifiable way. The tool is aimed at developers
of software who use tool sets for embedded type development and is not limited
to building just for RTEMS. Embedded development typically uses cross-compiling
tool chains, debuggers, and debugging aids. Together we call these a 'tool
set'. The RTEMS Source Builder is not limited to this role but designed to fit
with-in this specific niche. It can be used outside of the RTEMS project and we
welcome this happening in other open source or commercial projects.

The RTEMS Source Builder is typically used to build a set of tools or a 'build
set'. A 'build set' is a collection of packages and a package is a specific
tool, for example gcc or gdb. The RTEMS Source Builder attempts to support any
host environment that runs Python and you can build the package on. It is not
some sort of magic that can take any piece of source code and make it
build. Someone at some point in time has figured out how to build that package
from source and taught this tool. The RTEMS Source Builder has been tested on:

* <<_archlinux,Archlinux>>
* <<_centos,Centos>>
* <<_fedora,Fedora>>
* <<_freebsd,FreeBSD>>
* <<_netbsd,NetBSD>>
* <<_macos,MacOS>>
* <<_opensuse,openSUSE>>
* <<_raspbian,Raspbian>>
* <<_ubuntu,Ubuntu>>
* <<_windows,Windows>>

The RTEMS Source Builder has two types configuration data. The first is the
'build set'. A _build set_ describes a collection of packages that define a set
of tools you would use when developing software for RTEMS. For example the
basic GNU tool set is binutils, gcc, and gdb and is the typical base suite of
tools you need for an embedded cross-development type project. The second type
of configuration data is the configuration files and they define how a package
is built. Configuration files are scripts loosely based on the RPM spec file
format and detail the steps needed to build a package. The steps are
'preparation', 'building', and 'installing'. Scripts support macros, shell
expansion, logic, includes plus many more features useful when build packages.

The RTEMS Source Builder does not interact with any host package management
systems. There is no automatic dependence checking between various packages you
build or packages and software your host system you may have installed. We
assume the build sets and configuration files you are using have been created
by developers who do. If you have a problem please ask on the RTEMS Users
mailing list.

IMPORTANT: If you have a problem please see <<_bugs,the reporting bugs>>
           section.

Quick Start
-----------

The quick start will show you how to build a set of RTEMS tools for a supported
architecture. The tools are installed into a build _prefix_ and this is top of
a group of directories containing all the files needed to develop RTEMS
applications. Building an RTEMS build set will build all that you need. This
includes autoconf, automake, assemblers, linkers, compilers, debuggers,
standard libraries and RTEMS itself.

There is no need to become root or the administrator and we recommend you avoid
doing this. You can build and install the tools anywhere on the host's file
system you, as a standard user, have read and write access too. I recommend you
use your home directory and work under the directory `~/development/rtems`. The
examples shown here will do this.

You can use the build _prefix_ to install and maintain different versions of
the tools. Doing this lets you try a new set of tools while not touching your
proven working production set of tools. Once you have proven the new tools are
working rebuild with the 'production' prefix switching your development to them.

I also suggest you keep your environment to the bare minimum, particularly the
path variable. Using environment variables has been proven over the years to be
difficult to manage in production systems.

.Path to use when building applications
*************************************************************
To use the tools once finished just set your path to the 'bin' directory under
the _prefix_ you use. In the examples that follow the _prefix_ is
`$HOME/development/rtems/4.11` and is set using the `--prefix` option so the
path you need to configure to build applications can be set with the following
in a BASH shell:
-------------------------------------------------------------
$ export PATH=$HOME/development/rtems/4.11/bin:$PATH
-------------------------------------------------------------
Make sure you place the RTEMS tool path at the front of your path so they are
searched first. RTEMS can provide newer versions of some tools your operating
system provides and placing the RTEMS tools path at the front means it is
searched first and the RTEMS needed versions of the tools are used.
*************************************************************

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 head over to the RTEMS GIT repository and clone the code directly
from git:

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

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>
-------------------------------------------------------------

<1> A tool is in the environment path but does not match the expected path.
<2> The executable 'xz' is not found.
<3> The host's environment is set up correct.

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 <<_host_setups,Host Setups>> section lists packages you should install for
common host operating systems. It maybe worth checking if you have those
installed.

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, v0.2.0
Examining: config <2>
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>
    unstable/4.11/rtems-all.bset <6>
    unstable/4.11/rtems-arm.bset
    unstable/4.11/rtems-avr.bset
    unstable/4.11/rtems-bfin.bset
    unstable/4.11/rtems-h8300.bset
    unstable/4.11/rtems-i386.bset
    unstable/4.11/rtems-lm32.bset
    unstable/4.11/rtems-m32c.bset
    unstable/4.11/rtems-m32r.bset
    unstable/4.11/rtems-m68k.bset
    unstable/4.11/rtems-microblaze.bset
    unstable/4.11/rtems-mips.bset
    unstable/4.11/rtems-moxie.bset
    unstable/4.11/rtems-powerpc.bset
    unstable/4.11/rtems-sh.bset
    unstable/4.11/rtems-sparc.bset
    unstable/4.11/rtems-sparc64.bset
    unstable/4.11/rtems-v850.bset
-------------------------------------------------------------
<1> Only option needed is +--list-bsets+
<2> The paths inspected. See <<X1,+_configdir+>> variable.
<3> Build all RTEMS 4.10 supported architectures.
<4> The build set for the ARM architecture on RTEMS 4.10.
<5> Support build set file with common functionality included by other build
    set files.
<6> Unstable tool sets are used by RTEMS developers to test new tool sets. You
    are welcome to try them but you must remember they are unstable, can change
    at any point in time and your application may not work. If you have an
    issue with a production tool it may pay to try the unstable tool to see if
    it has been resolved.

Building
~~~~~~~~

In this quick start I will build 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>
-------------------------------------------------------------

<1> Providing a log file redirects the build output into a file. Logging the
    build output provides a simple way to report problems.
<2> The prefix is the location on your file system the tools are installed
    into. Provide a prefix to a location you have read and write access. You
    can use the prefix to install different versions or builds of tools. Just
    use the path to the tools you want to use when building RTEMS.
<3> The build set. This is the SPARC build set. First a specifically referenced
    file is checked for and if not found the '%{_configdir} path is
    searched. The set builder will first look for files with a +.bset+
    extension and then for a configuration file with a +.cfg+ extension.
<4> The SPARC build set first builds the expat library as is used in GDB. This
    is the expat configuration used.
<5> The binutils build configuration.
<6> The GCC and Newlib build configuration.
<7> The GDB build configuration.
<8> Installing the built packages to the install prefix.
<9> All the packages built are cleaned at the end. If the build fails all the
    needed files are present. You may have to clean up by deleting the build
    directory if the build fails.
<10> The time to build the package. This lets you see how different host
     hardware or configurations perform.

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 a directory called
+source+. If you run the build again the cached files are used. This is what
happened in the show example before.

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>
 (RTEMS4.11-RSB(cb12e4875c203f794a5cd4b3de36101ff9a88403)-1,gcc-4.7.2/newlib-2.0.0) (GCC)
-------------------------------------------------------------

<1> The target the compiler is built for.
<2> The configure options used to build GCC.
<3> The threading model is always RTEMS. This makes the RTEMS tools difficult
    for bare metal development more difficult.
<4> The version string. It contains the Git hash of the RTEMS Source Builder
    you are using. If your local clone has been modifed that state is also
    recorded in the version string. The hash allows you to track from a GCC
    executable back to the original source used to build it.

NOTE: The RTEMS thread model enables specific hooks in GCC so applications
built with RTEMS tools need the RTEMS runtime to operate correctly. You can use
RTEMS tools to build bare metal component but it is more difficult than with a
bare metal tool chain and you need to know what you are doing at a low
level. The RTEMS Source Builder can build bare metal tool chains.

Installing and Tar Files
~~~~~~~~~~~~~~~~~~~~~~~~

The RTEMS Source Builder can install the built packages directly and optionally
it can create a build set tar file or a 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 install because the `/home` is root access
only. To install you would:

-------------------------------------------------------------
$ cd
$ tar --strip-components=3 -xjf 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
-------------------------------------------------------------

<1> The option to create a build set tar file.
<2> The installation still happens unless you specify `--no-install`.
<3> Creating the build set tar file.

You can also suppress installing the files using the `--no-install` 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 --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
-------------------------------------------------------------

<1> The option to supressing installing the packages.
<2> Create the build set tar.

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
-------------------------------------------------------------

<1> The option to create packages tar files.
<2> The GDB package tar file.
<3> The build set tar file. All the others in a single tar file.

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.

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 Source Builder 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 while
the Source Builder is attempting to provide a specific service of repeatably
being able to build tool sets from source code.

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.

[[_bugs]]
Bugs, Crashes, and Build Failures
---------------------------------

The RTEMS Source Builder is a Python program and every care is taken to test
the code however bugs, crashes, and build failure can and do happen. If you
find a bug please report it via the RTEMS Bug tracker tool Bugzilla:

https://www.rtems.org/bugzilla/

or via email on the RTEMS Users list.

Please include the:

. Command line,
. The git hash,
. Host details with the output of the +uname -a+ command,
. If you have made any modifications.

If there is a crash please cut and paste the Python backtrace into the bug
report. If the tools fail to build please locate the first error in the log
file. This can be difficult to find on hosts with many cores so it sometimes
pays to run the command with the +--jobs=none+ option to get a log that is
correctly sequenced. If searching the log file seach for +error:+ and the error
should be just above it.

Project Sets
------------

The RTEMS Source Builder supports project configurations. Project
configurations can be public or private and can be contained in the RTEMS
Source Builder project if suitable, other projects they use the RTEM Source
Builder or privately on your local file system.

The configuration file loader searches the macro +_configdir+ and by default
this is set to +%{\_topdir}/config:%{\_sbdir}/config+ where +_topdir+ is the
your current working direct, in other words the directory you invoke the RTEMS
Source Builder command in, and +_sbdir+ is the directory where the RTEMS Source
Builder command resides. Therefore the +config+ directory under each of these
is searched so all you need to do is create a +config+ in your project and add
your configuration files. They do not need to be under the RTEMS Source Builder
source tree. Public projects are included in the main RTEMS Source Builder such
as RTEMS.

You can also add your own +patches+ directory next to your +config+ directory
as the +%patch+ command searches the +_patchdir+ macro variable and it is
by default set to +%{\_topdir}/patches:%{\_sbdir}/patches+.

The +source-builder/config+ directory provides generic scripts for building
various tools. You can specialise these in your private configurations to make
use of them. If you add new generic configurations please contribute them back
to the project

RTEMS Configurations
~~~~~~~~~~~~~~~~~~~~

The RTEMS 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.

RTEMS supports _stable_ and _unstable_. Stable configurations are fixed while
unstable configurations are supporting using snapshots of user macros and
reference release candidates or source extracted directly from version
control. The stable build sets are referenced as +<version>/rtems-<arch>+ and
include `autoconf` and `automake`.

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
-------------------------------------------------------------
<1> Setting the path.

TIP: 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
-------------------------------------------------------------

Cross Building
--------------

Cross building or Canadian cross compiling is the process of building a set of
RTEMS tools for one type of host on another host. The RSB is a source builder
so the need for this is not often called on because you can just build the
tools for the host you wish to run on. There are however a few special cases
where this is needed. The host may not have a stable reliable means of building
the tools, such as Windows, or you wish to manage the configuration of tools on
different hosts from a single environment because of auditing or verfication
reasons.

Canadian Cross Building
~~~~~~~~~~~~~~~~~~~~~~~

The process of building cross compilers on one host for another host is
commonly referred to as a Canadian cross build. 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.

Command Line
~~~~~~~~~~~~

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
-------------------------------------------------------------

Configuration
-------------

The RTEMS Source Builder has two types of configuration data:

. Build Sets
. Package Build Configurations

By default these files can be located in two separate directories and
searched. The first directory is +config+ in your current working directory
(+_topdir+) and the second is +config+ located in the base directory of the
RTEMS Source Builder command you run (+_sbdir+). The RTEMS directory +rtems+
located at the top of the RTEMS Source Builder source code is an example of a
specific build configuration directory. You can create custom or private build
configurations and if you run the RTEMS Source Builder command from that
directory your configurations will be used.

[[X1]] The configuration search path is a macro variable and is reference as
+%\{_configdir\}+. It's default is defined as:

-------------------------------------------------------------
_configdir          : dir      optional   %{_topdir}/config:%{_sbdir}/config <1>
-------------------------------------------------------------

<1> The +_topdir+ is the directory you run the command from and +_sbdir+ is the
location of the RTEMS Source Builder command.

Build set files have the file extension +.bset+ and the package build
configuration files have the file extension of +.cfg+. The +sb-set-builder+
command will search for _build sets_ and the +sb-builder+ commands works with
package build configuration files.

Both types of configuration files use the \'#' character as a comment
character. Anything after this character on the line is ignored. There is no
block comment.

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. There are a single line containing a Universal Resource Location or
URL and can contain macros and shell expansions. The <<_prep,%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.
'cvs:: Remote access to a CVS repository.
'file:: Local access to an existing source directory.

HTTP, HTTPS, and FTP
^^^^^^^^^^^^^^^^^^^^

Remote access to TAR files is provided using HTTP, HTTPS and FTP protocols. The
full URL provided is used to access the remote file including any query
components. The URL is parsed to extract the file component and the local
source directory is checked for that file. If the file is located the remote
file is not downloaded. Currently no other checks are made. If a download fails
you need to manually remove the file from the source directory and start the
build process again.

The URL can contain macros. These are expand before issuing the request to
download the file. The GNU GCC compiler source URL is:

-------------------------------------------------------------
Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
-------------------------------------------------------------

The type of compression is automatically detected from the file extension. The
supported compression formats are:

`gz`:: GNU ZIP
`bzip2`:: BZIP2 ??
`zip`:: ??
'xy':: XY ??

The output of the decompression tool is feed to the standard `tar` utility and
unpacked into the build directory.

If the URL references the GitHub API server 'https://api.github.com/' a tarball
of the specified version is download. For example the URL for the STLINK
project on GitHub and version is:

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

the TAR file is downloaded and used.

GIT
^^^

A GIT repository can be cloned and used as source. The GIT repository resides
in the 'source' directory under the `git` directory. You can edit, update and
use the repository as you normally do and the results will used to build the
tools. This allows you to prepare and test patches in the build environment the
tools are built in. The GIT URL only supports the GIT protocol. You can control
the repository via the URL by appending options and arguments to the GIT
path. The options are delimited by `?` and option arguments are delimited from
the options with `=`. The options are:

`branch`:: Checkout the specified branch.
`pull`:: Perform a pull to update the repository.
`fetch`:: Perform a fetch to get any remote updates.
`reset`:: Reset the repository. Useful to remove any local changes. You can
pass the `hard` argument to force a hard reset.

-------------------------------------------------------------
Source0: git://gcc.gnu.org/git/gcc.git?branch=gcc-4_7-branch?reset=hard
-------------------------------------------------------------

This will clone the GCC git repository and checkout the 4.7-branch and perform
a hard reset.

CVS
^^^

A CVS repository can be checked out. CVS is more complex than GIT to handle
because of the modules support. This can effect the paths the source ends up
in. The CVS URL only supports the CVS protocol. You can control the repository
via the URL by appending options and arguments to the CVS path. The options are
delimited by `?` and option arguments are delimited from the options with
`=`. The options are:

`module`:: The module to checkout.
`src-prefix`:: The path into the source where the module starts.
`tag`:: The CVS tag to checkout.
`date`:: The CVS date to checkout.

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

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 becauses 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.

Macro Maps and Files
^^^^^^^^^^^^^^^^^^^^

Macros are read in from files when the tool starts. The default settings are
read from the defaults macro file called `defaults.mc` located in the top level
RTEMS Source Builder command directory. User macros can be read in at start up
by using the `--macros` command line option.

The format for a macro in macro files is:

[options="header,compact",width="50%",cols="15%,15%,15%,55%"]
|=================================
| Name | Type | Attribute | String
|=================================

where 'Name' is a case insensitive macro name, the 'Type' field is:

[horizontal]
`none`:: Nothing, ignore.
`dir`:: A directory path.
`exe`:: An executable path.
`triplet`:: A GNU style architecture, platform, operating system string.

the 'Attribute' field is:

[horizontal]
`none`:: Nothing, ignore
`required`:: The host check must find the executable or path.
`optional`:: The host check generates a warning if not found.
`override`:: Only valid outside of the `global` map to indicate this macro
             overrides the same one in the `global` map when the map containing
             it is selected.
`undefine`:: Only valid outside of the `global` map to undefine the macro if it
             exists in the `global` map when the map containing it is
             selected. The `global` map's macro is not visible but still
             exists.

and the 'String' field is a single or tripled multiline quoted string. The
'String' can contain references to other macros. Macro that loop are not
currently detected and will cause the tool to lock up.

Maps are declared anywhere in the map using the map directive:

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

Any macro defintions following a map declaration are placed in that map and the
default map is `global` when loading a file. Maps are selected in configuration
files by using the `%select` directive.

-------------------------------------------------------------
%select my-special-map
-------------------------------------------------------------

Selecting a map means all requests for a macro first check the selected map and
if present return that value else the `global` map is used. Any new macros or
changes update only the `global` map. This may change in future releases so
please make sure you use the `override` attibute.

The macro files specificed on the command line are looked for in the
`_configdir` paths. See <<X1,+_configdir+>> variable for details. Included
files need to add the `%{_configdir}` macro to the start of the file.

Macro map files can include other macro map files using the `%include`
directive. The macro map to build _binutils_, _gcc_, _newlib_, _gdb_ and
_RTEMS_ from version control heads is:

-------------------------------------------------------------
# <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
-------------------------------------------------------------
<1> The file is `config/snapshots/binutils-gcc-newlib-gdb-head.mc`.

The macro map defaults to `global` at the start of each included file and the
map setting of the macro file including the other macro files does not change.

Personal Macros
^^^^^^^^^^^^^^^

When the tools start to run they will load personal macros. Personal macros are
in the standard format for macros in a file. There are two places personal
macros can be configured. The first is the environment variable
`RSB_MACROS`. If presentthe macros from the file the environment variable
points to are loaded. The second is a file called `.rsb_macros` in your home
directory. You need to have the environment variable `HOME` defined for this
work.

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

.To Mail Address

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_.

.From Mail Address

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.

.SMTP Host

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_.

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.

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.

Snapshot Testing
~~~~~~~~~~~~~~~~

Testing of release canidates and snapshots is important to those helping
maintain tool sets. The RTEMS Source Builder helps by providing a simple and
flexible way to use existing build sets and configuration without needing to
change them or creating new temporary build sets and configurations.

The process uses snapshot macro files loaded via the command line option
`--macros`. These files provide macros that override the standard build set and
configuration file macros.

Lets consider testing a GCC 4.7 snapshot for RTEMS 4.11. Lets assume the
current RTEMS 4.11 tools reference GCC 4.7.3 with a patch as the stable tool
set. We want to use a recent snapshot with no patches. In the
`rtems/config/snapshots` directoy create a file called `gcc-4.7-snapshot.mc`
containing:

-------------------------------------------------------------
[gcc-4.7-snapshot]
GCC_Version: none, override, '4.7-20130413'
Source0:     none, override, 'http://mirrors.kernel.org/sources.redhat.com/gcc/
snapshots/%{gcc_version}/gcc-%{gcc_version}.tar.bz2'
Patch0:      none, udefine,  ''
-------------------------------------------------------------

In the standard configuration file `source-builder/config/gcc-4.7-1.cfg` the
map is selected with:

-------------------------------------------------------------
#
# Select the GCC 4.7 Snapshot Macro Map
#
%select gcc-4.7-snapshot
-------------------------------------------------------------

On the command line add `--macros=snapshots/gcc-4.7-snapshot.mc` and this
snapshot will be built. With careful use of the `--prefix` option you can
locate the tools in a specific directory and test them without needing to
effect your production environment.

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:

[horizontal]
+%{}+:: 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.
+%setup+:: Setup a source package.
+%source+:: Define a source code package. This macro has a number appended.
+%patch+:: Define a patch. This macro has a is number appended.
+%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.

Expanding
^^^^^^^^^

A macro can be `%{string}` or the equivalent of `%string`. The following macro
expansions supported are:

`%{string}`;;
Expand the 'string' replacing the entire macro text with the text in the table
for the entry 'string . For example if 'var' is 'foo' then `${var}` would
become `foo`.

`%{expand: string}`;;
Expand the 'string' and then use it as a ``string'' to the macro expanding the
macro. For example if _foo_ is set to 'bar' and 'bar' is set to 'foobar' then
`%{expand:foo}` would result in `foobar`. Shell expansion can also be used.

`%{with string}`;;
Expand the macro to '1' if the macro `with_`'string' is defined else expand to
_0_. Macros with the name `with_`'string' can be define with command line
arguments to the RTEMS Source Builder commands.

`%{defined string}`;;
Expand the macro to '1' if a macro of name 'string' is defined else expand to '0'.

`%{?string: expression}`;;
Expand the macro to 'expression' if a macro of name 'string' is defined else expand to `%{nil}`.

`%{!?string: expression}`;;
Expand the macro to 'expression' if a macro of name 'string' is not defined. If
the macro is define expand to `%{nil}`.

`%(expression)`;;
Expand the macro to the result of running the 'expression' in a host shell. It
is assumed this is a Unix type shell. For example `%(whoami)` will return your
user name and `%(date)` will return the current date string.

%prep
^^^^^

The +%prep+ macro starts a block that continues until the next block macro. The
_prep_ or preparation block defines the setup of the package's source and is a
mix of RTEMS Source Builder macros and shell scripting. The sequence is
typically +%setup+ macros for source, +%patch+ macros to patch the source
mixed with some shell commands to correct any source issues.  A +%prep+ section
starts with a +%setup+ command. This creates the package source top level
directory then is followed by the first source file.

-------------------------------------------------------------
                     <1>       <2>
%setup -q -c -T -n %{name}-%{version}
%setup -q -T -D -n %{name}-%{version} -a0
-------------------------------------------------------------

<1> The package's name.
<2> The version of the package.

The source for a package is declared with the +%source*+ macro where +*+ is
a number. For example +%source0+ is the source 0 tar file and is defined with
something similar to this:

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

This URL is the primary location of the GNU GCC source code and the RTEMS
Source Builder can download the file from this location and by inspecting the
file extension use +bzip2+ decompression. When the +%prep+ section is processed
a check of the local +source+ directory is made to see if the file has already
been downloaded. If not found in the source cache directory the package is
downloaded from the URL. You can append other base URLs via the command line
option +--url+. This option accepts a comma delimited list of sites to try.

You can combine the source macro with conditional logic to implement a default
that can be over-riden in the top level files. This lets you reuse a generic
build script with different sources. This happens if you have a private source
package with local modifications. The following example is taken from the
+gcc-4.8-1.cfg+ build script.

-------------------------------------------------------------
%ifn %{defined Source0}
 Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
%endif
-------------------------------------------------------------

You could optionally have a few source files that make up the package. For
example GNU's GCC was a few tar files for a while and it is now a single tar
file. Support for multiple source files can be conditionally implemented with
the following scripting:

-------------------------------------------------------------
%{?source1:%setup -q -T -D -n %{name}-%{version} -a1}
-------------------------------------------------------------

The +source1+ macro value is checked and if present the command string after
the +:+ is executed. It is common to see a number of these present allowing top
level configuration files including a base configuration the ability to define
a number of source packages.

-------------------------------------------------------------
%{?source1:%setup -q -T -D -n %{name}-%{version} -a1}
%{?source2:%setup -q -T -D -n %{name}-%{version} -a2}
%{?source3:%setup -q -T -D -n %{name}-%{version} -a3}
-------------------------------------------------------------

Patching also occurs during the preparation stage. Patches are handled in a
similar way to the source packages. Most patches are based around the top of
the source tree. This is an example of the patch scripting for the GCC 4.8
series of compilers:

-------------------------------------------------------------
cd gcc-%{gcc_version} <1>
%{?patch0:%patch0 -p1} <2>
%{?patch1:%patch1 -p1}
%{?patch2:%patch2 -p1}
%{?patch3:%patch3 -p1}
%{?patch4:%patch4 -p1}
%{?patch5:%patch5 -p1}
%{?patch6:%patch6 -p1}
%{?patch7:%patch7 -p1}
%{?patch8:%patch8 -p1}
%{?patch9:%patch9 -p1}
cd .. <3>
-------------------------------------------------------------

<1> Change from the top of the source tree into the package being patched's top
    directory.
<2> The conditional macro expansion checks if +%patch0+ is defined and if
    defined issues the +%patch0" macro giving +-p1+ to the patch command.
<3> Return back to the top of the source tree.

%build
^^^^^^

The +%build+ macro starts a block that continues until the next block
macro. The build block is a series of shell commands that execute to build the
package. It assumes all source code has been unpacked, patch and adjusted so
the build will succeed.

The following is an example take from the GutHub STLink project:

NOTE: STLink is a JTAG debugging device for the ST ARM family of processors.

-------------------------------------------------------------
%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 ..
-------------------------------------------------------------

<1> Setup the PATH environment variable. This is not always needed.
<2> This package builds in the source tree so enter it.
<3> The package is actually checked directly out from the github project and so
    it needs its autoconf and automake files generated.
<4> Flags for a cross-compiled build.
<5> Various settings passed to configure to customise the build. In this
    example an include path is being set to the install point of _libusb_. This
    package requires _libusb_ is built before it.
<6> The +configure+ command. The RTEMS Source Builder provides all the needed
    paths as macro variables. You just need to provide them to +configure+.
<7> Running make. Do not use +make+ directly, use the RTEMS Source Builder's
    defined value. This value is specific to the host. A large number of
    packages need GNU make and on BSD systems this is +gmake+. You can
    optionally add the SMP flags if the packages build system can handle
    parallel building with multiple jobs. The +_smp_mflags+ value is
    automatically setup for SMP hosts to match the number of cores the host has.

%install
^^^^^^^^

The +%install+ macro starts a block that continues until the next block
macro. The install block is a series of shell commands that execute to install
the package. You can assume the package has build correctly when this block
starts executing.

Never install the package to the actual _prefix_ the package was built
with. Always install to the RTEMS Source Builder's temporary path defined in
the macro variable +\__tmpdir+. The RTEMS Source Builder sets up a shell
environment variable called +SB_BUILD_ROOT+ as the standard install point. Most
packages support adding +DESTDIR=+ to the _make install_ command.

Looking at the same example as in <<_build, %build>>:

-------------------------------------------------------------
%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 ..
-------------------------------------------------------------

<1> Setup the PATH environment variable. This is not always needed.
<2> Clean any installed files. This make sure the install is just what
    the package installs and not any left over files from a broken build or
    install.
<3> Enter the build directory. In this example it just happens to be the source
    directory.
<4> Run +make install+ to install the package overriding the +DESTDIR+ make
    variable.

%clean
^^^^^^

The +%clean+ macro starts a block that continues until the next block
macro. The clean block is a series of shell commands that execute to clean up
after a package has been built and install. This macro is currenly not been
used because the RTEMS Source Builder automatically cleans up.

%include
^^^^^^^^

The +%include+ macro inline includes the specific file. The +\__confdir+
path is searched. Any relative path component of the include file is appended
to each part of the +\__configdir+. Adding an extension is optional as files
with +.bset+ and +.cfg+ are automatically searched for.

Inline including means the file is processed as part of the configuration at
the point it is included. Parsing continues from the next line in the
configuration file that contains the +%include+ macro.

Including files allow a kind of configuration file reuse. The outer
configuration files provide specific information such as package version
numbers and patches and then include a generic configuration script which
builds the package.

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

%name
^^^^^

The name of the package being built. The name typically contains the components
of the package and their version number plus a revision number. For the GCC
with Newlib configuration the name is typically:

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

%summary
^^^^^^^^

The +%summary+ is a brief description of the package. It is useful when
reporting. This information is not capture in the package anywhere. For the GCC
with Newlib configuration the summary is typically:

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

%release
^^^^^^^^

The +%release+ is packaging number that allows revisions of a package to happen
where none package versions change. This value typically increases when the
configuration building the package changes.

-------------------------------------------------------------
%define release 1
-------------------------------------------------------------

%version
^^^^^^^^

The +%version% macro sets the version the package. If the package is a single
component it tracks that component's version number. For example in the
_libusb_ configuration the +%version+ is the same as +%libusb_version+, however
in a GCC with Newlib configuration there is no single version number. In this
case the GCC version is used.

-------------------------------------------------------------
Version: %{gcc_version}
-------------------------------------------------------------

%buildarch
^^^^^^^^^^

The +%buildarch+ macro is set to the architecture the package contains. This is
currently not used in the RTEMS Source Builder and may go away. This macro is
more important in a real packaging system where the package could end up on the
wrong architecture.

%setup
^^^^^^

The +%setup+ macro sets up the source code tree and is used in the +%prep+
section of the script. The options are:

[horizontal]
*Switch*:: *Description*
+-n+:: The -n option is used to set the name of the software's build
directory. This is necessary only when the source archive unpacks into a
directory named other than +<name>-<version>+.
+-c+:: The -c option is used to direct %setup to create the top-level build
directory before unpacking the sources.
+-D+:: The -D option is used to direct %setup to not delete the build directory
prior to unpacking the sources. This option is used when more than one source
archive is to be unpacked into the build directory, normally with the +-b+ or
+-a+ options.
+-T+:: The -T option is used to direct %setup to not perform the default
unpacking of the source archive specified by the first Source: macro. It is used
with the +-a+ or +-b+ options.
+-b <n>+:: The -b option is used to direct %setup to unpack the source archive
specified on the nth Source: macro line before changing directory into the build
directory.
+-a <n>+:: The -a option is used to direct %setup to unpack the source archive
specified on the nth Source: macro line after changing directory into the build
directory.

%source
^^^^^^^

The +%source+ macro is numbered and defines a source tar file used in the
package. The +%setup+ macro references the packages defined here. A macro is
defined as:

-------------------------------------------------------------
Source0: ftp://ftp.gnu.org/gnu/gcc/gcc-%{gcc_version}/gcc-%{gcc_version}.tar.bz2
-------------------------------------------------------------

The setup script is:

-------------------------------------------------------------
%setup -q -T -D -n %{name}-%{version} -a0
-------------------------------------------------------------

The +-a0+ means use +%source0+.

%patch
^^^^^^

The +%patch+ macro is numbered and can define a patch and in the +%prep+
section applies the patch. To define a patch append a +:+ followed by the patch
filename:

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

The +__patchdir+ path is search.

Placing +%patch+ in the +%prep+ section will apply it with any trailing options
passed to the +patch+ command. This allows the +-p+ option to be passed to
strip any leading path components from the patch contents.

-------------------------------------------------------------
%patch0 -p1
-------------------------------------------------------------

You will typically see the patch conditionally used as:

-------------------------------------------------------------
%{patch0:%patch0 -p1}
-------------------------------------------------------------

In this case the patch will only be applied if it is defined.

%echo
^^^^^

The +%echo+ macro outputs the following string to stdout. This can also be used
as `%{echo: message}`.

%warning
^^^^^^^^

The +%warning+ macro outputs the following string as a warning. This can also
be used as `%{warning: message}`.

%error
^^^^^^

The +%error+ macro outputs the follow string as an error and exits the RTEMS
Source Builder. This can also be used as `%{error: message}`.

%select
^^^^^^^

The +%select+ macro selects the map specified. If there is no map no error or
warning is generated. Macro maps provide a simple way for a user to override
the settings is a configuration file without having to edit it. The changes are
recorded in the build report so can be traced.

Configuration use different maps so macro overrides can target a specific
package.

The default map is `global'.

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

<1> The map switches to `gcc-4.8-snapshot`. Any overrides in this map will be
    used.
<2> Defining macros only updates the `global` map and not the selected map.

%define
^^^^^^^

The +%define+ macro defines a new macro or updates an existing one. If no value
is given it is assumed to be 1.

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

<1> The macro _one_ is set to 1.

%undefine
^^^^^^^^^

The +%undefine+ macro removes a macro if it exists. Any further references to
it will result in an undefine macro error.

%if
^^^

The +%if+ macro starts a conditional logic block that can optionally have a
_else_ section. A test follows this macro and can have the following operators:

[horizontal]
*Operator*:: *Description*
+%{}+:: Check the macro is set or _true_, ie non-zero.
+
-------------------------------------------------------------
%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
-------------------------------------------------------------
+!+:: The _not_ operator inverts the test of the macro.
+
-------------------------------------------------------------
%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
-------------------------------------------------------------
+==+:: The left hand size must equal the right hand side. For example:
+
-------------------------------------------------------------
%define one 1
%if ${one} == 1
 %warning The test passes
%else
 %error The test fails
%endif
-------------------------------------------------------------
+
You can also check to see if a macro is empty:
+
-------------------------------------------------------------
%if ${nothing} == %{nil}
 %warning The test passes
%else
 %error The test fails
%endif
-------------------------------------------------------------
+!=+:: The left hand size does not equal the right hand side. For example:
+
-------------------------------------------------------------
%define one 1
%if ${one} != 2
 %warning The test passes
%else
 %error The test fails
%endif
-------------------------------------------------------------
+
You can also check to see if something is set:
+
-------------------------------------------------------------
%if ${something} != %{nil}
 %warning The test passes
%else
 %error The test fails
%endif
-------------------------------------------------------------
+>+:: The left hand side is numerically greater than the right hand side.
+>=+:: The left hand side is numerically greater than or equal to the right
hand side.
+<+:: The left hand side is numerically less than the right hand side.
+\<=+:: The left hand side is numerically less than or equal to the right hand
side.

%ifn
^^^^

The +%ifn+ macro inverts the normal +%if+ logic. It avoids needing to provide
empty _if_ blocks followed by _else_ blocks. It is useful when checking if a
macro is defined:

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

%ifarch
^^^^^^^

The +%ifarch+ is a short cut for "+%if %{\_arch} == i386+". Currently not used.

%ifnarch
^^^^^^^^

The +%ifnarch+ is a short cut for "+%if %{\_arch} != i386+". Currently not
used.

%ifos
^^^^^

The +%ifos+ is a short cut for "+%if %{\_os} != mingw32+". It allows
conditional support for various operating system differences when building
packages.

%else
^^^^^

The +%else+ macro starts the conditional _else_ block.

%endfi
^^^^^^

The +%endif+ macro ends a conditional logic block.

%bconf_with
^^^^^^^^^^^

The +%bconf_with+ macro provides a way to test if the user has passed a
specific option on the command line with the +--with-<label>+ option. This
option is only available with the +sb-builder+ command.

%bconf_without
^^^^^^^^^^^^^^

The +%bconf_without+ macro provides a way to test if the user has passed a
specific option on the command line with the +--without-<label>+ option. This
option is only available with the +sb-builder+ command.


Commands
--------

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
-------------------------------------------------------------

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
-------------------------------------------------------------

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.
-------------------------------------------------------------

.Arguments
The +[args]+ are a list 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
+--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.

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
-------------------------------------------------------------

Host Setups
-----------

The host versions are listed. If a later version of the host operating system
exists it should unless listed.

Linux
~~~~~

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

Archlinux
^^^^^^^^^

The following packages are required on a fresh Archlinux 64bit installation:

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

Archlinux, by default installs `texinfo-5` which is incompatible for building
GCC 4.7 tree. You will have to obtain `texinfo-legacy` from `AUR` and provide
a manual override.

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

CentOS
^^^^^^

The following packages are required on a minimal CentOS 6.3 64bit installation:

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

The minimal CentOS distribution is a specific DVD that installs a minimal
system. If you use a full system some of these packages may have been
installed.

Fedora
^^^^^^

The RTEMS Source Builder has been tested on Fedora 18 64bit.

Raspbian
^^^^^^^^

The is the Debian distribution for the Raspberry Pi. The following packages are
required.

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

It is recommended you get Model B of the Pi with 512M of memory and to mount a
remote disk over the network. The tools can be build with a prefix under your
home directory as recommended and end up on the SD card.

Ubuntu
^^^^^^

The latest testing was with Ubuntu 12.10 64bit. A minimal installation was used
and the following packages installed.

-------------------------------------------------------------
$ sudo apt-get build-dep binutils gcc g++ gdb unzip git
-------------------------------------------------------------

FreeBSD
~~~~~~~

The RTEMS Source Builder has been tested on FreeBSD 9.1 64bit.

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
-------------------------------------------------------------

MacOS X
~~~~~~~

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.

Windows
~~~~~~~

Windows tool sets are supported creating native Windows executable. Native
Windows tools are built using a MinGW compiler and do not need any extra
libraries or emulation layer to run once built. The tools understand and use
standard Windows paths and integrate easly into Windows IDE environments. A
shell maybe needed to build other parts of your system however if your
development tools are all native Windows tool you can easly integrate these
tool sets.

.Ready To Go Windows Tools
NOTE: I provide tools for Windows at
http://www.rtems.org/ftp/pub/rtems/people/chrisj/source-builder/4.11/mingw32/

Building on Windows is a little more complicated because the Cygwin shell is
used rather than the MinGW MSYS shell. The MSYS shell is simpler because the
detected host triple is MinGW so the build is standard cross-compiler build.
The age of the MSYS code base, its stability and ability to to complete a build
with limitations such as the length of file names support make using MSYS
difficult therefore the more complex path of a Canadian cross-build using
Cygwin is supported.

Install a recent Cygwin version using the Cygwin setup tool. Select and install
the groups and packages listed:

.Cygwin Packages
[options="header,compact",width="50%",cols="20%,80%"]
|================================
|Group   |Package
|Archive |bsdtar
|        |unzip
|        |xz
|Devel   |autoconf
|        |autoconf2.1
|        |autoconf2.5
|        |automake
|        |binutils
|        |bison
|        |flex
|        |gcc4-core
|        |gcc4-g++
|        |git
|        |make
|        |mingw64-x86_64-binutils
|        |mingw64-x86_64-gcc-core
|        |mingw64-x86_64-g++
|        |mingw64-x86_64-runtime
|        |mingw64-x86_64-zlib
|        |patch
|        |zlib-devel
|MinGW   |mingw-zlib-devel
|Python  |python
|================================

The setup tool will add a number of dependent package and it is ok to accept
them.

I have found turning off Windows Defender improves performance if you have
another up to date virus detection tool installed and enabled. I used the
excellent `Process Hacker 2` tool to monitor the performance and I found the
Windows Defender service contributed a high load. In my case I had a 3rd party
virus tool installed so the Windows Defender service was not needed.

A Canadian cross-compile (Cxc) is required on Cygwin because the host is Cygwin
therefore a traditional cross-compile will result in Cygiwn binaries. With a
Canadian cross-compile a Cygwin cross-compiler is built as well as the MinGW
RTEMS cross-compiler. The Cygwin cross-compiler is required to build the C
runtime for the RTEMS target because we are building under Cygiwn. The build
output for an RTEMS 4.10 ARM tool set is:

-------------------------------------------------------------
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>
-------------------------------------------------------------

<1> The Cygwin version of the ARM cross-binutils.
<2> The +(Cxc)+ indicates this is the MinGW build of the package.
<3> Only the MinGW version is installed.
<4> Cygwin is slow so please be patient. This time was on an AMD Athlon 64bit
    Dual Core 6000+ running at 3GHz with 4G RAM running Windows 7 64bit.

CAUTION: Cygwin documents the 'Big List Of Dodgy Apps' or 'BLODA'. The link is
http://cygwin.com/faq/faq.html#faq.using.bloda and it is worth a
look. You will see a large number of common pieces of software found on Windows
systems that can cause problems. My testing has been performed with NOD32
running and I have seen some failures. The list is for all of Cygwin so I am
not sure which of the listed programs effect the RTEMS Source Biulder. The
following FAQ item talks about +fork+ failures and presents some technical
reasons they cannot be avoided in all cases. Cygwin and it's fork MSYS are
fantastic pieces of software in a difficult environment. I have found building
a single tool tends to work, building all at once is harder.


Build Status By Host
~~~~~~~~~~~~~~~~~~~~

This table lists the current build and testing status for reported hosts:

[grid="rows",format="csv"]
[options="header",cols="<,<,<,<,<,<"]
|===========================
OS,Uname,4.9,4.10,4.11,Comments
include::host-results.csv[]
|===========================

[NOTE]
==================================================================
Report any unlisted hosts as a patch.
==================================================================

History
-------

The RTEMS Source Builder is a stand alone tool based on another tool called the
'SpecBuilder'. The SpecBuilder was written for the RTEMS project to give me a
way to build tools on hosts that did not support RPMs. At the time the RTEMS
tools maintainer only used spec files to create various packages. This meant I
had either spec files, RPM files or SRPM files. The RPM and SPRM files where
useless because you needed an 'rpm' type tool to extract and manage them. There
are versions of 'rpm' for a number of non-RPM hosts however these proved to be
in various broken states and randomly maintained. The solution I settled on was
to use spec files so I wrote a Python based tool that parsed the spec file
format and allowed me to create a shell script I could run to build the
package. This approach proved successful and I was able to track the RPM
version of the RTEMS tools on a non-RPM host over a number of years. however
the SpecBuilder tool did not help me build tools or other packages not related
to the RTEMS project where there was no spec file I could use so I needed
another tool. Rather than start again I decided to take the parsing code for
the spec file format and build a new tool called the RTEMS Source Builder.