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-coverage python3-pkg-resources \
  31       python3-pycryptodome python3-pyelftools python3-pytest \
  32       python3-sphinxcontrib.apidoc python3-sphinx-rtd-theme python3-virtualenv \
  33       swig
  34
  35 SUSE based
  36 ~~~~~~~~~~
  37
  38 On suse based systems the cross compiler packages are named
  39 cross-<architecture>-gcc<version>.
  40
  41 You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture
  42 with
  43
  44 .. code-block:: bash
  45
  46     sudo zypper install gcc cross-aarch64-gcc10
  47
  48 Depending on the build targets further packages maybe needed.
  49
  50 .. code-block:: bash
  51
  52     zypper install bc bison flex gcc libopenssl-devel libSDL2-devel make \
  53       ncurses-devel python3-devel python3-pytest swig
  54
  55 Alpine Linux
  56 ~~~~~~~~~~~~
  57
  58 For building U-Boot on Alpine Linux at least the following packages are needed:
  59
  60 .. code-block:: bash
  61
  62     apk add alpine-sdk bc bison dtc flex linux-headers ncurses-dev \
  63       openssl-dev perl python3 py3-setuptools python3-dev sdl2-dev
  64
  65 Prerequisites
  66 -------------
  67
  68 For some boards you have to build prerequisite files before you can build
  69 U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
  70 beforehand. Please, refer to the board specific documentation
  71 :doc:`../board/index`.
  72
  73 Configuration
  74 -------------
  75
  76 Directory configs/ contains the template configuration files for the maintained
  77 boards following the naming scheme::
  78
  79     <board name>_defconfig
  80
  81 These files have been stripped of default settings. So you cannot use them
  82 directly. Instead their name serves as a make target to generate the actual
  83 configuration file .config. For instance the configuration template for the
  84 Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
  85 is generated by
  86
  87 .. code-block:: bash
  88
  89     make odroid-c2_defconfig
  90
  91 You can adjust the configuration using
  92
  93 .. code-block:: bash
  94
  95     make menuconfig
  96
  97 Building
  98 --------
  99
 100 When cross compiling you will have to specify the prefix of the cross-compiler.
 101 You can either specify the value of the CROSS_COMPILE variable on the make
 102 command line or export it beforehand.
 103
 104 .. code-block:: bash
 105
 106     CROSS_COMPILE=<compiler-prefix> make
 107
 108 Assuming cross compiling on Debian for ARMv8 this would be
 109
 110 .. code-block:: bash
 111
 112     CROSS_COMPILE=aarch64-linux-gnu- make
 113
 114 Build parameters
 115 ~~~~~~~~~~~~~~~~
 116
 117 A list of available parameters for the make command can be obtained via
 118
 119 .. code-block:: bash
 120
 121     make help
 122
 123 You can speed up compilation by parallelization using the -j parameter, e.g.
 124
 125 .. code-block:: bash
 126
 127     CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)
 128
 129 Further important build parameters are
 130
 131 * O=<dir> - generate all output files in directory <dir>, including .config
 132 * V=1 - verbose build
 133
 134 Devicetree compiler
 135 ~~~~~~~~~~~~~~~~~~~
 136
 137 Boards that use `CONFIG_OF_CONTROL` (i.e. almost all of them) need the
 138 devicetree compiler (dtc). Those with `CONFIG_PYLIBFDT` need pylibfdt, a Python
 139 library for accessing devicetree data. Suitable versions of these are included
 140 in the U-Boot tree in `scripts/dtc` and built automatically as needed.
 141
 142 To use the system versions of these, use the DTC parameter, for example
 143
 144 .. code-block:: bash
 145
 146     DTC=/usr/bin/dtc make
 147
 148 In this case, dtc and pylibfdt are not built. The build checks that the version
 149 of dtc is new enough. It also makes sure that pylibfdt is present, if needed
 150 (see `scripts_dtc` in the Makefile).
 151
 152 Note that the :doc:`tools` are always built with the included version of libfdt
 153 so it is not possible to build U-Boot tools with a system libfdt, at present.
 154
 155 Other build targets
 156 ~~~~~~~~~~~~~~~~~~~
 157
 158 A list of all make targets can be obtained via
 159
 160 .. code-block:: bash
 161
 162     make help
 163
 164 Important ones are
 165
 166 * clean - remove most generated files but keep the configuration
 167 * mrproper - remove all generated files + config + various backup files
 168
 169 Installation
 170 ------------
 171
 172 The process for installing U-Boot on the target device is device specific.
 173 Please, refer to the board specific documentation :doc:`../board/index`.