Build Instructions ================== All trusted service builds use CMake to create native build files for building and installing service binaries and other build products. Details about the tools needed for building are specified here: :ref:`Software Requirements`. All top-level build files are located beneath the 'deployments' parent directory under a sub-directory for each deployment. For more information about the project directory structure, see: :ref:`Project Structure`. Build Flow ---------- All deployment builds follow a common flow that results in the creation of executable binaries or libraries and the installation of files into an output directory. Deploying the contents of the output directory into the target environment is handled in an environment specific way and is not part of the common build flow. The build flow conforms to the conventional CMake process where building takes place in to following two stages: 1. Native build files, such as makefiles, are generated from CMake configuration files. 2. Native build tools, such as make, are used to build and install items, ready for deployment. The following activity diagram illustrates the common deployment build flow. The green activity states lie outside of the common build flow. Environment specific instructions are provided for deploying into different environments: .. uml:: uml/BuildFlow.puml Selecting the build type ------------------------- The build type selects code optimization and debug information related compiler settings. The build system follows the standard CMake methodology and uses the `CMAKE_BUILD_TYPE`_ variable. The build system uses the following build types: .. list-table:: Supported build types :header-rows: 1 * - Build type - Purpose - Description * - Debug - For debugging purposes. - Optimization is off, debugging information generation is enabled. * - MinSizeRel - Size optimized release build. - Optimization is configured to prefer small code size, debugging information is not generated. * - MinSizWithDebInfo - For debugging size optimized release build. - Optimization is configured to prefer small code size, debugging information generation is enabled. * - Release - Speed optimized release build. - Optimization is configured to prefer execution speed, debugging information is not generated. * - RelWithDebugInfo - For debugging speed optimized release build. - Optimization is configured to prefer execution speed, debugging information generation is enabled. Build type of external components can be configured with command line parameters. Parameter names follow this pattern: ``-D_BUILD_TYPE=`` e.g. ``-DNANOPB_BUILD_TYPE=Release``. Supported values are component specific, please refer to the appropriate cmake file under ``/external/``. Building and Installing ----------------------- When building from a clean environment where no generated build files exist, it is necessary to run the CMake command, specifying the source directory, the build directory and optionally, the install directory where build output is installed. To illustrate the steps involved, we will build the 'component-test' executable to run in the 'linux-pc' environment. The built executable is a standalone program that uses the CppUTest framework to run a set of component level tests on components from within the project. For this example, it is assumed that we are building under Linux and 'make' is used as the native build tool. The described steps may be used for any of the deployments under the top-level *deployments* directory. Starting from the project root directory, change directory to the relevant deployment directory:: cd deployments/component-test/linux-pc Build file generation is performed using the CMake command. If no CMAKE_INSTALL_PREFIX path is specified, build output will be installed in the default location (*build/install*). To generate build files that install to the default location, use:: cmake -S . -B build To generate build files that install to an alternative location, use:: cmake -S . -B build -DCMAKE_INSTALL_PREFIX= Having successfully generated build files, the native build tool may be run to build and install files using:: cd build make install In the above example, all build output is written to a sub-directory called 'build'. You are free to choose any location for build output. Dependencies on external components and in-tree built objects, such as libraries, are handled automatically by the build system during the *generating* phase. External components are fetched from the relevant source repository and built as part of the build context for the deployment binary being built. This allows deployment specific configuration and compiler options to be applied to the external component without impacting other builds. Dependencies on in-tree built libraries are handled in a similar manner. For information on running tests, see: :ref:`Running Tests`. For more information on deployments, see: :ref:`Deployments`. Installed build output files ---------------------------- On successfully completing the *building* phase of the build flow, a set of build output files are installed to the directory specified by CMAKE_INSTALL_PREFIX. The set of installed files will depend on the type of build and the environment in which the files will be deployed. The following table summarizes what files are installed for different typed of build during the *installing* phase of the build flow: .. list-table:: Example build output files :header-rows: 1 * - Deployment type - Environment - Files installed * - Binary executable - linux-pc, arm-linux - | *bin/* - program binary * - Shared library - linux-pc, arm-linux - | *include/* - public header files | *lib/* - shared library | *lib/cmake/* - cmake target import file * - SP image - opteesp - | *bin/* - stripped elf file for SP | *lib/make* - OP-TEE helper makefile * - SP collection - opteesp - | *bin/* - set of stripped elf files | *lib/make/* - set of OP-TEE helper makefiles Deploying installed files ------------------------- Having built and installed build output files to a known directory, further steps may be needed to deploy the files into the target processing environment. The nature of these steps will be different for different environments. To avoid overly complicating the common Trusted Services build system, details of how installed files are deployed into the target execution environment are handled separately and may rely on environment specific tools. Some example deployment methods are: * A filesystem share exists between a build machine and the target machine. Files installed into the shared directory are directly accessible by the target. * Installed files are incorporated into a third-party build process e.g. OP-TEE. The following guides provide instructions on deploying services and running programs on FVP: * :ref:`Deploying trusted services in S-EL0 Secure Partitions under OP-TEE` * :ref:`Running User-space Programs on FVP` Batch Building -------------- To support batching building of a set of deployments, a tool called b-test is included. For more information, see :doc:`b-test page <./b-test>` -------------- .. _CMAKE_BUILD_TYPE: https://cmake.org/cmake/help/v3.18/variable/CMAKE_BUILD_TYPE.html *Copyright (c) 2020-2022, Arm Limited and Contributors. All rights reserved.* SPDX-License-Identifier: BSD-3-Clause