docs/getting_started/prerequisites.rst

Prerequisites
=============

Build Host
----------

A relatively recent Linux distribution is recommended.
CI runs are done using Ubuntu 22.04 LTS (64-bit).

Toolchain
---------

The following toolchain is recommended for building Hafnium and the test
infrastructure:

- For a x86_64 Ubuntu host,

.. code:: shell

   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

- For a AArch64 Ubuntu host,

.. code:: shell

   https://github.com/llvm/llvm-project/releases/download/llvmorg-18.1.8/clang+llvm-18.1.8-aarch64-linux-gnu.tar.xz

.. note::

   Use of a native toolchain installed on the host (e.g. /usr/bin/clang) is
   not supported.

.. note::

   Using a toolchain version greater, or significantly lesser than the one
   specified is not guaranteed to work.

The PATH environment variable shall be adjusted to contain the LLVM/clang directory, e.g.:

.. code:: shell

   PATH=<toolchain_dir>/clang+llvm-18.1.8-x86_64-linux-gnu-ubuntu-18.04/bin:$PATH

Dependencies
------------

Build
^^^^^

The following command install the dependencies for the Hafnium build:

.. code:: shell

   sudo apt install make libssl-dev flex bison python3 python3-serial python3-pip device-tree-compiler

In addion, install the following python lib using `pip`_:

.. code:: shell

   pip3 install fdt

Documentation
^^^^^^^^^^^^^

To create a rendered copy of this documentation locally you can use the
`Sphinx`_ tool to build and package the plain-text documents into HTML-formatted
pages.

For building a local copy of the documentation you will need:

- Python 3 (3.8 or later)
- PlantUML (1.2017.15 or later)
- `Poetry`_ (Python dependency manager)

Below is an example set of instructions to get a working environment (tested on
Ubuntu):

.. code:: shell

    sudo apt install python3 python3-pip plantuml
    curl -sSL https://install.python-poetry.org | python3 -

Run the command below to install using Poetry, Python dependencies to build the documentation:

.. code:: shell

    poetry install --with docs

Poetry will create a new virtual environment and install all dependencies listed
in ``pyproject.toml``. You can get information about this environment, such as
its location and the Python version, with the command:

.. code:: shell

    poetry env info

--------------

*Copyright (c) 2023, Arm Limited. All rights reserved.*

.. _Sphinx: http://www.sphinx-doc.org/en/master/
.. _Poetry: https://python-poetry.org/docs/
.. _pip: https://pip.pypa.io/en/stable/