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 Prerequisites
  55 -------------
  56
  57 For some boards you have to build prerequisite files before you can build
  58 U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
  59 beforehand. Please, refer to the board specific documentation
  60 :doc:`../board/index`.
  61
  62 Configuration
  63 -------------
  64
  65 Directory configs/ contains the template configuration files for the maintained
  66 boards following the naming scheme::
  67
  68     <board name>_defconfig
  69
  70 These files have been stripped of default settings. So you cannot use them
  71 directly. Instead their name serves as a make target to generate the actual
  72 configuration file .config. For instance the configuration template for the
  73 Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
  74 is generated by
  75
  76 .. code-block:: bash
  77
  78     make odroid-c2_defconfig
  79
  80 You can adjust the configuration using
  81
  82 .. code-block:: bash
  83
  84     make menuconfig
  85
  86 Building
  87 --------
  88
  89 When cross compiling you will have to specify the prefix of the cross-compiler.
  90 You can either specify the value of the CROSS_COMPILE variable on the make
  91 command line or export it beforehand.
  92
  93 .. code-block:: bash
  94
  95     CROSS_COMPILE=<compiler-prefix> make
  96
  97 Assuming cross compiling on Debian for ARMv8 this would be
  98
  99 .. code-block:: bash
 100
 101     CROSS_COMPILE=aarch64-linux-gnu- make
 102
 103 Build parameters
 104 ~~~~~~~~~~~~~~~~
 105
 106 A list of available parameters for the make command can be obtained via
 107
 108 .. code-block:: bash
 109
 110     make help
 111
 112 You can speed up compilation by parallelization using the -j parameter, e.g.
 113
 114 .. code-block:: bash
 115
 116     CROSS_COMPILE=aarch64-linux-gnu- make -j$(nproc)
 117
 118 Further important build parameters are
 119
 120 * O=<dir> - generate all output files in directory <dir>, including .config
 121 * V=1 - verbose build
 122
 123 Devicetree compiler
 124 ~~~~~~~~~~~~~~~~~~~
 125
 126 Boards that use `CONFIG_OF_CONTROL` (i.e. almost all of them) need the
 127 devicetree compiler (dtc). Those with `CONFIG_PYLIBFDT` need pylibfdt, a Python
 128 library for accessing devicetree data. Suitable versions of these are included
 129 in the U-Boot tree in `scripts/dtc` and built automatically as needed.
 130
 131 To use the system versions of these, use the DTC parameter, for example
 132
 133 .. code-block:: bash
 134
 135     DTC=/usr/bin/dtc make
 136
 137 In this case, dtc and pylibfdt are not built. The build checks that the version
 138 of dtc is new enough. It also makes sure that pylibfdt is present, if needed
 139 (see `scripts_dtc` in the Makefile).
 140
 141 Note that the :doc:`tools` are always built with the included version of libfdt
 142 so it is not possible to build U-Boot tools with a system libfdt, at present.
 143
 144 Other build targets
 145 ~~~~~~~~~~~~~~~~~~~
 146
 147 A list of all make targets can be obtained via
 148
 149 .. code-block:: bash
 150
 151     make help
 152
 153 Important ones are
 154
 155 * clean - remove most generated files but keep the configuration
 156 * mrproper - remove all generated files + config + various backup files
 157
 158 Installation
 159 ------------
 160
 161 The process for installing U-Boot on the target device is device specific.
 162 Please, refer to the board specific documentation :doc:`../board/index`.