rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-31 11:01:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

user: Update Quick Start Guide

Browse Source 
- Add support for release source archives
- Add building the BSP using the RSB
- Add building packages using the RSB
- Add an application

Closes #2998
This commit is contained in:
Chris Johns 2020-03-12 15:13:39 +11:00
parent 88dd013b42
commit f6720264ea
12 changed files with 819 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
user/index.rst
View File

@ -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)

245
user/start/app.rst
View File

@ -1,11 +1,250 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2019 embedded brains GmbH
.. Copyright (C) 2019 Sebastian Huber
.. Copyright (C) 2020 Chris Johns
.. _QuickStartAPP:
Build Your Application
======================
TODO
You tested a BSP in the previous section. We built the ``erc32`` BSP
and it is installed under :file:`$HOME/quick-start/rtems/5`.
We will now create a simple hello world application with a Git
repository and using the `Waf <https://waf.io>`_ build system.
The application is be created in :file:`$HOME/quick-start/app/hello`.
In the output in this section the base directory :file:`$HOME/quick-start` was
replaced by ``$BASE``.
The steps in this section assume you are in the directory
:file:`$HOME/quick-start/app/hello` after the first step changes to
it.
Setup the application work space. Create a new Git repository, download
the Waf build system, and the `RTEMS Waf
<https://git.rtems.org/rtems_waf.git/tree/README>`_.
Create the application directory and change into it:
.. code-block:: none
mkdir -p $HOME/quick-start/app/hello
cd $HOME/quick-start/app/hello
Download the Waf build system and set it to executable:
.. code-block:: none
curl https://waf.io/waf-2.0.19 > waf
chmod +w waf
Initialise a new Git repository:
.. code-block:: none
git init
Add RTEMS Waf support as a Git sub-module and initialise it:
.. code-block:: none
git submodule add git://git.rtems.org/rtems_waf.git rtems_waf
Create the application source files. Three files are created with an
editor of your choice.
First create a C file that configures RTEMS. Using an editor create a
file called :file:`init.c` and copy the following configuration
settings:
.. code-block:: c
/*
* Simple RTEMS configuration
*/
#include <rtems.h>
#define CONFIGURE_APPLICATION_DOES_NOT_NEED_CLOCK_DRIVER
#define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
#define CONFIGURE_USE_DEVFS_AS_BASE_FILESYSTEM
#define CONFIGURE_RTEMS_INIT_TASKS_TABLE
#define CONFIGURE_MAXIMUM_TASKS 1
#define CONFIGURE_INIT
#include <rtems/confdefs.h>
Create the *hello world* application source file. Using an editor
create :file:`hello.c` and copy the follow code:
.. code-block:: c
/*
* Hello world example
*/
#include <rtems.h>
#include <stdlib.h>
#include <stdio.h>
rtems_task Init(
rtems_task_argument ignored
)
{
printf( "\nHello World\n" );
exit( 0 );
}
Finally create the Waf script. Using an editor create :file:`wscript`
and copy the Waf script:
.. code-block:: python
#
# Hello world Waf script
#
from __future__ import print_function
rtems_version = "5"
try:
import rtems_waf.rtems as rtems
except:
print('error: no rtems_waf git submodule')
import sys
sys.exit(1)
def init(ctx):
rtems.init(ctx, version = rtems_version, long_commands = True)
def bsp_configure(conf, arch_bsp):
# Add BSP specific configuration checks
pass
def options(opt):
rtems.options(opt)
def configure(conf):
rtems.configure(conf, bsp_configure = bsp_configure)
def build(bld):
rtems.build(bld)
bld(features = 'c cprogram',
target = 'hello.exe',
cflags = '-g -O2',
source = ['hello.c',
'init.c'])
Configure the application using Waf's ``configure`` command:
.. code-block:: none
./waf configure --rtems=$HOME/quick-start/rtems/5 --rtems-bsp=sparc/erc32
The output will be something close to:
.. code-block:: none
Setting top to : $BASE/app/hello
Setting out to : $BASE/app/hello/build
RTEMS Version : 5
Architectures : sparc-rtems5
Board Support Package (BSP) : sparc-rtems5-erc32
Show commands : no
Long commands : no
Checking for program 'sparc-rtems5-gcc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
Checking for program 'sparc-rtems5-g++' : $BASE/rtems/5/bin/sparc-rtems5-g++
Checking for program 'sparc-rtems5-gcc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
Checking for program 'sparc-rtems5-ld' : $BASE/rtems/5/bin/sparc-rtems5-ld
Checking for program 'sparc-rtems5-ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
Checking for program 'sparc-rtems5-nm' : $BASE/rtems/5/bin/sparc-rtems5-nm
Checking for program 'sparc-rtems5-objdump' : $BASE/rtems/5/bin/sparc-rtems5-objdump
Checking for program 'sparc-rtems5-objcopy' : $BASE/rtems/5/bin/sparc-rtems5-objcopy
Checking for program 'sparc-rtems5-readelf' : $BASE/rtems/5/bin/sparc-rtems5-readelf
Checking for program 'sparc-rtems5-strip' : $BASE/rtems/5/bin/sparc-rtems5-strip
Checking for program 'sparc-rtems5-ranlib' : $BASE/rtems/5/bin/sparc-rtems5-ranlib
Checking for program 'rtems-ld' : $BASE/rtems/5/bin/rtems-ld
Checking for program 'rtems-tld' : $BASE/rtems/5/bin/rtems-tld
Checking for program 'rtems-syms' : $BASE/rtems/5/bin/rtems-syms
Checking for program 'rtems-bin2c' : $BASE/rtems/5/bin/rtems-bin2c
Checking for program 'tar' : /usr/bin/tar
Checking for program 'gcc, cc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
Checking for program 'ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
Checking for program 'g++, c++' : $BASE/rtems/5/bin/sparc-rtems5-g++
Checking for program 'ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
Checking for program 'gas, gcc' : $BASE/rtems/5/bin/sparc-rtems5-gcc
Checking for program 'ar' : $BASE/rtems/5/bin/sparc-rtems5-ar
Checking for c flags '-MMD' : yes
Checking for cxx flags '-MMD' : yes
Compiler version (sparc-rtems5-gcc) : 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
Checking for a valid RTEMS BSP installation : yes
Checking for RTEMS_DEBUG : no
Checking for RTEMS_MULTIPROCESSING : no
Checking for RTEMS_NEWLIB : yes
Checking for RTEMS_POSIX_API : yes
Checking for RTEMS_SMP : no
Checking for RTEMS_NETWORKING : no
'configure' finished successfully (0.686s)
Build the application:
.. code-block:: none
./waf
The output will be something close to:
.. code-block:: none
Waf: Entering directory `$BASE/app/hello/build/sparc-rtems5-erc32'
[1/3] Compiling init.c
[2/3] Compiling hello.c
[3/3] Linking build/sparc-rtems5-erc32/hello.exe
Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems5-erc32'
'build-sparc-rtems5-erc32' finished successfully (0.183s)
Run the executable:
.. code-block:: none
$HOME/quick-start/rtems/5/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems5-erc32/hello.exe
The output will be something close to:
.. code-block:: none
RTEMS Testing - Run, 5.1.0
Command Line: $BASE/rtems/5/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems5-erc32/hello.exe
Host: FreeBSD hihi 12.1-RELEASE-p2 FreeBSD 12.1-RELEASE-p2 GENERIC amd64
Python: 3.7.6 (default, Jan 30 2020, 01:18:54) [Clang 6.0.1 (tags/RELEASE_601/final 335540)]
Host: FreeBSD-12.1-RELEASE-p2-amd64-64bit-ELF (FreeBSD hihi 12.1-RELEASE-p2 FreeBSD 12.1-RELEASE-p2 GENERIC amd64 amd64)
SIS - SPARC/RISCV instruction simulator 2.21, copyright Jiri Gaisler 2019
Bug-reports to jiri@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."

72
user/start/bootstrap.rst
View File

@ -8,48 +8,54 @@
Bootstrap the RTEMS Sources
===========================
You installed the tool suite in your installation prefix and cloned two RTEMS
repositories in the previous sections. We installed the tool suite in
:file:`$HOME/quick-start/rtems/5` and cloned the repositories in
:file:`$HOME/quick-start/src`.
You installed the tool suite in your installation prefix and made ready the
source for two RTEMS source packages in the previous sections. We installed
the tool suite in :file:`$HOME/quick-start/rtems/5` and unpacked the RSB source
in :file:`$HOME/quick-start/src`.
If you use source archives of a released RTEMS version, then you can skip this
section.
You only need to *bootstrap* the RTEMS sources if you have used
:ref:`QuickStartSources_Git` to get the sources. If you use source archives of
a released RTEMS version you can skip this section and move to
:ref:`QuickStartBSPBuild`.
Before you can build a :ref:`Board Support Package (BSP) <BSPs>` for your
target hardware, you have to bootstrap the build system in the RTEMS sources.
This is only necessary, if you use a Git repository clone of the RTEMS sources.
You have to do this after a fresh repository clone and sometimes after build
system file updates (e.g. after a ``git pull``). If you are not a build
system expert, then do the bootstrap after each update of build system files.
This is a bit annoying, but improving the build system is a complex and time
consuming undertaking. Feel free to help the RTEMS Project to improve it. For
the bootstrap it is important that the right version of Autotools
(:file:`autoconf` and :file:`automake`) are in your ``$PATH``. The right
version of Autotools is shipped with the RTEMS tool suite you already
installed.
target hardware from Git cloned RTEMS sources, you have to bootstrap the build
system in the RTEMS sources. This is only necessary if you use a Git
repository clone of the RTEMS sources. You have to do this after a fresh
repository clone and sometimes after build system file updates (e.g. after a
``git pull``). If you are not a build system expert, then do the bootstrap
after each update of build system files. This is a bit annoying, but improving
the build system is a complex and time consuming undertaking. Feel free to
help the RTEMS Project to improve it. For the bootstrap it is important that
the right version of Autotools (:file:`autoconf` and :file:`automake`) are in
your ``$PATH``. The right version of Autotools is shipped with the RTEMS tool
suite you already installed. Set the path to the tool suite installed under
your selected *prefix*:
.. code-block:: none
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
export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
./bootstrap -c
$HOME/quick-start/src/rsb/source-builder/sb-bootstrap
./rtems-bootstrap
These commands should output something like this (omitted lines are denoted by
...):
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

142
user/start/bsp-build.rst
View File

@ -8,35 +8,134 @@
Build a Board Support Package (BSP)
===================================
You installed the tool suite in your installation prefix, cloned two RTEMS
repositories and bootstrapped the RTEMS sources in the previous sections. We
installed the tool suite in :file:`$HOME/quick-start/rtems/5` and cloned the
repositories in :file:`$HOME/quick-start/src`. We also bootstrapped the RTEMS
sources.
You installed the tool suite in your installation prefix, made ready the source
for two RTEMS source packages and if you are using a Git clone bootstrapped the
RTEMS sources in the previous sections. We installed the tool suite in
:file:`$HOME/quick-start/rtems/5` and unpacked the source in
:file:`$HOME/quick-start/src`.
You are now able to build :ref:`Board Support Packages (BSPs) <BSPs>` for all
architectures where you have an RTEMS tool suite installed. To build
applications on top of RTEMS, you have to configure, build and install a BSP
for your target hardware. To select a proper BSP for your target hardware
consult the :ref:`BSPs <BSPs>` chapter. We select the `erc32` BSP.
architectures you have an installed RTEMS tool suite. To build applications on
top of RTEMS, you have to build and install a BSP for your target hardware. To
select a proper BSP for your target hardware consult the :ref:`BSPs <BSPs>`
chapter. We select the `erc32` BSP. The ``erc32`` BSP uses approximately 2.3G
bytes of disk space when the testsuite is built and 44M bytes of space when
installed.
We configure, build and install the BSP in four steps. The first step is to
create a build directory. It must be separate from the RTEMS source directory.
We use :file:`$HOME/quick-start/build/b-erc32`.
We will first show how to build the BSP using the RSB and then we will show how
to build the same BSP `manually <QuickStartBSPBuild_Manual>`_. You only need to
use one of the listed methods to build the BSP.
In the output in this section the base directory :file:`$HOME/quick-start` was
replaced by ``$BASE``.
.. QuickStartBSPBuild_RSB:
RSB BSP Build
-------------
The RSB build of RTEMS does not use the RTEMS source we made ready. It uses the
RSB source you downloaded in a previous section. If you are using a release RSB
source archive the BSP built is the released kernel image. If you are using a
Git clone of the RSB the BSP will be version referenced in the RSB clone.
To build the BSP with all the tests run this command:
.. code-block:: none
cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
--target=sparc-rtems5 --with-rtems-bsp=erc32 --with-rtems-tests=yes 5/rtems-kernel
This command should output something like this:
.. code-block:: none
RTEMS Source Builder - Set Builder, 5.1.0
Build Set: 5/rtems-kernel
config: tools/rtems-kernel-5.cfg
package: sparc-rtems5-kernel-erc32-1
building: sparc-rtems5-kernel-erc32-1
sizes: sparc-rtems5-kernel-erc32-1: 2.279GB (installed: 44.612MB)
cleaning: sparc-rtems5-kernel-erc32-1
reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-erc32-1.txt
reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-erc32-1.xml
installing: sparc-rtems5-kernel-erc32-1 -> $BASE/
cleaning: sparc-rtems5-kernel-erc32-1
Build Set: Time 0:03:09.896961
The RSB BSP build can be customised with following RSB command line options:
``--with-rtems-tests``:
Build the test suite. If ``yes`` is provided all tests in the testsuite are
build. If ``no`` is provided no tests are built and if ``samples`` is
provided only the sample executables are built, e.g.
``--with-rtems-tests=yes``.
``--with-rtems-smp``:
Build with SMP support. The BSP has to have SMP support or this option will
fail with an error.
``--with-rtems-legacy-network``:
Build the legacy network software. We recommend you use the current network
support in the RTEMS BSP Library (libbsd) unless you need to maintain a
legacy product. Do not use the legacy networking software for new
developments.
``--with-rtems-bspopts``:
Build the BSP with BSP specific options. This is an advanced option. Please
refer to the BSP specific details in the :ref:`Board Support Packages
(BSPs)` of this manual or the BSP source code in the RTEMS source
directory. To supply a list of options quote then list with ``"``, e.g.
``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"``
If you have built a BSP with the RSB, you can move on to
:ref:`QuickStartBSPTest`.
.. QuickStartBSPBuild_Manual:
Manual BSP Build
----------------
We manually build the BSP in four steps. The first step is to create a build
directory. It must be separate from the RTEMS source directory. We use
:file:`$HOME/quick-start/build/b-erc32`.
.. code-block:: none
mkdir -p $HOME/quick-start/build/b-erc32
The second step is to configure the BSP. There are various configuration
options available. Some configuration options are BSP-specific. Prepend the
RTEMS tool suite binary directory to your ``$PATH`` throughout the remaining
steps.
The second step is to set your path. Prepend the RTEMS tool suite binary
directory to your ``$PATH`` throughout the remaining steps. Run the command:
.. code-block:: none
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
export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
$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'

2
user/start/bsp-test.rst
View File

@ -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)

21
user/start/host.rst
View File

@ -1,21 +0,0 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2019 embedded brains GmbH
.. Copyright (C) 2019 Sebastian Huber
.. _QuickStartHost:
Prepare Your Host Computer
==========================
The *host computer* is a computer you use to develop applications. It runs all
your tools, editors, documentation viewers, etc. To get started with RTEMS
development you need tools from your host's operating system to build the RTEMS
tool suite from source. This is not a one-click installation process, but
there are :ref:`good reasons <WhyBuildFromSource>` to build everything from
source. You need a native C, C++ and Python development environment. Please
make sure that you can build native C/C++ applications on your host computer.
You must be able to build native Python C modules. Usually, you have to
install a Python development package for this. Please have a look at the
:ref:`Host Computer <host-computer>` chapter for the gory details. In
particular :ref:`Microsoft Windows <microsoft-windows>` user should do this.

3
user/start/index.rst
View File

@ -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

35
user/start/prefixes.rst
View File

@ -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.
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:`other tools <HostTools>`
provided by the RTEMS Project. The RTEMS
Newlib, etc.) for your target architecture and :ref:`RTEMS tools <HostTools>`
provided by the RTEMS Project. The RTEMS Tools are a toolkit that help create
the RTEMS ecosystem and help support the building of embedded real-time
applications and systems.
You build and install the tool suite with the :ref:`RTEMS Source Builder (RSB)
<RSB>`. By default, the RSB will start the prefix path with a host operating
system specific path plus :file:`rtems` plus the RTEMS version, e.g.
:file:`/opt/rtems/5` on Linux and :file:`/usr/local/rtems/5` on FreeBSD and
macOS.
system specific path plus :file:`rtems`, and the RTEMS version, e.g.
:file:`/opt/rtems/5` on Linux, and :file:`/usr/local/rtems/5` on FreeBSD and
macOS. Placing the RTEMS version number in the path lets you manage and
migrate RTEMS versions as they are released.
It is strongly recommended to run the RSB as a *normal user* and not with
*root* privileges (also known as *super user* or *Administrator*). You have to
make sure that your normal user has sufficient privileges to create files and
directories under the prefix. For example, you can create a directory
:file:`/opt/rtems` and give it to a developer group with read, write and
:file:`/opt/rtems` and give it to a developer group with read, write, and
execute permissions. Alternatively, you can choose a prefix in your home
directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component
:file:`$HOME/project-x/rtems/5`. For more ideas, see the
:ref:`project sandboxing <ProjectSandboxing>` section. In this quick start
chapter, we will choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool
suite prefix.
:file:`$HOME/project-x/rtems/5`. For more ideas, see the :ref:`project
sandboxing <ProjectSandboxing>` section. In this quick start chapter, we will
choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool suite prefix.
.. warning::

64
user/start/preparation.rst Normal file
View File

@ -0,0 +1,64 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
.. Copyright (C) 2019 embedded brains GmbH
.. Copyright (C) 2019 Sebastian Huber
.. Copyright (C) 2020 Chris Johns
.. _QuickStartPreparation:
Preparation
===========
You need to perform some basic preparation to get started with RTEMS
development. You need tools from your host's operating system to build the
RTEMS tool suite from source. The RTEMS tools you build are used to build the
Board Support Package (BSP) libraries for your target hardware from source. The
BSP libraries contain the RTEMS operating system. This is not a one-click
installation process, but there are :ref:`good reasons <WhyBuildFromSource>` to
build everything from source.
During this Quick Start guide you will:
* Select a suitable place to install RTEMS.
* Select if you download all the source code before you start building RTEMS or
the source is downloaded on demand as it is needed. If you do not have a
reliable internet connection we recommend you download all the source before
starting a build.
* Build a tool suite.
* Build and test a BSP.
* Optionally build additional packages.
Alternatively you can build a BSP as a package using the RSB. This is
covered in :ref:`QuickStartBSPPackages`
Host Computer
-------------
The *host computer* is a computer you use to develop applications. It runs all
your tools, editors, documentation viewers, etc. You need a native C, C++, and
Python development environment. Please make sure you can build native C/C++
applications on your host computer. You must be able to build native Python C
modules as some RTEMS tools contain these modules. Usually, you have to
install a Python development package for this. Please have a look at the
:ref:`Host Computer <host-computer>` chapter for the gory details. In
particular :ref:`Microsoft Windows <microsoft-windows>` users should do this.
Selecting a BSP
---------------
If you are new to RTEMS and you are looking to try RTEMS then the best suited
Board Support Package (BSP) is the :ref:`SPARC ERC32 <BSP_sparc_erc32>`
(``erc32``). The SPARC ERC32 BSP has a robust simulator that runs the example
and test executables on your host computer. This Quick Start guide will build
the ``erc32`` BSP and run RTEMS tests executables in the simulator. The ERC32
BSP is a SPARC architecture BSP so the tool suite name is ``sparc-rtems5``.
If you are looking for a hardware target to run RTEMS on we recommend the
:ref:`BeagleBone Black <BSP_arm_beagleboneblack>` (``beagleboneblack``)
BSP. The BeagleBone Black support includes the RTEMS BSD Library (``libbsd``)
and networking. The BeagleBone Black BSP is an ARM architecture BSP so the tool
suite name is ``arm-rtems5``.

184
user/start/rsb-packages.rst Normal file
View File

@ -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.

131
user/start/sources.rst
View File

@ -2,6 +2,7 @@
.. Copyright (C) 2019 embedded brains GmbH
.. Copyright (C) 2019 Sebastian Huber
.. Copyright (C) 2020 Chris Johns
.. _QuickStartSources:
@ -10,14 +11,80 @@ Obtain the Sources
You have considered and chosen a suitable installation prefix in the previous
section. We have chosen :file:`$HOME/quick-start/rtems/5` as the installation
prefix.
prefix. We will show how to use a released version of RTEMS and then as an
alternative we will show you using the :ref:`RSB Git repository
<QuickStartSources_Git>`. Consider using a Git clone if you wish to make
contributions to the RTEMS Project.
You need at least two source archives or Git repositories to work with RTEMS.
You can download the source archives for a released RTEMS version or you can
clone Git repositories to get all versions of RTEMS including the development
head.
You need the RTEMS Source Builder (RSB) to work with RTEMS and we prefer you
use a released version. A released version of the RSB downloads all source code
from the RTEMS servers. Each release archives all the referenced source
providing long term stability as changes in upstream projects do not effect a
release's build.
We will clone the Git repositories into :file:`$HOME/quick-start/src`.
You will need approximately 1.5G bytes of disk space to build the tools, RTEMS
kernel, network stack and 3rd party packages for the ERC32 BSP.
.. _QuickStartSources_Released:
Releases
--------
You can download the source archives for a released RTEMS version from RTEMS'
servers. Releases can be view at https://ftp.rtems.org/pub/rtems/releases with
the releases listed as a series under a release's major number. For RTEMS 5.1.0
the release series is `5 <https://ftp.rtems.org/pub/rtems/releases/5>`_ and the
release path is https://ftp.rtems.org/pub/rtems/releases/5/5.1.0.
To work with the archives of a released RTEMS version, simply replace the
version number ``5`` used throughout this chapter with the version number you
selected, e.g. ``sparc-rtems4.11``, ``sparc-rtems6``, and so on.
Download and unpack using the ``curl`` and ``tar`` command with these commands:
.. code-block:: none
mkdir -p $HOME/quick-start/src
cd $HOME/quick-start/src
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
---
Alternatively, clone the Git repositories into :file:`$HOME/quick-start/src`.
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
@ -26,27 +93,41 @@ We will clone the Git repositories into :file:`$HOME/quick-start/src`.
git clone git://git.rtems.org/rtems-source-builder.git rsb
git clone git://git.rtems.org/rtems.git
The :file:`rsb` repository clone contains the
:ref:`RTEMS Source Builder (RSB) <RSB>`. We clone it into
:file:`rsb` to get shorter paths during the tool suite build. The
:file:`rtems` repository clone contains the RTEMS sources. These two
repositories are enough to get started. There are
`more repositories <https://git.rtems.org>`_ available.
The :file:`rsb` repository clone contains the :ref:`RTEMS Source Builder (RSB)
<RSB>`. We clone it into :file:`rsb` to get shorter paths during the tool
suite build. The :file:`rtems` repository clone contains the RTEMS sources.
These two repositories are enough to get started. There are `more repositories
<https://git.rtems.org>`_ available.
Alternatively, you can download the source archives of a released RTEMS
version.
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
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 -
cd $HOME/quick-start/src/rsb/rtems
../source-builder/sb-set-builder --source-only-download 5/rtems-sparc
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.
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.

126
user/start/tools.rst
View File

@ -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 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 must select the
:ref:`target architecture <TargetArchitectures>` for which you need a tool
suite. In this quick start chapter we choose `sparc-rtems5`. The
`sparc-rtems5` is the tool suite name for the SPARC architecture and RTEMS
version 5. The tool suite for RTEMS and the RTEMS sources are tightly coupled.
For example, do not use a RTEMS version 5 tool suite with RTEMS version 4.11
sources and vice versa. We use the RSB in two steps. The first step is to
download additional sources and patches. Afterwards, you could disconnect your
host computer from the internet. It is no longer required to work with RTEMS.
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.
.. 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
If you encounter errors in the first step, check your internet connection,
firewall settings, virus scanners and the availability of the download servers.
The seconds step is to build and install the tool suite.
Build and install the tool suite:
.. code-block:: none
@ -52,75 +27,52 @@ The seconds step is to build and install the tool suite.
../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 5/rtems-sparc
This command should output something like this (omitted lines are denoted by
...):
...). The build host appears as part of the name of the package being
built. The name you see may vary depending on the host you are using:
.. code-block:: none
RTEMS Source Builder - Set Builder, 5 (98588a55961a)
warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip
RTEMS Source Builder - Set Builder, 5.1.0
Build Set: 5/rtems-sparc
...
config: tools/rtems-gcc-7.4.0-newlib-3e24fbf6f.cfg
package: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
building: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
sizes: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1: 4.651GB (installed: 879.191MB)
cleaning: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
config: tools/rtems-binutils-2.34.cfg
package: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
building: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
sizes: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1: 305.866MB (installed: 29.966MB)
cleaning: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.txt
reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.xml
config: tools/rtems-gcc-7.5.0-newlib-fbaa096.cfg
package: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
building: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
....
Build Sizes: usage: 5.618GB total: 1.105GB (sources: 141.559MB, patches: 185.823KB, installed 989.908MB)
Build Set: Time 0:22:02.262039
Build Sizes: usage: 5.684GB total: 1.112GB (sources: 143.803MB, patches: 21.348KB, installed 995.188MB)
Build Set: Time 0:21:35.626294
In case the seconds step was successful, you can check if for example the cross
C compiler works with the following command:
Once the build has successfully completed you can check if the cross C compiler
works with the following command:
.. code-block:: none
$HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc --version --verbose
$HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc --version
This command should output something like below. In this output the actual
prefix path was replaced by ``$PREFIX``. The ``compiled by`` line depends on
the native C++ compiler of your host computer. In the output you see the Git
hash of the RSB. This helps you to identify the exact sources which were used
to build the cross compiler of your RTEMS tool suite.
This command should output something like below. The version informtion helps
you to identify the exact sources used to build the cross compiler of your
RTEMS tool suite. In the output you see the version of RTEMS or the hash from
the RSB repository if you are building using a Git repository clone. The Newlib
hash is the version of Newlib in the RTEMS's github
`sourceware-mirror-newlib-cygwin
<https://github.com/RTEMS/sourceware-mirror-newlib-cygwin>`_ repository. The
``sources`` and ``patches`` directories created by the RSB contain all the
source code used.
.. code-block:: none
Using built-in specs.
COLLECT_GCC=$PREFIX/bin/sparc-rtems5-gcc
COLLECT_LTO_WRAPPER=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/lto-wrapper
sparc-rtems5-gcc (GCC) 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
sparc-rtems5-gcc (GCC) 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
Copyright (C) 2017 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Target: sparc-rtems5
Configured with: ../gcc-7.4.0/configure --prefix=$PREFIX --bindir=$PREFIX/bin --exec_prefix=$PREFIX --includedir=$PREFIX/include --libdir=$PREFIX/lib --libexecdir=$PREFIX/libexec --mandir=$PREFIX/share/man --infodir=$PREFIX/share/info --datadir=$PREFIX/share --build=x86_64-freebsd12.0 --host=x86_64-freebsd12.0 --target=sparc-rtems5 --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib --disable-nls --without-included-gettext --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto --enable-newlib-io-c99-formats --enable-newlib-iconv --enable-newlib-iconv-encodings=big5,cp775,cp850,cp852,cp855,cp866,euc_jp,euc_kr,euc_tw,iso_8859_1,iso_8859_10,iso_8859_11,iso_8859_13,iso_8859_14,iso_8859_15,iso_8859_2,iso_8859_3,iso_8859_4,iso_8859_5,iso_8859_6,iso_8859_7,iso_8859_8,iso_8859_9,iso_ir_111,koi8_r,koi8_ru,koi8_u,koi8_uni,ucs_2,ucs_2_internal,ucs_2be,ucs_2le,ucs_4,ucs_4_internal,ucs_4be,ucs_4le,us_ascii,utf_16,utf_16be,utf_16le,utf_8,win_1250,win_1251,win_1252,win_1253,win_1254,win_1255,win_1256,win_1257,win_1258 --enable-threads --disable-plugin --enable-libgomp --enable-languages=c,c++
Thread model: rtems
gcc version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (GCC)
COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/cc1 -quiet -v -iprefix $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/ help-dummy -quiet -dumpbase help-dummy -mcpu=v7 -auxbase help-dummy -version --version -o /tmp//ccuAN1wc.s
GNU C11 (GCC) version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (sparc-rtems5)
compiled by GNU C version 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540), GMP version 6.1.0, MPFR version 3.1.4, MPC version 1.0.3, isl version isl-0.16.1-GMP
GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072
COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/as -v -s --version -o /tmp//ccFVgRAa.o /tmp//ccuAN1wc.s
GNU assembler version 2.32 (sparc-rtems5) using BFD version (GNU Binutils) 2.32
GNU assembler (GNU Binutils) 2.32
Copyright (C) 2019 Free Software Foundation, Inc.
This program is free software; you may redistribute it under the terms of
the GNU General Public License version 3 or later.
This program has absolutely no warranty.
This assembler was configured for a target of `sparc-rtems5'.
COMPILER_PATH=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../libexec/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/
LIBRARY_PATH=$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../lib/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/
COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/collect2 --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc
collect2 version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/ld --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc
GNU ld (GNU Binutils) 2.32
Copyright (C) 2019 Free Software Foundation, Inc.
This program is free software; you may redistribute it under the terms of
the GNU General Public License version 3 or (at your option) a later version.
This program has absolutely no warranty.
COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
Add ``--verbose`` to the GCC command for the the verbose version details.