[rtems-docs commit] user: Update Quick Start Guide

Chris Johns chrisj at rtems.org
Thu Mar 12 21:23:37 UTC 2020


Module:    rtems-docs
Branch:    master
Commit:    f6720264ea8ebfdd3a6b7819650520a2d18e7c31
Changeset: http://git.rtems.org/rtems-docs/commit/?id=f6720264ea8ebfdd3a6b7819650520a2d18e7c31

Author:    Chris Johns <chrisj at rtems.org>
Date:      Thu Mar 12 15:13:39 2020 +1100

user: Update Quick Start Guide

- Add support for release source archives
- Add building the BSP using the RSB
- Add building packages using the RSB
- Add an application

Closes #2998

---

 user/index.rst              |   2 +-
 user/start/app.rst          | 245 +++++++++++++++++++++++++++++++++++++++++++-
 user/start/bootstrap.rst    |  72 +++++++------
 user/start/bsp-build.rst    | 142 +++++++++++++++++++++----
 user/start/bsp-test.rst     |   2 +-
 user/start/host.rst         |  21 ----
 user/start/index.rst        |   3 +-
 user/start/prefixes.rst     |  35 ++++---
 user/start/preparation.rst  |  64 ++++++++++++
 user/start/rsb-packages.rst | 184 +++++++++++++++++++++++++++++++++
 user/start/sources.rst      | 133 +++++++++++++++++++-----
 user/start/tools.rst        | 128 ++++++++---------------
 12 files changed, 821 insertions(+), 210 deletions(-)

diff --git a/user/index.rst b/user/index.rst
index 0e644c9..98a01cf 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -17,7 +17,7 @@ RTEMS User Manual (|version|).
     | |copy| 2017 Tanu Hari Dixit
     | |copy| 2016, 2019 embedded brains GmbH
     | |copy| 2016, 2019 Sebastian Huber
-    | |copy| 2012, 2019 Chris Johns
+    | |copy| 2012, 2020 Chris Johns
     | |copy| 2012 Gedare Bloom
     | |copy| 1988, 2018 On-Line Applications Research Corporation (OAR)
 
diff --git a/user/start/app.rst b/user/start/app.rst
index fdf6bb7..98fb284 100644
--- a/user/start/app.rst
+++ b/user/start/app.rst
@@ -1,11 +1,250 @@
 .. SPDX-License-Identifier: CC-BY-SA-4.0
 
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
 
 .. _QuickStartAPP:
 
 Build Your Application
 ======================
 
-TODO
+You tested a BSP in the previous section.  We built the ``erc32`` BSP
+and it is installed under :file:`$HOME/quick-start/rtems/5`.
+
+We will now create a simple hello world application with a Git
+repository and using the `Waf <https://waf.io>`_ build system.
+
+The application is be created in :file:`$HOME/quick-start/app/hello`.
+
+In the output in this section the base directory :file:`$HOME/quick-start` was
+replaced by ``$BASE``.
+
+The steps in this section assume you are in the directory
+:file:`$HOME/quick-start/app/hello` after the first step changes to
+it.
+
+Setup the application work space. Create a new Git repository, download
+the Waf build system, and the `RTEMS Waf
+<https://git.rtems.org/rtems_waf.git/tree/README>`_.
+
+Create the application directory and change into it:
+
+.. code-block:: none
+
+    mkdir -p $HOME/quick-start/app/hello
+    cd $HOME/quick-start/app/hello
+
+Download the Waf build system and set it to executable:
+
+.. code-block:: none
+
+    curl https://waf.io/waf-2.0.19 > waf
+    chmod +w waf
+
+Initialise a new Git repository:
+
+.. code-block:: none
+
+    git init
+
+Add RTEMS Waf support as a Git sub-module and initialise it:
+
+.. code-block:: none
+
+    git submodule add git://git.rtems.org/rtems_waf.git rtems_waf
+
+Create the application source files. Three files are created with an
+editor of your choice.
+
+First create a C file that configures RTEMS. Using an editor create a
+file called :file:`init.c` and copy the following configuration
+settings:
+
+.. code-block:: c
+
+    /*
+     * Simple RTEMS configuration
+     */
+    #include <rtems.h>
+
+    #define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
+    #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+    #define CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
+
+    #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+    #define CONFIGURE_MAXIMUM_TASKS 1
+
+    #define CONFIGURE_INIT
+
+    #include <rtems/confdefs.h>
+
+Create the *hello world* application source file. Using an editor
+create :file:`hello.c` and copy the follow code:
+
+.. code-block:: c
+
+    /*
+     * Hello world example
+     */
+    #include <rtems.h>
+    #include <stdlib.h>
+    #include <stdio.h>
+
+    rtems_task Init(
+      rtems_task_argument ignored
+    )
+    {
+      printf( "\nHello World\n" );
+      exit( 0 );
+    }
+
+Finally create the Waf script. Using an editor create :file:`wscript`
+and copy the Waf script:
+
+.. code-block:: python
+
+    #
+    # Hello world Waf script
+    #
+    from __future__ import print_function
+
+    rtems_version = "5"
+
+    try:
+        import rtems_waf.rtems as rtems
+    except:
+        print('error: no rtems_waf git submodule')
+        import sys
+        sys.exit(1)
+
+    def init(ctx):
+        rtems.init(ctx, version = rtems_version, long_commands = True)
+
+    def bsp_configure(conf, arch_bsp):
+        # Add BSP specific configuration checks
+        pass
+
+    def options(opt):
+        rtems.options(opt)
+
+    def configure(conf):
+        rtems.configure(conf, bsp_configure = bsp_configure)
+
+    def build(bld):
+        rtems.build(bld)
+
+        bld(features = 'c cprogram',
+            target = 'hello.exe',
+            cflags = '-g -O2',
+            source = ['hello.c',
+                      'init.c'])
+
+Configure the application using Waf's ``configure`` command:
+
+.. code-block:: none
+
+    ./waf configure --rtems=$HOME/quick-start/rtems/5 --rtems-bsp=sparc/erc32
+
+The output will be something close to:
+
+.. code-block:: none
+
+     Setting top to                           : $BASE/app/hello
+     Setting out to                           : $BASE/app/hello/build
+     RTEMS Version                            : 5
+     Architectures                            : sparc-rtems5
+     Board Support Package (BSP)              : sparc-rtems5-erc32
+     Show commands                            : no
+     Long commands                            : no
+     Checking for program 'sparc-rtems5-gcc'  : $BASE/rtems/5/bin/sparc-rtems5-gcc
+     Checking for program 'sparc-rtems5-g++'  : $BASE/rtems/5/bin/sparc-rtems5-g++
+     Checking for program 'sparc-rtems5-gcc'  : $BASE/rtems/5/bin/sparc-rtems5-gcc
+     Checking for program 'sparc-rtems5-ld'   : $BASE/rtems/5/bin/sparc-rtems5-ld
+     Checking for program 'sparc-rtems5-ar'   : $BASE/rtems/5/bin/sparc-rtems5-ar
+     Checking for program 'sparc-rtems5-nm'   : $BASE/rtems/5/bin/sparc-rtems5-nm
+     Checking for program 'sparc-rtems5-objdump' : $BASE/rtems/5/bin/sparc-rtems5-objdump
+     Checking for program 'sparc-rtems5-objcopy' : $BASE/rtems/5/bin/sparc-rtems5-objcopy
+     Checking for program 'sparc-rtems5-readelf' : $BASE/rtems/5/bin/sparc-rtems5-readelf
+     Checking for program 'sparc-rtems5-strip'   : $BASE/rtems/5/bin/sparc-rtems5-strip
+     Checking for program 'sparc-rtems5-ranlib'  : $BASE/rtems/5/bin/sparc-rtems5-ranlib
+     Checking for program 'rtems-ld'             : $BASE/rtems/5/bin/rtems-ld
+     Checking for program 'rtems-tld'            : $BASE/rtems/5/bin/rtems-tld
+     Checking for program 'rtems-syms'           : $BASE/rtems/5/bin/rtems-syms
+     Checking for program 'rtems-bin2c'          : $BASE/rtems/5/bin/rtems-bin2c
+     Checking for program 'tar'                  : /usr/bin/tar
+     Checking for program 'gcc, cc'              : $BASE/rtems/5/bin/sparc-rtems5-gcc
+     Checking for program 'ar'                   : $BASE/rtems/5/bin/sparc-rtems5-ar
+     Checking for program 'g++, c++'             : $BASE/rtems/5/bin/sparc-rtems5-g++
+     Checking for program 'ar'                   : $BASE/rtems/5/bin/sparc-rtems5-ar
+     Checking for program 'gas, gcc'             : $BASE/rtems/5/bin/sparc-rtems5-gcc
+     Checking for program 'ar'                   : $BASE/rtems/5/bin/sparc-rtems5-ar
+     Checking for c flags '-MMD'                 : yes
+     Checking for cxx flags '-MMD'               : yes
+     Compiler version (sparc-rtems5-gcc)         : 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
+     Checking for a valid RTEMS BSP installation : yes
+     Checking for RTEMS_DEBUG                    : no
+     Checking for RTEMS_MULTIPROCESSING          : no
+     Checking for RTEMS_NEWLIB                   : yes
+     Checking for RTEMS_POSIX_API                : yes
+     Checking for RTEMS_SMP                      : no
+     Checking for RTEMS_NETWORKING               : no
+     'configure' finished successfully (0.686s)
+
+Build the application:
+
+.. code-block:: none
+
+    ./waf
+
+The output will be something close to:
+
+.. code-block:: none
+
+    Waf: Entering directory `$BASE/app/hello/build/sparc-rtems5-erc32'
+    [1/3] Compiling init.c
+    [2/3] Compiling hello.c
+    [3/3] Linking build/sparc-rtems5-erc32/hello.exe
+    Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems5-erc32'
+    'build-sparc-rtems5-erc32' finished successfully (0.183s)
+
+Run the executable:
+
+.. code-block:: none
+
+    $HOME/quick-start/rtems/5/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems5-erc32/hello.exe
+
+The output will be something close to:
+
+.. code-block:: none
+
+    RTEMS Testing - Run, 5.1.0
+     Command Line: $BASE/rtems/5/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems5-erc32/hello.exe
+     Host: FreeBSD hihi 12.1-RELEASE-p2 FreeBSD 12.1-RELEASE-p2 GENERIC amd64
+     Python: 3.7.6 (default, Jan 30 2020, 01:18:54) [Clang 6.0.1 (tags/RELEASE_601/final 335540)]
+    Host: FreeBSD-12.1-RELEASE-p2-amd64-64bit-ELF (FreeBSD hihi 12.1-RELEASE-p2 FreeBSD 12.1-RELEASE-p2 GENERIC amd64 amd64)
+
+     SIS - SPARC/RISCV instruction simulator 2.21,  copyright Jiri Gaisler 2019
+     Bug-reports to jiri at gaisler.se
+
+     ERC32 emulation enabled
+
+     Loaded build/sparc-rtems5-erc32/hello.exe, entry 0x02000000
+
+    Hello World
+
+    *** FATAL ***
+    fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT)
+    fatal code: 0 (0x00000000)
+    RTEMS version: 5.1.0
+    RTEMS tools: 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
+    executing thread ID: 0x08a010001
+    executing thread name: UI1
+    cpu 0 in error mode (tt = 0x101)
+       107883  0200b6c0:  91d02000   ta  0x0
+    Run time     : 0:00:01.011474
+
+Commit the application to the repository:
+
+.. code-block:: none
+
+    git add init.c hello.c wscript
+    git commit -m "My first RTEMS application."
diff --git a/user/start/bootstrap.rst b/user/start/bootstrap.rst
index 9fcf79b..1594f89 100644
--- a/user/start/bootstrap.rst
+++ b/user/start/bootstrap.rst
@@ -8,48 +8,54 @@
 Bootstrap the RTEMS Sources
 ===========================
 
-You installed the tool suite in your installation prefix and cloned two RTEMS
-repositories in the previous sections.  We installed the tool suite in
-:file:`$HOME/quick-start/rtems/5` and cloned the repositories in
-:file:`$HOME/quick-start/src`.
+You installed the tool suite in your installation prefix and made ready the
+source for two RTEMS source packages in the previous sections.  We installed
+the tool suite in :file:`$HOME/quick-start/rtems/5` and unpacked the RSB source
+in :file:`$HOME/quick-start/src`.
 
-If you use source archives of a released RTEMS version, then you can skip this
-section.
+You only need to *bootstrap* the RTEMS sources if you have used
+:ref:`QuickStartSources_Git` to get the sources. If you use source archives of
+a released RTEMS version you can skip this section and move to
+:ref:`QuickStartBSPBuild`.
 
 Before you can build a :ref:`Board Support Package (BSP) <BSPs>` for your
-target hardware, you have to bootstrap the build system in the RTEMS sources.
-This is only necessary, if you use a Git repository clone of the RTEMS sources.
-You have to do this after a fresh repository clone and sometimes after build
-system file updates (e.g.  after a ``git pull``).  If you are not a build
-system expert, then do the bootstrap after each update of build system files.
-This is a bit annoying, but improving the build system is a complex and time
-consuming undertaking.  Feel free to help the RTEMS Project to improve it.  For
-the bootstrap it is important that the right version of Autotools
-(:file:`autoconf` and :file:`automake`) are in your ``$PATH``.  The right
-version of Autotools is shipped with the RTEMS tool suite you already
-installed.
+target hardware from Git cloned RTEMS sources, you have to bootstrap the build
+system in the RTEMS sources.  This is only necessary if you use a Git
+repository clone of the RTEMS sources.  You have to do this after a fresh
+repository clone and sometimes after build system file updates (e.g.  after a
+``git pull``).  If you are not a build system expert, then do the bootstrap
+after each update of build system files.  This is a bit annoying, but improving
+the build system is a complex and time consuming undertaking.  Feel free to
+help the RTEMS Project to improve it.  For the bootstrap it is important that
+the right version of Autotools (:file:`autoconf` and :file:`automake`) are in
+your ``$PATH``.  The right version of Autotools is shipped with the RTEMS tool
+suite you already installed. Set the path to the tool suite installed under
+your selected *prefix*:
 
 .. code-block:: none
 
-    cd $HOME/quick-start/src/rtems
     export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
-    ./bootstrap -c
-    $HOME/quick-start/src/rsb/source-builder/sb-bootstrap
 
-These commands should output something like this (omitted lines are denoted by
-...):
+Change into the RTEMS source tree to *bootstrap* the build system:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rtems
+    ./rtems-bootstrap
+
+This command should output something like this (omitted lines are denoted by
+``...``):
 
 .. code-block:: none
 
-    removing automake generated Makefile.in files
-    removing configure files
-    removing aclocal.m4 files
-    $ $HOME/quick-start/src/rsb/source-builder/sb-bootstrap
-    RTEMS Source Builder - RTEMS Bootstrap, 5 (f07504d27192)
-      1/120: autoreconf: configure.ac
-      2/120: autoreconf: c/configure.ac
-      3/120: autoreconf: c/src/configure.ac
-      4/120: autoreconf: c/src/lib/libbsp/arm/configure.ac
+    RTEMS Bootstrap, 1.0
+      1/122: autoreconf: configure.ac
+      2/122: autoreconf: testsuites/configure.ac
+      3/122: autoreconf: testsuites/fstests/configure.ac
+      4/122: autoreconf: testsuites/smptests/configure.ac
+      5/122: autoreconf: testsuites/psxtests/configure.ac
+      6/122: autoreconf: testsuites/mptests/configure.ac
     ...
-    120/120: autoreconf: testsuites/tmtests/configure.ac
-    Bootstrap time: 0:00:48.744222
+    121/122: autoreconf: c/src/lib/libbsp/lm32/milkymist/configure.ac
+    122/122: autoreconf: c/src/make/configure.ac
+    Bootstrap time: 0:00:46.404643
diff --git a/user/start/bsp-build.rst b/user/start/bsp-build.rst
index 3b9eb15..33ecb29 100644
--- a/user/start/bsp-build.rst
+++ b/user/start/bsp-build.rst
@@ -8,35 +8,134 @@
 Build a Board Support Package (BSP)
 ===================================
 
-You installed the tool suite in your installation prefix, cloned two RTEMS
-repositories and bootstrapped the RTEMS sources in the previous sections.  We
-installed the tool suite in :file:`$HOME/quick-start/rtems/5` and cloned the
-repositories in :file:`$HOME/quick-start/src`.  We also bootstrapped the RTEMS
-sources.
+You installed the tool suite in your installation prefix, made ready the source
+for two RTEMS source packages and if you are using a Git clone bootstrapped the
+RTEMS sources in the previous sections.  We installed the tool suite in
+:file:`$HOME/quick-start/rtems/5` and unpacked the source in
+:file:`$HOME/quick-start/src`.
 
 You are now able to build :ref:`Board Support Packages (BSPs) <BSPs>` for all
-architectures where you have an RTEMS tool suite installed.  To build
-applications on top of RTEMS, you have to configure, build and install a BSP
-for your target hardware.  To select a proper BSP for your target hardware
-consult the :ref:`BSPs <BSPs>` chapter.  We select the `erc32` BSP.
+architectures you have an installed RTEMS tool suite.  To build applications on
+top of RTEMS, you have to build and install a BSP for your target hardware.  To
+select a proper BSP for your target hardware consult the :ref:`BSPs <BSPs>`
+chapter.  We select the `erc32` BSP. The ``erc32`` BSP uses approximately 2.3G
+bytes of disk space when the testsuite is built and 44M bytes of space when
+installed.
 
-We configure, build and install the BSP in four steps.  The first step is to
-create a build directory.  It must be separate from the RTEMS source directory.
-We use :file:`$HOME/quick-start/build/b-erc32`.
+We will first show how to build the BSP using the RSB and then we will show how
+to build the same BSP `manually <QuickStartBSPBuild_Manual>`_. You only need to
+use one of the listed methods to build the BSP.
+
+In the output in this section the base directory :file:`$HOME/quick-start` was
+replaced by ``$BASE``.
+
+.. QuickStartBSPBuild_RSB:
+
+RSB BSP Build
+-------------
+
+The RSB build of RTEMS does not use the RTEMS source we made ready. It uses the
+RSB source you downloaded in a previous section. If you are using a release RSB
+source archive the BSP built is the released kernel image. If you are using a
+Git clone of the RSB the BSP will be version referenced in the RSB clone.
+
+To build the BSP with all the tests run this command:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rsb/rtems
+    ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
+        --target=sparc-rtems5 --with-rtems-bsp=erc32 --with-rtems-tests=yes 5/rtems-kernel
+
+This command should output something like this:
+
+.. code-block:: none
+
+    RTEMS Source Builder - Set Builder, 5.1.0
+    Build Set: 5/rtems-kernel
+    config: tools/rtems-kernel-5.cfg
+    package: sparc-rtems5-kernel-erc32-1
+    building: sparc-rtems5-kernel-erc32-1
+    sizes: sparc-rtems5-kernel-erc32-1: 2.279GB (installed: 44.612MB)
+    cleaning: sparc-rtems5-kernel-erc32-1
+    reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-erc32-1.txt
+    reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-erc32-1.xml
+    installing: sparc-rtems5-kernel-erc32-1 -> $BASE/
+    cleaning: sparc-rtems5-kernel-erc32-1
+    Build Set: Time 0:03:09.896961
+
+The RSB BSP build can be customised with following RSB command line options:
+
+``--with-rtems-tests``:
+    Build the test suite. If ``yes`` is provided all tests in the testsuite are
+    build. If ``no`` is provided no tests are built and if ``samples`` is
+    provided only the sample executables are built, e.g.
+    ``--with-rtems-tests=yes``.
+
+``--with-rtems-smp``:
+    Build with SMP support. The BSP has to have SMP support or this option will
+    fail with an error.
+
+``--with-rtems-legacy-network``:
+    Build the legacy network software. We recommend you use the current network
+    support in the RTEMS BSP Library (libbsd) unless you need to maintain a
+    legacy product. Do not use the legacy networking software for new
+    developments.
+
+``--with-rtems-bspopts``:
+    Build the BSP with BSP specific options. This is an advanced option. Please
+    refer to the BSP specific details in the :ref:`Board Support Packages
+    (BSPs)` of this manual or the BSP source code in the RTEMS source
+    directory. To supply a list of options quote then list with ``"``, e.g.
+    ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"``
+
+If you have built a BSP with the RSB, you can move on to
+:ref:`QuickStartBSPTest`.
+
+.. QuickStartBSPBuild_Manual:
+
+Manual BSP Build
+----------------
+
+We manually build the BSP in four steps.  The first step is to create a build
+directory.  It must be separate from the RTEMS source directory.  We use
+:file:`$HOME/quick-start/build/b-erc32`.
 
 .. code-block:: none
 
     mkdir -p $HOME/quick-start/build/b-erc32
 
-The second step is to configure the BSP.  There are various configuration
-options available.  Some configuration options are BSP-specific.  Prepend the
-RTEMS tool suite binary directory to your ``$PATH`` throughout the remaining
-steps.
+The second step is to set your path. Prepend the RTEMS tool suite binary
+directory to your ``$PATH`` throughout the remaining steps. Run the command:
 
 .. code-block:: none
 
-    cd $HOME/quick-start/build/b-erc32
     export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
+
+Check your installed tools can be found by running:
+
+.. code-block:: none
+
+    command -v sparc-rtems5-gcc && echo "found" || echo "not found"
+
+The output should be:
+
+.. code-block:: none
+
+    found
+
+If ``not found`` is printed the tools are not correctly installed or the path
+has not been correctly set. Check the contents of the path
+:file:`$HOME/quick-start/rtems/5/bin` manually and if :file:`sparc-rtems5-gcc`
+is present the path is wrong. If the file cannot be found return to
+:ref:`QuickStartTools` and install the tools again.
+
+The third step is to configure the BSP.  There are various configuration
+options available.  Some configuration options are BSP-specific.
+
+.. code-block:: none
+
+    cd $HOME/quick-start/build/b-erc32
     $HOME/quick-start/src/rtems/configure \
         --prefix=$HOME/quick-start/rtems/5 \
         --enable-maintainer-mode \
@@ -45,7 +144,7 @@ steps.
         --enable-tests
 
 This command should output something like this (omitted lines are denoted by
-...):
+``...``):
 
 .. code-block:: none
 
@@ -64,7 +163,7 @@ This command should output something like this (omitted lines are denoted by
 
     config.status: creating Makefile
 
-Building the BSP is the third step.
+Building the BSP is the forth step.
 
 .. code-block:: none
 
@@ -72,8 +171,7 @@ Building the BSP is the third step.
     make
 
 This command should output something like this (omitted lines are denoted by
-...).  In this output the base directory :file:`$HOME/quick-start` was replaced
-by ``$BASE``.
+...).
 
 .. code-block:: none
 
@@ -97,7 +195,7 @@ by ``$BASE``.
     configure: creating make/erc32.cache
     gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
     ...
-    sparc-rtems5-gcc  -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -B./../../lib/libbsp/sparc/erc32 -B$BASE/src/rtems/bsps/sparc/erc32/start -specs bsp_specs -qrtems -L./../../cpukit -L$BASE/src/rtems/bsps/sparc/shared/start -Wl,--wrap=printf -Wl,--wrap=puts -Wl,--wrap=putchar -Wl,--gc-sections -o spwkspace.exe spwkspace/spwkspace-init.o ./../../lib/libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a 
+    sparc-rtems5-gcc  -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -B./../../lib/libbsp/sparc/erc32 -B$BASE/src/rtems/bsps/sparc/erc32/start -specs bsp_specs -qrtems -L./../../cpukit -L$BASE/src/rtems/bsps/sparc/shared/start -Wl,--wrap=printf -Wl,--wrap=puts -Wl,--wrap=putchar -Wl,--gc-sections -o spwkspace.exe spwkspace/spwkspace-init.o ./../../lib/libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a
     gmake[5]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites/sptests'
     gmake[4]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites'
     gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
diff --git a/user/start/bsp-test.rst b/user/start/bsp-test.rst
index aefeeb9..f609c59 100644
--- a/user/start/bsp-test.rst
+++ b/user/start/bsp-test.rst
@@ -29,7 +29,7 @@ by ``$BASE``.
 
 .. code-block:: none
 
-    RTEMS Testing - Tester, 5.0.not_released
+    RTEMS Testing - Tester, 5.1.0
      Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis --rtems-tools=$BASE/rtems/5 .
      Python: 2.7.15 (default, Jan 10 2019, 01:14:47) [GCC 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540)]
     Host: FreeBSD-12.0-RELEASE-p2-amd64-64bit-ELF (FreeBSD Build_FreeBSD12 12.0-RELEASE-p2 FreeBSD 12.0-RELEASE-p2 GENERIC amd64 amd64)
diff --git a/user/start/host.rst b/user/start/host.rst
deleted file mode 100644
index f891f5d..0000000
--- a/user/start/host.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
-
-.. _QuickStartHost:
-
-Prepare Your Host Computer
-==========================
-
-The *host computer* is a computer you use to develop applications.  It runs all
-your tools, editors, documentation viewers, etc.  To get started with RTEMS
-development you need tools from your host's operating system to build the RTEMS
-tool suite from source.  This is not a one-click installation process, but
-there are :ref:`good reasons <WhyBuildFromSource>` to build everything from
-source.  You need a native C, C++ and Python development environment.  Please
-make sure that you can build native C/C++ applications on your host computer.
-You must be able to build native Python C modules.  Usually, you have to
-install a Python development package for this.  Please have a look at the
-:ref:`Host Computer <host-computer>` chapter for the gory details.  In
-particular :ref:`Microsoft Windows <microsoft-windows>` user should do this.
diff --git a/user/start/index.rst b/user/start/index.rst
index d6333f3..3289fa2 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -14,7 +14,7 @@ applications on top of RTEMS.
 
 .. toctree::
 
-    host
+    preparation
     prefixes
     sources
     tools
@@ -22,3 +22,4 @@ applications on top of RTEMS.
     bsp-build
     bsp-test
     app
+    rsb-packages
diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst
index 9727503..67255d0 100644
--- a/user/start/prefixes.rst
+++ b/user/start/prefixes.rst
@@ -21,32 +21,39 @@ path.  Packages for your host computer typically use a default prefix of
 :file:`/usr/local` on FreeBSD and Linux.
 
 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, an RTEMS kernel for a BSP, and you may build and install
+third party libraries. You can build all the parts as a stack with a single
+prefix or you can separate various parts by providing different prefixes to
+each part as it is built. Using separate prefixes is for experienced RTEMS
+users.
 
-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
+Do not select a prefix that is under the top of any of the source trees. The
+prefix collects the install output of the various build steps you take in this
+guide and need to be kept separate from the sources used.
 
+The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB,
+Newlib, etc.)  for your target architecture and :ref:`RTEMS tools <HostTools>`
+provided by the RTEMS Project. The RTEMS Tools are a toolkit that help create
+the RTEMS ecosystem and help support the building of embedded real-time
+applications and systems.
 
 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.
+system specific path plus :file:`rtems`, and the RTEMS version, e.g.
+:file:`/opt/rtems/5` on Linux, and :file:`/usr/local/rtems/5` on FreeBSD and
+macOS. Placing the RTEMS version number in the path lets you manage and
+migrate RTEMS versions as they are released.
 
 It is strongly recommended to run the RSB as a *normal user* and not with
 *root* privileges (also known as *super user* or *Administrator*).  You have to
 make sure that your normal user has sufficient privileges to create files and
 directories under the prefix.  For example, you can create a directory
-:file:`/opt/rtems` and give it to a developer group with read, write and
+:file:`/opt/rtems` and give it to a developer group with read, write, and
 execute permissions.  Alternatively, you can choose a prefix in your home
 directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component
-:file:`$HOME/project-x/rtems/5`.  For more ideas, see the
-:ref:`project sandboxing <ProjectSandboxing>` section.  In this quick start
-chapter, we will choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool
-suite prefix.
+:file:`$HOME/project-x/rtems/5`.  For more ideas, see the :ref:`project
+sandboxing <ProjectSandboxing>` section.  In this quick start chapter, we will
+choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool suite prefix.
 
 .. warning::
 
diff --git a/user/start/preparation.rst b/user/start/preparation.rst
new file mode 100644
index 0000000..546a03d
--- /dev/null
+++ b/user/start/preparation.rst
@@ -0,0 +1,64 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
+
+.. _QuickStartPreparation:
+
+Preparation
+===========
+
+You need to perform some basic preparation to get started with RTEMS
+development.  You need tools from your host's operating system to build the
+RTEMS tool suite from source.  The RTEMS tools you build are used to build the
+Board Support Package (BSP) libraries for your target hardware from source. The
+BSP libraries contain the RTEMS operating system.  This is not a one-click
+installation process, but there are :ref:`good reasons <WhyBuildFromSource>` to
+build everything from source.
+
+During this Quick Start guide you will:
+
+* Select a suitable place to install RTEMS.
+
+* Select if you download all the source code before you start building RTEMS or
+  the source is downloaded on demand as it is needed.  If you do not have a
+  reliable internet connection we recommend you download all the source before
+  starting a build.
+
+* Build a tool suite.
+
+* Build and test a BSP.
+
+* Optionally  build additional packages.
+
+Alternatively you can build a BSP as a package using the RSB. This is
+covered in :ref:`QuickStartBSPPackages`
+
+Host Computer
+-------------
+
+The *host computer* is a computer you use to develop applications.  It runs all
+your tools, editors, documentation viewers, etc.  You need a native C, C++, and
+Python development environment.  Please make sure you can build native C/C++
+applications on your host computer.  You must be able to build native Python C
+modules as some RTEMS tools contain these modules.  Usually, you have to
+install a Python development package for this.  Please have a look at the
+:ref:`Host Computer <host-computer>` chapter for the gory details.  In
+particular :ref:`Microsoft Windows <microsoft-windows>` users should do this.
+
+Selecting a BSP
+---------------
+
+If you are new to RTEMS and you are looking to try RTEMS then the best suited
+Board Support Package (BSP) is the :ref:`SPARC ERC32 <BSP_sparc_erc32>`
+(``erc32``). The SPARC ERC32 BSP has a robust simulator that runs the example
+and test executables on your host computer. This Quick Start guide will build
+the ``erc32`` BSP and run RTEMS tests executables in the simulator. The ERC32
+BSP is a SPARC architecture BSP so the tool suite name is ``sparc-rtems5``.
+
+If you are looking for a hardware target to run RTEMS on we recommend the
+:ref:`BeagleBone Black <BSP_arm_beagleboneblack>` (``beagleboneblack``)
+BSP. The BeagleBone Black support includes the RTEMS BSD Library (``libbsd``)
+and networking. The BeagleBone Black BSP is an ARM architecture BSP so the tool
+suite name is ``arm-rtems5``.
diff --git a/user/start/rsb-packages.rst b/user/start/rsb-packages.rst
new file mode 100644
index 0000000..f677928
--- /dev/null
+++ b/user/start/rsb-packages.rst
@@ -0,0 +1,184 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 Contemporary Software
+.. Copyright (C) 2020 Chris Johns
+
+.. _QuickStartBSPPackages:
+
+Build an RSB Package
+====================
+
+This section describes how to build an RTEMS package using the RSB.  Before we
+start to build a package with the RSB you need to complete these steps:
+
+- :ref:`QuickStartPrefixes`
+
+- :ref:`QuickStartSources`.
+
+Return to here once you have completed these steps.
+
+You have chosen an installation prefix, the BSP to build, the tool's
+architecure and prepared the source for the RSB in the previous sections.  We
+have chosen :file:`$HOME/quick-start/rtems/5` as the installation prefix, the
+``erc32`` BSP and the SPARC architecture name of ``sparc-rtems5``, and unpacked
+the RSB source in :file:`$HOME/quick-start/src`.
+
+You are now able to build :ref:`BSP Packages` or 3rd party libraries of code if you
+have built a BSP.
+
+RTEMS Packages
+--------------
+
+RTEMS Packages are source packages the RSB build to run on RTEMS. An installed
+package is a set of header files and libraries. Your application include the
+packages header files to make calls to the package's code and include the
+libraries in it's linker options.
+
+RTEMS packages can be part of the RTEMS Project or they can be external
+packages from 3rd parties. RTEMS Project packages include the BSPs and BSD
+Library package called ``libbsd``. External 3rd party packages include
+networking such has ``curl`` or ``libcurl`` to graphics libraries.
+
+Packages can depend on other packages and need to be build in the corret
+order. For example the FreeBSD Library package depends on the BSP package and a
+3rd party library such as ``curl`` depends on the FreeBSD Library package. We
+call this layering a vertical software stack.
+
+RTEMS applications are cross-compiled and this adds complexity when building
+libraries of code. RTEMS Packages build with the RSB manage this complexity for
+you.
+
+Package are libraries so they will not be linked into your application until
+you make calls to the the code and add the library to your application's linker
+command line.
+
+.. QuickStartRSBPackage_BSPStack:
+
+BSP Stack Build
+---------------
+
+A BSP stack build is a single command that uses the RSB to build a BSP software
+stack of:
+
+* Tool suite
+
+* BSP
+
+* Packages
+
+The packages built depend on the BSP and the default will build all packages for a
+BSP.
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rsb/rtems
+    ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
+        --with-rtems-tests=yes 5/bsps/erc32
+
+This command should output something like this:
+
+.. code-block:: none
+
+    RTEMS Source Builder - Set Builder, 5.1.0
+    Build Set: 5/bsps/erc32
+    Build Set: 5/rtems-sparc.bset
+    Build Set: 5/rtems-autotools.bset
+    Build Set: 5/rtems-autotools-internal.bset
+    config: tools/rtems-autoconf-2.69-1.cfg
+    package: autoconf-2.69-x86_64-freebsd12.1-1
+    building: autoconf-2.69-x86_64-freebsd12.1-1
+    sizes: autoconf-2.69-x86_64-freebsd12.1-1: 7.505MB (installed: 0.000B)
+    ...
+    building: protobuf-2.6.1-sparc-rtems5-1
+    sizes: protobuf-2.6.1-sparc-rtems5-1: 228.079MB (installed: 84.408MB)
+    cleaning: protobuf-2.6.1-sparc-rtems5-1
+    reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.txt
+    reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.xml
+    staging: protobuf-2.6.1-sparc-rtems5-1 -> $HOME/quick-start/src/rsb/rtems/build/tmp/sb-500-staging
+    cleaning: protobuf-2.6.1-sparc-rtems5-1
+    Build Set: Time 0:00:23.564992
+    Build Set: Time 0:02:27.380299
+    installing: 5/bsps/erc32 -> $HOME/quick-start/rtems/
+    clean staging: 5/bsps/erc32
+    Staging Size: 1.372GB
+    Build Set: Time 0:24:17.83979
+
+The RSB BSP build can be customised with following RSB command line options:
+
+``--with-rtems-tests``:
+    Build the test suite. If ``yes`` is provided all tests in the testsuite are
+    build. If ``no`` is provided no tests are built and if ``samples`` is
+    provided only the sample executables are built, e.g.
+    ``--with-rtems-tests=yes``.
+
+``--with-rtems-smp``:
+    Build with SMP support. The BSP has to have SMP support or this option will
+    fail with an error.
+
+``--with-rtems-bspopts``:
+    Build the BSP with BSP specific options. This is an advanced option. Please
+    refer to the BSP specific details in the :ref:`Board Support Packages
+    (BSPs)` of this manual or the BSP source code in the RTEMS source
+    directory. To supply a list of options quote then list with ``"``, e.g.
+    ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"``
+
+Only a limited number of BSPs have RSB support to build as a software stack. To
+see which BSPs are supported run this command:
+
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rsb/rtems
+    ../source-builder/sb-set-builder --list-bsets | grep bsps
+
+Package Build
+-------------
+
+Packages are built using RSB build sets. A build set is a set of builds need to
+build a packages. The build steps can be dependencies a package has or it could
+be a stack of software to provide specific functionality, i.e. a build set can
+be a list of build sets. To view the avaliable build sets run this command:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rsb/rtems
+    ../source-builder/sb-set-builder --list-bsets
+
+RTEMS package naming is based on the naming FreeBSD uses in its ports
+collection.
+
+This Quick Start Guide will build the BSD Library or :file:`5/rtems-libbsd`.
+
+An RTEMS package is hosted on RTEMS so the tool suite name needs to be supplied
+using the ``--host`` option, e.g. ``--host=sparc-rtem5``. The BSP needs to be
+provided using the ``--with-rtems-bsp`` option,
+e.g. ``--with-rtems-bsp=erc32``. The commands to build ``libbsd`` for the
+``erc32`` BSP are:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rsb/rtems
+    ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
+      --host=sparc-rtems5 --with-rtems-bsp=erc32 5/rtems-libbsd
+
+This command should output something like this:
+
+.. code-block:: none
+
+    RTEMS Source Builder - Set Builder, 5.1.0
+    Build Set: 5/rtems-libbsd
+    config: tools/rtems-libbsd-5.cfg
+    package: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+    building: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+    sizes: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1: 1.199GB (installed: 116.541MB)
+    cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+    reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.txt
+    reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.xml
+    installing: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 -> $HOME/quick-start/rtems/5
+    cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+    Build Set: Time 0:00:51.898231
+
+.. note::
+
+   Not all packages will build or run with all BSPs. Please ask on the
+   :r:list:`users` if you have any issues.
diff --git a/user/start/sources.rst b/user/start/sources.rst
index 692e2bc..70b1456 100644
--- a/user/start/sources.rst
+++ b/user/start/sources.rst
@@ -2,6 +2,7 @@
 
 .. Copyright (C) 2019 embedded brains GmbH
 .. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
 
 .. _QuickStartSources:
 
@@ -10,43 +11,123 @@ Obtain the Sources
 
 You have considered and chosen a suitable installation prefix in the previous
 section.  We have chosen :file:`$HOME/quick-start/rtems/5` as the installation
-prefix.
+prefix. We will show how to use a released version of RTEMS and then as an
+alternative we will show you using the :ref:`RSB Git repository
+<QuickStartSources_Git>`. Consider using a Git clone if you wish to make
+contributions to the RTEMS Project.
 
-You need at least two source archives or Git repositories to work with RTEMS.
-You can download the source archives for a released RTEMS version or you can
-clone Git repositories to get all versions of RTEMS including the development
-head.
+You need the RTEMS Source Builder (RSB) to work with RTEMS and we prefer you
+use a released version. A released version of the RSB downloads all source code
+from the RTEMS servers. Each release archives all the referenced source
+providing long term stability as changes in upstream projects do not effect a
+release's build.
 
-We will clone the Git repositories into :file:`$HOME/quick-start/src`.
+You will need approximately 1.5G bytes of disk space to build the tools, RTEMS
+kernel, network stack and 3rd party packages for the ERC32 BSP.
+
+.. _QuickStartSources_Released:
+
+Releases
+--------
+
+You can download the source archives for a released RTEMS version from RTEMS'
+servers. Releases can be view at https://ftp.rtems.org/pub/rtems/releases with
+the releases listed as a series under a release's major number. For RTEMS 5.1.0
+the release series is `5 <https://ftp.rtems.org/pub/rtems/releases/5>`_ and the
+release path is https://ftp.rtems.org/pub/rtems/releases/5/5.1.0.
+
+To work with the archives of a released RTEMS version, simply replace the
+version number ``5`` used throughout this chapter with the version number you
+selected, e.g. ``sparc-rtems4.11``, ``sparc-rtems6``, and so on.
+
+Download and unpack using the ``curl`` and ``tar`` command with these commands:
 
 .. code-block:: none
 
     mkdir -p $HOME/quick-start/src
     cd $HOME/quick-start/src
-    git clone git://git.rtems.org/rtems-source-builder.git rsb
-    git clone git://git.rtems.org/rtems.git
+    curl https://ftp.rtems.org/pub/rtems/releases/5/5.1.0/rtems-source-builder-5.1.0.tar.xz | tar xJf -
+
+If ``curl`` does not work consider using ``wget`` or a browser.
+
+The RSB is unpacked under the path ``rtems-source-builder-5.1.0``. Rename this
+to ``rsb`` to get shorter paths during the tool suite build. To do this run
+these commands:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src
+    mv rtems-source-builder-5.1.0 rsb
+
+.. _QuickStartSources_Released_RTEMS:
+
+If you wish to build the RTEMS kernel from source obtain the RTEMS kernel
+sources:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src
+    curl https://ftp.rtems.org/pub/rtems/releases/5/5.1.0/rtems-5.1.0.tar.xz | tar xJf -
+
+.. _QuickStartSources_Git:
+
+Git
+---
 
-The :file:`rsb` repository clone contains the
-:ref:`RTEMS Source Builder (RSB) <RSB>`.  We clone it into
-:file:`rsb` to get shorter paths during the tool suite build.  The
-:file:`rtems` repository clone contains the RTEMS sources.  These two
-repositories are enough to get started.  There are
-`more repositories <https://git.rtems.org>`_ available.
+Alternatively, clone the Git repositories into :file:`$HOME/quick-start/src`.
 
-Alternatively, you can download the source archives of a released RTEMS
-version.
+A Git repository clone gives you some flexibility with the added complexity of
+needing to use a Git branch to build a released version.  With Git you can
+switch between branches to try out different RTEMS versions and you have access
+to the RTEMS source history. The RTEMS Project welcomes contributions.  The Git
+repositories enable you to easily create patches and track local changes.
+
+You can clone the Git repository to get all versions of RTEMS including the
+development head.  Release branches in Git are kept stable however they may
+differ from a release's source archive.
 
 .. code-block:: none
 
     mkdir -p $HOME/quick-start/src
     cd $HOME/quick-start/src
-    curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-4.11.3.tar.xz | tar xJf -
-    curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-source-builder-4.11.3.tar.xz | tar xJf -
-
-This quick start chapter focuses on working with the Git repository clones
-since this gives you some flexibility.  You can switch between branches to try
-out different RTEMS versions.  You have access to the RTEMS source history.
-The RTEMS Project welcomes contributions.  The Git repositories enable you to
-easily create patches and track local changes.  If you prefer to work with
-archives of a released RTEMS version, then simply replace the version number 5
-used throughout this chapter with the version number you selected, e.g. 4.11.
+    git clone git://git.rtems.org/rtems-source-builder.git rsb
+    git clone git://git.rtems.org/rtems.git
+
+The :file:`rsb` repository clone contains the :ref:`RTEMS Source Builder (RSB)
+<RSB>`.  We clone it into :file:`rsb` to get shorter paths during the tool
+suite build.  The :file:`rtems` repository clone contains the RTEMS sources.
+These two repositories are enough to get started.  There are `more repositories
+<https://git.rtems.org>`_ available.
+
+Offline Download
+----------------
+
+If you have limited Internet access you can download the source before you
+start building. If you are permanently connected to the Internet you do not
+need to do this and the sources will be automatically download on demand when
+needed.
+
+Once the sources have been downloaded you could disconnect your host computer
+from the Internet.  It is no longer required to work with RTEMS. To download
+the sources to build the ERC 32 BSP before building run the following commands:
+
+.. code-block:: none
+
+    cd $HOME/quick-start/src/rsb/rtems
+    ../source-builder/sb-set-builder --source-only-download 5/rtems-sparc
+
+This command should output something like this (omitted lines are denoted by
+``...``):
+
+.. code-block:: none
+
+    RTEMS Source Builder - Set Builder, 5.1.0
+    Build Set: 5/rtems-sparc
+    ...
+    download: https://ftp.rtems.org/pub/rtems/releases/5/5.1.0/5.1.0/sources/gcc-7.5.0.tar.xz -> sources/gcc-7.5.0.tar.xz
+    ...
+    Build Sizes: usage: 0.000B total: 143.814MB (sources: 143.793MB, patches: 21.348KB, installed 0.000B)
+    Build Set: Time 0:05:52.617958
+
+If you encounter errors, check your internet connection, firewall settings,
+virus scanners and the availability of the download servers.
diff --git a/user/start/tools.rst b/user/start/tools.rst
index 07dc1e0..c3f039b 100644
--- a/user/start/tools.rst
+++ b/user/start/tools.rst
@@ -2,49 +2,24 @@
 
 .. Copyright (C) 2019 embedded brains GmbH
 .. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
 
 .. _QuickStartTools:
 
 Install the Tool Suite
 ======================
 
-You have chosen an installation prefix and cloned two RTEMS repositories in the
-previous sections.  We have chosen :file:`$HOME/quick-start/rtems/5` as the
-installation prefix and cloned the repositories in
-:file:`$HOME/quick-start/src`.
-
-You must select the
-:ref:`target architecture <TargetArchitectures>` for which you need a tool
-suite.  In this quick start chapter we choose `sparc-rtems5`.  The
-`sparc-rtems5` is the tool suite name for the SPARC architecture and RTEMS
-version 5.  The tool suite for RTEMS and the RTEMS sources are tightly coupled.
-For example, do not use a RTEMS version 5 tool suite with RTEMS version 4.11
-sources and vice versa.  We use the RSB in two steps.  The first step is to
-download additional sources and patches.  Afterwards, you could disconnect your
-host computer from the internet.  It is no longer required to work with RTEMS.
+You have chosen an installation prefix, the BSP to build, the tool's
+architecure and prepared the source for the RSB in the previous sections.  We
+have chosen :file:`$HOME/quick-start/rtems/5` as the installation prefix, the
+``erc32`` BSP and the SPARC architecture name of ``sparc-rtems5``, and unpacked
+the RSB source in :file:`$HOME/quick-start/src`.
 
-.. code-block:: none
-
-    cd $HOME/quick-start/src/rsb/rtems
-    ../source-builder/sb-set-builder --source-only-download 5/rtems-sparc
-
-This command should output something like this (omitted lines are denoted by
-...):
-
-.. code-block:: none
-
-    RTEMS Source Builder - Set Builder, 5 (98588a55961a)
-    warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip
-    Build Set: 5/rtems-sparc
-    ...
-    download: https://ftp.gnu.org/gnu/gcc/gcc-7.4.0/gcc-7.4.0.tar.xz -> sources/gcc-7.4.0.tar.xz
-    ...
-    Build Sizes: usage: 0.000B total: 141.738MB (sources: 141.559MB, patches: 183.888KB, installed 0.000B)
-    Build Set: Time 0:01:17.613061
+The tool suite for RTEMS and the RTEMS sources are tightly coupled.  For
+example, do not use a RTEMS version 5 tool suite with RTEMS version 4.11
+sources and vice versa.
 
-If you encounter errors in the first step, check your internet connection,
-firewall settings, virus scanners and the availability of the download servers.
-The seconds step is to build and install the tool suite.
+Build and install the tool suite:
 
 .. code-block:: none
 
@@ -52,75 +27,52 @@ The seconds step is to build and install the tool suite.
     ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 5/rtems-sparc
 
 This command should output something like this (omitted lines are denoted by
-...):
+...). The build host appears as part of the name of the package being
+built. The name you see may vary depending on the host you are using:
 
 .. code-block:: none
 
-    RTEMS Source Builder - Set Builder, 5 (98588a55961a)
-    warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip
+    RTEMS Source Builder - Set Builder, 5.1.0
     Build Set: 5/rtems-sparc
     ...
-    config: tools/rtems-gcc-7.4.0-newlib-3e24fbf6f.cfg
-    package: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
-    building: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
-    sizes: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1: 4.651GB (installed: 879.191MB)
-    cleaning: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
+    config: tools/rtems-binutils-2.34.cfg
+    package: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
+    building: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
+    sizes: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1: 305.866MB (installed: 29.966MB)
+    cleaning: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
+    reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.txt
+    reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.xml
+    config: tools/rtems-gcc-7.5.0-newlib-fbaa096.cfg
+    package: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
+    building: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
     ....
-    Build Sizes: usage: 5.618GB total: 1.105GB (sources: 141.559MB, patches: 185.823KB, installed 989.908MB)
-    Build Set: Time 0:22:02.262039
+    Build Sizes: usage: 5.684GB total: 1.112GB (sources: 143.803MB, patches: 21.348KB, installed 995.188MB)
+    Build Set: Time 0:21:35.626294
 
-In case the seconds step was successful, you can check if for example the cross
-C compiler works with the following command:
+Once the build has successfully completed you can check if the cross C compiler
+works with the following command:
 
 .. code-block:: none
 
-    $HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc --version --verbose
+    $HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc --version
 
-This command should output something like below.  In this output the actual
-prefix path was replaced by ``$PREFIX``.  The ``compiled by`` line depends on
-the native C++ compiler of your host computer.  In the output you see the Git
-hash of the RSB.  This helps you to identify the exact sources which were used
-to build the cross compiler of your RTEMS tool suite.
+This command should output something like below.  The version informtion helps
+you to identify the exact sources used to build the cross compiler of your
+RTEMS tool suite.  In the output you see the version of RTEMS or the hash from
+the RSB repository if you are building using a Git repository clone. The Newlib
+hash is the version of Newlib in the RTEMS's github
+`sourceware-mirror-newlib-cygwin
+<https://github.com/RTEMS/sourceware-mirror-newlib-cygwin>`_ repository. The
+``sources`` and ``patches`` directories created by the RSB contain all the
+source code used.
 
 .. code-block:: none
 
-    Using built-in specs.
-    COLLECT_GCC=$PREFIX/bin/sparc-rtems5-gcc
-    COLLECT_LTO_WRAPPER=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/lto-wrapper
-    sparc-rtems5-gcc (GCC) 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
+    sparc-rtems5-gcc (GCC) 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
     Copyright (C) 2017 Free Software Foundation, Inc.
     This is free software; see the source for copying conditions.  There is NO
     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 
 
-    Target: sparc-rtems5
-    Configured with: ../gcc-7.4.0/configure --prefix=$PREFIX --bindir=$PREFIX/bin --exec_prefix=$PREFIX --includedir=$PREFIX/include --libdir=$PREFIX/lib --libexecdir=$PREFIX/libexec --mandir=$PREFIX/share/man --infodir=$PREFIX/share/info --datadir=$PREFIX/share --build=x86_64-freebsd12.0 --host=x86_64-freebsd12.0 --target=sparc-rtems5 --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib --disable-nls --without-included-gettext --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto --enable-newlib-io-c99-formats --enable-newlib-iconv --enable-newlib-iconv-encodings=big5,cp775,cp850,cp852,cp855,cp866,euc_jp,euc_kr,euc_tw,iso_8859_1,iso_8859_10,iso_8859_11,iso_8859_13,iso_8859_14,iso_8859_15,iso_8859_2,iso_8859_3,iso_8859_4,iso_8859_5,iso_8859_6,iso_8859_7,iso_8859_8,iso_8859_9,iso_ir_111,koi8_r,koi8_ru,koi8_u,koi8_uni,ucs_2,ucs_2_internal,ucs_2be,ucs_2le,ucs_4,ucs_4_internal,ucs_4be,ucs_4le,us_ascii,utf_16,utf_16be,utf_16le,utf_8,win_1250
 ,win_1251,win_1252,win_1253,win_1254,win_1255,win_1256,win_1257,win_1258 --enable-threads --disable-plugin --enable-libgomp --enable-languages=c,c++
-    Thread model: rtems
-    gcc version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (GCC) 
-    COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
-     $PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/cc1 -quiet -v -iprefix $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/ help-dummy -quiet -dumpbase help-dummy -mcpu=v7 -auxbase help-dummy -version --version -o /tmp//ccuAN1wc.s
-    GNU C11 (GCC) version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (sparc-rtems5)
-            compiled by GNU C version 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540), GMP version 6.1.0, MPFR version 3.1.4, MPC version 1.0.3, isl version isl-0.16.1-GMP
-
-    GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072
-    COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
-     $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/as -v -s --version -o /tmp//ccFVgRAa.o /tmp//ccuAN1wc.s
-    GNU assembler version 2.32 (sparc-rtems5) using BFD version (GNU Binutils) 2.32
-    GNU assembler (GNU Binutils) 2.32
-    Copyright (C) 2019 Free Software Foundation, Inc.
-    This program is free software; you may redistribute it under the terms of
-    the GNU General Public License version 3 or later.
-    This program has absolutely no warranty.
-    This assembler was configured for a target of `sparc-rtems5'.
-    COMPILER_PATH=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../libexec/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/
-    LIBRARY_PATH=$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../lib/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/
-    COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
-     $PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/collect2 --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc
-    collect2 version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
-    $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/ld --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc
-    GNU ld (GNU Binutils) 2.32
-    Copyright (C) 2019 Free Software Foundation, Inc.
-    This program is free software; you may redistribute it under the terms of
-    the GNU General Public License version 3 or (at your option) a later version.
-    This program has absolutely no warranty.
-    COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
+
+Add ``--verbose`` to the GCC command for the the verbose version details.



More information about the vc mailing list