1Prerequisites
2=============
3
4This document describes the software requirements for building |TF-A| for
5AArch32 and AArch64 target platforms.
6
7It may possible to build |TF-A| with combinations of software packages that are
8different from those listed below, however only the software described in this
9document can be officially supported.
10
11Getting the TF-A Source
12-----------------------
13
14Source code for |TF-A| is maintained in a Git repository hosted on
15`TrustedFirmware.org`_. To clone this repository from the server, run the following
16in your shell:
17
18.. code:: shell
19
20    git clone "https://review.trustedfirmware.org/TF-A/trusted-firmware-a"
21
22
23Requirements
24------------
25
26======================== =====================
27        Program          Min supported version
28======================== =====================
29Arm Compiler             6.18
30Arm GNU Compiler         13.2
31Clang/LLVM               11.0.0
32Device Tree Compiler     1.4.7
33GNU make                 3.81
34mbed TLS\ [#f1]_         3.6.0
35Node.js [#f2]_           16
36OpenSSL                  1.0.0
37Poetry [#f2]_            1.3.2
38QCBOR\ [#f3]_            1.2
39Sphinx\ [#f2]_           2.4.4
40======================== =====================
41
42.. [#f1] Required for Trusted Board Boot and Measured Boot.
43.. [#f2] Required only for building TF-A documentation.
44.. [#f3] Required only when enabling DICE Protection Environment support.
45
46Toolchain
47^^^^^^^^^
48
49|TF-A| can be compiled using any cross-compiler toolchain specified in the
50preceding table that target Armv7-A or Armv8-A. For AArch32 and
51AArch64 builds, the respective targets required are ``arm-none-eabi`` and
52``aarch64-none-elf``.
53
54Testing has been performed with version 13.2.Rel1 (gcc 13.2) of the Arm
55GNU compiler, which can be installed from the `Arm Developer website`_.
56
57In addition, a native compiler is required to build supporting tools.
58
59.. note::
60   Versions greater than the ones specified are likely but not guaranteed to
61   work. This is predominantly because TF-A carries its own copy of compiler-rt,
62   which may be older than the version expected by the compiler. Fixes and bug
63   reports are always welcome.
64
65.. note::
66   For instructions on how to select the cross compiler refer to
67   :ref:`Performing an Initial Build`.
68
69OpenSSL
70^^^^^^^
71
72OpenSSL is required to build the cert_create, encrypt_fw, and fiptool tools.
73
74If using OpenSSL 3, older Linux versions may require it to be built from
75source code, as it may not be available in the default package repositories.
76Please refer to the OpenSSL project documentation for more information.
77
78.. warning::
79    Versions 1.0.x and from v3.0.0 up to v3.0.6 are strongly advised against due
80    to concerns regarding security vulnerabilities!
81
82Device Tree Compiler (DTC)
83^^^^^^^^^^^^^^^^^^^^^^^^^^
84
85Needed if you want to rebuild the provided Flattened Device Tree (FDT)
86source files (``.dts`` files). DTC is available for Linux through the package
87repositories of most distributions.
88
89Arm Development Studio (`Arm-DS`_)
90^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
91
92The standard software package used for debugging software on Arm development
93platforms and |FVP| models.
94
95Node.js
96^^^^^^^
97
98Highly recommended, and necessary in order to install and use the packaged
99Git hooks and helper tools. Without these tools you will need to rely on the
100CI for feedback on commit message conformance.
101
102Poetry
103^^^^^^
104
105Required for managing Python dependencies, this will allow you to reliably
106reproduce a Python environment to build documentation and run analysis tools.
107Most importantly, it ensures your system environment will not be affected by
108dependencies in the Python scripts.
109
110.. _prerequisites_software_and_libraries:
111
112Package Installation (Linux)
113----------------------------
114
115|TF-A| can be compiled on both Linux and Windows-based machines.
116However, we strongly recommend using a UNIX-compatible build environment.
117
118Testing is performed using Ubuntu 22.04 LTS (64-bit), but other distributions
119should also work, provided the necessary tools and libraries are installed.
120
121The following are steps to install the required packages:
122
123.. code:: shell
124
125    sudo apt install build-essential
126
127The optional packages can be installed using:
128
129.. code:: shell
130
131    sudo apt install device-tree-compiler
132
133Additionally, to install a version of Node.js compatible with TF-A's repository
134scripts, you can use the `Node Version Manager`_. To install both NVM and an
135appropriate version of Node.js, run the following **from the root directory of
136the repository**:
137
138.. code:: shell
139
140    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
141    exec "$SHELL" -ic "nvm install; exec $SHELL"
142
143.. _Node Version Manager: https://github.com/nvm-sh/nvm#install--update-script
144
145Supporting Files
146----------------
147
148TF-A has been tested with pre-built binaries and file systems from `Linaro
149Release 20.01`_. Alternatively, you can build the binaries from source using
150instructions in :ref:`Performing an Initial Build`.
151
152.. _prerequisites_get_source:
153
154Additional Steps for Contributors
155^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
156
157If you are planning on contributing back to TF-A, there are some things you'll
158want to know.
159
160TF-A is hosted by a `Gerrit Code Review`_ server. Gerrit requires that all
161commits include a ``Change-Id`` footer, and this footer is typically
162automatically generated by a Git hook installed by you, the developer.
163
164If you have Node.js installed already, you can automatically install this hook,
165along with any additional hooks and Javascript-based tooling that we use, by
166running from within your newly-cloned repository:
167
168.. code:: shell
169
170    npm install --no-save
171
172If you have opted **not** to install Node.js, you can install the Gerrit hook
173manually by running:
174
175.. code:: shell
176
177    curl -Lo $(git rev-parse --git-dir)/hooks/commit-msg https://review.trustedfirmware.org/tools/hooks/commit-msg
178    chmod +x $(git rev-parse --git-dir)/hooks/commit-msg
179
180You can read more about Git hooks in the *githooks* page of the Git
181documentation, available `here <https://git-scm.com/docs/githooks>`_.
182
183--------------
184
185*Copyright (c) 2021-2024, Arm Limited. All rights reserved.*
186
187.. _Arm Developer website: https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/downloads
188.. _Gerrit Code Review: https://www.gerritcodereview.com/
189.. _Linaro Release Notes: https://community.arm.com/dev-platforms/w/docs/226/old-release-notes
190.. _Linaro instructions: https://community.arm.com/dev-platforms/w/docs/304/arm-reference-platforms-deliverables
191.. _Arm-DS: https://developer.arm.com/Tools%20and%20Software/Arm%20Development%20Studio
192.. _Linaro Release 20.01: http://releases.linaro.org/members/arm/platforms/20.01
193.. _TrustedFirmware.org: https://www.trustedfirmware.org/
194