Merge duplicative RSB Quick Start into Users Guide

4 files changed, 240 insertions, 18 deletions

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