How to build a new gcc (optional)
=================================

Why this may be needed
----------------------

RTEMS needs a modern gcc (GNU C-Compiler) toolchain on your host. If you cannot
install a compatible version of gcc, you can build it locally.

Note: the documentation was taken from these sites::

  https://gcc.gnu.org/wiki/InstallingGCC
  https://gcc.gnu.org/install/configure.html

How to build
------------

You first have to review or change some configuration variables in file CONFIG.COMMON.

Activate gcc usage by setting RTEMS_CROSS_USE_LOCAL_GCC to "yes" (see 
:ref:`common configuration variables <common_config_variables>`).

gcc directory settings
----------------------

.. note::
   You usually don't need to change these.

The installation base directory is given on the command line and gcc will be
installed in directory "gcc" below this.

If you want to fine-tune installation, build and source directories, you can do
this by changing the following variables in file CONFIG.COMMON:

.. _gcc_config_variables:

.. note::
  `$INSTALLTOP` is defined by :doc:`bin/setup.sh <setup>`,
  `$TOP` is the directory where rtems-from-scratch is located

+----------------------------+--------------------+------------------------------------------+
| Variable                   | default value      | explanation                              |
+============================+====================+==========================================+
| GCC_INSTALL_DIR            | $INSTALLTOP/gcc    | Directory where the gnu-c compiler       |
|                            |                    | is installed                             |
+----------------------------+--------------------+------------------------------------------+
| GCC_SRC_DIR                | $TOP/src/gcc       | Directory where the gnu-c compiler       |
|                            |                    | sources are put                          |
+----------------------------+--------------------+------------------------------------------+
| GCC_BUILD_DIR              | $TOP/src/gcc/build | Directory where the gnu-c compiler       |
|                            |                    | is built                                 |
+----------------------------+--------------------+------------------------------------------+
| GCC_VERSION                | 9.3.0              | Version of the host gnu-c compiler       |
|                            |                    | if this is built locally                 |
+----------------------------+--------------------+------------------------------------------+
| GCC_DOWNLOAD_PREREQUISITES | yes                | Automatically download prerequisites     |
|                            |                    | needed for gcc build                     |
+----------------------------+--------------------+------------------------------------------+
| GCC_LANGUAGES              | "c,c++"            | gcc languages that will be supported     |
+----------------------------+--------------------+------------------------------------------+
| GCC_MAKE_OPTS              | "-s -j"            | Make options for GCC, remove "-j" if you |
|                            |                    | have low memory                          |
+----------------------------+--------------------+------------------------------------------+

Run the build script
--------------------

The gcc compiler will be installed in directory GCC_INSTALL_DIR.

Run::

  bin/build-gcc.sh

How to use the compiler
-----------------------

In file :doc:`CONFIG.COMMON <config_common>` 
variable RTEMS_CROSS_USE_LOCAL_GCC must be set to "yes".

The compiler is then found by :doc:`build-crosstools.sh <kernel>`
automatically.

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

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

  . /usr/local/rtems/gcc/setenv.sh

This redefines the PATH variable so the gcc compiler and all it's tools are
found before your system's gcc compiler and tools.