1Prerequisites
2=============
3
4Build Host
5----------
6
7A relatively recent Linux distribution is recommended.
8CI runs are done using Ubuntu 22.04 LTS (64-bit).
9
10Toolchain
11---------
12
13The clang-20 toolchain is recommended for building Hafnium and the test
14infrastructure. On Ubuntu, the toolchain can be installed from the LLVM apt
15repository (https://apt.llvm.org/).
16
17.. note::
18
19   Using a toolchain version greater than, or significantly lesser than the one
20   specified is not guaranteed to work.
21
22.. note::
23
24   You may also use the Docker container if you are unable to install the
25   toolchain on your host machine, see the :ref:`Using_Docker` section.
26
27Dependencies
28------------
29
30Build
31^^^^^
32
33The following command install the dependencies for the Hafnium build:
34
35.. code:: shell
36
37   sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip device-tree-compiler
38
39In addition, install the following python libraries using `pip`_:
40
41.. code:: shell
42
43   pip3 install fdt click
44
45The file kokoro/static_checks.sh runs a series of static code checks into Hafnium's codebase.
46Hafnium follows the linux kernel coding guidelines. As such, the static code checks using the
47'checkpatch.pl' script from linux source tree. To setup and download 'checkpatch.pl':
48
49.. code:: shell
50
51   ./build/setup_checkpatch.sh
52
53Then test it works with:
54
55.. code:: shell
56
57   make checkpatch
58
59System and Python Packages for test infrastructure
60^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
61
62The `Shrinkwrap`_ tool is a core component of the hftest scripts and is included
63as a submodule. It relies on the following system packages to function correctly:
64
65.. code:: shell
66
67   sudo apt-get install -y git netcat-openbsd python3 python3-pip telnet
68
69Further, install the required Python packages:
70
71.. code:: shell
72
73   pip3 install --user fdt pyyaml termcolor tuxmake
74
75.. note::
76
77   These manual installation steps are not required if you're using the Docker
78   based test environment. All necessary dependencies—system packages,
79   Python modules, and Shrinkwrap environment configuration—are already
80   pre-installed and automated inside the Docker image provided by the
81   Hafnium repository (see :ref:`Using_Docker`).
82
83Documentation
84^^^^^^^^^^^^^
85
86To create a rendered copy of this documentation locally you can use the
87`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
88pages.
89
90For building a local copy of the documentation you will need:
91
92- Python 3 (3.8 or later)
93- PlantUML (1.2017.15 or later)
94- `Poetry`_ (Python dependency manager)
95
96Below is an example set of instructions to get a working environment (tested on
97Ubuntu):
98
99.. code:: shell
100
101    sudo apt install python3 python3-pip plantuml
102    curl -sSL https://install.python-poetry.org | python3 -
103
104Run the command below to install using Poetry, Python dependencies to build the documentation:
105
106.. code:: shell
107
108    poetry install --with docs
109
110Poetry will create a new virtual environment and install all dependencies listed
111in ``pyproject.toml``. You can get information about this environment, such as
112its location and the Python version, with the command:
113
114.. code:: shell
115
116    poetry env info
117
118--------------
119
120*Copyright (c) 2023-2025, Arm Limited. All rights reserved.*
121
122.. _Shrinkwrap: https://shrinkwrap.docs.arm.com
123.. _Sphinx: http://www.sphinx-doc.org/en/master/
124.. _Poetry: https://python-poetry.org/docs/
125.. _pip: https://pip.pypa.io/en/stable/
126