user/rsb: Update 3rd party package build and add packaging details.

5 files changed, 577 insertions, 319 deletions

diff --git a/user/rsb/configuration.rst b/user/rsb/configuration.rst
index e9a6ad4..fc387a1 100644
--- a/user/rsb/configuration.rst
+++ b/user/rsb/configuration.rst
@@ -879,13 +879,13 @@ The script language is implemented in terms of macros. The built-in list is:
 ``%hash``:
   Define a checksum for a source or patch file.
 
-``%echo``:
+``%{echo message}``:
   Print the following string as a message.
 
-``%warning``:
+``%{warning message}``:
   Print the following string as a warning and continue.
 
-``%error``:
+``%{error message}``:
   Print the following string as an error and exit.
 
 ``%select``:
diff --git a/user/rsb/cross-canadian-cross.rst b/user/rsb/cross-canadian-cross.rst
index d78952f..8eceed3 100644
--- a/user/rsb/cross-canadian-cross.rst
+++ b/user/rsb/cross-canadian-cross.rst
@@ -15,21 +15,21 @@ 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
-the build runs. An example is building a package such as NTP for RTEMS on your
+Cross building is where the *build* machine and *host* are different. The
+*build* machine runs the RSB and the *host* machine is where the output from
+the build runs. An example is building a package such as Curl for RTEMS on your
 development machine.
 
-To build the NTP package for RTEMS you enter the RSB command:
+To build the Curl package for RTEMS you enter the RSB command:
 
 .. code-block:: none
 
     $ ../source-builder/sb-set-builder \
-       --log=log_ntp_arm.txt \
+       --log=log_curl_arm.txt \
        --prefix=$HOME/development/rtems/5 \  <1>
        --host=arm-rtems5 \  <2>
        --with-rtems-bsp=xilinx_zynq_zc706 \  <3>
-       5/net/ntp
+       5/ftp/curl
 
 .. topic:: Items:
 
@@ -42,9 +42,18 @@ To build the NTP package for RTEMS you enter the RSB command:
 
 .. note: Installing Into Different Directories
 
-  If you install BSPs into a different path to the prefix use the
-  ``--with-tools`` option to specify the path to the tools. Do not add the
-  'bin' directory at the end of the path.
+  If you use a prefix that is different to the path the build RTEMS BSP is
+  installed under use the ``--with-rtems`` option to specify the top level path
+  to the RTEMS BSP. Do not add an extra directories to the path,the RSB knows
+  how to search the path.
+
+  If the tools have been installed in a different location to the RTEMS BSP and
+  the prefix use the ``--with-tools`` option to specift the top level path to
+  the installed tools Again do not add an extar directory such as ``bin`` as
+  the RSB knows how to search the supplied tools path.
+
+  We recommend you install all thrid party packages using the same prefix.
+  the RTEM BSP you can use the
 
 Canadian Cross Building
 ^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/user/rsb/index.rst b/user/rsb/index.rst
index d499800..c307ebe 100644
--- a/user/rsb/index.rst
+++ b/user/rsb/index.rst
@@ -6,30 +6,47 @@
 
 .. _RSB:
 
-RTEMS Source Builder
-********************
+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
-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 development. The RSB is not limited to building tools just
-for RTEMS, you can build bare metal development environments.
+The RTEMS Source Builder or RSB is a tool to build packages from source. The
+RTEMS project uses it to build it's compilers, tools, kernel and 3rd party
+packages. The tool is aimed at developers of software for RTEMS who use tool
+sets for embedded development.
+
+The RSB consolidates the details you need to build a package from source in a
+controlled and verifiable way. The RSB is not limited to building tools for
+RTEMS, you can build bare metal development environments.
+
+.. comment: TBD: The section "Installing and Tar Files" does not exist.
+
+The RSB section of this manual caters for a range of users from new to
+experienced RTEMS developers who want to understand the RTEMS Source
+Builder. New users who just want to build tools should follow :ref:`QuickStart`
+in this manual. Users building a binary tool set for release can read the
+"Installing and Tar Files". Users wanting to run and test bleeding edge tools
+or packages, or wanting update or extend the RSB's configuration can read the
+remaining sections.
 
 Embedded development typically uses cross-compiling tool chains, debuggers, and
 debugging aids. Together we call these a **tool set**. The RTEMS Source Builder
 is designed to fit this specific niche but is not limited to it. The RSB can be
 used outside of the RTEMS project and we welcome this.
 
-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, or library. The RTEMS Source Builder attempts to
-support any host environment that runs Python and you can build the package
-on. The RSB 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 is typically used to build a set of packages or a
+**build set**. A **build set** is a collection of packages and a package is a
+specific tool, for example GCC, GDB, or library of code and a single **build
+set** can build them all in a single command. The RTEMS Source Builder
+attempts to support any host environment that runs Python and you can build
+the package on. The RSB 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.
+
+.. sidebar:: Setting up your Host
+
+   See :ref:`QuickStartHost` for details on setting up hosts.
 
-The RTEMS Source Builder has been tested on:
+The RTEMS Source Builder is known to work on:
 
 - ArchLinux
 - CentOS
@@ -40,19 +57,16 @@ The RTEMS Source Builder has been tested on:
 - openSUSE
 - FreeBSD
 - NetBSD
+- Solaris
 - MacOS
 - Windows
 
-.. topic:: Setting up your Host
-
-   See :ref:`QuickStartHost` for details on setting up hosts.
-
 The RTEMS Source Builder has two types of 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
+of configuration data are the configuration files and they define how a package
 is built. Configuration files are scripts loosely based on the RPM spec file
 format and they detail the steps needed to build a package. The steps are
 *preparation*, *building*, and *installing*. Scripts support macros, shell
@@ -66,16 +80,6 @@ by developers who do. Support is provided for package config or ``pkgconfig``
 type files so you can check and use standard libraries if present. If you have
 a problem please ask on our :r:list:`devel`.
 
-.. comment: TBD: The section "Installing and Tar Files" does not exist.
-
-This documentation caters for a range of users from new to experienced RTEMS
-developers who want to understand the RTEMS Source Builder. New users
-who just want to build tools should follow the Quick Start section in
-the User's Guide.  Users building a binary tool set for release can
-read the "Installing and Tar Files". Users wanting to run and test
-bleeding edge tools or packages, or wanting update or extend the RSB's
-configuration can read the remaining sections.
-
 .. topic:: Bug Reporting
 
    If you think you have found a problem please see :ref:`Bugs, Crashes, and
@@ -83,12 +87,12 @@ configuration can read the remaining sections.
 
 .. toctree::
 
-    why-build-from-source.rst
-    project-sets
-    cross-canadian-cross
-    third-party-packages
-    configuration
-    commands
-    deployment
-    bug-reporting
-    history
+   why-build-from-source.rst
+   project-sets
+   cross-canadian-cross
+   third-party-packages
+   configuration
+   commands
+   deployment
+   bug-reporting
+   history
diff --git a/user/rsb/project-sets.rst b/user/rsb/project-sets.rst
index 2fb8dc5..6eb8729 100644
--- a/user/rsb/project-sets.rst
+++ b/user/rsb/project-sets.rst
@@ -7,22 +7,21 @@ 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 RTEMS Source
-Builder or privately on your local file system.
+Source Builder project if suitable.
 
 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``.
+this is set to ``%{_topdir}/config:%{_sbdir}/config`` where ``_topdir`` is your
+current working directory, or the directory you invoke the RTEMS Source Builder
+command in. The macro ``_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 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
@@ -38,7 +37,7 @@ available is to grep the configuration files for ``with`` and ``without``.
 Bare Metal
 ^^^^^^^^^^
 
-The RSB contains a 'bare' configuration tree and you can use this to add
+The RSB contains a ``bare`` configuration tree and you can use this to add
 packages you use on the hosts. For example 'qemu' is supported on a range of
 hosts. RTEMS tools live in the ``rtems/config`` directory tree. RTEMS packages
 include tools for use on your host computer as well as packages you can build
@@ -81,79 +80,30 @@ you would use ``sparc-elf``:
 RTEMS
 ^^^^^
 
-The RTEMS Configurations found in the ``rtems`` directory. The configurations
-are grouped by RTEMS version. In RTEMS the tools are specific to a specific
-version because of variations between Newlib and RTEMS. Restructuring in RTEMS
-and Newlib sometimes moves *libc* functionality between these two parts and
-this makes existing tools incompatible with RTEMS.
+The RTEMS Configurations are found in the ``rtems`` directory. The
+configurations are grouped by RTEMS version and a release normally only
+contains the configurations for that release.. 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
+have a bug in other architecture. Architecture specific patches should only be
+appliaed when build the related architecture. A patch may fix a problem on one
+architecture however it could introduce a problem in another
+architecture. Limiting exposure limits any possible crosstalk between
 architectures.
 
-If you are building a released version of RTEMS the release RTEMS tar file will
-be downloaded and built as part of the build process. If you are building a
-tool set for use with the development branch of RTEMS, the development branch
-will be cloned directly from the RTEMS GIT repository and built.
-
-When building RTEMS within the RTEMS Source Builder it needs a suitable working
-``autoconf`` and ``automake``. These packages need to built and installed in their
-prefix in order for them to work. The RTEMS Source Builder installs all
-packages only after they have been built so if you host does not have a
-recent enough version of ``autoconf`` and ``automake`` you first need to build them
-and install them then build your tool set. The commands are:
-
-.. code-block:: none
-
-    $ ../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
-
-.. topic:: Items:
-
-  1. Setting the path.
-
-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:
-
-.. code-block:: none
-
-    $ ../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*:
-
-.. code-block:: none
-
-    $ ../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
+If you have a configuation issue try adding 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.
 
 Following features can be enabled/disabled via the command line for the RTEMS
 build sets:
 
-``--without-rtems``
-  Do not build RTEMS when building an RTEMS build set.
-
 ``--without-cxx``
   Do not build a C++ compiler.
 
@@ -166,6 +116,16 @@ build sets:
 ``--with-objc``
   Attempt to build a C++ compiler.
 
+The RSB provides build sets for some BSPs. These build sets will build:
+
+- Compiler, linker, debugger and RTEMS Tools.
+
+- RTEMS Kernel for the BSP
+
+- Optionally LibBSD if supported by the BSP.
+
+- Third party packages if supported by the BSP.
+
 Patches
 ^^^^^^^
 
@@ -183,24 +143,18 @@ package's patch management tools directly. If the RSB does not support the
 specific patch manage tool please contact the mailing list to see if support
 can be added.
 
-Patches for packages developed by the RTEMS project can be placed in the RTEMS
-Tools Git repository. The ``tools`` directory in the repository has various
-places a patch can live. The tree is broken down in RTEMS releases and then
-tools within that release. If the package is not specific to any release the
-patch can be added closer to the top under the package's name. Patches to fix
-specific tool related issues for a specific architecture should be grouped
-under the specific architecture and only applied when building that
-architecture avoiding a patch breaking an uneffected architecture.
+Referenced patches should be placed in a location that is easy to access and
+download with a stable URL. We recommend attaching a patch to an RTEMS ticket
+in it's bug reporting system or posting to a mailing list with online archives.
 
-Patches in the RTEMS Tools repository need to be submitted to the upstream
-project. It should not be a clearing house for patches that will not be
-accepted upstream.
+RTEMS's former practice of placing patches in the RTEMS Tools Git repository
+has been stopped.
 
 Patches are added to a component's name and in the ``%prep:`` section the
-patches can be set up, meaning they are applied to source. The patches
-are applied in the order they are added. If there is a dependency make
-sure you order the patches correctly when you add them. You can add any
-number of patches and the RSB will handle them efficently.
+patches can be set up, meaning they are applied to source. The patches are
+applied in the order they are added. If there is a dependency make sure you
+order the patches correctly when you add them. You can add any number of
+patches and the RSB will handle them efficently.
 
 Patches can have options. These are added before the patch URL. If no options
 are provided the patch's setup default options are used.
@@ -226,15 +180,15 @@ used to add a checksum for a patch that is used to verify the patch:
 
 .. code-block:: spec
 
-    %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
+    %hash sha512 <1> gdb-sim-lm32uart.diff <2> 77d07087 ... e7db17fb <3>
 
 .. topic:: Items:
 
-  1. The type of checksum, in the case an MD5 hash.
+  1. The type of checksum, in the case an SHA512 hash.
 
   2. The patch file the checksum is for.
 
-  3. The MD5 hash.
+  3. The SHA512 hash.
 
 The patches are applied when a patch ``setup`` command is issued in the
 ``%prep:`` section. All patches in the group are applied. To apply the GDB
diff --git a/user/rsb/third-party-packages.rst b/user/rsb/third-party-packages.rst
index b8ca15a..0d9fa81 100644
--- a/user/rsb/third-party-packages.rst
+++ b/user/rsb/third-party-packages.rst
@@ -2,127 +2,311 @@
 
 .. Copyright (C) 2012, 2016 Chris Johns <chrisj@rtems.org>
 
-RTEMS Third-Party Packages
---------------------------
+Third-Party Packages
+--------------------
 
 This section describes how to build and add an RTEMS third-party package to the
 RSB.
 
 A third-party package is a library or software package built to run on RTEMS,
-examples are NTP, Net-Snmp, libjpeg or Python. These pieces of software can be
-used to help build RTEMS applications. The package is built for a specific
-BSP and so requires a working RTEMS tool chain and an installed RTEMS Board
-Support Package (BSP).
+examples are Curl, NTP, Net-Snmp, libjpeg and more. These pieces of software
+can be used to help build RTEMS applications. The package is built for a
+specific BSP and so requires a working RTEMS tool chain, an installed RTEMS
+Board Support Package (BSP), and a network stack if the package uses
+networking resources.
 
-The RSB support for building third-party packages is based around the *pkconfig*
-files (PC) installed with the BSP. The pkgconfig support in RTEMS is considered
-experimental and can have some issues for some BSPs. This issue is rooted deep
-in the RTEMS build system. If you have any issues with this support please ask
-on the RTEMS developers mailing list.
+.. sidebar:: Help
+
+   If you have any issues using, building or adding third party packages please
+   ask on the RTEMS users mailing list.
+
+
+The RSB support for building third-party packages is based around the
+*pkconfig* files (PC) installed with the BSP. The pkgconfig support in RTEMS is
+considered experimental and can have some issues for some BSPs. This issue is
+rooted deep in the RTEMS build system.
 
 Vertical Integration
 ^^^^^^^^^^^^^^^^^^^^
 
 The RSB supports horizontal integration with support for multiple
 architectures. Adding packages to the RSB as libraries is vertical
-integration. Building the GCC tool chain requires you build an assembler before
-you build a compiler. The same can be done for third-party libraries, you can
-crate build sets that stack library dependences vertically to create a *stack*.
+integration. Building the GCC tool chain requires you build an assembler
+before you build a compiler. The same can be done for third-party libraries,
+you can create build sets that stack library dependences vertically to create
+a *stack*.
 
 Building
 ^^^^^^^^
 
 To build a package you need to have a suitable RTEMS tool chain and RTEMS BSP
 installed. The set builder command line requires you provide the tools path,
-the RTEMS host, and the prefix path to the installed RTEMS BSP. The prefix
-needs to be the same as the prefix used to build RTEMS.
-
-To build Net-SNMP the command is:
+the RTEMS architecture (host), the BSP, and the prefix path used to the
+install RTEMS BSP.
+
+The RSB prefix option (``--prefix``) provided when building a package is the
+path to:
+
+#. The tools, RTEMS kernel and any dependent libraries such as LibBSD. The
+   package will be installed into the prefix path. This build configuration can
+   be used to make a complete set of development tools and libraries for a
+   project or product under a single path.
+
+#. The RTEMS kernel and any dependent libraries such as LibBSD. The tools path
+   needs to be in the environment path (not recommended) or provided to the set
+   builder command by the ``--with-tools`` option. The package will be
+   installed into the prefix path. This build configuration can be used when
+   you have a set of tools used with a number of RTEMS BSPs. The tools can be
+   shared between the different BSPs.
+
+#. The path the package is installed into. The tools path needs to be in the
+   environment path (not recommended) or provided to the set builder command
+   using the ``--with-tools`` option. The path to the RTEMS kernel and any
+   dependent libraries such as LibBSD needs to be supplied to the set builder
+   command using the ``--with-rtems`` option. This build configuration can be
+   used when you have a set of libraries you are testing with a changing RTEMS
+   kernel. Becareful using this configuration as changes in RTEMS interfaces
+   may require rebuilding these packages.
+
+The set builder command option ``--host`` is used to provide the RTEMS
+architecture the package is being built for. For example ``--host=arm-rtems5``
+is used for any ARM BSP.
+
+The set builder command option ``--with-rtems-bsp`` is the RTEMS BSP the
+package is being built for. The BSP is searched for under the path provided by
+the command option ``--with-rtems`` and if this option is not provided the
+provided prefix is searched.
+
+The following example builds and installs the Curl networking package for the
+ARM BeagleBone Black BSP installing it into the same path the tools, RTEMS
+kernel and LibBSD are installed in.
 
 .. code-block:: none
 
-    $ cd rtems-source-builder/rtems
-    $ ../source-builder/sb-set-builder --log=log_sis_net_snmp \
-        --prefix=$HOME/development/rtems/bsps/4.11 \
-        --with-tools=$HOME/development/rtems/4.11 \
-        --host=sparc-rtems4.11 --with-rtems-bsp=erc32 4.11/net-mgmt/net-snmp
-    RTEMS Source Builder - Set Builder, v0.3.0
-    Build Set: 4.11/net-mgmt/net-snmp
-    config: net-mgmt/net-snmp-5.7.2.1-1.cfg
-    package: net-snmp-5.7.2.1-sparc-rtems4.11-1
-    building: net-snmp-5.7.2.1-sparc-rtems4.11-1
-    installing: net-snmp-5.7.2.1-sparc-rtems4.11-1 -> /Users/chris/development/rtems/bsps/4.11
-    cleaning: net-snmp-5.7.2.1-sparc-rtems4.11-1
-    Build Set: Time 0:01:10.651926
+ $ ../source-builder/sb-set-builder --prefix=$HOME/development/cs/rtems/5 \
+       --log=curl.txt --host=arm-rtems5 --with-rtems-bsp=beagleboneblack ftp/curl
+ RTEMS Source Builder - Set Builder, 5 (2bdae1f169e4)
+ Build Set: ftp/curl
+ config: ftp/curl-7.65.1-1.cfg
+ package: curl-v7.65.1-arm-rtems5-1
+ download: https://curl.haxx.se/download/curl-7.65.1.tar.xz -> sources/curl-7.65.1.tar.xz
+ downloading: sources/curl-7.65.1.tar.xz - 2.3MB of 2.3MB (100%)
+ building: curl-v7.65.1-arm-rtems5-1
+ sizes: curl-v7.65.1-arm-rtems5-1: 87.055MB (installed: 2.238MB)
+ cleaning: curl-v7.65.1-arm-rtems5-1
+ reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.txt
+ reporting: ftp/curl-7.65.1-1.cfg -> curl-v7.65.1-arm-rtems5-1.xml
+ installing: curl-v7.65.1-arm-rtems5-1 -> /Users/chris/development/cs/rtems/5
+ cleaning: curl-v7.65.1-arm-rtems5-1
+ Build Set: Time 0:01:10.006872
 
 Adding
 ^^^^^^
 
-Adding a package requires you first build it manually by downloading the source
-for the package and building it for RTEMS using the command line of a standard
-shell. If the package has not been ported to RTEMS you will need to port it and
-this may require you asking questions on the package's user or development
-support lists as well as RTEMS's developers list. Your porting effort may end
-up with a patch. RTEMS requires a patch be submitted upstream to the project's
-community as well as RTEMS so it can be added to the RTEMS Tools git
-repository. A patch in the RTEMS Tools git reposiitory can then be referenced
-by an RSB configuration file.
-
-A package may create executables, for example NTP normally creates executables
-such as ``ntdp``, ``ntpupdate``, or ``ntpdc``. These executables can be useful
-when testing the package however they are of limited use by RTEMS users because
-they cannot be directly linked into a user application. Users need to link to
-the functions in these executables or even the executable as a function placed
-in libraries. If the package does not export the code in a suitable manner
-please contact the project's commuinity and see if you can work them to provide
-a way for the code to be exported. This may be difficult because exporting
-internal headers and functions opens the project up to API compatibility issues
-they did not have before. In the simplest case attempting to get the code into
-a static library with a single call entry point exported in a header would give
-RTEMS user's access to the package's main functionality.
-
-A package requires 3 files to be created:
-
-- The first file is the RTEMS build set file and it resides in the
-  ``rtems/config/%{rtems_version}`` path in a directory tree based on the
-  FreeBSD ports collection. For the NTP package and RTEMS 4.11 this is
-  ``rtems/config/4.11/net/ntp.bset``. If you do not know the FreeBSD port path
-  for the package you are adding please ask. The build set file references a
-  specific configuration file therefore linking the RTEMS version to a specific
-  version of the package you are adding. Updating the package to a new version
-  requires changing the build set to the new configuration file.
-
-- The second file is an RTEMS version specific configuration file and it
-  includes the RSB RTEMS BSP support. These configuration files reside in the
-  ``rtems/config`` tree again under the FreeBSD port's path name. For example
-  the NTP package is found in the ``net`` directory of the FreeBSD ports tree
-  so the NTP configuration path is ``rtems/config/net/ntp-4.2.6p5-1.cfg`` for
-  that specific version. The configuration file name typically provides version
-  specific references and the RTEMS build set file references a specific
-  version. This configuration file references the build configuration file held
-  in the common configuration file tree.
-
-- The build configuration. This is a common script that builds the package. It
-  resides in the ``source-builder/config`` directory and typically has the
-  packages's name with the major version number. If the build script does not
-  change for each major version number a *common* base script can be created
-  and included by each major version configuration script. The *gcc* compiler
-  configuration is an example. This approach lets you branch a version if
-  something changes that is not backwards compatible. It is important to keep
-  existing versions building. The build configuration should be able to build a
-  package for the build host as well as RTEMS as the RSB abstracts the RTEMS
-  specific parts. See :ref:`Configuration` for more details.
+Adding a package requires you first build it manually by downloading the
+source for the package and building it for RTEMS using the command line of a
+standard shell. If the package has not been ported to RTEMS you will need to
+port it and this may require asking questions on the package's user or
+development support lists as well as RTEMS's developers list. Your porting
+effort may end up with a patch. RTEMS requires a patch be submitted upstream
+to the project's community as well as RTEMS. The RTEMS submission is best as a
+patch attached to ticket in Trac. A patch attached to a ticket can be
+referenced by an RSB configuration file and used in a build.
+
+.. sidebar:: Patches in Trac
+
+   Attaching patches for packages to Trac tickets provides an easy to reference
+   URL the RSB can fetch. The patch URL does not change across RTEMS versions
+   and it does not depend on the state or layout of a git repo.
+
+
+A package may create executables, for example Curl normally creates an
+executable called ``curl`` how ever it will probailty not run because the
+needed RTEMS configuration is not suitable. If found the RSB automatically
+adds the RTEMS library ``librtemsdefaultconfig.a`` to the ``LIBS`` variable
+used to link executables. This library provides a limited configuraiton
+suitable for linking an executable however it is not a set up that allows the
+resulting executable to run correctly. As a result it is best not to install
+these executables.
+
+A custom RTEMS patch to an executate's source code can turn it into a function
+that can be called by the RTEMS shell. Users can call the function in their
+executables simulating the running of the package's command. If the package
+does not export the code in a suitable manner please contact the project's
+commuinity and see if you can work with them to provide a way for the code to
+be exported. This may be difficult because exporting internal headers and
+functions opens the project up to API compatibility issues they did not have
+before. In the simplest case attempting to get the code into a static library
+with a single call entry point exported in a header would give RTEMS user's
+access to the package's main functionality.
+
+A package requires at least three (3) files to be created:
+
+  Published Package Name:
+    The first file is the RTEMS build set file and it resides under the
+    ``rtems/config`` path in a directory tree based on the FreeBSD ports
+    collection. For the Curl package and RTEMS 5 this is
+    ``rtems/config/ftp/curl.bset``. If you do not know the FreeBSD port path
+    for the package you are adding please ask. The build set file references a
+    specific configuration file therefore linking the RTEMS version to a
+    specific version of the package you are adding. Updating the package to a
+    new version requires changing the build set to the new configuration file.
+
+  Package Version Configuration File:
+    The second file is an RTEMS version specific configuration file and it
+    includes the RSB RTEMS BSP support. These configuration files reside in
+    the ``rtems/config`` tree and under the FreeBSD port's path name. For
+    example the Curl package is found in the ``ftp`` directory of the FreeBSD
+    ports tree so the Curl configuration path is
+    ``rtems/config/ftp/curl-7.65.1-1.cfg`` for that specific version. The
+    configuration file name typically provides version specific references and
+    the RTEMS build set file references a specific version. This configuration
+    file references the build configuration file held in the common
+    configuration file tree. An SHA512 hash is required to verify the source
+    package that is downloaded.
+
+  Build Configuration File:
+    The build configuration. This is a common script that builds the
+    package. It resides in the ``source-builder/config`` directory and
+    typically has the packages's name with the major version number. If the
+    build script does not change for each major version number a *common* base
+    script can be created and included by each major version configuration
+    script. The *gcc* compiler configuration is an example. This approach lets
+    you branch a version if something changes that is not backwards
+    compatible. It is important to keep existing versions building. The build
+    configuration should be able to build a package for the build host as well
+    as RTEMS as the RSB abstracts the RTEMS specific parts. See
+    :ref:`Configuration` for more details.
+
+Host and Build Flags
+^^^^^^^^^^^^^^^^^^^^
+
+A package's build is controlled by setting the compiler names and flags that
+are used when building. The RSB provides a macro called
+``%{host_build_flags}`` to define these flags for you. Use this macro in the
+```%build`` section of your config script file to define the set up needed to
+build a native package or to cross-compile to a specific host such as RTEMS
+. The typical ``%build`` section is:
+
+.. code-block:: spec
+
+ %build
+   build_top=$(pwd)
+
+   %{build_directory}
+
+   mkdir -p ${build_dir}
+   cd ${build_dir}
+
+   %{host_build_flags}
+
+   ../${source_dir_curl}/configure \
+     --host=%{_host} \
+     --prefix=%{_prefix} \
+     --bindir=%{_bindir} \
+     --exec_prefix=%{_exec_prefix} \
+     --includedir=%{_includedir} \
+     --libdir=%{_libdir} \
+     --libexecdir=%{_libexecdir} \
+     --mandir=%{_mandir} \
+     --infodir=%{_infodir} \
+     --datadir=%{_datadir}
+
+   %{__make} %{?_smp_mflags} all
+
+   cd ${build_top}
+
+The ``%{host_build_flags}`` checks if the build is native for the development
+host or a cross-compile build.
+
+For a cross-complication build the flags are:
+
+``CC``, ``CC_FOR_HOST``:
+ The C compiler used to build the package. For an RTEMS build this is the
+ RTEMS C compiler. For example the ARM architecture and RTEMS 5 the value is
+ set to ``arm-rtems5-gcc``.
+
+``CXX``, ``CXX_FOR_HOST``:
+ The C++ compiler used to build the package. For an RTEMS build this is the
+ RTEMS C++ compiler. For example the ARM architecture and RTEMS 5 the value is
+ set to ``arm-rtems5-g++``.
+
+``CPPFLAGS``, ``CPPFLAGS_FOR_HOST``:
+ The C compiler preprocessor flags used to build the package. Set any include
+ paths in this variable as some configure scripts will warns you if include
+ paths are set in the ``CFLAGS``.
+
+``CFLAGS``, ``CFLAGS_FOR_HOST``:
+ The C compiler flags used when running the C compiler. Set any include paths
+ in the ``CPPFLAGS`` variable as some configure scripts will warn you if
+ include paths in this variable.
+
+``CXXFLAGS``, ``CXXFLAGS_FOR_HOST``:
+ The C++ compiler flags used when running the C++ compiler. Set any include
+ paths in the ``CPPFLAGS`` variable as some configure scripts will warn you if
+ include paths in this variable.
+
+``LDFLAGS``, ``LDFLAGS_FOR_HOST``:
+ The linker flags used whne link package executables. The C or C++ compiler
+ is used to run the linker.
+
+``LIBS``, ``LIBS_FOR_HOST``:
+ A list of libraries passed to the linker when linking an executable.
+
+``CC_FOR_BUILD``:
+ The native C compiler.
+
+``CXX_FOR_BUILD``:
+ The native C++ compiler.
+
+``CPPFLAGS_FOR_BUILD``:
+ The C preprocessor flags used when preprocessoring a native C source file.
+
+``CFLAGS_FOR_BUILD``:
+ The native C compiler flags used when running the native C compiler.
+
+``CXXFLAGS_FOR_BUILD``:
+ The native C++ compiler flags used when running the native C++ compiler.
+
+``LDFLAGS_FOR_BUILD``:
+ The native linker flags used when linking a native executable.
+
+``LIBS_FOR_BUILD``:
+ The native libraries used to when linking a native executable.
+
+For a native build the flags are:
+
+``CC``, ``CC_FOR_BUILD``:
+ The native C compiler.
+
+``CXX``, ``CXX_FOR_BUILD``:
+ The native C++ compiler.
+
+``CPPFLAGS``, ``CPPFLAGS_FOR_BUILD``:
+ The C preprocessor flags used when preprocessoring a native C source file.
+
+``CFLAGS``, ``CFLAGS_FOR_BUILD``:
+ The native C compiler flags used when running the native C compiler.
+
+``CXXFLAGS``, ``CXXFLAGS_FOR_BUILD``:
+ The native C++ compiler flags used when running the native C++ compiler.
+
+``LDFLAGS``, ``LDFLAGS_FOR_BUILD``:
+ The native linker flags used when linking a native executable.
+
+``LIBS``, ``LIBS_FOR_BUILD``:
+ The native libraries used to when linking a native executable.
 
 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
+The RSB provides support to build packages for RTEMS. RTEMS applications can
+be viewed as statically linked executables operating in a single address
 space. As a result only the static libraries a package builds are required and
-these libraries need to be ABI compatible with the RTEMS kernel and application
-code meaning compiler ABI flags cannot be mixed when building code. The 3rd
-party package need to use the same compiler flags as the BSP used to build
-RTEMS.
+these libraries need to be ABI compatible with the RTEMS kernel and
+application code. This means the compiler ABI flags used to build all the code
+in the executable must be the same. A 3rd party package must use the same
+compiler flags as the BSP used to build RTEMS.
 
 .. note::
 
@@ -134,39 +318,32 @@ RTEMS.
 
 The RSB provides the configuration file ``rtems/config/rtems-bsp.cfg`` to
 support building third-party packages and you need to include this file in your
-RTEMS version specific configuration file. For example the Net-SNMP
-configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
+RTEMS version specific configuration file. For example the Curl configuration
+file ``rtems/config/curl/curl-7.65.1-1.cfg``:
 
 .. code-block:: spec
 
-    #
-    # NetSNMP 5.7.2.1
-    #
-    %if %{release} == %{nil}
-     %define release 1    <1>
-    %endif
+ #
+ # Curl 7.65.1
+ #
 
-    %include %{_configdir}/rtems-bsp.cfg   <2>
+ %if %{release} == %{nil}
+  %define release 1  <1>
+ %endif
 
-    #
-    # NetSNMP Version
-    #
-    %define net_snmp_version 5.7.2.1   <3>
+ %include %{_configdir}/rtems-bsp.cfg   <2>
 
-    #
-    # We need some special flags to build this version.
-    #
-    %define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0
+ #
+ # Curl Version
+ #
+ %define curl_version 7.65.1   <3>
 
-    #
-    # Patch for RTEMS support.
-    #
-    %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>
+ %hash sha512 curl-%{curl_version}.tar.xz aba2d979a...72b6ac55df4   <4>
 
-    #
-    # NetSNMP Build configuration
-    #
-    %include %{_configdir}/net-snmp-5-1.cfg   <6>
+ #
+ # Curl Build configuration
+ #
+ %include %{_configdir}/curl-1.cfg <5>
 
 .. topic:: Items:
 
@@ -174,54 +351,93 @@ configuration file ``rtems/config/net-mgmt/net-snmp-5.7.2.1-1.cfg``:
 
   2. Include the RSB RTEMS BSP support.
 
-  3. The Net-SNMP package's version.
-
-  4. Add specific ``CFLAGS`` to the build process. See the
-     ``net-snmp-5.7.2.1-1.cfg`` for details.
+  3. The Curl package's version.
 
-  5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
+  4. The SHA512 hash for the source file. The hash here has been shortened.
 
-  6. The Net-SNMP standard build configuration.
+  5. The Curl standard build configuration.
 
 The RSB RTEMS BSP support file ``rtems/config/rtems-bsp.cfg`` checks to make
-sure standard command line options are provided. These include ``--host`` and
-``--with-rtems-bsp``. If the ``--with-tools`` command line option is not given
-the ``${_prefix}`` is used:
+sure the required RSB command line options are provided. These include
+``--host`` and ``--with-rtems-bsp``. If the ``--with-tools`` command line
+option is not given the ``${_prefix}`` is used as the path to the tools. If
+the ``--with-rtems`` command line option is not given the ``${_prefix}`` is
+used as the path to the installed RTEMS BSP.
+
+.. note::
+
+   The RTEMS BSP and any dependent 3rd party packages must be installed to be
+   seen as available. A path to the location the BSP has been built will not
+   work.
+
+The first check is to make sure a target is not specified. This is only used
+for Canadian cross-compilication builds and currently there is no support for
+RTEMS third party packages to build that way:
 
 .. code-block:: spec
 
-    %if %{_host} == %{nil} <1>
-     %error No RTEMS target specified: --host=host
-    %endif
+ #
+ # The target is used by compilers or Cxc builds.
+ #
+ %if %{_target} != %{nil}
+  %error RTEMS BSP builds use --host and not --target
+ %endif
 
-    %ifn %{defined with_rtems_bsp} <2>
-     %error No RTEMS BSP specified: --with-rtems-bsp=bsp
-    %endif
+A host is required using the ``--host`` option:
 
-    %ifn %{defined with_tools} <3>
-     %define with_tools %{_prefix}
-    %endif
+.. code-block:: spec
 
-    #
-    # Set the path to the tools.
-    #
-    %{path prepend %{with_tools}/bin} <4>
+ #
+ # We need a host from the user to specifiy the RTEMS architecture and major
+ # version.
+ #
+ %if %{_host} == %{nil} && %{rtems_bsp_error} <1>
+  %error No RTEMS host or BSP specified: --host=<arch>-rtems<ver>
+ %endif
 
-.. topic:: Items:
+An RTEMS BSP is required using the ``--with-bsp`` option:
+
+.. code-block:: spec
 
-  1. Check the host has been set.
+ #
+ # We need a BSP from the user.
+ #
+ %ifn %{defined with_rtems_bsp}
+  %if %{rtems_bsp_error}
+   %error No RTEMS BSP specified: --rtems-bsp=arch/bsp (or --with-rtems-bsp=bsp)
+  %endif
+  %define with_rtems_bsp sparc/erc32
+ %endif
 
-  2. Check a BSP has been specified.
+Check if the ``--with-tools`` or ``--with-rtems`` options have been provided
+and if they are not provided use the ``--prefix`` path:
 
-  3. If no tools path has been provided assume they are under the
-     ``%{_prefix}``.
+.. code-block:: spec
+
+ #
+ # If no tools or RTEMS provided use the prefix.
+ #
+ %ifn %{defined with_tools}
+  %define with_tools %{_prefix}
+ %endif
 
-  4. Add the tools ``bin`` path to the system path.
+ %ifn %{defined with_rtems}
+  %define with_rtems %{_prefix}
+ %endif
 
-RTEMS exports the build flags used in *pkgconfig* (.pc) files and the RSB can
-read and manage them even when there is no pkgconfig support installed on your
-build machine. Using this support we can obtain a BSP's configuration and set
-some standard macros variables (``rtems/config/rtems-bsp.cfg``):
+Add the tools path to the envnironment path:
+
+.. code-block:: spec
+
+ #
+ # Set the path to the tools.
+ #
+ %{path prepend %{with_tools}/bin}
+
+RTEMS exports the build configuration in *pkgconfig* (.pc) files. The RSB can
+read these files even when there is no ``pkgconfig`` support installed on your
+development machine. The *pkgconfig* support provides a BSP's configuration and
+the RSB uses it to set the followng RSB macros variables:
 
 .. code-block:: spec
 
@@ -242,17 +458,17 @@ some standard macros variables (``rtems/config/rtems-bsp.cfg``):
 
   1. Set the path to the BSP's pkgconfig file.
 
-  2. Let pkgconfig know this is a cross-compile build.
+  2. Let *pkgconfig* know this is a cross-compile build.
 
-  3. Filter flags such as warnings. Warning flags are specific to a package.
+  3. Filter flags such as warnings. Warning flags are specific to a package and
+     RTEMS exports it's warnings flags in the BSP configuration settings.
 
-  4. Ask pkgconfig for the various items we require.
+  4. Ask *pkgconfig* for the various settings we require.
 
-The flags obtain by pkgconfig and given a ``rtems_bsp_`` prefix and we uses these
-to set the RSB host support CFLAGS, LDFLAGS and LIBS flags. When we build a 3rd
-party library your host computer is the _build_ machine and RTEMS is the _host_
-machine therefore we set the ``host`` variables
-(``rtems/config/rtems-bsp.cfg``):
+The flags obtained by *pkgconfig* and given a ``rtems_bsp`` prefix are used to
+set the RTEMS host variables ``CFLAGS``, ``LDFLAGS`` and ``LIBS``. When we
+build a third party library your host computer is the **build** machine and
+RTEMS is the **host** machine therefore we set the ``host`` variables:
 
 .. code-block:: spec
 
@@ -263,9 +479,9 @@ machine therefore we set the ``host`` variables
 Finally we provide all the paths you may require when configuring a
 package. Packages by default consider the ``_prefix`` the base and install
 various files under this tree. The package you are building is specific to a
-BSP and so needs to install into the specific BSP path under the
-``_prefix``. This allows more than BSP build of this package to be install
-under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
+BSP and needs to install it's files into the RTEMS specific BSP path under the
+``_prefix``. This allows more than BSP build of this package to be installed
+under the same ``_prefix`` at the same time:
 
 .. code-block:: spec
 
@@ -291,15 +507,14 @@ under the same ``_prefix`` at the same time (``rtems/config/rtems-bsp.cfg``):
 
 .. topic:: Items:
 
-  1. The path to the BSP.
+  1. The path to the installed BSP.
 
 When you configure a package you can reference these paths and the RSB will
-provide sensible default or in this case map them to the BSP
-(``source-builder/config/ntp-4-1.cfg``):
+provide sensible default or in this case map them to the BSP:
 
 .. code-block:: spec
 
-      ../${source_dir_ntp}/configure \ <1>
+      ../${source_dir_curl}/configure \ <1>
         --host=%{_host} \
         --prefix=%{_prefix} \
         --bindir=%{_bindir} \
@@ -309,17 +524,93 @@ provide sensible default or in this case map them to the BSP
         --libexecdir=%{_libexecdir} \
         --mandir=%{_mandir} \
         --infodir=%{_infodir} \
-        --datadir=%{_datadir} \
-        --disable-ipv6 \
-        --disable-HOPFPCI
+        --datadir=%{_datadir}
 
 .. topic:: Items:
 
-  1. The configure command for NTP.
+  1. The configure command for Curl.
+
+
+BSP Configuration
+^^^^^^^^^^^^^^^^^
+
+The following RSB macros are defined when building a package for RTEMS:
+
+.. note::
+
+    A complete list can be obtained by building with the ``--trace`` flag. The
+    log will contain a listing of all macros before and after the configuration
+    is loaded.
+
+``%{rtems_bsp}``:
+ The name of the RTEMS BSP.
+
+``%{rtems_bsp_cc}``:
+ The C compiler name for the RTEMS BSP.
+
+``%{rtems_bsp_cflags}``:
+ The C compiler flags for the RTEMS BSP.
+
+``%{rtems_bsp_ccflags}``:
+ The C++ compiler flags for the RTEMS BSP.
+
+``%{rtems_bsp_incpath}``:
+ The include path to teh RTEMS BSP header files.
+
+``%{rtems_bsp_ldflags}``:
+ The linker flags for the RTEMS BSP.
+
+``%{rtems_bsp_libs}``:
+ The libraries used when linking an RTEMS BSP executable.
+
+``%{rtems_bsp_prefix}``:
+ The prefix for the RTEMS BSP.
+
+``%{rtems-libbsd}``:
+ The variable is set to ``found`` if LibBSD is available.
+
+``%{rtems-defaultconfig}``:
+ The path of the RSB helper script to locate find header files or libraries.
+
+``%{_host}``
+ The host triplet passed on the command line to the set builder using the
+ ``--host`` options. This is the RTEMS architecture and version. For example
+ ``arm-rtems5``.
+
+``%{host_cflags}``:
+ The BSP ``CFLAGS`` returned by ``pkgconfig``.
+
+``%{host_cxxflags}``:
+ The BSP ``CXXFLAGS`` returned by ``pkgconfig``.
+
+``%{host_includes}``:
+ The BSP include paths returned by ``pkgconfig``.
+
+``%{host_ldflags}``:
+ The BSP ``LDFLAGS`` returned by ``pkgconfig``.
+
+``%{host_libs}``:
+ The libraries needed to be linked to create an executable. If LibBSD is
+ installed the library ``-lbsd`` is added. If the BSP has installed the RTEMS
+ default configuration library (``-lrtemsdefaultconfig``) it is added to the
+ list of libraries.
+
+``%{host_build_flags}``:
+ This macro is defined in ``defaults.mc`` and is a series of shell commands
+ that set up the environment to build an RTEMS package. If the host and the
+ build triplets are the same it is a native build for your development host. If
+ the host is not the build machine it is a cross-complitation build. For either
+ case the following are defined.
+
+``%{_host_os}``:
+ The host operating system extracted from the ``--host`` command line
+ option. For example the operating sstem for the host of ``arm-rtems5`` is
+ ``rtems5``.
 
-RTEMS BSP Configuration
-^^^^^^^^^^^^^^^^^^^^^^^
+``%{_host_arch}``:
+ The host architecture extracted from the ``--host`` command line option. For
+ example the architecture for the host of ``arm-rtems5`` is ``arm``.
 
-To build a package for RTEMS you need to build it with the matching BSP
-configuration. A BSP can be built with specific flags that require all code
-being used needs to be built with the same flags.
+``%{_host_cpu}``:
+ The host cpu extracted from the ``--host`` command line option. For
+ example the cpu for the host of ``arm-rtems5`` is ``arm``.