doc/build/gcc.rst

Building with GCC
=================

Dependencies
------------

For building U-Boot you need a GCC compiler for your host platform. If you
are not building on the target platform you further need  a GCC cross compiler.

Debian based
~~~~~~~~~~~~

On Debian based systems the cross compiler packages are named
gcc-<architecture>-linux-gnu.

You could install GCC and the GCC cross compiler for the ARMv8 architecture with

.. code-block:: bash

    sudo apt-get install gcc gcc-aarch64-linux-gnu

Depending on the build targets further packages maybe needed

.. code-block:: bash

    sudo apt-get install bc bison build-essential coccinelle \
      device-tree-compiler dfu-util efitools flex gdisk graphviz imagemagick \
      liblz4-tool libguestfs-tools libncurses-dev libpython3-dev libsdl2-dev \
      libssl-dev lz4 lzma lzma-alone openssl python3 python3-coverage \
      python3-pycryptodome python3-pyelftools python3-pytest \
      python3-sphinxcontrib.apidoc python3-sphinx-rtd-theme python3-virtualenv \
      swig

SUSE based
~~~~~~~~~~

On suse based systems the cross compiler packages are named
cross-<architecture>-gcc<version>.

You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture
with

.. code-block:: bash

    sudo zypper install gcc cross-aarch64-gcc10

Depending on the build targets further packages maybe needed.

.. code-block:: bash

    zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \
      ncurses-devel python3-devel python3-pytest swig

Prerequisites
-------------

For some boards you have to build prerequisite files before you can build
U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
beforehand. Please, refer to the board specific documentation
:doc:`../board/index`.

Configuration
-------------

Directory configs/ contains the template configuration files for the maintained
boards following the naming scheme::

    <board name>_defconfig

These files have been stripped of default settings. So you cannot use them
directly. Instead their name serves as a make target to generate the actual
configuration file .config. For instance the configuration template for the
Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
is generated by

.. code-block:: bash

    make odroid-c2_defconfig

You can adjust the configuration using

.. code-block:: bash

    make menuconfig

Building
--------

When cross compiling you will have to specify the prefix of the cross-compiler.
You can either specify the value of the CROSS_COMPILE variable on the make
command line or export it beforehand.

.. code-block:: bash

    CROSS_COMPILE=<compiler-prefix> make

Assuming cross compiling on Debian for ARMv8 this would be

.. code-block:: bash

    CROSS_COMPILE=aarch64-linux-gnu- make

Build parameters
~~~~~~~~~~~~~~~~

A list of available parameters for the make command can be obtained via

.. code-block:: bash

    make help

You can speed up compilation by parallelization using the -j parameter, e.g.

.. code-block:: bash

    CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)

Further important build parameters are

* O=<dir> - generate all output files in directory <dir>, including .config
* V=1 - verbose build

Other build targets
~~~~~~~~~~~~~~~~~~~

A list of all make targets can be obtained via

.. code-block:: bash

    make help

Important ones are

* clean - remove most generated files but keep the configuration
* mrproper - remove all generated files + config + various backup files

Installation
------------

The process for installing U-Boot on the target device is device specific.
Please, refer to the board specific documentation :doc:`../board/index`.