doc/build/gcc.rst

   1 Building with GCC
   2 =================
   3
   4 Dependencies
   5 ------------
   6
   7 For building U-Boot you need a GCC compiler for your host platform. If you
   8 are not building on the target platform you further need  a GCC cross compiler.
   9
  10 Debian based
  11 ~~~~~~~~~~~~
  12
  13 On Debian based systems the cross compiler packages are named
  14 gcc-<architecture>-linux-gnu.
  15
  16 You could install GCC and the GCC cross compiler for the ARMv8 architecture with
  17
  18 .. code-block:: bash
  19
  20     sudo apt-get install gcc gcc-aarch64-linux-gnu
  21
  22 Depending on the build targets further packages maybe needed
  23
  24 .. code-block:: bash
  25
  26     sudo apt-get install bc bison build-essential coccinelle \
  27       device-tree-compiler dfu-util efitools flex gdisk graphviz imagemagick \
  28       liblz4-tool libgnutls28-dev libguestfs-tools libncurses-dev \
  29       libpython3-dev libsdl2-dev libssl-dev lz4 lzma lzma-alone openssl \
  30       pkg-config python3 python3-asteval python3-coverage python3-filelock \
  31       python3-pkg-resources python3-pycryptodome python3-pyelftools \
  32       python3-pytest python3-pytest-xdist python3-sphinxcontrib.apidoc \
  33       python3-sphinx-rtd-theme python3-subunit python3-testtools \
  34       python3-virtualenv swig uuid-dev
  35
  36 SUSE based
  37 ~~~~~~~~~~
  38
  39 On suse based systems the cross compiler packages are named
  40 cross-<architecture>-gcc<version>.
  41
  42 You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture
  43 with
  44
  45 .. code-block:: bash
  46
  47     sudo zypper install gcc cross-aarch64-gcc10
  48
  49 Depending on the build targets further packages maybe needed.
  50
  51 .. code-block:: bash
  52
  53     zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \
  54       ncurses-devel python3-devel python3-pytest swig
  55
  56 Alpine Linux
  57 ~~~~~~~~~~~~
  58
  59 For building U-Boot on Alpine Linux at least the following packages are needed:
  60
  61 .. code-block:: bash
  62
  63     apk add alpine-sdk bc bison dtc flex linux-headers ncurses-dev \
  64       openssl-dev perl python3 py3-setuptools python3-dev sdl2-dev
  65
  66 Prerequisites
  67 -------------
  68
  69 For some boards you have to build prerequisite files before you can build
  70 U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
  71 beforehand. Please, refer to the board specific documentation
  72 :doc:`../board/index`.
  73
  74 Configuration
  75 -------------
  76
  77 Directory configs/ contains the template configuration files for the maintained
  78 boards following the naming scheme::
  79
  80     <board name>_defconfig
  81
  82 These files have been stripped of default settings. So you cannot use them
  83 directly. Instead their name serves as a make target to generate the actual
  84 configuration file .config. For instance the configuration template for the
  85 Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
  86 is generated by
  87
  88 .. code-block:: bash
  89
  90     make odroid-c2_defconfig
  91
  92 You can adjust the configuration using
  93
  94 .. code-block:: bash
  95
  96     make menuconfig
  97
  98 Building
  99 --------
 100
 101 When cross compiling you will have to specify the prefix of the cross-compiler.
 102 You can either specify the value of the CROSS_COMPILE variable on the make
 103 command line or export it beforehand.
 104
 105 .. code-block:: bash
 106
 107     CROSS_COMPILE=<compiler-prefix> make
 108
 109 Assuming cross compiling on Debian for ARMv8 this would be
 110
 111 .. code-block:: bash
 112
 113     CROSS_COMPILE=aarch64-linux-gnu- make
 114
 115 Build parameters
 116 ~~~~~~~~~~~~~~~~
 117
 118 A list of available parameters for the make command can be obtained via
 119
 120 .. code-block:: bash
 121
 122     make help
 123
 124 You can speed up compilation by parallelization using the -j parameter, e.g.
 125
 126 .. code-block:: bash
 127
 128     CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)
 129
 130 Further important build parameters are
 131
 132 * O=<dir> - generate all output files in directory <dir>, including .config
 133 * V=1 - verbose build
 134
 135 Devicetree compiler
 136 ~~~~~~~~~~~~~~~~~~~
 137
 138 Boards that use `CONFIG_OF_CONTROL` (i.e. almost all of them) need the
 139 devicetree compiler (dtc). Those with `CONFIG_PYLIBFDT` need pylibfdt, a Python
 140 library for accessing devicetree data. Suitable versions of these are included
 141 in the U-Boot tree in `scripts/dtc` and built automatically as needed.
 142
 143 To use the system versions of these, use the DTC parameter, for example
 144
 145 .. code-block:: bash
 146
 147     DTC=/usr/bin/dtc make
 148
 149 In this case, dtc and pylibfdt are not built. The build checks that the version
 150 of dtc is new enough. It also makes sure that pylibfdt is present, if needed
 151 (see `scripts_dtc` in the Makefile).
 152
 153 Note that the :doc:`tools` are always built with the included version of libfdt
 154 so it is not possible to build U-Boot tools with a system libfdt, at present.
 155
 156 Link-time optimisation (LTO)
 157 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 158
 159 U-Boot supports link-time optimisation which can reduce the size of the final
 160 U-Boot binaries, particularly with SPL.
 161
 162 At present this can be enabled by ARM boards by adding `CONFIG_LTO=y` into the
 163 defconfig file. Other architectures are not supported. LTO is enabled by default
 164 for sandbox.
 165
 166 This does incur a link-time penalty of several seconds. For faster incremental
 167 builds during development, you can disable it by setting `NO_LTO` to `1`.
 168
 169 .. code-block:: bash
 170
 171     NO_LTO=1 make
 172
 173 Other build targets
 174 ~~~~~~~~~~~~~~~~~~~
 175
 176 A list of all make targets can be obtained via
 177
 178 .. code-block:: bash
 179
 180     make help
 181
 182 Important ones are
 183
 184 * clean - remove most generated files but keep the configuration
 185 * mrproper - remove all generated files + config + various backup files
 186
 187 Installation
 188 ------------
 189
 190 The process for installing U-Boot on the target device is device specific.
 191 Please, refer to the board specific documentation :doc:`../board/index`.