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

1 files changed, 463 insertions, 172 deletions

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