[PATCH 3/3] user: Document new build system

Sebastian Huber sebastian.huber at embedded-brains.de
Fri Jul 3 09:17:46 UTC 2020


Update #3818.
---
 user/bld/index.rst         | 283 +++++++++++++++++++++++++++++++++++++
 user/index.rst             |   1 +
 user/start/bootstrap.rst   |  61 --------
 user/start/bsp-build.rst   | 149 +++++++++----------
 user/start/bsp-test.rst    |  14 +-
 user/start/index.rst       |   1 -
 user/start/preparation.rst |  10 +-
 7 files changed, 365 insertions(+), 154 deletions(-)
 create mode 100644 user/bld/index.rst
 delete mode 100644 user/start/bootstrap.rst

diff --git a/user/bld/index.rst b/user/bld/index.rst
new file mode 100644
index 0000000..1b8df1a
--- /dev/null
+++ b/user/bld/index.rst
@@ -0,0 +1,283 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 Sebastian Huber
+
+.. index:: build system
+
+.. _BSPBuildSystem:
+
+BSP Build System
+****************
+
+The purpose of the BSP build system is to produce and install artefacts from the
+RTEMS sources such as static libraries, start files, linker command files,
+configuration header files, header files, test programs, package description
+files, and third-party build system support files.
+
+Overview
+========
+
+The BSP build system consists of three components which are all included in the
+RTEMS sources
+
+* the `waf <https://waf.io/>`_ meta build system command line tool,
+
+* a `wscript <https://git.rtems.org/rtems/tree/wcript>`_ file used by ``waf``,
+  and
+
+* a
+  `set of build specification items <https://git.rtems.org/rtems/tree/spec/build>`_
+  maintained by a text editor just like other source files.
+
+The build system is controlled by the user through
+
+* commands passed to the ``waf`` command line tool,
+
+* command line options passed to ``waf``, and
+
+* configuration files (e.g. ``config.ini``) used by ``wscript`` through ``waf``
+  invocations.
+
+Configurable things which are subject to a local installation variant such as
+paths to tools are intended to be passed as command line options to the ``waf``
+command line tool.  Which BSPs are built and how they are configured by means of
+options is placed in configuration files (e.g. ``config.ini``).  The
+configuration files may reside anywhere in the file system and the goal is to
+have it under version control by the user.
+
+Work Flow
+=========
+
+There are five steps necessary to build and install one or more BSPs.
+
+1. Select which BSPs you want to build.  See also :ref:`BSPs` and
+   ``./waf bsp_list``.
+
+2. Write a BSP build configuration file (e.g. ``config.ini``) which determines
+   which BSPs are built and how they are configured.
+
+3. Run the ``./waf configure`` command to generate the build
+   environment.
+
+4. Build the BSP artefacts with ``./waf``.  The build uses the build environment
+   created by ``./waf configure``.  The BSP build configuration file (e.g.
+   ``config.ini``) is no longer used and may be deleted.
+
+5. Install the BSP artefacts with ``./waf install``.
+
+Commands
+========
+
+The BSP build system is controlled by invocations of the ``./waf`` command line
+tool instead of the well known ``make``.  Since waf is written in Python, a
+standard Python 2.7 or 3 installation without third-party packages is required
+to run it.  The ``./waf`` command line tool must be invoked in the RTEMS source
+tree top-level directory.
+
+Some commands accept the ``--rtems-specs`` command line option.  This option
+specifies paths to build specification items.  It is an advanced option and
+there is normally no need to use it.  It may be used to customize the build at
+the level of the build specification.  For more information see the
+`Build System` chapter of the
+`RTEMS Software Engineering <https://docs.rtems.org/branches/master/eng/build-system.rst>`_
+guide.
+
+Help
+----
+
+Use ``./waf --help`` to get a list of commands and options.
+
+BSP List
+--------
+
+The BSP list command ``./waf bsp_list`` loads the build specification items and
+generates a list of base BSPs from it.  The list is sorted by architecture and
+base BSP name.  Which base BSPs are listed can be controlled by the
+``--rtems-bsps`` command line option.  It expects a comma-separated list of
+`Python regular expressions <https://docs.python.org/3/library/re.html#regular-expression-syntax>`_
+which select the desired BSP variants.  The path to the build specification
+items can be specified by the ``--rtems-specs`` command line option.
+
+.. code-block:: none
+
+    $ ./waf bsp_list --rtems-bsps=sparc/
+    sparc/at697f
+    sparc/erc32
+    sparc/gr712rc
+    sparc/gr740
+    sparc/leon2
+    sparc/leon3
+    sparc/ut699
+    sparc/ut700
+
+.. code-block:: none
+
+    $ ./waf bsp_list --rtems-bsps='/leon,/rv64imac$'
+    riscv/rv64imac
+    sparc/leon2
+    sparc/leon3
+
+BSP Defaults
+------------
+
+The BSP defaults command ``./waf bsp_defaults`` loads the build specification
+items and generates a list options with default values for each base BSP from
+it.  The list is sorted by architecture and base BSP name.  Which base BSPs are
+listed can be controlled by the ``--rtems-bsps`` command line option.  Default
+values may depend on the selected compiler.  The compiler can be specified by
+the ``--rtems-compiler`` command line option.  The path to the build
+specification items can be specified by the ``--rtems-specs`` command line
+option.
+
+.. code-block:: none
+
+    $ ./waf bsp_defaults --rtems-bsps=gr712rc --rtems-compiler=gcc | grep ABI_FLAGS
+    ABI_FLAGS = -mcpu=leon3 -mfix-gr712rc
+
+.. code-block:: none
+
+    $ ./waf bsp_defaults --rtems-bsps=gr712rc --rtems-compiler=clang | grep ABI_FLAGS
+    ABI_FLAGS = -mcpu=gr712rc
+
+Configure
+---------
+
+The configure command ``./waf configure`` loads the BSP build configuration
+files and the build specification items and configures the build environment
+accordingly.  The configuration files can be specified by the ``--rtems-config``
+command line option.  It expects a comma-separated list of paths to the
+configuration files.  By default, the file ``config.ini`` is used.  The paths to
+RTEMS tools can be specified by the ``--rtems-tools`` command line option.  It
+expects a comma-separated list of prefix paths to tools, e.g.  compiler, linker,
+etc.  By default, the installation prefix is used for the RTEMS tools.  Tools
+are searched in the prefix path and also in a ``bin`` subdirectory of the prefix
+path.  The path to the build specification items can be specified by the
+``--rtems-specs`` command line option.
+
+Build, Clean, and Install
+-------------------------
+
+The commands ``./waf``, ``./waf clean``, and ``./waf install`` load the build
+specification items according to the specification paths stored in the build
+environment.  The BSP build configuration files (e.g. ``config.ini``) used by
+the ``./waf configure`` command to create the build environment are not longer
+used and may be deleted.  The build commands perform a dependency tracking and
+re-build artefacts if input sources changed.  Input sources are also the build
+specification.
+
+Configuration
+=============
+
+The BSP build configuration is done via INI-style configuration files.  The
+configuration files are consumed by the ``./waf configure`` command.  By
+default, the file ``config.ini`` is used.  You can specify other configuration
+files with the ``--rtems-config`` command line option.  The configuration files
+consist of sections and options (key-value pairs).
+
+To build a particular BSP, you have to create a section with the BSP variant
+name.
+
+.. code-block:: ini
+
+    [sparc/erc32]
+
+This one line configuration file is sufficient to build the base BSP
+`sparc/erc32` with default values for all options.  The base BSPs are determined
+by the build specification.  The ``./waf bsp_list`` command lists all base BSPs.
+You can create your own BSP names.  However, in this case you have to inherit
+from a base BSP.  The inheritance works only within an architecture, e.g. a
+`riscv` BSP cannot inherit options from an `arm` BSP.
+
+.. code-block:: ini
+
+    [sparc/foobar]
+    INHERIT = erc32
+
+The inheritance works recursively and must end up in a base BSP.
+
+.. code-block:: ini
+
+    [sparc/foo]
+    INHERIT = erc32
+
+    [sparc/bar]
+    INHERIT = foo
+
+A child BSP variant inherits all options from the parent BSP variant.  The child
+BSP can override the inherited options.
+
+You can determine the compiler used to build the BSP with the ``COMPILER``
+option.
+
+.. code-block:: ini
+
+    [sparc/gr740_gcc]
+    INHERIT = gr740
+    COMPILER = gcc
+
+    [sparc/gr740_clang]
+    INHERIT = gr740
+    COMPILER = clang
+
+Use the ``./waf bsp_defaults`` command to get a list of all configuration
+options with default values.
+
+.. code-block:: none
+
+    $ ./waf bsp_defaults --rtems-bsps=sparc/erc32
+    [sparc/erc32]
+    # Flags passed to the library archiver
+    ARFLAGS = crD
+    # Warning flags passed to the C compiler
+    CC_WARNING_FLAGS = -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs
+    # Warning flags passed to the C++ compiler
+    CXX_WARNING_FLAGS =
+    # Flags passed to the linker (GNU ld)
+    LDFLAGS = -Wl,--gc-sections
+    # Enable the Ada support
+    __RTEMS_ADA__ = False
+    # Enable the RTEMS internal debug support
+    RTEMS_DEBUG = False
+    ...
+    # Install the legacy application Makefile framework.
+    INSTALL_LEGACY_MAKEFILES = True
+
+It is not recommended to blindly add all the options obtained through the
+``./waf bsp_defaults`` command to custom configuration files.  The specified
+options should be kept at the necessary minimum to get the desired build.
+
+Some projects may still want to specify all options in a configuration file to
+be independent of changes in the base BSP.  You can review differences between
+the user and base BSP values with the ``diff`` command.
+
+.. code-block:: none
+
+    $ ./waf bsp_defaults --rtems-bsps=sparc/erc32 > config.ini
+    $ sed -i 's/BUILD_TESTS = False/BUILD_TESTS = True/' config.ini
+    $ ./waf bsp_defaults --rtems-bsps=sparc/erc32 | diff -u - config.ini
+    --- config.ini  2019-12-04 08:21:36.049335872 +0100
+    +++ -   2019-12-04 08:21:41.187432405 +0100
+    @@ -31,7 +31,7 @@
+     # Build the Ada test programs (may be also enabled by BUILD_TESTS)
+     BUILD_ADATESTS = False
+     # Build the test programs
+    -BUILD_TESTS = False
+    +BUILD_TESTS = True
+     # Build the benchmark programs (may be also enabled by BUILD_TESTS)
+     BUILD_BENCHMARKS = False
+     # Build the file system test programs (may be also enabled by
+
+There is a special section ``DEFAULT`` which can be used to specify default
+values for all other sections of the configuration file.  In the following
+example configuration file, building of the tests is enabled for the
+`sparc/erc32` and the `riscv/griscv` BSP.
+
+.. code-block:: ini
+
+    [DEFAULT]
+    BUILD_TESTS = True
+
+    [sparc/erc32]
+
+    [riscv/griscv]
diff --git a/user/index.rst b/user/index.rst
index 0e6e886..a91aa55 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -39,6 +39,7 @@ RTEMS User Manual (|version|).
     installation/index
 
     hardware/index
+    bld/index
     bsps/index
 
     exe/index
diff --git a/user/start/bootstrap.rst b/user/start/bootstrap.rst
deleted file mode 100644
index 1594f89..0000000
--- a/user/start/bootstrap.rst
+++ /dev/null
@@ -1,61 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
-
-.. _QuickStartBootstrap:
-
-Bootstrap the RTEMS Sources
-===========================
-
-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`.
-
-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 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
-
-    export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
-
-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
-
-    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
-    ...
-    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 8bc6233..137b3ab 100644
--- a/user/start/bsp-build.rst
+++ b/user/start/bsp-build.rst
@@ -132,87 +132,83 @@ has not been correctly set. Check the contents of the path
 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.
+The first step is to configure the BSP.  There are various BSP build
+configuration options available.  Some options are BSP-specific.  Each section
+in the INI-style configuration file ``config.ini`` instructs the build system to
+build a particular BSP variant (`sparc/erc32` in our case).  We enable the build
+of the tests with the ``BUILD_TESTS = True`` option and use default values for
+everything else.  For detailed information about the BSP build system, see
+:ref:`BSPBuildSystem`.
 
 .. 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 \
-        --target=sparc-rtems5 \
-        --enable-rtemsbsp=erc32 \
-        --enable-tests
+    cd $HOME/quick-start/src/rtems
+    echo "[sparc/erc32]" > config.ini
+    echo "BUILD_TESTS = True" >> config.ini
+    ./waf configure --prefix=$HOME/quick-start/rtems/5
 
-This command should output something like this (omitted lines are denoted by
-``...``):
+The first invocation of ``./waf`` needs a bit of time (e.g. 10 seconds) since an
+internal cache file is populated.  This command should output something like
+this.  In this output the base directory :file:`$HOME/quick-start` was replaced
+by ``$BASE``.
 
 .. code-block:: none
 
-    checking for gmake... gmake
-    checking for RTEMS Version... 5.0.0
-    checking build system type... x86_64-unknown-freebsd12.0
-    checking host system type... x86_64-unknown-freebsd12.0
-    checking target system type... sparc-unknown-rtems5
-    ...
-    config.status: creating Makefile
-
-    target architecture: sparc.
-    available BSPs: erc32.
-    'gmake all' will build the following BSPs: erc32.
-    other BSPs can be built with 'gmake RTEMS_BSP="bsp1 bsp2 ..."'
-
-    config.status: creating Makefile
-
-Building the BSP is the forth step.
+    Setting top to                           : $BASE/src/rtems
+    Setting out to                           : $BASE/src/rtems/build
+    Regenerate build specification cache (needs a couple of seconds)...
+    Configure board support package (BSP)    : sparc/erc32
+    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-ar'   : $BASE/rtems/5/bin/sparc-rtems5-ar
+    Checking for program 'sparc-rtems5-ld'   : $BASE/rtems/5/bin/sparc-rtems5-ld
+    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 program 'gcc, cc'           : $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
+    Checking for program 'rtems-bin2c'       : $BASE/rtems/5/bin/rtems-bin2c
+    Checking for program 'gzip'              : /usr/bin/gzip
+    Checking for program 'pax'               : /usr/bin/pax
+    Checking for program 'rtems-ld'          : $BASE/rtems/5/bin/rtems-ld
+    Checking for program 'rtems-syms'        : $BASE/rtems/5/bin/rtems-syms
+    Checking for program 'xz'                : /usr/bin/xz
+    'configure' finished successfully (11.069s)
+
+Building the BSP is the second step.
 
 .. code-block:: none
 
-    cd $HOME/quick-start/build/b-erc32
-    make
+    cd $HOME/quick-start/src/rtems
+    ./waf
 
 This command should output something like this (omitted lines are denoted by
 ...).
 
 .. code-block:: none
 
-    Configuring RTEMS_BSP=erc32
-    checking for gmake... gmake
-    checking build system type... x86_64-unknown-freebsd12.0
-    checking host system type... sparc-unknown-rtems5
-    checking rtems target cpu... sparc
-    checking for a BSD-compatible install... /usr/bin/install -c
-    checking whether build environment is sane... yes
-    checking for sparc-rtems5-strip... sparc-rtems5-strip
-    checking for a thread-safe mkdir -p... $BASE/src/rtems/c/src/../../install-sh -c -d
-    checking for gawk... no
-    checking for mawk... no
-    checking for nawk... nawk
-    checking whether gmake sets $(MAKE)... yes
-    checking whether to enable maintainer-specific portions of Makefiles... yes
-    checking for RTEMS_BSP... erc32
-    checking whether CPU supports libposix... yes
-    configure: setting up make/custom
-    configure: creating make/erc32.cache
-    gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
+    Waf: Entering directory `$BASE/src/rtems/build'
+    Waf: Leaving directory `$BASE/src/rtems/build'
+    'build' finished successfully (0.546s)
+    Waf: Entering directory `$BASE/src/rtems/build/sparc/erc32'
+    [   1/3922] Compiling bsps/sparc/shared/start/start.S
+    [   2/3922] Compiling bsps/shared/dev/serial/mc68681_reg4.c
+    [   3/3922] Compiling bsps/shared/dev/rtc/icm7170.c
     ...
-    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'
-    gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
-    gmake[1]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
-    gmake[1]: Entering directory '$BASE/build/b-erc32'
-    gmake[1]: Nothing to be done for 'all-am'.
-    gmake[1]: Leaving directory '$BASE/build/b-erc32'
+    [4038/4038] Linking build/sparc/erc32/testsuites/tmtests/tmoverhd.exe
+    Waf: Leaving directory `$BASE/src/rtems/build/sparc/erc32'
+    'build_sparc/erc32' finished successfully (58.678s)
 
 The last step is to install the BSP.
 
 .. code-block:: none
 
-    cd $HOME/quick-start/build/b-erc32
-    make install
+    cd $HOME/quick-start/src/rtems
+    ./waf install
 
 This command should output something like this (omitted lines are denoted by
 ...).  In this output the base directory :file:`$HOME/quick-start` was replaced
@@ -220,27 +216,16 @@ by ``$BASE``.
 
 .. code-block:: none
 
-    Making install in sparc-rtems5/c
-    gmake[1]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
-    Making install in .
-    gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
-    gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
-    gmake[3]: Nothing to be done for 'install-exec-am'.
-    gmake[3]: Nothing to be done for 'install-data-am'.
-    gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
-    gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
-    Making install in erc32
-    gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
-    gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
-    Making install-am in .
-    Making install-am in cpukit
-    gmake[4]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
-    gmake[5]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
-    gmake[5]: Nothing to be done for 'install-exec-am'.
-     $BASE/src/rtems/c/src/../../cpukit/../install-sh -c -d '$BASE/rtems/5/sparc-rtems5/erc32/lib/include'
+    Waf: Entering directory `$BASE/src/rtems/build'
+    Waf: Leaving directory `$BASE/src/rtems/build'
+    'install' finished successfully (0.544s)
+    Waf: Entering directory `$BASE/src/rtems/build/sparc/erc32'
+    + install $BASE/rtems/5/sparc-rtems5/erc32/lib/start.o (from build/sparc/erc32/start.o)
+    + install $BASE/rtems/5/sparc-rtems5/erc32/lib/include/bspopts.h (from build/sparc/erc32/bsps/include/bspopts.h)
+    + install $BASE/rtems/5/sparc-rtems5/erc32/lib/include/rtems/zilog/z8036.h (from bsps/include/rtems/zilog/z8036.h)
     ...
-    $BASE/src/rtems/make/Templates/Makefile.lib '$BASE/rtems/5/share/rtems5/make/Templates'
-     $BASE/src/rtems/./install-sh -c -d '$BASE/rtems/5/make/custom'
-     /usr/bin/install -c -m 644 $BASE/src/rtems/make/custom/default.cfg '$BASE/rtems/5/make/custom'
-    gmake[2]: Leaving directory '$BASE/build/b-erc32'
-    gmake[1]: Leaving directory '$BASE/build/b-erc32'
+    + install $BASE/rtems/5/sparc-rtems5/erc32/lib/include/rtems/score/watchdogimpl.h (from cpukit/include/rtems/score/watchdogimpl.h)
+    + install $BASE/rtems/5/sparc-rtems5/erc32/lib/include/rtems/score/watchdogticks.h (from cpukit/include/rtems/score/watchdogticks.h)
+    + install $BASE/rtems/5/sparc-rtems5/erc32/lib/include/rtems/score/wkspace.h (from cpukit/include/rtems/score/wkspace.h)
+    Waf: Leaving directory `$BASE/src/rtems/build/sparc/erc32'
+    'install_sparc/erc32' finished successfully (2.985s)
diff --git a/user/start/bsp-test.rst b/user/start/bsp-test.rst
index f609c59..9243f5d 100644
--- a/user/start/bsp-test.rst
+++ b/user/start/bsp-test.rst
@@ -8,20 +8,20 @@
 Test a Board Support Package (BSP)
 ==================================
 
-You built a BSP with tests in the previous section.  We built the ``erc32`` BSP
-in :file:`$HOME/quick-start/build/b-erc32`.
+You built a BSP with tests in the previous section.  We built the
+``sparc/erc32`` BSP in :file:`$HOME/quick-start/src/rtems`.
 
 You should run the RTEMS test suite on your target hardware.  The RTEMS Project
 provides some support to do this, see the :ref:`Testing <Testing>` chapter for
 the details.
 
-On the ``erc32`` BSP we selected for this quick start chapter this is easy.
-Just run this command:
+On the ``sparc/erc32`` BSP we selected for this quick start chapter this is
+easy.  Just run this command:
 
 .. code-block:: none
 
-    cd $HOME/quick-start/build/b-erc32
-    rtems-test --rtems-bsp=erc32-sis --rtems-tools=$HOME/quick-start/rtems/5 .
+    cd $HOME/quick-start/src/rtems
+    rtems-test --rtems-bsp=erc32-sis build/sparc/erc32
 
 This command should output something like this (omitted lines are denoted by
 ...).  In this output the base directory :file:`$HOME/quick-start` was replaced
@@ -30,7 +30,7 @@ by ``$BASE``.
 .. code-block:: none
 
     RTEMS Testing - Tester, 5.1.0
-     Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis --rtems-tools=$BASE/rtems/5 .
+     Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis build/sparc/erc32
      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)
     [  1/589] p:0   f:0   u:0   e:0   I:0   B:0   t:0   i:0   W:0   | sparc/erc32: dhrystone.exe
diff --git a/user/start/index.rst b/user/start/index.rst
index 8d47126..17c34e1 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -18,7 +18,6 @@ applications on top of RTEMS.
     prefixes
     sources
     tools
-    bootstrap
     bsp-build
     bsp-test
     app
diff --git a/user/start/preparation.rst b/user/start/preparation.rst
index eb0d56b..68a7927 100644
--- a/user/start/preparation.rst
+++ b/user/start/preparation.rst
@@ -45,9 +45,11 @@ 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.
+install a Python development package for this.  The Python scripts of the RTEMS
+Project expect on POSIX systems that a ``python`` command is available [1]_.
+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
 ---------------
@@ -111,3 +113,5 @@ within a release branch, for example the tools packaged with 5.1.1 still use
 the ``sparc-rtems5`` moniker, but are likely not the same as the tools used
 in version 5.1.0. This tool mismatch can be a source of confusion. Be sure to
 use the toolchain that matches your release.
+
+.. [1] The Python scripts use a shebang of ``#!/usr/bin/env python``.
-- 
2.26.2



More information about the devel mailing list