Add first version of CMake framework code
This commit adds the core elements of the framework and documentation:
- Map utility: store key-value pairs.
- Group utility: store build configuration options.
- STGT API: describe the targets.
- Compiler abstraction functions for GCC.
- Other helper functions.
- New CMake system type called "Embedded", using correct output file
prefixes and extensions.
- Sphinx based documentation which includes:
- licensing information
- version numbering policy
- documentation on how-to build the documentation
In addition the following utility files are added:
- .editorconfig
- .gitignore
Change-Id: If19a171ef066775d3544fba82f1cc70a5fb0e7d7
Signed-off-by: Balint Dobszay <balint.dobszay@arm.com>
Co-authored-by: Gyorgy Szing <gyorgy.szing@arm.com>
Co-authored-by: Bence Szépkúti <bence.szepkuti@arm.com>
diff --git a/doc/user_guide.rst b/doc/user_guide.rst
new file mode 100644
index 0000000..d4e87e4
--- /dev/null
+++ b/doc/user_guide.rst
@@ -0,0 +1,180 @@
+User Guide
+==========
+
+This guide describes how the framework features are supposed to be used, through
+an example implementation for the |TF-A| project. Please refer to the `TF-A
+repository`_ for the code.
+
+Root CMakeLists file
+--------------------
+
+The root CMakeLists file contains the following sections:
+
+#. Set required CMake version
+
+ This is mandatory at the start of every CMake project. The framework
+ requires version 3.13 or newer.
+
+#. Set default build type
+
+ Set the default value for ``CMAKE_BUILD_TYPE`` as a cache entry. This
+ ensures that the variable will have a value when it is not specified as a
+ command line argument.
+
+#. Set project root dir
+
+ This is not strictly necessary, but makes referring to project relative
+ paths easier. Using ``CMAKE_CURRENT_LIST_DIR`` is recommended, it contains
+ the absolute path to the directory containing the currently processed file.
+
+#. Find the framework
+
+ The framework is written as a CMake module, which can be used by
+ :cmake:command:`find_package`. This will take care of the version matching
+ and adding the framework dir to the module path.
+
+ In the example, we try to find the framework at the parent directory of the
+ TF-A project dir and inside the TF-A project. If the framework is not
+ found, we clone the git repository using :cmake:module:`FetchContent`. The
+ path to the framework can also be provided as a command line option to
+ CMake, using ``-DTFACMF_DIR=<path to framework>``.
+
+#. Add project specific paths
+
+ There are some CMake modules which are specific to the project, so cannot
+ be part of the generic framework (e.g. find fiptool). These should also be
+ added to the module path.
+
+#. Set CMake system parameters
+
+ The framework provides a new platform called ``Embedded``. The project
+ should set :cmake:variable:`CMAKE_SYSTEM_NAME` to ``Embedded`` in order to
+ use the platform. This is an important step as this method is the only way
+ in CMake to ensure the correct output extension, library name
+ prefix/suffix, etc.
+
+ :cmake:variable:`CMAKE_SYSTEM_PROCESSOR` should be set to ``arm``. This has
+ no particular effect, but it indicates that the project is cross-compiled.
+
+#. Include framework files
+
+ It is more convenient to include the framework files here. The config and
+ target files included later will inherit the environment.
+
+#. Start CMake project
+
+ The start of a CMake project, ``C`` and ``ASM`` languages should be
+ selected.
+
+#. Find platform module
+
+ Currently for finding platform related config a minimal
+ :cmake:command:`find_package` module is implemented. These module files
+ describing the platform are located in the ``<TF-A root>/cmake/HwPlat``
+ directory, which is added to :cmake:variable:`CMAKE_MODULE_PATH` in the
+ project specific paths section.
+
+ A platform description file contains more :cmake:command:`find_package`
+ calls to find other external tools which are needed by the platform, and
+ sets the following global variables:
+
+ * :cmake:variable:`HW_PLAT_CONFIG`: path to config file which contains
+ the :cmake:module:`group` for the platform options,
+ * :cmake:variable:`HW_PLAT_TARGET`: path to target file which contains
+ target creation, adding source files, etc. for the platform,
+ * :cmake:variable:`HW_PLAT_IMAGE`: path to file which describes the steps
+ of packaging the compiled binaries into an image (e.g. fiptool usage).
+
+ The files indicated by these variables should be included in the relevant
+ sections of the root CMakeLists file, as described below.
+
+#. Include config files
+
+ All the config files containing the settings groups have to be included.
+ These create and fill the groups with content, so in the target files we
+ can select which group to apply on which target. This means including the
+ :cmake:variable:`HW_PLAT_CONFIG` too.
+
+#. Include target files
+
+ The target files selected for the current build have to be included. These
+ create the target and add source files, includes, etc. to the target.
+ Include :cmake:variable:`HW_PLAT_TARGET` in this section.
+
+ Currently there is no solution provided to select which targets are
+ necessary, except adding/removing the include command in this section. A
+ better solution would be to decide based on the current build configuration
+ (from Kconfig?) so targets can be selected without modifying the CMakeLists
+ file.
+
+#. Include image files
+
+ The files describing how to package the output binaries into an image can
+ be included here. Since this is platform specific, only
+ :cmake:variable:`HW_PLAT_IMAGE` should be used.
+
+Config file
+-----------
+
+The config files are located in the ``<TF-A root>/configs`` directory. Each
+config file creates a :cmake:module:`group` using :cmake:command:`group_new` and
+fills the group with content using :cmake:command:`group_add`.
+
+An important topic in the example is the difference between the ``CONFIG`` and
+``DEFINE`` types in a group. The idea is, that ``CONFIG`` is a parameter that
+affects the build, i.e. what sources are necessary for a given target, etc.
+while ``DEFINE`` is a simple C language define. Often a build option falls into
+both categories, but not necessarily. For example,
+
+* ``ENABLE_AMU`` is a config, because it affects the build, it determines
+ whether ``amu.c`` is added to ``BL31`` or not. It is a define too, because
+ there is ``#if ENABLE_AMU`` conditional compilation in the C source,
+
+* ``FVP_MAX_PE_PER_CPU`` is a define only, because it does not affect the list
+ of files necessary for the build,
+
+* ``ENABLE_STACK_PROTECTOR`` is a config only, because it is never used in the
+ source code.
+
+Target file
+-----------
+
+A target file can be one of two types, ``CMakeLists.txt`` or ``<module
+name>.cmake``. The former is for a module which is likely to be reused in other
+projects and can be built stand-alone, the latter is a module which only has
+meaning as part of the project. A ``CMakeLists.txt`` must contain a
+:cmake:command:`project` command and has to be included using
+:cmake:command:`add_subdirectory`, while a ``<module name>.cmake`` cannot start
+a new project and the file is simply included with the :cmake:command:`include`
+command.
+
+A target file uses the :cmake:module:`STGT` functions to create a target, add
+groups to the target, add source files, etc. Please check the example code in
+TF-A, e.g.:
+
+* ``bl*/bl*.cmake``
+* ``plat/arm/board/fvp/platform.cmake``
+* ``plat/arm/common/arm_common.cmake``
+* ``lib/libc/CMakeLists.txt``
+* etc.
+
+Image file
+----------
+
+The purpose of this file is to package the output binaries into an image, using
+the platform specific tools. The recommendation is to use
+:cmake:command:`add_custom_target` which depends on the targets/files packaged
+into the image. It is likely that ``ALL`` should be added to the command
+options, since usually this image is the final output of the build, so no other
+targets will depend on this therefore it would not be built without ``ALL``.
+Please check the example in ``plat/arm/board/fvp/image.cmake``.
+
+.. todo:: Add support for ``install`` feature of CMake.
+
+--------------
+
+.. _`TF-A repository`: https://git.trustedfirmware.org/TF-A/trusted-firmware-a.git/
+
+*Copyright (c) 2019-2020, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause