[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