1Building with GCC
2=================
3
4Dependencies
5------------
6
7For building U-Boot you need a GCC compiler for your host platform. If you
8are not building on the target platform you further need  a GCC cross compiler.
9
10Debian based
11~~~~~~~~~~~~
12
13On Debian based systems the cross compiler packages are named
14gcc-<architecture>-linux-gnu.
15
16You 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
22Depending 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
36SUSE based
37~~~~~~~~~~
38
39On suse based systems the cross compiler packages are named
40cross-<architecture>-gcc<version>.
41
42You could install GCC and the GCC 10 cross compiler for the ARMv8 architecture
43with
44
45.. code-block:: bash
46
47    sudo zypper install gcc cross-aarch64-gcc10
48
49Depending 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
56Alpine Linux
57~~~~~~~~~~~~
58
59For 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
66Prerequisites
67-------------
68
69For some boards you have to build prerequisite files before you can build
70U-Boot, e.g. for the some boards you will need to build the ARM Trusted Firmware
71beforehand. Please, refer to the board specific documentation
72:doc:`../board/index`.
73
74Configuration
75-------------
76
77Directory configs/ contains the template configuration files for the maintained
78boards following the naming scheme::
79
80    <board name>_defconfig
81
82These files have been stripped of default settings. So you cannot use them
83directly. Instead their name serves as a make target to generate the actual
84configuration file .config. For instance the configuration template for the
85Odroid C2 board is called odroid-c2_defconfig. The corresponding .config file
86is generated by
87
88.. code-block:: bash
89
90    make odroid-c2_defconfig
91
92You can adjust the configuration using
93
94.. code-block:: bash
95
96    make menuconfig
97
98Building
99--------
100
101When cross compiling you will have to specify the prefix of the cross-compiler.
102You can either specify the value of the CROSS_COMPILE variable on the make
103command line or export it beforehand.
104
105.. code-block:: bash
106
107    CROSS_COMPILE=<compiler-prefix> make
108
109Assuming cross compiling on Debian for ARMv8 this would be
110
111.. code-block:: bash
112
113    CROSS_COMPILE=aarch64-linux-gnu- make
114
115Build parameters
116~~~~~~~~~~~~~~~~
117
118A list of available parameters for the make command can be obtained via
119
120.. code-block:: bash
121
122    make help
123
124You 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
130Further important build parameters are
131
132* O=<dir> - generate all output files in directory <dir>, including .config
133* V=1 - verbose build
134
135Devicetree compiler
136~~~~~~~~~~~~~~~~~~~
137
138Boards that use `CONFIG_OF_CONTROL` (i.e. almost all of them) need the
139devicetree compiler (dtc). Those with `CONFIG_PYLIBFDT` need pylibfdt, a Python
140library for accessing devicetree data. Suitable versions of these are included
141in the U-Boot tree in `scripts/dtc` and built automatically as needed.
142
143To 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
149In this case, dtc and pylibfdt are not built. The build checks that the version
150of dtc is new enough. It also makes sure that pylibfdt is present, if needed
151(see `scripts_dtc` in the Makefile).
152
153Note that the :doc:`tools` are always built with the included version of libfdt
154so it is not possible to build U-Boot tools with a system libfdt, at present.
155
156Link-time optimisation (LTO)
157~~~~~~~~~~~~~~~~~~~~~~~~~~~~
158
159U-Boot supports link-time optimisation which can reduce the size of the final
160U-Boot binaries, particularly with SPL.
161
162At present this can be enabled by ARM boards by adding `CONFIG_LTO=y` into the
163defconfig file. Other architectures are not supported. LTO is enabled by default
164for sandbox.
165
166This does incur a link-time penalty of several seconds. For faster incremental
167builds during development, you can disable it by setting `NO_LTO` to `1`.
168
169.. code-block:: bash
170
171    NO_LTO=1 make
172
173Other build targets
174~~~~~~~~~~~~~~~~~~~
175
176A list of all make targets can be obtained via
177
178.. code-block:: bash
179
180    make help
181
182Important ones are
183
184* clean - remove most generated files but keep the configuration
185* mrproper - remove all generated files + config + various backup files
186
187Installation
188------------
189
190The process for installing U-Boot on the target device is device specific.
191Please, refer to the board specific documentation :doc:`../board/index`.
192