1Building
2========
3
4This page assumes the :ref:`Prerequisites` have been followed to install all project dependencies.
5
6Hafnium
7^^^^^^^
8
9Most common options
10~~~~~~~~~~~~~~~~~~~
11
12By default, Hafnium builds all target platforms along with tests with clang.
13From Hafnium top level directory, use:
14
15.. code:: shell
16
17   make
18
19The resulting Hafnium images are located in `out/reference/<platform>/hafnium.bin`.
20
21It is possible to build Hafnium for a single platform target omitting tests,
22resulting in faster builds when the test suite is not required.
23For example to build the SPMC targeting FVP:
24
25.. code:: shell
26
27   make PLATFORM=secure_aem_v8a_fvp_vhe
28
29The resulting FVP image is located in
30`out/reference/secure_aem_v8a_fvp_vhe_clang/hafnium.bin`.
31
32Multiple platform names can be provided for building e.g.:
33
34.. code:: shell
35
36   make PLATFORM="secure_aem_v8a_fvp_vhe,secure_tc"
37
38To get a list of available platforms, you may use:
39
40.. code:: shell
41
42    make list
43
44resulting in:
45
46.. code:: shell
47
48    Supported platforms:  ['secure_rd_fremont', 'secure_rd_fremont_cfg1', 'secure_aem_v8a_fvp_vhe', 'aem_v8a_fvp_vhe', 'aem_v8a_fvp_vhe_ffa_v1_1', 'qemu_aarch64_vhe', 'secure_qemu_aarch64', 'rpi4', 'secure_tc']
49
50Additional options
51~~~~~~~~~~~~~~~~~~
52
53The presence of assertions in the final build can be set using the `ENABLE_ASSERTIONS`
54make variable, by default this is set to `true`, meaning asserts are included in the build.
55
56.. code:: shell
57
58   make ENABLE_ASSERTIONS=<true|false>
59
60Each project in the `project` directory specifies a root configurations of the
61build. Adding a project is the preferred way to extend support to new platforms.
62The target project that is built is selected by the `PROJECT` make variable, the
63default project is 'reference'.
64
65.. code:: shell
66
67   make PROJECT=<project_name>
68
69If you wish to change the value of the make variables you may need to first use:
70
71.. code:: shell
72
73   make clobber
74
75So the `args.gn` file will be regenerated with the new values.
76
77Troubleshoot(Clean Up Artifacts)
78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
79Before building Hafnium, ensure the Clang toolchain is installed and available
80in your `PATH`. This is usually sufficient for a successful build.
81
82If you encounter errors related to missing or incompatible C library headers
83(e.g., after a failed build or toolchain update), clean up stale artifacts by running:
84
85.. code:: shell
86
87   make clobber
88
89This command removes previously generated build outputs, which can help resolve
90issues caused by outdated intermediate files. It's a useful troubleshooting step
91but not required for a fresh setup.
92
93.. _Using_Docker:
94
95Using Docker
96^^^^^^^^^^^^
97
98We provide a Docker container to ensure a consistent development environment.
99Build the container with `./build/docker/build.sh`. You can run commands in the
100container with `./build/run_in_container.sh -i bash`:
101
102.. code:: shell
103
104   ./build/docker/build.sh
105   ./build/run_in_container.sh -i bash
106   make
107
108Alternatively, the Makefile will automatically use the Docker container
109if the environment variable `HAFNIUM_HERMETIC_BUILD` is set to `true`:
110
111.. code:: shell
112
113   ./build/docker/build.sh
114   HAFNIUM_HERMETIC_BUILD=true make
115
116Hafnium Documentation
117^^^^^^^^^^^^^^^^^^^^^
118
119If you have already sourced a virtual environment, Poetry will respect this and
120install dependencies there.
121
122.. code:: shell
123
124   poetry run make doc
125
126--------------
127
128*Copyright (c) 2023, Arm Limited. All rights reserved.*
129