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 following toolchain is recommended for building Hafnium and the test
14infrastructure:
15
16- For a x86_64 Ubuntu host,
17
18.. code:: shell
19
20   https://github.com/llvm/llvm-project/releases/download/llvmorg-18.1.8/clang+llvm-18.1.8-x86_64-linux-gnu-ubuntu-18.04.tar.xz
21
22- For a AArch64 Ubuntu host,
23
24.. code:: shell
25
26   https://github.com/llvm/llvm-project/releases/download/llvmorg-18.1.8/clang+llvm-18.1.8-aarch64-linux-gnu.tar.xz
27
28.. note::
29
30   Use of a native toolchain installed on the host (e.g. /usr/bin/clang) is
31   not supported.
32
33.. note::
34
35   Using a toolchain version greater, or significantly lesser than the one
36   specified is not guaranteed to work.
37
38The PATH environment variable shall be adjusted to contain the LLVM/clang directory, e.g.:
39
40.. code:: shell
41
42   PATH=<toolchain_dir>/clang+llvm-18.1.8-x86_64-linux-gnu-ubuntu-18.04/bin:$PATH
43
44Dependencies
45------------
46
47Build
48^^^^^
49
50The following command install the dependencies for the Hafnium build:
51
52.. code:: shell
53
54   sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip device-tree-compiler
55
56In addion, install the following python lib using `pip`_:
57
58.. code:: shell
59
60   pip3 install fdt
61
62Documentation
63^^^^^^^^^^^^^
64
65To create a rendered copy of this documentation locally you can use the
66`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
67pages.
68
69For building a local copy of the documentation you will need:
70
71- Python 3 (3.8 or later)
72- PlantUML (1.2017.15 or later)
73- `Poetry`_ (Python dependency manager)
74
75Below is an example set of instructions to get a working environment (tested on
76Ubuntu):
77
78.. code:: shell
79
80    sudo apt install python3 python3-pip plantuml
81    curl -sSL https://install.python-poetry.org | python3 -
82
83To install Python dependencies using Poetry:
84
85.. code:: shell
86
87    poetry install
88
89Poetry will create a new virtual environment and install all dependencies listed
90in ``pyproject.toml``. You can get information about this environment, such as
91its location and the Python version, with the command:
92
93.. code:: shell
94
95    poetry env info
96
97--------------
98
99*Copyright (c) 2023, Arm Limited. All rights reserved.*
100
101.. _Sphinx: http://www.sphinx-doc.org/en/master/
102.. _Poetry: https://python-poetry.org/docs/
103.. _pip: https://pip.pypa.io/en/stable/
104