From 4ea43e39c76ba4a5407916a21d0300a7099305e9 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Fri, 22 Nov 2019 15:32:28 +0100 Subject: user: Document BSP new build system Update #3818. --- 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 ++- 5 files changed, 81 insertions(+), 154 deletions(-) delete mode 100644 user/start/bootstrap.rst (limited to 'user/start') 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) ` 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 ` 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 ` chapter for the gory details. In -particular :ref:`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 ` chapter for the +gory details. In particular :ref:`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``. -- cgit v1.2.3