Merge duplicative RSB Quick Start into Users Guide

8 files changed, 312 insertions, 558 deletions

diff --git a/rsb/building-tools-and-rtems.rst b/rsb/building-tools-and-rtems.rst
new file mode 100644
index 0000000..5fd5d78
--- /dev/null
+++ b/rsb/building-tools-and-rtems.rst
@@ -0,0 +1,38 @@
+.. comment SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. comment COPYRIGHT (c) 2012 - 2016, 2018.
+.. comment Chris Johns <chrisj@rtems.org>
+
+Building Tools and RTEMS
+========================
+
+The Quick Start section of the RTEMS Users Guide covers the typical
+information and process needed to build both an RTEMS toolset and
+RTEMS itself. This section has information on specific configuration
+options that may be needed.
+
+Controlling the Build
+---------------------
+
+Build sets can be controlled via the command line to enable and disable various
+features. There is no definitive list of build options that can be listed
+because they are implemented with the configuration scripts. The best way to
+find what is available is to grep the configuration files. for ``with`` and
+``without``.
+
+Following are currently available:
+
+``--without-rtems``
+  Do not build RTEMS when building an RTEMS build set.
+
+``--without-cxx``
+  Do not build a C++ compiler.
+
+``--with-ada``
+  Attempt to build an Ada compiler.  You need a native GNAT installed.
+
+``--with-fortran``
+  Attempt to build a Fortran compiler.
+
+``--with-objc``
+  Attempt to build a C++ compiler.
diff --git a/rsb/index.rst b/rsb/index.rst
index 7b64945..36e0883 100644
--- a/rsb/index.rst
+++ b/rsb/index.rst
@@ -53,7 +53,7 @@ Table of Contents
 	:numbered:
 
         source-builder
-	quick-start
+        building-tools-and-rtems.rst
 	hosts
 	project-sets
 	cross-canadian-cross
diff --git a/rsb/quick-start.rst b/rsb/quick-start.rst
deleted file mode 100644
index 16102f7..0000000
--- a/rsb/quick-start.rst
+++ /dev/null
@@ -1,535 +0,0 @@
-.. comment SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. comment COPYRIGHT (c) 2012 - 2016.
-.. comment Chris Johns <chrisj@rtems.org>
-
-Quick Start
-===========
-
-The quick start will show you how to build a set of RTEMS tools for a supported
-architecture. The tools are installed into a build *prefix*. The *prefix* is the
-top of a group of directories containing all the files needed to develop RTEMS
-applications. Building an RTEMS build set will build all that you need. This
-includes autoconf, automake, assemblers, linkers, compilers, debuggers,
-standard libraries and RTEMS itself.
-
-There is no need to become root or the administrator and we recommend you
-avoid doing this. You can build and install the tools anywhere on the
-host's file system you, as a standard user, have read and write access
-too. I recommend you use your home directory and work under the directory
-``~/development/rtems``. The examples shown here will do this.
-
-You can use the build *prefix* to install and maintain different versions of
-the tools. Doing this lets you try a new set of tools while not touching your
-proven working production set of tools. Once you have proven the new tools are
-working rebuild with the *production* prefix switching your development to them.
-
-We recommend you keep your environment to the bare minimum, particularly the
-path variable. Using environment variables has been proven over the years to be
-difficult to manage in production systems.
-
-.. warning::
-
-    The RSB assumes your host is set up and the needed packages are installed
-    and configured to work. If your host has not been set up please refer to
-    :ref:`Hosts` and your host's section for packages you need to install.
-
-.. topic:: Path to use when building applications:
-
-    Do not forget to set the path before you use the tools, for example to
-    build the RTEMS kernel.
-
-    The RSB by default will install (copy) the executables to a directory tree
-    under the *prefix* you supply. To use the tools once finished just set your
-    path to the ``bin`` directory under the *prefix* you use. In the examples
-    that follow the *prefix* is ``$HOME/development/rtems/4.11`` and is set
-    using the ``--prefix`` option so the path you need to configure to build
-    applications can be set with the following in a BASH shell:
-
-    .. code-block:: shell
-
-      $ export PATH=$HOME/development/rtems/4.11/bin:$PATH
-
-    Make sure you place the RTEMS tool path at the front of your path so they
-    are searched first. RTEMS can provide newer versions of some tools your
-    operating system provides and placing the RTEMS tools path at the front
-    means it is searched first and the RTEMS needed versions of the tools are
-    used.
-
-.. note::
-
-    RSB and RTEMS have a matching *git branch* for each version of RTEMS. For
-    example, if you want to build a toolchain for 4.11, then you should
-    checkout the 4.11 branch of the RSB:
-
-    .. code-block:: shell
-
-      $ git checkout -t origin/4.11
-
-    Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
-
-Setup
------
-
-Setup a development work space::
-
-    $ cd
-    $ mkdir -p development/rtems/src
-    $ cd development/rtems/src
-
-The RTEMS Source Builder is distributed as source. It is Python code so all you
-need to do is download the release's RSB tarball or clone the code directly
-from the RTEMS GIT repository::
-
-    $ git clone git://git.rtems.org/rtems-source-builder.git
-    $ cd rtems-source-builder
-
-.. topic:: Workspaces
-
-   The examples in the *Quick Start Guide* build and install tools in your
-   *home* directory. Please refer to the RTEMS User Manual for more detail
-   about *Sandboxing* and the *prefix*.
-
-Checking
---------
-
-The next step is to check if your host is set up correctly. The RTEMS Source
-Builder provides a tool to help::
-
-    $ source-builder/sb-check
-    warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
-    warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
-    error: exe: not found: (_xz) /usr/local/bin/xz    <2>
-    RTEMS Source Builder environment is not correctly set up
-    $ source-builder/sb-check
-    RTEMS Source Builder environment is ok   <3>
-
-.. topic:: Items:
-
-  1. A tool is in the environment path but it does not match the expected path.
-
-  2. The executable ``xz`` is not found.
-
-  3. The host's environment is set up correct.
-
-The checking tool will output a list of executable files not found if problems
-are detected. Locate those executable files and install them. You may also be
-given a list of warnings about executable files not in the expected location
-however the executable was located somewhere in your environment's path. You
-will need to check each tool to determine if this is an issue. An executable
-not in the standard location may indicate it is not the host operating system's
-standard tool. It maybe ok or it could be buggy, only you can determine this.
-
-The :ref:`Hosts` section lists packages you should install for common host
-operating systems. It maybe worth checking if you have those installed.
-
-Build Sets
-----------
-
-The RTEMS tools can be built within the RTEMS Source Builder's source tree. We
-recommend you do this so lets change into the RTEMS directory in the RTEMS
-Source Builder package::
-
-    $ cd rtems
-
-If you are unsure how to specify the build set for the architecture you wish to
-build ask the tool::
-
-    $ ../source-builder/sb-set-builder --list-bsets   <1>
-    RTEMS Source Builder - Set Builder, v4.11.0
-    Examining: config
-    Examining: ../source-builder/config    <2>
-        4.10/rtems-all.bset      <3>
-        4.10/rtems-arm.bset      <4>
-        4.10/rtems-autotools.bset
-        4.10/rtems-avr.bset
-        4.10/rtems-bfin.bset
-        4.10/rtems-h8300.bset
-        4.10/rtems-i386.bset
-        4.10/rtems-lm32.bset
-        4.10/rtems-m32c.bset
-        4.10/rtems-m32r.bset
-        4.10/rtems-m68k.bset
-        4.10/rtems-mips.bset
-        4.10/rtems-nios2.bset
-        4.10/rtems-powerpc.bset
-        4.10/rtems-sh.bset
-        4.10/rtems-sparc.bset
-        4.11/rtems-all.bset
-        4.11/rtems-arm.bset
-        4.11/rtems-autotools.bset
-        4.11/rtems-avr.bset
-        4.11/rtems-bfin.bset
-        4.11/rtems-h8300.bset
-        4.11/rtems-i386.bset
-        4.11/rtems-lm32.bset
-        4.11/rtems-m32c.bset
-        4.11/rtems-m32r.bset
-        4.11/rtems-m68k.bset
-        4.11/rtems-microblaze.bset
-        4.11/rtems-mips.bset
-        4.11/rtems-moxie.bset
-        4.11/rtems-nios2.bset
-        4.11/rtems-powerpc.bset
-        4.11/rtems-sh.bset
-        4.11/rtems-sparc.bset
-        4.11/rtems-sparc64.bset
-        4.11/rtems-v850.bset
-        4.9/rtems-all.bset
-        4.9/rtems-arm.bset
-        4.9/rtems-autotools.bset
-        4.9/rtems-i386.bset
-        4.9/rtems-m68k.bset
-        4.9/rtems-mips.bset
-        4.9/rtems-powerpc.bset
-        4.9/rtems-sparc.bset
-        gnu-tools-4.6.bset
-        rtems-4.10-base.bset    <5>
-        rtems-4.11-base.bset
-        rtems-4.9-base.bset
-        rtems-base.bset         <5>
-
-.. topic:: Items:
-
-  1. Only option required is ``--list-bsets``
-
-  2. The paths inspected. See :ref:`Configuration`.
-
-  3. A build set to build all RTEMS 4.10 supported architectures.
-
-  4. The build set for the ARM architecture on RTEMS 4.10.
-
-  5. Support build set file with common functionality included by other build
-     set files.
-
-Building
---------
-
-The quick start builds a SPARC tool set::
-
-    $ ../source-builder/sb-set-builder --log=l-sparc.txt \   <1>
-          --prefix=$HOME/development/rtems/4.11 \       <2>
-          4.11/rtems-sparc           <3>
-    Source Builder - Set Builder, v0.2.0
-    Build Set: 4.11/rtems-sparc
-    config: expat-2.1.0-1.cfg        <4>
-    package: expat-2.1.0-x86_64-freebsd9.1-1
-    building: expat-2.1.0-x86_64-freebsd9.1-1
-    config: tools/rtems-binutils-2.22-1.cfg        <5>
-    package: sparc-rtems4.11-binutils-2.22-1
-    building: sparc-rtems4.11-binutils-2.22-1
-    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg   <6>
-    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    config: tools/rtems-gdb-7.5.1-1.cfg      <7>
-    package: sparc-rtems4.11-gdb-7.5.1-1
-    building: sparc-rtems4.11-gdb-7.5.1-1
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <8>
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
-    cleaning: expat-2.1.0-x86_64-freebsd9.1-1     <9>
-    cleaning: sparc-rtems4.11-binutils-2.22-1
-    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    cleaning: sparc-rtems4.11-gdb-7.5.1-1
-    Build Set: Time 0:13:43.616383        <10>
-
-.. topic:: Items
-
-  1. Providing a log file redirects the build output into a file. Logging the
-     build output provides a simple way to report problems.
-
-  2. The prefix is the location on your file system the tools are installed
-     into. Provide a prefix to a location you have read and write access. You
-     can use the prefix to install different versions or builds of tools. Just
-     use the path to the tools you want to use when building RTEMS.
-
-  3. The build set. This is the SPARC build set. First a specifically
-     referenced file is checked for and if not found the ``%{_configdir}`` path
-     is searched. The set builder will first look for files with a ``.bset``
-     extension and then for a configuration file with a ``.cfg`` extension.
-
-  4. The SPARC build set first builds the expat library as it is used in GDB.
-     This is the expat configuration used.
-
-  5. The binutils build configuration.
-
-  6. The GCC and Newlib build configuration.
-
-  7. The GDB build configuration.
-
-  8. Installing the built packages to the install prefix.
-
-  9. All the packages built are cleaned at the end. If the build fails all the
-     needed files are present. You may have to clean up by deleting the build
-     directory if the build fails.
-
-  10. The time to build the package. This lets you see how different host
-      hardware or configurations perform.
-
-Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and
-RTEMS applications. When the build runs you will notice the tool fetch the
-source code from the internet. These files are cached in directies called
-``source`` and ``patches``. If you run the build again the cached files are
-used. This is what happened in the shown example. Archiving these directories
-archives the source you need to recreate the build.
-
-.. topic:: RTEMS Releases
-
-  The RSB found in a release will automatically build and install RTEMS. If you
-  do not want a released version of the RSB to build RTEMS add
-  ``--without-rtems`` to the command line. The development version requires
-  adding ``--with-rtems`` to build RTEMS. Use this option to create a single
-  command to build the tools and RTEMS.
-
-  The source used in release builds is downloaded from the RTEMS FTP
-  server. This ensures the source is always available for a release.
-
-The installed tools::
-
-    $ ls $HOME/development/rtems/4.11
-    bin         include     lib         libexec     share       sparc-rtems4.11
-    $ ls $HOME/development/rtems/4.11/bin
-    sparc-rtems4.11-addr2line       sparc-rtems4.11-cpp
-    sparc-rtems4.11-gcc-ar          sparc-rtems4.11-gprof
-    sparc-rtems4.11-objdump         sparc-rtems4.11-size
-    sparc-rtems4.11-ar              sparc-rtems4.11-elfedit
-    sparc-rtems4.11-gcc-nm          sparc-rtems4.11-ld
-    sparc-rtems4.11-ranlib          sparc-rtems4.11-strings
-    sparc-rtems4.11-as              sparc-rtems4.11-g++
-    sparc-rtems4.11-gcc-ranlib      sparc-rtems4.11-ld.bfd
-    sparc-rtems4.11-readelf         sparc-rtems4.11-strip
-    sparc-rtems4.11-c++             sparc-rtems4.11-gcc
-    sparc-rtems4.11-gcov            sparc-rtems4.11-nm
-    sparc-rtems4.11-run             xmlwf
-    sparc-rtems4.11-c++filt         sparc-rtems4.11-gcc-4.7.2
-    sparc-rtems4.11-gdb             sparc-rtems4.11-objcopy
-    sparc-rtems4.11-sis
-    $ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v
-    Using built-in specs.
-    COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc
-    COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \
-    libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper
-    Target: sparc-rtems4.11                         <1>
-    Configured with: ../gcc-4.7.2/configure         <2>
-    --prefix=/home/chris/development/rtems/4.11
-    --bindir=/home/chris/development/rtems/4.11/bin
-    --exec_prefix=/home/chris/development/rtems/4.11
-    --includedir=/home/chris/development/rtems/4.11/include
-    --libdir=/home/chris/development/rtems/4.11/lib
-    --libexecdir=/home/chris/development/rtems/4.11/libexec
-    --mandir=/home/chris/development/rtems/4.11/share/man
-    --infodir=/home/chris/development/rtems/4.11/share/info
-    --datadir=/home/chris/development/rtems/4.11/share
-    --build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11
-    --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib
-    --with-system-zlib --disable-nls --without-included-gettext
-    --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto
-    --enable-threads --enable-plugin --enable-newlib-io-c99-formats
-    --enable-newlib-iconv --enable-languages=c,c++
-    Thread model: rtems             <3>
-    gcc version 4.7.2 20120920      <4>
-     (RTEMS 4.11 RSB cb12e4875c203f794a5cd4b3de36101ff9a88403)-1 newlib 2.0.0) (GCC)
-
-.. topic:: Items
-
-  1. The target the compiler is built for.
-
-  2. The configure options used to build GCC.
-
-  3. The threading model is always RTEMS. This makes using the RTEMS tools for
-     bare metal development more difficult.
-
-  4. The version string. It contains the Git hash of the RTEMS Source Builder
-     you are using. If your local clone has been modifed that state is also
-     recorded in the version string. The hash allows you to track from a GCC
-     executable back to the original source used to build it.
-
-.. note::
-
-   The RTEMS thread model enables specific hooks in GCC so applications built
-   with RTEMS tools need the RTEMS runtime to operate correctly. You can use
-   RTEMS tools to build bare metal component but it is more difficult than with
-   a bare metal tool chain and you need to know what you are doing at a low
-   level. The RTEMS Source Builder can build bare metal tool chains as
-   well. Look in the top level ``bare`` directory.
-
-Deployment
-----------
-
-If you wish to create and distribute your build or you want to archive a build
-you can create a tar file. We term this deploying a build. This is a more
-advanced method for binary packaging and installing of tools.
-
-By default the RTEMS Source Builder installs the built packages directly and
-optionally it can also create a *build set tar file* or a *package tar file*
-per package built. The normal and default behaviour is to let the RTEMS Source
-Builder install the tools. The source will be downloaded, built, installed and
-cleaned up.
-
-The tar files are created with the full build prefix present and if you follow
-the examples given in this documentation the path is absolute. This can cause
-problems if you are installing on a host you do not have super user or
-administrator rights on because the prefix path may references part you do not
-have write access too and tar will not extract the files. You can use the
-``--strip-components`` option in tar if your host tar application supports it
-to remove the parts you do not have write access too or you may need to unpack
-the tar file somewhere and copy the file tree from the level you have write
-access from. Embedding the full prefix path in the tar files lets you know what
-the prefix is and is recommended. For example if
-``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
-directory to the root (``/``) and untar the file because the ``/home`` is root
-access only. To install a tar file you have downloaded into your new machine's
-``Downloads`` directory in your home directoty you would enter:
-
-.. code-block:: shell
-
-    $ cd /somewhere
-    $ tar --strip-components=3 -xjf \
-          $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
-
-A build set tar file is created by adding ``--bset-tar-file`` option to the
-``sb-set-builder`` command::
-
-    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
-             --prefix=$HOME/development/rtems/4.11 \
-             --bset-tar-file \     <1>
-             4.11/rtems-sparc
-    Source Builder - Set Builder, v0.2.0
-    Build Set: 4.11/rtems-sparc
-    config: expat-2.1.0-1.cfg
-    package: expat-2.1.0-x86_64-freebsd9.1-1
-    building: expat-2.1.0-x86_64-freebsd9.1-1
-    config: tools/rtems-binutils-2.22-1.cfg
-    package: sparc-rtems4.11-binutils-2.22-1
-    building: sparc-rtems4.11-binutils-2.22-1
-    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
-    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    config: tools/rtems-gdb-7.5.1-1.cfg
-    package: sparc-rtems4.11-gdb-7.5.1-1
-    building: sparc-rtems4.11-gdb-7.5.1-1
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
-    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
-    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2      <3>
-    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
-    cleaning: sparc-rtems4.11-binutils-2.22-1
-    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    cleaning: sparc-rtems4.11-gdb-7.5.1-1
-    Build Set: Time 0:15:25.92873
-
-.. topic:: Items
-
-  1. The option to create a build set tar file.
-
-  2. The installation still happens unless you specify ``--no-install``.
-
-  3. Creating the build set tar file.
-
-You can also suppress installing the files using the ``--no-install``
-option. This is useful if your prefix is not accessiable, for example when
-building Canadian cross compiled tool sets::
-
-    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
-                --prefix=$HOME/development/rtems/4.11 \
-                --bset-tar-file \
-                --no-install \      <1>
-                4.11/rtems-sparc
-    Source Builder - Set Builder, v0.2.0
-    Build Set: 4.11/rtems-sparc
-    config: expat-2.1.0-1.cfg
-    package: expat-2.1.0-x86_64-freebsd9.1-1
-    building: expat-2.1.0-x86_64-freebsd9.1-1
-    config: tools/rtems-binutils-2.22-1.cfg
-    package: sparc-rtems4.11-binutils-2.22-1
-    building: sparc-rtems4.11-binutils-2.22-1
-    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
-    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    config: tools/rtems-gdb-7.5.1-1.cfg
-    package: sparc-rtems4.11-gdb-7.5.1-1
-    building: sparc-rtems4.11-gdb-7.5.1-1
-    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2    <2>
-    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
-    cleaning: sparc-rtems4.11-binutils-2.22-1
-    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    cleaning: sparc-rtems4.11-gdb-7.5.1-1
-    Build Set: Time 0:14:11.721274
-    $ ls tar
-    rtems-4.11-sparc-rtems4.11-1.tar.bz2
-
-.. topic:: Items
-
-  1. The option to supressing installing the packages.
-
-  2. Create the build set tar.
-
-A package tar file can be created by adding the ``--pkg-tar-files`` to the
-``sb-set-builder`` command. This creates a tar file per package built in the
-build set::
-
-    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
-            --prefix=$HOME/development/rtems/4.11 \
-            --bset-tar-file \
-            --pkg-tar-files \        <1>
-            --no-install 4.11/rtems-sparc
-    Source Builder - Set Builder, v0.2.0
-    Build Set: 4.11/rtems-sparc
-    config: expat-2.1.0-1.cfg
-    package: expat-2.1.0-x86_64-freebsd9.1-1
-    building: expat-2.1.0-x86_64-freebsd9.1-1
-    config: tools/rtems-binutils-2.22-1.cfg
-    package: sparc-rtems4.11-binutils-2.22-1
-    building: sparc-rtems4.11-binutils-2.22-1
-    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
-    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    config: tools/rtems-gdb-7.5.1-1.cfg
-    package: sparc-rtems4.11-gdb-7.5.1-1
-    building: sparc-rtems4.11-gdb-7.5.1-1
-    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
-    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
-    cleaning: sparc-rtems4.11-binutils-2.22-1
-    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
-    cleaning: sparc-rtems4.11-gdb-7.5.1-1
-    Build Set: Time 0:14:37.658460
-    $ ls tar
-    expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
-    sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
-    sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
-
-.. topic:: Items
-
-  1. The option to create packages tar files.
-
-  2. The GDB package tar file.
-
-  3. The build set tar file. All the others in a single tar file.
-
-Controlling the Build
----------------------
-
-Build sets can be controlled via the command line to enable and disable various
-features. There is no definitive list of build options that can be listed
-because they are implemented with the configuration scripts. The best way to
-find what is available is to grep the configuration files. for ``with`` and
-``without``.
-
-Following are currently available:
-
-``--without-rtems``
-  Do not build RTEMS when building an RTEMS build set.
-
-``--without-cxx``
-  Do not build a C++ compiler.
-
-``--with-ada``
-  Attempt to build an Ada compiler.  You need a native GNAT installed.
-
-``--with-fortran``
-  Attempt to build a Fortran compiler.
-
-``--with-objc``
-  Attempt to build a C++ compiler.
diff --git a/rsb/source-builder.rst b/rsb/source-builder.rst
index ef5ba61..7e81244 100644
--- a/rsb/source-builder.rst
+++ b/rsb/source-builder.rst
@@ -66,10 +66,11 @@ 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. New users can follow the Quick Start section up to the "Installing
-and Tar Files" to get a working tools and RTEMS. 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
+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
@@ -154,3 +155,31 @@ The *SpecBuilder* tool did not build tools or packages unrelated to the RTEMS
 Project where no suitable *spec* file was available so another tool was
 needed. Rather than start again Chris decided to take the parsing code for the
 *spec* file format and build a new tool called the RTEMS Source Builder.
+
+Controlling the Tools Build
+---------------------------
+
+Build sets can be controlled via the command line to enable and disable various
+features. There is no definitive list of build options that can be listed
+because they are implemented with the configuration scripts. The best way to
+find what is available is to grep the configuration files. for ``with`` and
+``without``.
+
+Following are currently available:
+
+``--without-rtems``
+  Do not build RTEMS when building an RTEMS build set.
+
+``--without-cxx``
+  Do not build a C++ compiler.
+
+``--with-ada``
+  Attempt to build an Ada compiler.  You need a native GNAT installed.
+
+``--with-fortran``
+  Attempt to build a Fortran compiler.
+
+``--with-objc``
+  Attempt to build a C++ compiler.
+
+
diff --git a/user/ecosys/index.rst b/user/ecosys/index.rst
index 1e9ee12..1ea97df 100644
--- a/user/ecosys/index.rst
+++ b/user/ecosys/index.rst
@@ -85,3 +85,159 @@ to create personalised development environments. The RTEMS Project does not
 provide packaging and deployment for a specific host environment, target
 architecture or BSP. The RTEMS Project encourages users and organizations to
 fill this role for the community.
+
+Building and Deploying Tool Binaries
+------------------------------------
+
+If you wish to create and distribute your build or you want to archive a build
+you can create a tar file. We term this deploying a build. This is a more
+advanced method for binary packaging and installing of tools.
+
+By default the RTEMS Source Builder installs the built packages directly and
+optionally it can also create a *build set tar file* or a *package tar file*
+per package built. The normal and default behaviour is to let the RTEMS Source
+Builder install the tools. The source will be downloaded, built, installed and
+cleaned up.
+
+The tar files are created with the full build prefix present and if you follow
+the examples given in this documentation the path is absolute. This can cause
+problems if you are installing on a host you do not have super user or
+administrator rights on because the prefix path may references part you do not
+have write access too and tar will not extract the files. You can use the
+``--strip-components`` option in tar if your host tar application supports it
+to remove the parts you do not have write access too or you may need to unpack
+the tar file somewhere and copy the file tree from the level you have write
+access from. Embedding the full prefix path in the tar files lets you know what
+the prefix is and is recommended. For example if
+``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
+directory to the root (``/``) and untar the file because the ``/home`` is root
+access only. To install a tar file you have downloaded into your new machine's
+``Downloads`` directory in your home directoty you would enter:
+
+.. code-block:: shell
+
+    $ cd /somewhere
+    $ tar --strip-components=3 -xjf \
+          $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2
+
+A build set tar file is created by adding ``--bset-tar-file`` option to the
+``sb-set-builder`` command::
+
+    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+             --prefix=$HOME/development/rtems/4.11 \
+             --bset-tar-file \     <1>
+             4.11/rtems-sparc
+    Source Builder - Set Builder, v0.2.0
+    Build Set: 4.11/rtems-sparc
+    config: expat-2.1.0-1.cfg
+    package: expat-2.1.0-x86_64-freebsd9.1-1
+    building: expat-2.1.0-x86_64-freebsd9.1-1
+    config: tools/rtems-binutils-2.22-1.cfg
+    package: sparc-rtems4.11-binutils-2.22-1
+    building: sparc-rtems4.11-binutils-2.22-1
+    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    config: tools/rtems-gdb-7.5.1-1.cfg
+    package: sparc-rtems4.11-gdb-7.5.1-1
+    building: sparc-rtems4.11-gdb-7.5.1-1
+    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
+    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
+    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2      <3>
+    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+    cleaning: sparc-rtems4.11-binutils-2.22-1
+    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    cleaning: sparc-rtems4.11-gdb-7.5.1-1
+    Build Set: Time 0:15:25.92873
+
+.. topic:: Items
+
+  1. The option to create a build set tar file.
+
+  2. The installation still happens unless you specify ``--no-install``.
+
+  3. Creating the build set tar file.
+
+You can also suppress installing the files using the ``--no-install``
+option. This is useful if your prefix is not accessiable, for example when
+building Canadian cross compiled tool sets::
+
+    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+                --prefix=$HOME/development/rtems/4.11 \
+                --bset-tar-file \
+                --no-install \      <1>
+                4.11/rtems-sparc
+    Source Builder - Set Builder, v0.2.0
+    Build Set: 4.11/rtems-sparc
+    config: expat-2.1.0-1.cfg
+    package: expat-2.1.0-x86_64-freebsd9.1-1
+    building: expat-2.1.0-x86_64-freebsd9.1-1
+    config: tools/rtems-binutils-2.22-1.cfg
+    package: sparc-rtems4.11-binutils-2.22-1
+    building: sparc-rtems4.11-binutils-2.22-1
+    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    config: tools/rtems-gdb-7.5.1-1.cfg
+    package: sparc-rtems4.11-gdb-7.5.1-1
+    building: sparc-rtems4.11-gdb-7.5.1-1
+    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2    <2>
+    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+    cleaning: sparc-rtems4.11-binutils-2.22-1
+    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    cleaning: sparc-rtems4.11-gdb-7.5.1-1
+    Build Set: Time 0:14:11.721274
+    $ ls tar
+    rtems-4.11-sparc-rtems4.11-1.tar.bz2
+
+.. topic:: Items
+
+  1. The option to supressing installing the packages.
+
+  2. Create the build set tar.
+
+A package tar file can be created by adding the ``--pkg-tar-files`` to the
+``sb-set-builder`` command. This creates a tar file per package built in the
+build set::
+
+    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
+            --prefix=$HOME/development/rtems/4.11 \
+            --bset-tar-file \
+            --pkg-tar-files \        <1>
+            --no-install 4.11/rtems-sparc
+    Source Builder - Set Builder, v0.2.0
+    Build Set: 4.11/rtems-sparc
+    config: expat-2.1.0-1.cfg
+    package: expat-2.1.0-x86_64-freebsd9.1-1
+    building: expat-2.1.0-x86_64-freebsd9.1-1
+    config: tools/rtems-binutils-2.22-1.cfg
+    package: sparc-rtems4.11-binutils-2.22-1
+    building: sparc-rtems4.11-binutils-2.22-1
+    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
+    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    config: tools/rtems-gdb-7.5.1-1.cfg
+    package: sparc-rtems4.11-gdb-7.5.1-1
+    building: sparc-rtems4.11-gdb-7.5.1-1
+    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
+    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
+    cleaning: sparc-rtems4.11-binutils-2.22-1
+    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
+    cleaning: sparc-rtems4.11-gdb-7.5.1-1
+    Build Set: Time 0:14:37.658460
+    $ ls tar
+    expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
+    sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
+    sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2
+
+.. topic:: Items
+
+  1. The option to create packages tar files.
+
+  2. The GDB package tar file.
+
+  3. The build set tar file. All the others in a single tar file.
+
+
diff --git a/user/hosts/os.rst b/user/hosts/os.rst
index a120ec2..82ff4de 100644
--- a/user/hosts/os.rst
+++ b/user/hosts/os.rst
@@ -30,3 +30,48 @@ most features on Windows are supported but you are best to ask on the
 :r:list:`users` if you have a specific question.
 
 We recommend you maintain your operating system by installing any updates.
+
+We also recommend you keep your environment to the bare minimum,
+particularly the PATH variable. Using environment variables has been
+proven over the years to be difficult to manage in production systems.
+
+.. warning::
+
+    The RSB assumes your host is set up and the needed packages are installed
+    and configured to work. If your host has not been set up please refer to
+    :ref:`Hosts` and your host's section for packages you need to install.
+
+.. topic:: Path to use when building applications:
+
+    Do not forget to set the path before you use the tools, for example to
+    build the RTEMS kernel.
+
+    The RSB by default will install (copy) the executables to a directory tree
+    under the *prefix* you supply. To use the tools once finished just set your
+    path to the ``bin`` directory under the *prefix* you use. In the examples
+    that follow the *prefix* is ``$HOME/development/rtems/4.11`` and is set
+    using the ``--prefix`` option so the path you need to configure to build
+    applications can be set with the following in a BASH shell:
+
+    .. code-block:: shell
+
+      $ export PATH=$HOME/development/rtems/4.11/bin:$PATH
+
+    Make sure you place the RTEMS tool path at the front of your path so they
+    are searched first. RTEMS can provide newer versions of some tools your
+    operating system provides and placing the RTEMS tools path at the front
+    means it is searched first and the RTEMS needed versions of the tools are
+    used.
+
+.. note::
+
+    RSB and RTEMS have a matching *git branch* for each version of RTEMS. For
+    example, if you want to build a toolchain for 4.11, then you should
+    checkout the 4.11 branch of the RSB:
+
+    .. code-block:: shell
+
+      $ git checkout -t origin/4.11
+
+    Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.
+
diff --git a/user/installation/releases.rst b/user/installation/releases.rst
index c21326d..3860d74 100644
--- a/user/installation/releases.rst
+++ b/user/installation/releases.rst
@@ -48,8 +48,9 @@ shosted here. It has excellent internet access and performance.
 
 .. note:: **Controlling the RTEMS Kernel Build**
 
-   Building releases by default builds the RTEMS kernel. To not build the RTEMS
-   kernel add the ``--without-rtems`` option to the RSB command line.
+   Building releases by default does not build the RTEMS kernel. To
+   build the RTEMS kernel add the ``--with-rtems`` option to the RSB
+   command line.
 
    By default all the BSPs for an architecture are built. If you only wish to
    have a specific BSP built you can specify the BSP list by providing to the
@@ -284,4 +285,4 @@ discussed in :ref:`msys2_parallel_builds`.
  cleaning: sparc-rtems4.11-kernel-4.11.0-1
  Build Set: Time 0:19:15.713662
 
-You can now build a 3rd party library or an application as defailted in TBD.
+You can now build a 3rd party library or an application as defaulted in TBD.
diff --git a/user/start/index.rst b/user/start/index.rst
index f5e72ca..1016678 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -10,27 +10,47 @@ Quick Start
 
 The following is a quick start guide that provides a basic set of commands to
 build the RTEMS Tools and Kernel. The quick start guide provides links to the
-detailed sections if any problems are encoutnered.
+detailed sections if any problems are encountered.
 
-The detailed procedure for installing RTEMS can be found in
-:ref:`installation`.
+The detailed procedure for installing an RTEMS Workspace and installing
+all tools can be found in :ref:`installation`. This includes information
+on installation points, developer versions, and the RTEMS kernel.
 
-The development host computer needs to be set up for this quick start procedure
-to complete successfully. :ref:`host-computer` details what is needed for the
-supported host operating systems. If Windows is being used it is recommended
-following the procedure in :ref:`microsoft-windows` first.
+The short version of this procedure is as follows
+(:ref:`posix-host-tools-chain`):
+
+#. Create a workspace (:ref:`installation`),
+
+#. Download the RTEMS Source Builder (RSB),
+
+#. Build an RTEMS tool chain for a specific target architecture,
+
+#. Download RTEMS, and then
+
+#. Build RTEMS for a specific Board Support Package (BSP).
+
+Each of these steps is described in a section in this guide.
+
+Creating a Workspace
+====================
+
+Before beginning, the development host computer needs to be set up for
+this quick start procedure to complete successfully. :ref:`host-computer`
+details what is needed for the supported host operating systems. If
+Windows is being used it is recommended following the procedure in
+:ref:`microsoft-windows` first.
 
 There are many ways and locations a suitable environment can be set up. A
 common factor that defines the final location of tools and projects is the
-place you have suitable storage. :ref:`Prefixes` and :ref:`project-sandboxing`
-provide detailed examples of possible locations and set ups .
-
-This procedure installs a developer set up using the RTEMS Git repositories on
-a Unix (POSIX) or MacOS host. The output from the commands has been removed and
-replaced with ``...``.
+place you have suitable storage. Another is permissions.  There is no
+need to become root or the administrator and we recommend you avoid
+doing this. You can build and install the tools anywhere on the host's
+file system you, as a standard user, have read and write access too.
+:ref:`Prefixes` and :ref:`project-sandboxing` provide detailed examples
+of possible locations and set ups.
 
-Create a workspace, download the RTEMS Source Builder (RSB) and build a tool
-chain (:ref:`posix-host-tools-chain`):
+Simple Example
+==============
 
 .. code-block:: shell