rtems-docs/rsb/quick-start.rst

.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. comment COPYRIGHT (c) 2012 - 2016.
.. comment Chris Johns <chrisj@rtems.org>

Quick Start
===========

The quick start will show you how to build a set of RTEMS tools for a supported
architecture. The tools are installed into a build *prefix*. The *prefix* is the
top of a group of directories containing all the files needed to develop RTEMS
applications. Building an RTEMS build set will build all that you need. This
includes autoconf, automake, assemblers, linkers, compilers, debuggers,
standard libraries and RTEMS itself.

There is no need to become root or the administrator and we recommend you
avoid doing this. You can build and install the tools anywhere on the
host's file system you, as a standard user, have read and write access
too. I recommend you use your home directory and work under the directory
``~/development/rtems``. The examples shown here will do this.

You can use the build *prefix* to install and maintain different versions of
the tools. Doing this lets you try a new set of tools while not touching your
proven working production set of tools. Once you have proven the new tools are
working rebuild with the *production* prefix switching your development to them.

We recommend you keep your environment to the bare minimum, particularly the
path variable. Using environment variables has been proven over the years to be
difficult to manage in production systems.

.. warning::

    The RSB assumes your host is set up and the needed packages are installed
    and configured to work. If your host has not been set up please refer to
    :ref:`Hosts` and your host's section for packages you need to install.

.. topic:: Path to use when building applications:

    Do not forget to set the path before you use the tools, for example to
    build the RTEMS kernel.

    The RSB by default will install (copy) the executables to a directory tree
    under the *prefix* you supply. To use the tools once finished just set your
    path to the ``bin`` directory under the *prefix* you use. In the examples
    that follow the *prefix* is ``$HOME/development/rtems/4.11`` and is set
    using the ``--prefix`` option so the path you need to configure to build
    applications can be set with the following in a BASH shell:

    .. code-block:: shell

      $ export PATH=$HOME/development/rtems/4.11/bin:$PATH

    Make sure you place the RTEMS tool path at the front of your path so they
    are searched first. RTEMS can provide newer versions of some tools your
    operating system provides and placing the RTEMS tools path at the front
    means it is searched first and the RTEMS needed versions of the tools are
    used.

.. note::

    RSB and RTEMS have a matching *git branch* for each version of RTEMS. For
    example, if you want to build a toolchain for 4.11, then you should
    checkout the 4.11 branch of the RSB:

    .. code-block:: shell

      $ git checkout -t origin/4.11

    Branches are available for the 4.9, 4.10, and 4.11 versions of RTEMS.

Setup
-----

Setup a development work space::

    $ cd
    $ mkdir -p development/rtems/src
    $ cd development/rtems/src

The RTEMS Source Builder is distributed as source. It is Python code so all you
need to do is download the release's RSB tarball or clone the code directly
from the RTEMS GIT repository::

    $ git clone git://git.rtems.org/rtems-source-builder.git
    $ cd rtems-source-builder

.. topic:: Workspaces

   The examples in the *Quick Start Guide* build and install tools in your
   *home* directory. Please refer to the RTEMS User Manual for more detail
   about *Sandboxing* and the *prefix*.

Checking
--------

The next step is to check if your host is set up correctly. The RTEMS Source
Builder provides a tool to help::

    $ source-builder/sb-check
    warning: exe: absolute exe found in path: (__objcopy) /usr/local/bin/objcopy <1>
    warning: exe: absolute exe found in path: (__objdump) /usr/local/bin/objdump
    error: exe: not found: (_xz) /usr/local/bin/xz    <2>
    RTEMS Source Builder environment is not correctly set up
    $ source-builder/sb-check
    RTEMS Source Builder environment is ok   <3>

.. topic:: Items:

  1. A tool is in the environment path but it does not match the expected path.

  2. The executable ``xz`` is not found.

  3. The host's environment is set up correct.

The checking tool will output a list of executable files not found if problems
are detected. Locate those executable files and install them. You may also be
given a list of warnings about executable files not in the expected location
however the executable was located somewhere in your environment's path. You
will need to check each tool to determine if this is an issue. An executable
not in the standard location may indicate it is not the host operating system's
standard tool. It maybe ok or it could be buggy, only you can determine this.

The :ref:`Hosts` section lists packages you should install for common host
operating systems. It maybe worth checking if you have those installed.

Build Sets
----------

The RTEMS tools can be built within the RTEMS Source Builder's source tree. We
recommend you do this so lets change into the RTEMS directory in the RTEMS
Source Builder package::

    $ cd rtems

If you are unsure how to specify the build set for the architecture you wish to
build ask the tool::

    $ ../source-builder/sb-set-builder --list-bsets   <1>
    RTEMS Source Builder - Set Builder, v4.11.0
    Examining: config
    Examining: ../source-builder/config    <2>
        4.10/rtems-all.bset      <3>
        4.10/rtems-arm.bset      <4>
        4.10/rtems-autotools.bset
        4.10/rtems-avr.bset
        4.10/rtems-bfin.bset
        4.10/rtems-h8300.bset
        4.10/rtems-i386.bset
        4.10/rtems-lm32.bset
        4.10/rtems-m32c.bset
        4.10/rtems-m32r.bset
        4.10/rtems-m68k.bset
        4.10/rtems-mips.bset
        4.10/rtems-nios2.bset
        4.10/rtems-powerpc.bset
        4.10/rtems-sh.bset
        4.10/rtems-sparc.bset
        4.11/rtems-all.bset
        4.11/rtems-arm.bset
        4.11/rtems-autotools.bset
        4.11/rtems-avr.bset
        4.11/rtems-bfin.bset
        4.11/rtems-h8300.bset
        4.11/rtems-i386.bset
        4.11/rtems-lm32.bset
        4.11/rtems-m32c.bset
        4.11/rtems-m32r.bset
        4.11/rtems-m68k.bset
        4.11/rtems-microblaze.bset
        4.11/rtems-mips.bset
        4.11/rtems-moxie.bset
        4.11/rtems-nios2.bset
        4.11/rtems-powerpc.bset
        4.11/rtems-sh.bset
        4.11/rtems-sparc.bset
        4.11/rtems-sparc64.bset
        4.11/rtems-v850.bset
        4.9/rtems-all.bset
        4.9/rtems-arm.bset
        4.9/rtems-autotools.bset
        4.9/rtems-i386.bset
        4.9/rtems-m68k.bset
        4.9/rtems-mips.bset
        4.9/rtems-powerpc.bset
        4.9/rtems-sparc.bset
        gnu-tools-4.6.bset
        rtems-4.10-base.bset    <5>
        rtems-4.11-base.bset
        rtems-4.9-base.bset
        rtems-base.bset         <5>

.. topic:: Items:

  1. Only option required is ``--list-bsets``

  2. The paths inspected. See :ref:`Configuration`.

  3. A build set to build all RTEMS 4.10 supported architectures.

  4. The build set for the ARM architecture on RTEMS 4.10.

  5. Support build set file with common functionality included by other build
     set files.

Building
--------

The quick start builds a SPARC tool set::

    $ ../source-builder/sb-set-builder --log=l-sparc.txt \   <1>
          --prefix=$HOME/development/rtems/4.11 \       <2>
          4.11/rtems-sparc           <3>
    Source Builder - Set Builder, v0.2.0
    Build Set: 4.11/rtems-sparc
    config: expat-2.1.0-1.cfg        <4>
    package: expat-2.1.0-x86_64-freebsd9.1-1
    building: expat-2.1.0-x86_64-freebsd9.1-1
    config: tools/rtems-binutils-2.22-1.cfg        <5>
    package: sparc-rtems4.11-binutils-2.22-1
    building: sparc-rtems4.11-binutils-2.22-1
    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg   <6>
    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    config: tools/rtems-gdb-7.5.1-1.cfg      <7>
    package: sparc-rtems4.11-gdb-7.5.1-1
    building: sparc-rtems4.11-gdb-7.5.1-1
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <8>
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    cleaning: expat-2.1.0-x86_64-freebsd9.1-1     <9>
    cleaning: sparc-rtems4.11-binutils-2.22-1
    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    cleaning: sparc-rtems4.11-gdb-7.5.1-1
    Build Set: Time 0:13:43.616383        <10>

.. topic:: Items

  1. Providing a log file redirects the build output into a file. Logging the
     build output provides a simple way to report problems.

  2. The prefix is the location on your file system the tools are installed
     into. Provide a prefix to a location you have read and write access. You
     can use the prefix to install different versions or builds of tools. Just
     use the path to the tools you want to use when building RTEMS.

  3. The build set. This is the SPARC build set. First a specifically
     referenced file is checked for and if not found the ``%{_configdir}`` path
     is searched. The set builder will first look for files with a ``.bset``
     extension and then for a configuration file with a ``.cfg`` extension.

  4. The SPARC build set first builds the expat library as it is used in GDB.
     This is the expat configuration used.

  5. The binutils build configuration.

  6. The GCC and Newlib build configuration.

  7. The GDB build configuration.

  8. Installing the built packages to the install prefix.

  9. All the packages built are cleaned at the end. If the build fails all the
     needed files are present. You may have to clean up by deleting the build
     directory if the build fails.

  10. The time to build the package. This lets you see how different host
      hardware or configurations perform.

Your SPARC RTEMS 4.11 tool set will be installed and ready to build RTEMS and
RTEMS applications. When the build runs you will notice the tool fetch the
source code from the internet. These files are cached in directies called
``source`` and ``patches``. If you run the build again the cached files are
used. This is what happened in the shown example. Archiving these directories
archives the source you need to recreate the build.

.. topic:: RTEMS Releases

  The RSB found in a release will automatically build and install RTEMS. If you
  do not want a released version of the RSB to build RTEMS add
  ``--without-rtems`` to the command line. The development version requires
  adding ``--with-rtems`` to build RTEMS. Use this option to create a single
  command to build the tools and RTEMS.

  The source used in release builds is downloaded from the RTEMS FTP
  server. This ensures the source is always available for a release.

The installed tools::

    $ ls $HOME/development/rtems/4.11
    bin         include     lib         libexec     share       sparc-rtems4.11
    $ ls $HOME/development/rtems/4.11/bin
    sparc-rtems4.11-addr2line       sparc-rtems4.11-cpp
    sparc-rtems4.11-gcc-ar          sparc-rtems4.11-gprof
    sparc-rtems4.11-objdump         sparc-rtems4.11-size
    sparc-rtems4.11-ar              sparc-rtems4.11-elfedit
    sparc-rtems4.11-gcc-nm          sparc-rtems4.11-ld
    sparc-rtems4.11-ranlib          sparc-rtems4.11-strings
    sparc-rtems4.11-as              sparc-rtems4.11-g++
    sparc-rtems4.11-gcc-ranlib      sparc-rtems4.11-ld.bfd
    sparc-rtems4.11-readelf         sparc-rtems4.11-strip
    sparc-rtems4.11-c++             sparc-rtems4.11-gcc
    sparc-rtems4.11-gcov            sparc-rtems4.11-nm
    sparc-rtems4.11-run             xmlwf
    sparc-rtems4.11-c++filt         sparc-rtems4.11-gcc-4.7.2
    sparc-rtems4.11-gdb             sparc-rtems4.11-objcopy
    sparc-rtems4.11-sis
    $ $HOME/development/rtems/4.11/bin/sparc-rtems4.11-gcc -v
    Using built-in specs.
    COLLECT_GCC=/home/chris/development/rtems/4.11/bin/sparc-rtems4.11-gcc
    COLLECT_LTO_WRAPPER=/usr/home/chris/development/rtems/4.11/bin/../ \
    libexec/gcc/sparc-rtems4.11/4.7.2/lto-wrapper
    Target: sparc-rtems4.11                         <1>
    Configured with: ../gcc-4.7.2/configure         <2>
    --prefix=/home/chris/development/rtems/4.11
    --bindir=/home/chris/development/rtems/4.11/bin
    --exec_prefix=/home/chris/development/rtems/4.11
    --includedir=/home/chris/development/rtems/4.11/include
    --libdir=/home/chris/development/rtems/4.11/lib
    --libexecdir=/home/chris/development/rtems/4.11/libexec
    --mandir=/home/chris/development/rtems/4.11/share/man
    --infodir=/home/chris/development/rtems/4.11/share/info
    --datadir=/home/chris/development/rtems/4.11/share
    --build=x86_64-freebsd9.1 --host=x86_64-freebsd9.1 --target=sparc-rtems4.11
    --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib
    --with-system-zlib --disable-nls --without-included-gettext
    --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto
    --enable-threads --enable-plugin --enable-newlib-io-c99-formats
    --enable-newlib-iconv --enable-languages=c,c++
    Thread model: rtems             <3>
    gcc version 4.7.2 20120920      <4>
     (RTEMS 4.11 RSB cb12e4875c203f794a5cd4b3de36101ff9a88403)-1 newlib 2.0.0) (GCC)

.. topic:: Items

  1. The target the compiler is built for.

  2. The configure options used to build GCC.

  3. The threading model is always RTEMS. This makes using the RTEMS tools for
     bare metal development more difficult.

  4. The version string. It contains the Git hash of the RTEMS Source Builder
     you are using. If your local clone has been modifed that state is also
     recorded in the version string. The hash allows you to track from a GCC
     executable back to the original source used to build it.

.. note::

   The RTEMS thread model enables specific hooks in GCC so applications built
   with RTEMS tools need the RTEMS runtime to operate correctly. You can use
   RTEMS tools to build bare metal component but it is more difficult than with
   a bare metal tool chain and you need to know what you are doing at a low
   level. The RTEMS Source Builder can build bare metal tool chains as
   well. Look in the top level ``bare`` directory.

Deployment
----------

If you wish to create and distribute your build or you want to archive a build
you can create a tar file. We term this deploying a build. This is a more
advanced method for binary packaging and installing of tools.

By default the RTEMS Source Builder installs the built packages directly and
optionally it can also create a *build set tar file* or a *package tar file*
per package built. The normal and default behaviour is to let the RTEMS Source
Builder install the tools. The source will be downloaded, built, installed and
cleaned up.

The tar files are created with the full build prefix present and if you follow
the examples given in this documentation the path is absolute. This can cause
problems if you are installing on a host you do not have super user or
administrator rights on because the prefix path may references part you do not
have write access too and tar will not extract the files. You can use the
``--strip-components`` option in tar if your host tar application supports it
to remove the parts you do not have write access too or you may need to unpack
the tar file somewhere and copy the file tree from the level you have write
access from. Embedding the full prefix path in the tar files lets you know what
the prefix is and is recommended. For example if
``/home/chris/development/rtems/4.11`` is the prefix used you cannot change
directory to the root (``/``) and untar the file because the ``/home`` is root
access only. To install a tar file you have downloaded into your new machine's
``Downloads`` directory in your home directoty you would enter:

.. code-block:: shell

    $ cd /somewhere
    $ tar --strip-components=3 -xjf \
          $HOME/Downloads/rtems-4.11-sparc-rtems4.11-1.tar.bz2

A build set tar file is created by adding ``--bset-tar-file`` option to the
``sb-set-builder`` command::

    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
             --prefix=$HOME/development/rtems/4.11 \
             --bset-tar-file \     <1>
             4.11/rtems-sparc
    Source Builder - Set Builder, v0.2.0
    Build Set: 4.11/rtems-sparc
    config: expat-2.1.0-1.cfg
    package: expat-2.1.0-x86_64-freebsd9.1-1
    building: expat-2.1.0-x86_64-freebsd9.1-1
    config: tools/rtems-binutils-2.22-1.cfg
    package: sparc-rtems4.11-binutils-2.22-1
    building: sparc-rtems4.11-binutils-2.22-1
    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    config: tools/rtems-gdb-7.5.1-1.cfg
    package: sparc-rtems4.11-gdb-7.5.1-1
    building: sparc-rtems4.11-gdb-7.5.1-1
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11 <2>
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    installing: rtems-4.11-sparc-rtems4.11-1 -> /home/chris/development/rtems/4.11
    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2      <3>
    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
    cleaning: sparc-rtems4.11-binutils-2.22-1
    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    cleaning: sparc-rtems4.11-gdb-7.5.1-1
    Build Set: Time 0:15:25.92873

.. topic:: Items

  1. The option to create a build set tar file.

  2. The installation still happens unless you specify ``--no-install``.

  3. Creating the build set tar file.

You can also suppress installing the files using the ``--no-install``
option. This is useful if your prefix is not accessiable, for example when
building Canadian cross compiled tool sets::

    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
                --prefix=$HOME/development/rtems/4.11 \
                --bset-tar-file \
                --no-install \      <1>
                4.11/rtems-sparc
    Source Builder - Set Builder, v0.2.0
    Build Set: 4.11/rtems-sparc
    config: expat-2.1.0-1.cfg
    package: expat-2.1.0-x86_64-freebsd9.1-1
    building: expat-2.1.0-x86_64-freebsd9.1-1
    config: tools/rtems-binutils-2.22-1.cfg
    package: sparc-rtems4.11-binutils-2.22-1
    building: sparc-rtems4.11-binutils-2.22-1
    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    config: tools/rtems-gdb-7.5.1-1.cfg
    package: sparc-rtems4.11-gdb-7.5.1-1
    building: sparc-rtems4.11-gdb-7.5.1-1
    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2    <2>
    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
    cleaning: sparc-rtems4.11-binutils-2.22-1
    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    cleaning: sparc-rtems4.11-gdb-7.5.1-1
    Build Set: Time 0:14:11.721274
    $ ls tar
    rtems-4.11-sparc-rtems4.11-1.tar.bz2

.. topic:: Items

  1. The option to supressing installing the packages.

  2. Create the build set tar.

A package tar file can be created by adding the ``--pkg-tar-files`` to the
``sb-set-builder`` command. This creates a tar file per package built in the
build set::

    $ ../source-builder/sb-set-builder --log=l-sparc.txt \
            --prefix=$HOME/development/rtems/4.11 \
            --bset-tar-file \
            --pkg-tar-files \        <1>
            --no-install 4.11/rtems-sparc
    Source Builder - Set Builder, v0.2.0
    Build Set: 4.11/rtems-sparc
    config: expat-2.1.0-1.cfg
    package: expat-2.1.0-x86_64-freebsd9.1-1
    building: expat-2.1.0-x86_64-freebsd9.1-1
    config: tools/rtems-binutils-2.22-1.cfg
    package: sparc-rtems4.11-binutils-2.22-1
    building: sparc-rtems4.11-binutils-2.22-1
    config: tools/rtems-gcc-4.7.2-newlib-1.20.0-1.cfg
    package: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    building: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    config: tools/rtems-gdb-7.5.1-1.cfg
    package: sparc-rtems4.11-gdb-7.5.1-1
    building: sparc-rtems4.11-gdb-7.5.1-1
    tarball: tar/rtems-4.11-sparc-rtems4.11-1.tar.bz2
    cleaning: expat-2.1.0-x86_64-freebsd9.1-1
    cleaning: sparc-rtems4.11-binutils-2.22-1
    cleaning: sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1
    cleaning: sparc-rtems4.11-gdb-7.5.1-1
    Build Set: Time 0:14:37.658460
    $ ls tar
    expat-2.1.0-x86_64-freebsd9.1-1.tar.bz2           sparc-rtems4.11-binutils-2.22-1.tar.bz2
    sparc-rtems4.11-gdb-7.5.1-1.tar.bz2 <2>           rtems-4.11-sparc-rtems4.11-1.tar.bz2 <3>
    sparc-rtems4.11-gcc-4.7.2-newlib-1.20.0-1.tar.bz2

.. topic:: Items

  1. The option to create packages tar files.

  2. The GDB package tar file.

  3. The build set tar file. All the others in a single tar file.

Controlling the Build
---------------------

Build sets can be controlled via the command line to enable and disable various
features. There is no definitive list of build options that can be listed
because they are implemented with the configuration scripts. The best way to
find what is available is to grep the configuration files. for ``with`` and
``without``.

Following are currently available:

``--without-rtems``
  Do not build RTEMS when building an RTEMS build set.

``--without-cxx``
  Do not build a C++ compiler.

``--with-ada``
  Attempt to build an Ada compiler.  You need a native GNAT installed.

``--with-fortran``
  Attempt to build a Fortran compiler.

``--with-objc``
  Attempt to build a C++ compiler.