Index: user/rsb/configuration.rst
===================================================================
--- user/rsb/configuration.rst	(revision 6185f6e635203117ce6fdde8f9dcff01c6c7bafd)
+++ user/rsb/configuration.rst	(revision bb47f890c82595ba493a82aa860c6892a52e1e8c)
@@ -880,11 +880,11 @@
   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.
 
Index: user/rsb/cross-canadian-cross.rst
===================================================================
--- user/rsb/cross-canadian-cross.rst	(revision 6185f6e635203117ce6fdde8f9dcff01c6c7bafd)
+++ user/rsb/cross-canadian-cross.rst	(revision bb47f890c82595ba493a82aa860c6892a52e1e8c)
@@ -16,19 +16,19 @@
 ^^^^^^^^^^^^^^
 
-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:
@@ -43,7 +43,16 @@
 .. 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
Index: user/rsb/index.rst
===================================================================
--- user/rsb/index.rst	(revision 6185f6e635203117ce6fdde8f9dcff01c6c7bafd)
+++ user/rsb/index.rst	(revision bb47f890c82595ba493a82aa860c6892a52e1e8c)
@@ -7,13 +7,25 @@
 .. _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
@@ -22,13 +34,18 @@
 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.
 
-The RTEMS Source Builder has been tested on:
+.. sidebar:: Setting up your Host
+
+   See :ref:`QuickStartHost` for details on setting up hosts.
+
+The RTEMS Source Builder is known to work on:
 
 - ArchLinux
@@ -41,10 +58,7 @@
 - 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
@@ -53,5 +67,5 @@
 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
@@ -67,14 +81,4 @@
 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
 
@@ -84,11 +88,11 @@
 .. 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
Index: user/rsb/project-sets.rst
===================================================================
--- user/rsb/project-sets.rst	(revision 6185f6e635203117ce6fdde8f9dcff01c6c7bafd)
+++ user/rsb/project-sets.rst	(revision bb47f890c82595ba493a82aa860c6892a52e1e8c)
@@ -8,20 +8,19 @@
 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
@@ -39,5 +38,5 @@
 ^^^^^^^^^^
 
-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
@@ -82,9 +81,10 @@
 ^^^^^
 
-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
@@ -92,67 +92,17 @@
 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,4 +116,14 @@
 ``--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
@@ -184,22 +144,16 @@
 can be added.
 
-Patches for packages developed by the RTEMS project can be placed in the RTEMS
-Tools Git repository. The ``tools`` directory in the repository has various
-places a patch can live. The tree is broken down in RTEMS releases and then
-tools within that release. If the package is not specific to any release the
-patch can be added closer to the top under the package's name. Patches to fix
-specific tool related issues for a specific architecture should be grouped
-under the specific architecture and only applied when building that
-architecture avoiding a patch breaking an uneffected architecture.
-
-Patches in the RTEMS Tools repository need to be submitted to the upstream
-project. It should not be a clearing house for patches that will not be
-accepted upstream.
+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.
+
+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
@@ -227,13 +181,13 @@
 .. code-block:: spec
 
-    %hash md5 <1> gdb-sim-lm32uart.diff <2> 77d070878112783292461bd6e7db17fb <3>
-
-.. topic:: Items:
-
-  1. The type of checksum, in the case an MD5 hash.
+    %hash sha512 <1> gdb-sim-lm32uart.diff <2> 77d07087 ... e7db17fb <3>
+
+.. topic:: Items:
+
+  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
Index: user/rsb/third-party-packages.rst
===================================================================
--- user/rsb/third-party-packages.rst	(revision 6185f6e635203117ce6fdde8f9dcff01c6c7bafd)
+++ user/rsb/third-party-packages.rst	(revision bb47f890c82595ba493a82aa860c6892a52e1e8c)
@@ -3,6 +3,6 @@
 .. 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
@@ -10,14 +10,20 @@
 
 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).
-
-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.
+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.
+
+.. 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
@@ -26,7 +32,8 @@
 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
@@ -35,93 +42,270 @@
 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::
@@ -135,37 +319,30 @@
 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``:
-
-.. code-block:: spec
-
-    #
-    # NetSNMP 5.7.2.1
-    #
-    %if %{release} == %{nil}
-     %define release 1    <1>
-    %endif
-
-    %include %{_configdir}/rtems-bsp.cfg   <2>
-
-    #
-    # NetSNMP Version
-    #
-    %define net_snmp_version 5.7.2.1   <3>
-
-    #
-    # We need some special flags to build this version.
-    #
-    %define net_snmp_cflags <4> -DNETSNMP_CAN_USE_SYSCTL=1 -DARP_SCAN_FOUR_ARGUMENTS=1 -DINP_IPV6=0
-
-    #
-    # Patch for RTEMS support.
-    #
-    %patch add net-snmp %{rtems_git_tools}/net-snmp/rtems-net-snmp-5.7.2.1-20140623.patch <5>
-
-    #
-    # NetSNMP Build configuration
-    #
-    %include %{_configdir}/net-snmp-5-1.cfg   <6>
+RTEMS version specific configuration file. For example the Curl configuration
+file ``rtems/config/curl/curl-7.65.1-1.cfg``:
+
+.. code-block:: spec
+
+ #
+ # Curl 7.65.1
+ #
+
+ %if %{release} == %{nil}
+  %define release 1  <1>
+ %endif
+
+ %include %{_configdir}/rtems-bsp.cfg   <2>
+
+ #
+ # Curl Version
+ #
+ %define curl_version 7.65.1   <3>
+
+ %hash sha512 curl-%{curl_version}.tar.xz aba2d979a...72b6ac55df4   <4>
+
+ #
+ # Curl Build configuration
+ #
+ %include %{_configdir}/curl-1.cfg <5>
 
 .. topic:: Items:
@@ -175,52 +352,91 @@
   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.
-
-  5. The RTEMS Net-SNMP patch downloaded from the RTEMS Tools git repo.
-
-  6. The Net-SNMP standard build configuration.
+  3. The Curl package's version.
+
+  4. The SHA512 hash for the source file. The hash here has been shortened.
+
+  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:
-
-.. code-block:: spec
-
-    %if %{_host} == %{nil} <1>
-     %error No RTEMS target specified: --host=host
-    %endif
-
-    %ifn %{defined with_rtems_bsp} <2>
-     %error No RTEMS BSP specified: --with-rtems-bsp=bsp
-    %endif
-
-    %ifn %{defined with_tools} <3>
-     %define with_tools %{_prefix}
-    %endif
-
-    #
-    # Set the path to the tools.
-    #
-    %{path prepend %{with_tools}/bin} <4>
-
-.. topic:: Items:
-
-  1. Check the host has been set.
-
-  2. Check a BSP has been specified.
-
-  3. If no tools path has been provided assume they are under the
-     ``%{_prefix}``.
-
-  4. Add the tools ``bin`` path to the system path.
-
-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``):
+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
+
+ #
+ # The target is used by compilers or Cxc builds.
+ #
+ %if %{_target} != %{nil}
+  %error RTEMS BSP builds use --host and not --target
+ %endif
+
+A host is required using the ``--host`` option:
+
+.. code-block:: spec
+
+ #
+ # 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
+
+An RTEMS BSP is required using the ``--with-bsp`` option:
+
+.. code-block:: spec
+
+ #
+ # 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
+
+Check if the ``--with-tools`` or ``--with-rtems`` options have been provided
+and if they are not provided use the ``--prefix`` path:
+
+.. code-block:: spec
+
+ #
+ # If no tools or RTEMS provided use the prefix.
+ #
+ %ifn %{defined with_tools}
+  %define with_tools %{_prefix}
+ %endif
+
+ %ifn %{defined with_rtems}
+  %define with_rtems %{_prefix}
+ %endif
+
+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
@@ -243,15 +459,15 @@
   1. Set the path to the BSP's pkgconfig file.
 
-  2. Let pkgconfig know this is a cross-compile build.
-
-  3. Filter flags such as warnings. Warning flags are specific to a package.
-
-  4. Ask pkgconfig for the various items 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``):
+  2. Let *pkgconfig* know this is a cross-compile build.
+
+  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 settings we require.
+
+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
@@ -264,7 +480,7 @@
 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
@@ -292,13 +508,12 @@
 .. 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``):
-
-.. code-block:: spec
-
-      ../${source_dir_ntp}/configure \ <1>
+provide sensible default or in this case map them to the BSP:
+
+.. code-block:: spec
+
+      ../${source_dir_curl}/configure \ <1>
         --host=%{_host} \
         --prefix=%{_prefix} \
@@ -310,16 +525,92 @@
         --mandir=%{_mandir} \
         --infodir=%{_infodir} \
-        --datadir=%{_datadir} \
-        --disable-ipv6 \
-        --disable-HOPFPCI
+        --datadir=%{_datadir}
 
 .. topic:: Items:
 
-  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
-being used needs to be built with the same flags.
+  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``.
+
+``%{_host_arch}``:
+ The host architecture extracted from the ``--host`` command line option. For
+ example the architecture for the host of ``arm-rtems5`` is ``arm``.
+
+``%{_host_cpu}``:
+ The host cpu extracted from the ``--host`` command line option. For
+ example the cpu for the host of ``arm-rtems5`` is ``arm``.
Index: user/start/prefixes.rst
===================================================================
--- user/start/prefixes.rst	(revision 6185f6e635203117ce6fdde8f9dcff01c6c7bafd)
+++ user/start/prefixes.rst	(revision bb47f890c82595ba493a82aa860c6892a52e1e8c)
@@ -21,12 +21,19 @@
 :file:`/usr/local` on FreeBSD and Linux.
 
-You have to select a prefix for your RTEMS tool suite installation.  The RTEMS
-tool suite consists of a cross tool chain (Binutils, GCC, GDB, Newlib, etc.)
-for your target architecture and :ref:`other tools <HostTools>` provided by the
-RTEMS Project.  You build and install the tool suite with the
-:ref:`RTEMS Source Builder (RSB) <RSB>`.  By default, the RSB will start the
-prefix path with a host operating system specific path plus :file:`rtems` plus
-the RTEMS version, e.g.  :file:`/opt/rtems/5` on Linux and
-:file:`/usr/local/rtems/5` on FreeBSD and macOS.
+You have to select a prefix for your installation. You will build and install
+the RTEMS tool suite, an RTEMS kernel for a BSP and you may build and install
+third party libraries. You can build them all as a stack with a single prefix
+or you can
+
+The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB,
+Newlib, etc.)  for your target architecture and :ref:`other tools <HostTools>`
+provided by the RTEMS Project. The RTEMS
+
+
+You build and install the tool suite with the :ref:`RTEMS Source Builder (RSB)
+<RSB>`.  By default, the RSB will start the prefix path with a host operating
+system specific path plus :file:`rtems` plus the RTEMS version, e.g.
+:file:`/opt/rtems/5` on Linux and :file:`/usr/local/rtems/5` on FreeBSD and
+macOS.
 
 It is strongly recommended to run the RSB as a *normal user* and not with
