1Build Instructions
2==================
3All trusted service builds use CMake to create native build files for building and installing service binaries
4and other build products.  Details about the tools needed for building are specified here:
5:ref:`Software Requirements`.
6
7All top-level build files are located beneath the 'deployments' parent directory under a sub-directory
8for each deployment.  For more information about the project directory structure, see:
9:ref:`Project Structure`.
10
11Build Flow
12----------
13All deployment builds follow a common flow that results in the creation of executable binaries or libraries
14and the installation of files into an output directory.  Deploying the contents of the output directory into
15the target environment is handled in an environment specific way and is not part of the common build
16flow.  The build flow conforms to the conventional CMake process where building takes place in to following
17two stages:
18
19  1. Native build files, such as makefiles, are generated from CMake configuration files.
20  2. Native build tools, such as make, are used to build and install items, ready for deployment.
21
22The following activity diagram illustrates the common deployment build flow.  The green activity states
23lie outside of the common build flow.  Environment specific instructions are provided for deploying into
24different environments:
25
26.. uml:: uml/BuildFlow.puml
27
28.. _`Selecting the build type`:
29
30Selecting the build type
31-------------------------
32The build type selects code optimization and debug information related compiler settings. The build system follows the
33standard CMake methodology and can be controlled with the `CMAKE_BUILD_TYPE`_ variable.
34
35The build system uses the following build types:
36
37.. list-table:: Supported build types
38   :header-rows: 1
39
40   * - Build type
41     - Purpose
42     - Shared library suffix
43     - Description
44   * - Debug
45     - For debugging purposes.
46     - `d`
47     - Optimization is off, debugging information generation is enabled.
48   * - DebugCoverage
49     - For coverage measurement purposes.
50     - `c`
51     - Optimization is off, debugging information generation is enabled, code is compiled to enable gcov based coverage
52       measurement.
53   * - MinSizeRel
54     - Size optimized release build.
55     - None.
56     - Optimization is configured to prefer small code size, debugging information is not generated.
57   * - MinSizWithDebInfo
58     - For debugging size optimized release build.
59     - None.
60     - Optimization is configured to prefer small code size, debugging information generation is enabled.
61   * - Release
62     - Speed optimized release build.
63     - None.
64     - Optimization is configured to prefer execution speed, debugging information is not generated.
65   * - RelWithDebugInfo
66     - For debugging speed optimized release build.
67     - None.
68     - Optimization is configured to prefer execution speed, debugging information generation is enabled.
69
70Build type of external components can be configured with command line arguments. Argument names follow this pattern:
71``-D<upper case component name>_BUILD_TYPE=<value>`` e.g. ``-DNANOPB_BUILD_TYPE=Release``. Supported values are
72component specific, please refer to the appropriate cmake file under ``<TS_ROOT>/external/<name>``.
73
74Binaries of the ``Debug`` and ``DebugCoverage`` build types will have a suffix appended to their base name. This allows
75multiple binaries to coexist on the same system at the same time. However the system integrator can only select
76a single "release" build type.
77
78
79Building and Installing
80-----------------------
81When building from a clean environment where no generated build files exist, it is necessary to run
82the CMake command, specifying the source directory, the build directory and optionally, the install
83directory where build output is installed.
84
85To illustrate the steps involved, we will build the 'component-test' executable to run in the
86'linux-pc' environment.  The built executable is a standalone program that uses the CppUTest
87framework to run a set of component level tests on components from within the project.  For this
88example, it is assumed that we are building under Linux and 'make' is used as the native build tool.
89
90The described steps may be used for any of the deployments under the top-level *deployments* directory.
91
92Starting from the project root directory, change directory to the relevant deployment directory::
93
94  cd deployments/component-test/linux-pc
95
96Build file generation is performed using the CMake command.  If no CMAKE_INSTALL_PREFIX path is
97specified, build output will be installed in the default location (*build/install*).  To generate
98build files that install to the default location, use::
99
100  cmake -S . -B build
101
102To generate build files that install to an alternative location, use::
103
104  cmake -S . -B build -DCMAKE_INSTALL_PREFIX=<install_dir>
105
106Having successfully generated build files, the native build tool may be run to build and install
107files using::
108
109  cd build
110  make install
111
112In the above example, all build output is written to a sub-directory called 'build'.  You
113are free to choose any location for build output.
114
115Dependencies on external components and in-tree built objects, such as libraries,
116are handled automatically by the build system during the *generating* phase.  External components
117are fetched from the relevant source repository and built as part of the build context for the
118deployment binary being built.  This allows deployment specific configuration and compiler options
119to be applied to the external component without impacting other builds.  Dependencies on in-tree
120built libraries are handled in a similar manner.
121
122For information on running tests, see:
123:ref:`Running Tests`.
124
125For more information on deployments, see:
126:ref:`Deployments`.
127
128Installed build output files
129----------------------------
130On successfully completing the *building* phase of the build flow, a set of build output files are
131installed to the directory specified by CMAKE_INSTALL_PREFIX.  The set of installed files will
132depend on the type of build and the environment in which the files will be deployed.  The following
133table summarizes what files are installed for different typed of build during the *installing* phase
134of the build flow:
135
136.. list-table:: Example build output files
137  :header-rows: 1
138
139  * - Deployment type
140    - Environment
141    - Files installed
142  * - Binary executable
143    - linux-pc, arm-linux
144    - | *bin/* - program binary
145  * - Shared library
146    - linux-pc, arm-linux
147    - | *include/* - public header files
148      | *lib/* - shared library
149      | *lib/cmake/* - cmake target import file
150  * - SP image
151    - opteesp
152    - | *bin/* - stripped elf file for SP
153      | *lib/make* - OP-TEE helper makefile
154  * - SP collection
155    - opteesp
156    - | *bin/* - set of stripped elf files
157      | *lib/make/* - set of OP-TEE helper makefiles
158
159
160Deploying installed files
161-------------------------
162Having built and installed build output files to a known directory, further steps may be needed to
163deploy the files into the target processing environment.  The nature of these steps will be different
164for different environments.
165
166To avoid overly complicating the common Trusted Services build system, details of how installed files
167are deployed into the target execution environment are handled separately and may rely on environment
168specific tools.
169
170Some example deployment methods are:
171
172  * A filesystem share exists between a build machine and the target machine. Files installed into the shared directory are
173    directly accessible by the target.
174  * Installed files are incorporated into a third-party build process e.g. OP-TEE.
175
176The following guides provide instructions on deploying services and running programs on FVP:
177
178* :ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE`
179* :ref:`Running User-space Programs on FVP`
180
181Batch Building
182--------------
183To support batching building of a set of deployments, a tool called b-test is included.  For
184more information, see
185:doc:`b-test page <./b-test>`
186
187--------------
188
189.. _CMAKE_BUILD_TYPE: https://cmake.org/cmake/help/v3.18/variable/CMAKE_BUILD_TYPE.html
190
191*Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.*
192
193SPDX-License-Identifier: BSD-3-Clause
194