From f6720264ea8ebfdd3a6b7819650520a2d18e7c31 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Thu, 12 Mar 2020 15:13:39 +1100 Subject: 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(-) delete mode 100644 user/start/host.rst create mode 100644 user/start/preparation.rst create mode 100644 user/start/rsb-packages.rst 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 `_ 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 +`_. + +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 + + #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 + +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 + #include + #include + + 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@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) ` 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) ` 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 ` 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 ` +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 `_. 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 ` 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 ` chapter for the gory details. In -particular :ref:`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 ` -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 ` +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) `. 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 ` 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 ` 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 ` 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 ` chapter for the gory details. In +particular :ref:`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 ` +(``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 ` (``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 +`. 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 `_ 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) `. 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 `_ 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) +`. 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 +`_ 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 ` 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 +`_ 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. -- cgit v1.2.3