============
Introduction
============

.. _RTEMS: https://www.rtems.org

.. _RTEMS_source_builder: https://docs.rtems.org/branches/master/user/rsb/index.html

This project is used to set up a development environment for RTEMS_ on a Linux
system. Basic development tools like "make" and "gcc" should already be
installed, everything else including the complete cross-development tool chain is
downloaded from the internet and built locally.

Why not use the RTEMS_source_builder_ directly ?
------------------------------------------------

The RTEMS_source_builder_ for older versions of RTEMS is no longer maintained and has some problems when run on modern linux systems.

The goal of this project is to make the installation of
the RTEMS_ toolchain as easy as possible. In the easiest case, you just have to
provide a base configuration directory, everything else works automatically.

Which scripts are needed ?
--------------------------

- :doc:`setup.sh <setup>` is always needed to define the installation directory
  'INSTALLTOP' in file 'CONFIG.SITE'.
- :doc:`build-gcc.sh <gcc>` is only needed when gcc on your host system is too
  old for RTEMS_. This builds a new gcc
- :doc:`build-python2.sh <python2>` is only needed when you don't have Python 2
  and cannot install it with your package manager.
- :doc:`build-crosstools.sh <crosstools>` is always needed, this builds the
  cross compiler toolchain.
- :doc:`build-kernel.sh <kernel>` is only needed when you want to create a
  bootable image with the RTEMS_ kernel. 

build-gcc.sh, build-python2.sh and build-crosstools.sh each create a file
"setenv.sh" that can be sourced with::

  source setenv.sh

to make the programs available in your shell.

Configuration files
-------------------

The configuration files for specific versions of RTEMS_ are named
"CONFIG-RTEMS-NN" where "NN" is the RTEMS_ version number and an optional
suffix. Here is the current (as of 2021-03-02) list of configuration files:

- CONFIG-RTEMS-4.9 : RTEMS 4.9
- CONFIG-RTEMS-4.10 : RTEMS 4.10
- CONFIG-RTEMS-4.11 : RTEMS 4.11
- CONFIG-RTEMS-5 : RTEMS 5 

These files above are not intended to be changed.

There is also a configuration file with common configuration settings, here you
may change things to configure the program for your needs:

- :doc:`CONFIG.COMMON <config_common>`

Multi version support
---------------------

You can build the RTEMS_ cross compiler toolchain for more than one RTEMS_
version by invoking the build script :doc:`build-crosstools.sh <crosstools>`
again with a different configuration file. You do not have to check out
rtems-from-scratch again to do this.