path: root/rsb
diff options
Diffstat (limited to 'rsb')
10 files changed, 112 insertions, 100 deletions
diff --git a/rsb/bug-reporting.rst b/rsb/bug-reporting.rst
index a2d4b70..c039fed 100644
--- a/rsb/bug-reporting.rst
+++ b/rsb/bug-reporting.rst
@@ -6,7 +6,7 @@
.. _Bugs, Crashes, and Build Failures:
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 failures can and do happen. If you
@@ -50,7 +50,7 @@ error should be just above it.
.. _Contributing:
We welcome all users adding, fixing, updating and upgrading packages and their
configurations. The RSB is open source and open to contributions. These can be
diff --git a/rsb/commands.rst b/rsb/commands.rst
index 4c8160a..3ef7772 100644
--- a/rsb/commands.rst
+++ b/rsb/commands.rst
@@ -4,10 +4,10 @@
.. comment Chris Johns <>
Checker (sb-check)
This commands checks your system is set up correctly. Most options are ignored::
@@ -47,7 +47,7 @@ This commands checks your system is set up correctly. Most options are ignored::
Environment is ok
Defaults (sb-defaults)
This commands outputs and the default macros for your when given no
arguments. Most options are ignored::
@@ -85,7 +85,7 @@ arguments. Most options are ignored::
--regression : Set --no-install, --keep-going and --always-clean
Set Builder (sb-set-builder)
This command builds a set::
@@ -286,7 +286,7 @@ The ``arguments`` are a list of build sets to build.
``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``::
diff --git a/rsb/configuration.rst b/rsb/configuration.rst
index 2b6da90..62fc073 100644
--- a/rsb/configuration.rst
+++ b/rsb/configuration.rst
@@ -6,7 +6,7 @@
.. _Configuration:
The RTEMS Source Builder has two types of configuration data:
@@ -46,7 +46,7 @@ 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``
@@ -76,7 +76,7 @@ following schemes are provided:
Local access to an existing source directory.
Remote access to TAR or ZIP files is provided using HTTP, HTTPS and FTP
protocols. The full URL provided is used to access the remote file including
@@ -139,7 +139,7 @@ STLINK project on GitHub and version is:
%source set stlink{stlink_version}.tar.gz
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
@@ -183,7 +183,7 @@ used by the RSB to select a git repository can be removed using *none* or
replaced with one of the standard git protcols.
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
@@ -211,7 +211,7 @@ The following is an example of checking out from a CVS repository:
%source set newlib cvs://
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
@@ -242,7 +242,7 @@ 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 ```` located in the top
@@ -339,7 +339,7 @@ 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
@@ -350,7 +350,7 @@ directory. You need to have the environment variable ``HOME`` defined for this
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:
@@ -393,7 +393,7 @@ 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,
@@ -426,7 +426,7 @@ 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
@@ -477,7 +477,7 @@ the earlier revision number will not be effected by the change. This locks down
a specific configuration over time.
Personal Configurations
The RSB supports personal configurations. You can view the RTEMS support in the
``rtems`` directory as a private configuration tree that resides within the RSB
@@ -497,7 +497,7 @@ build set file. The section 'Adding New Configurations' details how to add a
new confguration.
New Configurations
This section describes how to add a new configuration to the RSB. We will add a
configuration to build the Device Tree Compiler. The Device Tree Compiler or
@@ -510,7 +510,7 @@ DTC is supported in the RSB and you can find the configuration files under the
``bare/config`` tree. I suggest you have a brief look over these files.
Layering by Including
Configurations can be layered using the ``%include`` directive. The user
invokes the outer layers which include inner layers until all the required
@@ -521,7 +521,7 @@ release to another. Macro variables are used to provide the specific
configuration details.
Configuration File Numbering
Configuration files have a number at the end. This is a release number for that
configuration and it gives us the ability to track a specific configuration for
@@ -536,7 +536,7 @@ configuration file between version 1.1.0 and version 1.2.0. An update to any
previous release lets us still build the package.
Common Configuration Scripts
Common configuration scripts that are independent of version, platform and
architecture are useful to everyone. These live in the Source Builder's
@@ -547,7 +547,7 @@ built. They expect to be wrapped by a configuration file that ties the package
to a specific version and optionally specific patches.
DTC Example
We will be building the DTC for your host rather than a package for RTEMS. We
will create a file called ``source-builder/config/dtc-1-1.cfg``. This is a
@@ -755,7 +755,7 @@ The command also supplies the ``--trace`` option. The output in the log file
will contian all the macros.
New configuration files require debugging. There are two types of
debugging. The first is debugging RSB script bugs. The ``--dry-run`` option is
@@ -773,7 +773,7 @@ and change directory into them and manually run commands until to figure what
the package requires.
Configuration files specify how to build a package. Configuration files are
scripts and have a ``.cfg`` file extension. The script format is based loosely
@@ -876,7 +876,7 @@ The script language is implemented in terms of macros. The built-in list is:
command line option.
A macro can be ``%{string}`` or the equivalent of ``%string``. The following macro
expansions supported are:
@@ -918,7 +918,7 @@ expansions supported are:
.. _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
@@ -1011,7 +1011,7 @@ To apply these patches::
.. _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
@@ -1074,7 +1074,7 @@ a JTAG debugging device for the ST ARM family of processors::
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
@@ -1113,7 +1113,7 @@ Looking at the same example as in :ref:`build`::
make variable.
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
@@ -1121,7 +1121,7 @@ after a package has been built and install. This macro is currenly not been
used because the RTEMS Source Builder automatically cleans up.
The ``%include`` macro inline includes the specific file. The ``__confdir``
path is searched. Any relative path component of the include file is appended
@@ -1140,7 +1140,7 @@ builds the package::
%include %{_configdir}/gcc-4.7-1.cfg
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
@@ -1149,7 +1149,7 @@ with Newlib configuration the name is typically::
Name: %{_target}-gcc-%{gcc_version}-newlib-%{newlib_version}-%{release}
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
@@ -1158,7 +1158,7 @@ with Newlib configuration the summary is typically::
Summary: GCC v%{gcc_version} and Newlib v%{newlib_version} for target %{_target} on host %{_host}
The ``%release`` is packaging number that allows revisions of a package to
happen where none package versions change. This value typically increases when
@@ -1167,7 +1167,7 @@ the configuration building the package changes::
%define release 1
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
@@ -1178,7 +1178,7 @@ number. In this case the GCC version is used::
Version: %{gcc_version}
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
@@ -1186,7 +1186,7 @@ is more important in a real packaging system where the package could end up on
the wrong architecture.
The ``%source`` macro has 3 commands that controls what it does. You can
``set`` the source files, ``add`` source files to a source group, and ``setup``
@@ -1255,7 +1255,7 @@ Accepted options are:
the build directory.
The ``%patch`` macro has the same 3 command as the ``%source`` command however
the ``set`` commands is not really that useful with the with command. You add
@@ -1291,7 +1291,7 @@ patches::
2. The default option used to apply the patch.
The ``%hash`` macro requires 3 arguments and defines a checksum for a specific
file. The checksum is not applied until the file is checked before downloading
@@ -1324,25 +1324,25 @@ Downloading of repositories such as git and cvs cannot be checksumed. It is
assumed those protocols and tools manage the state of the files.
The ``%echo`` macro outputs the following string to stdout. This can also be used
as ``%{echo: message}``.
The ``%warning`` macro outputs the following string as a warning. This can also
be used as ``%{warning: message}``.
The ``%error`` macro outputs the follow string as an error and exits the RTEMS
Source Builder. This can also be used as ``%{error: message}``.
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
@@ -1365,7 +1365,7 @@ The default map is ``global``::
2. Defining macros only updates the ``global`` map and not the selected map.
The ``%define`` macro defines a new macro or updates an existing one. If no
value is given it is assumed to be ``1``::
@@ -1379,13 +1379,13 @@ value is given it is assumed to be ``1``::
1. The macro _one_ is set to 1.
The ``%undefine`` macro removes a macro if it exists. Any further references to
it will result in an undefine macro error.
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:
@@ -1462,7 +1462,7 @@ The ``%if`` macro starts a conditional logic block that can optionally have a
right hand side.
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
@@ -1473,42 +1473,42 @@ macro is defined::
The ``%ifarch`` is a short cut for ``%if %{_arch} == i386``. Currently not used.
The ``%ifnarch`` is a short cut for ``%if %{_arch} != i386``. Currently not
The ``%ifos`` is a short cut for ``%if %{_os} != mingw32``. It allows
conditional support for various operating system differences when building
The ``%else`` macro starts the conditional *else* block.
The ``%endif`` macro ends a conditional logic block.
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.
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
diff --git a/rsb/cross-canadian-cross.rst b/rsb/cross-canadian-cross.rst
index b085046..d4fce9e 100644
--- a/rsb/cross-canadian-cross.rst
+++ b/rsb/cross-canadian-cross.rst
@@ -4,7 +4,7 @@
.. comment Chris Johns <>
Cross and Canadian Cross Building
Cross building and Canadian Cross building is the process of building on one
machine an executable that runs on another machine. An example is building a
@@ -14,7 +14,7 @@ and Canadian cross building.
This sections details how to the RSB to cross and Canadian cross build.
Cross Building
Cross building is where the _build_ machine and _host_ are different. The
_build_ machine runs the RSB and the _host_ machine is where the output from
@@ -46,7 +46,7 @@ To build the NTP package for RTEMS you enter the RSB command::
'bin' directory at the end of the path.
Canadian Cross Building
A Canadian cross builds are where the **build**, **host** and **target**
machines all differ. For example building an RTEMS compiler for an ARM
diff --git a/rsb/hosts.rst b/rsb/hosts.rst
index 51c9e25..ba565d5 100644
--- a/rsb/hosts.rst
+++ b/rsb/hosts.rst
@@ -6,13 +6,13 @@
.. _Hosts:
The known supported hosts are listed in the following sections. If a host or a
new version of a host is known to work and it not listed please lets us know.
A number of different Linux distrubutions are known to work. The following have
been tested and report as working.
@@ -20,7 +20,7 @@ been tested and report as working.
.. _ArchLinux:
The following packages are required on a fresh Archlinux 64bit installation::
@@ -37,7 +37,7 @@ provide a manual override::
.. _CentOS:
The following packages are required on a minimal CentOS 6.3 64bit installation::
@@ -51,7 +51,7 @@ installed.
.. _Fedora:
The RTEMS Source Builder has been tested on Fedora 19 64bit with the following
@@ -62,7 +62,7 @@ packages::
.. _Raspbian:
The is the Debian distribution for the Raspberry Pi. The following packages are
@@ -78,7 +78,7 @@ prefix under your home directory as recommended and end up on the SD card.
.. _Xubuntu:
The latest version is Ubuntu 16.04.1 LTS 64bit. This section also includes
Xubuntu. A minimal installation was used and the following packages installed::
@@ -89,7 +89,7 @@ Xubuntu. A minimal installation was used and the following packages installed::
.. _Linux Mint:
Linux Mint
zlib package is required on Linux Mint. It has a different name (other
than the usual zlib-dev)::
@@ -99,7 +99,7 @@ than the usual zlib-dev)::
.. _openSUSE:
This has been reported to work but no instructions were provided. This is an
opportunity to contribute. Please submit any guidance you can provide.
@@ -107,7 +107,7 @@ opportunity to contribute. Please submit any guidance you can provide.
.. _FreeBSD:
The RTEMS Source Builder has been tested on FreeBSD 9.1, 10.3 and 11 64bit
version. You need to install some ports. They are::
@@ -131,7 +131,7 @@ install' rather than 'portinstall'.
.. _NetBSD:
The RTEMS Source Builder has been tested on NetBSD 6.1 i386. Packages to add
@@ -143,7 +143,7 @@ are::
.. _MacOS:
The RTEMS Source Builder has been tested on Mountain Lion. You will need to
install the Xcode app using the *App Store* tool, run Xcode and install the
@@ -152,7 +152,7 @@ Developers Tools package within Xcode.
.. _Mavericks:
The RSB works on Mavericks and the GNU tools can be built for RTEMS using the
Mavericks clang LLVM tool chain. You will need to build and install a couple of
@@ -169,14 +169,14 @@ tools. The following are required:
5.0.5. XZ builds and installs cleanly.
The RSB works on Serria with the latest Xcode.
.. _Windows:
Windows tool sets are supported. The tools are native Windows executable which
means they do not need an emulation layer to run once built. The tools
@@ -194,7 +194,7 @@ shell. There are a few options, Cygwin and MSYS2. I recommend MSYS2.
.. _MSYS2:
This is a new version of the MinGW project's original MSYS. MSYS2 is based
around the Arch Linux pacman packager. MSYS and MSYS2 are a specific fork of
@@ -223,6 +223,7 @@ the start of your path. The MSYS2 python does not work with waf.
.. _Cygwin:
Building on Windows is a little more complicated because the Cygwin shell is
used rather than the MSYS2 shell. The MSYS2 shell is simpler because the
diff --git a/rsb/index.rst b/rsb/index.rst
index 00011b6..be41f2e 100644
--- a/rsb/index.rst
+++ b/rsb/index.rst
@@ -1,8 +1,16 @@
.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-RTEMS Source Builder
+.. comment Heading
+.. comment 1 ======
+.. comment 2 ------
+.. comment 3 ~~~~~~
+.. comment 4 ^^^^^^
+.. highlight:: shell
+RTEMS |version| Source Builder
| COPYRIGHT (c) 2012 - 2016.
| Chris Johns <>
@@ -31,6 +39,9 @@ to the Community Project hosted at
Git Repositories
================ =============================
+Table of Contents
.. toctree::
:maxdepth: 5
diff --git a/rsb/project-sets.rst b/rsb/project-sets.rst
index 269d2b6..8abd080 100644
--- a/rsb/project-sets.rst
+++ b/rsb/project-sets.rst
@@ -4,7 +4,7 @@
.. comment Chris Johns <>
Project Sets
The RTEMS Source Builder supports project configurations. Project
configurations can be public or private and can be contained in the RTEMS
@@ -31,7 +31,7 @@ use of them. If you add new generic configurations please contribute them back
to the project
Bare Metal
The RSB contains a 'bare' configuration tree and you can use this to add
packages you use on the hosts. For example 'qemu' is supported on a range of
@@ -72,7 +72,7 @@ you would use `sparc-elf`::
cleaning: arm-eabihf-gdb-7.7-1
The RTEMS Configurations found in the ``rtems`` directory. The configurations
are grouped by RTEMS version. In RTEMS the tools are specific to a specific
@@ -136,7 +136,7 @@ and the following uses the version control heads for ``binutils``, ``gcc``,
Packages being built by the RSB need patches from time to time and the RSB
supports patching upstream packages. The patches are held in a seperate
diff --git a/rsb/quick-start.rst b/rsb/quick-start.rst
index 1d4677e..e3696a5 100644
--- a/rsb/quick-start.rst
+++ b/rsb/quick-start.rst
@@ -4,7 +4,7 @@
.. comment Chris Johns <>
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*. The *prefix* is the
@@ -69,7 +69,7 @@ difficult to manage in production systems.
Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
Setup a development work space::
@@ -91,7 +91,7 @@ from the RTEMS GIT repository::
about *Sandboxing* and the *prefix*.
The next step is to check if your host is set up correctly. The RTEMS Source
Builder provides a tool to help::
@@ -124,7 +124,7 @@ The :ref:`Hosts` 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
@@ -203,7 +203,7 @@ build ask the tool::
set files.
The quick start builds a SPARC tool set::
@@ -354,12 +354,12 @@ The installed tools::
level. The RTEMS Source Builder can build bare metal tool chains as
well. Look in the top level ``bare`` directory.
-Distributing and Archiving A Build
If you wish to create and distribute your build or you want to archive a build
-you can create a tar file. This is a more advanced method for binary packaging
-and installing of tools.
+you can create a tar file. We term this deploying a build. This is a more
+advanced method for binary packaging and installing of tools.
By default the RTEMS Source Builder installs the built packages directly and
optionally it can also create a *build set tar file* or a *package tar file*
@@ -508,7 +508,7 @@ build set::
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
diff --git a/rsb/source-builder.rst b/rsb/source-builder.rst
index e26e9a4..add2dc6 100644
--- a/rsb/source-builder.rst
+++ b/rsb/source-builder.rst
@@ -4,7 +4,7 @@
.. comment Chris Johns <>
RTEMS Source Builder
The RTEMS Source Builder or RSB is a tool to build packages from source. It is
used by the RTEMS project to build it's compilers and OS. The RSB helps
@@ -78,7 +78,7 @@ configuration can read the remaining sections.
Build Failures`.
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
@@ -134,7 +134,7 @@ any extra packages as a super user is always helpful in maintaining a secure
computing environment.
The RTEMS Source Builder is a stand alone tool based on another tool called the
*SpecBuilder* written by Chris Johns. The *SpecBuilder* was written around 2010
diff --git a/rsb/third-party-packages.rst b/rsb/third-party-packages.rst
index cda7183..a43abeb 100644
--- a/rsb/third-party-packages.rst
+++ b/rsb/third-party-packages.rst
@@ -4,7 +4,7 @@
.. comment Chris Johns <>
RTEMS 3rd Party Packages
This section describes how to build and add an RTEMS 3rd party package to the
@@ -22,7 +22,7 @@ in the RTEMS build system. If you have any issues with this support please ask
on the RTEMS developers mailing list.
Vertical Integration
The RSB supports horizontal integration with support for multiple
architectures. Adding packages to the RSB as libraries is vertical
@@ -31,7 +31,7 @@ you build a compiler. The same can be done for 3rd party libraries, you can
crate build sets that stack library dependences vertically to create a *stack*.
To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
installed. The set builder command line requires you provide the tools path,
@@ -57,7 +57,7 @@ To build Net-SNMP the command is:
Build Set: Time 0:01:10.651926
Adding a package requires you first build it manually by downloading the source
for the package and building it for RTEMS using the command line of a standard
@@ -115,7 +115,7 @@ A package requires 3 files to be created:
specific parts. See :ref:`Configuration` for more details.
BSP Support
The RSB provides support to help build packages for RTEMS. RTEMS applications
can be viewed as statically linked executables operating in a single address
@@ -307,7 +307,7 @@ provide sensible default or in this case map them to the BSP
1. The configure command for NTP.
RTEMS BSP Configuration
To build a package for RTEMS you need to build it with the matching BSP
configuration. A BSP can be built with specific flags that require all code