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 libgnutls28-dev libguestfs-tools libncurses-dev \
      libpython3-dev libsdl2-dev libssl-dev lz4 lzma lzma-alone openssl \
      pkg-config python3 python3-asteval python3-coverage python3-filelock \
      python3-pkg-resources python3-pycryptodome python3-pyelftools \
      python3-pytest python3-pytest-xdist python3-sphinxcontrib.apidoc \
      python3-sphinx-rtd-theme python3-subunit python3-testtools \
      python3-virtualenv swig uuid-dev

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

Alpine Linux
~~~~~~~~~~~~

For building U-Boot on Alpine Linux at least the following packages are needed:

.. code-block:: bash

    apk add alpine-sdk bc bison dtc flex gnutls-dev linux-headers ncurses-dev \
      openssl-dev py3-elftools py3-setuptools python3-dev swig util-linux-dev

Depending on the build target further packages may be needed:

* sandbox with lcd: sdl2-dev
* riscv64 S-mode targets: opensbi
* some arm64 targets: arm-trusted-firmware

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

Out-of-tree building
~~~~~~~~~~~~~~~~~~~~

By default building is performed locally and the objects are saved in the source
directory. To build out-out-tree use one of the two methods below:

Add O= parameter to the make command line:

.. code-block:: bash

    make O=/tmp/build distclean
    make O=/tmp/build NAME_defconfig
    make O=/tmp/build

Use environment variable KBUILD_OUTPUT:

.. code-block:: bash

    export KBUILD_OUTPUT=/tmp/build
    make distclean
    make NAME_defconfig
    make

.. note::

    The command line "O=" parameter overrides the KBUILD_OUTPUT environment
    variable.

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

Devicetree compiler
~~~~~~~~~~~~~~~~~~~

Boards that use `CONFIG_OF_CONTROL` (i.e. almost all of them) need the
devicetree compiler (dtc). Those with `CONFIG_PYLIBFDT` need pylibfdt, a Python
library for accessing devicetree data. Suitable versions of these are included
in the U-Boot tree in `scripts/dtc` and built automatically as needed.

To use the system versions of these, use the DTC parameter, for example

.. code-block:: bash

    DTC=/usr/bin/dtc make

In this case, dtc and pylibfdt are not built. The build checks that the version
of dtc is new enough. It also makes sure that pylibfdt is present, if needed
(see `scripts_dtc` in the Makefile).

Note that the :doc:`tools` are always built with the included version of libfdt
so it is not possible to build U-Boot tools with a system libfdt, at present.

Link-time optimisation (LTO)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

U-Boot supports link-time optimisation which can reduce the size of the final
U-Boot binaries, particularly with SPL.

At present this can be enabled by ARM boards by adding `CONFIG_LTO=y` into the
defconfig file. Other architectures are not supported. LTO is enabled by default
for sandbox.

This does incur a link-time penalty of several seconds. For faster incremental
builds during development, you can disable it by setting `NO_LTO` to `1`.

.. code-block:: bash

    NO_LTO=1 make

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`.