[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