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