How to build the RTEMS cross tools
==================================

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

.. _crosstools:

Configure directories
---------------------

The installation base directory is given on the command line and RTEMS cross
tools as a default will be installed in directory "crosstools/RTEMSVERSION" below this.

You may change the directories with entries in file 
:ref:`CONFIG.COMMON <common_config_variables>`.

Configure build options
-----------------------

Make options and the usage of "nice" (so compiling will run with low priority
on your system) is also configured in 
:ref:`CONFIG.COMMON <common_config_variables>`.

Set the RTEMS version
---------------------

You provide the RTEMS version by providing the matching file "CONFIG-RTEMS-NN"
on the command line.

"NN" is the RTEMS version to be built. 

Set the RTEMS architecture
--------------------------

There are many supported architectures. Currently tested is:

- rtems-powerpc

The architecture is specified in variable RTEMS_ARCH in file 
:ref:`CONFIG.COMMON <common_config_variables>`.

Build the cross tools
---------------------

Just enter::

  bin/build-crosstools.sh CONFIGFILE

where CONFIGFILE is the file "CONFIG-RTEMS-NN" that specifies the RTEMS version.

Troubleshooting
+++++++++++++++

If building the cross tools fails, the RTEMS_source_builder_ usually prints the
name of it's log file. Open the log file and see what the problem is. In most
cases you need to install an additional package. 

After this, re-run the build process with::

  bin/build-crosstools.sh CONFIGFILE

When the program complains that the installation directory already exists and
asks if it should be removed, answer "y".

When the program complains that the source directory ("../src/..") already
exists, you may:

- remove it for a clean start by entering "r"
- re-use it, which is faster, by entering "k"

How to use the cross tools
--------------------------

The kernel-building script :doc:`build-kernel.sh <kernel>` project will use the
cross tools automatically.

If you want to use the cross tools in your applications, source file
`setenv.sh` which is placed in directory $RTEMS_CROSS_INSTALL_DIR as it is
defined in file :doc:`CONFIG.COMMON <config_common>`. 

If for example, you defined `INSTALLTOP <setup>` as '/usr/local/rtems', didn't
change RTEMS_CROSS_INSTALL_DIR in file CONFIG.COMMON and built the cross tools
for RTEMS 5, the command would be::

  . /usr/local/rtems/crosstools/5/setenv.sh
  
This redefines the PATH variable that the cross compiler and tools are
found.