build(cmake): create initial `CMakeLists.txt`
This change adds the initial `CMakeLists.txt` file, which represents
our brand new build system entrypoint.
CMake 3.20 has been chosen as our supported CMake version, as it is
reasonably recent (allowing us to write more expressive CMake list
files) while still being relatively easy to acquire.
Some minor changes to our documentation configuration have also been
made to allow us to effectively document the build system, including
the addition of Intersphinx and the CMake Sphinx domain. Combined,
these allow us to link to the official CMake documentation and to
provide semantic CMake documentation.
Change-Id: I961ec1b51492ce2c77732a3c23cbb2f1de7ff805
Signed-off-by: Chris Kay <chris.kay@arm.com>
Co-authored-by: Balint Dobszay <balint.dobszay@arm.com>
Co-authored-by: Bence Szépkúti <bence.szepkuti@arm.com>
Co-authored-by: Gyorgy Szing <gyorgy.szing@arm.com>
Co-authored-by: Jack Bond-Preston <jack.bond-preston@arm.com>
diff --git a/docs/cmake/manual/modules.rst b/docs/cmake/manual/modules.rst
new file mode 100644
index 0000000..c9b6059
--- /dev/null
+++ b/docs/cmake/manual/modules.rst
@@ -0,0 +1,48 @@
+Modules
+=======
+
+.. default-domain:: cmake
+
+.. contents::
+
+This page documents the CMake modules that are packaged with the build system,
+and which offer convenience functions for actions used frequently within it.
+
+See the :manual:`cmake-modules(7) <manual:cmake-modules(7)>` manual for a list
+of modules provided by CMake directly.
+
+Utility Modules
+---------------
+
+Internal Modules
+^^^^^^^^^^^^^^^^
+
+Modules specific to the Trusted Firmware-A build system.
+
+.. toctree::
+ :glob:
+ :maxdepth: 1
+
+External Modules
+^^^^^^^^^^^^^^^^
+
+Modules used by, but with no strict relation to, the Trusted Firmware-A build
+system.
+
+.. toctree::
+ :glob:
+ :maxdepth: 1
+
+Find Modules
+------------
+
+CMake :ref:`Find Modules`, used to locate libraries and programs on the host
+system.
+
+.. toctree::
+ :glob:
+ :maxdepth: 1
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_BINARY_DIR.rst b/docs/cmake/manual/variable/common/TFA_BINARY_DIR.rst
new file mode 100644
index 0000000..1bf2955
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_BINARY_DIR.rst
@@ -0,0 +1,13 @@
+TFA_BINARY_DIR
+==============
+
+.. default-domain:: cmake
+
+.. variable:: TFA_BINARY_DIR
+
+Top-level binary directory for the Trusted Firmware-A project. See
+:variable:`<PROJECT-NAME>_BINARY_DIR <variable:<PROJECT-NAME>_BINARY_DIR>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_SOURCE_DIR.rst b/docs/cmake/manual/variable/common/TFA_SOURCE_DIR.rst
new file mode 100644
index 0000000..ec94724
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_SOURCE_DIR.rst
@@ -0,0 +1,13 @@
+TFA_SOURCE_DIR
+==============
+
+.. default-domain:: cmake
+
+.. variable:: TFA_SOURCE_DIR
+
+Top-level source directory for the Trusted Firmware-A project. See
+:variable:`<PROJECT-NAME>_SOURCE_DIR <variable:<PROJECT-NAME>_SOURCE_DIR>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_VERSION.rst b/docs/cmake/manual/variable/common/TFA_VERSION.rst
new file mode 100644
index 0000000..b4f0b8e
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_VERSION.rst
@@ -0,0 +1,13 @@
+TFA_VERSION
+===========
+
+.. default-domain:: cmake
+
+.. variable:: TFA_VERSION
+
+Current version of the Trusted Firmware-A project. See
+:variable:`<PROJECT-NAME>_VERSION <variable:<PROJECT-NAME>_VERSION>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_VERSION_MAJOR.rst b/docs/cmake/manual/variable/common/TFA_VERSION_MAJOR.rst
new file mode 100644
index 0000000..d746359
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_VERSION_MAJOR.rst
@@ -0,0 +1,13 @@
+TFA_VERSION_MAJOR
+=================
+
+.. default-domain:: cmake
+
+.. variable:: TFA_VERSION_MAJOR
+
+First version number component of the :variable:`TFA_VERSION` variable. See
+:variable:`<PROJECT-NAME>_VERSION_MAJOR <variable:<PROJECT-NAME>_VERSION_MAJOR>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_VERSION_MINOR.rst b/docs/cmake/manual/variable/common/TFA_VERSION_MINOR.rst
new file mode 100644
index 0000000..b5a0334
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_VERSION_MINOR.rst
@@ -0,0 +1,13 @@
+TFA_VERSION_MINOR
+=================
+
+.. default-domain:: cmake
+
+.. variable:: TFA_VERSION_MINOR
+
+Second version number component of the :variable:`TFA_VERSION` variable. See
+:variable:`<PROJECT-NAME>_VERSION_MINOR <variable:<PROJECT-NAME>_VERSION_MINOR>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_VERSION_PATCH.rst b/docs/cmake/manual/variable/common/TFA_VERSION_PATCH.rst
new file mode 100644
index 0000000..fc5d59d
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_VERSION_PATCH.rst
@@ -0,0 +1,13 @@
+TFA_VERSION_PATCH
+=================
+
+.. default-domain:: cmake
+
+.. variable:: TFA_VERSION_PATCH
+
+Third version number component of the :variable:`TFA_VERSION` variable. See
+:variable:`<PROJECT-NAME>_VERSION_PATCH <variable:<PROJECT-NAME>_VERSION_PATCH>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variable/common/TFA_VERSION_TWEAK.rst b/docs/cmake/manual/variable/common/TFA_VERSION_TWEAK.rst
new file mode 100644
index 0000000..e0dd202
--- /dev/null
+++ b/docs/cmake/manual/variable/common/TFA_VERSION_TWEAK.rst
@@ -0,0 +1,13 @@
+TFA_VERSION_TWEAK
+=================
+
+.. default-domain:: cmake
+
+.. variable:: TFA_VERSION_TWEAK
+
+Fourth version number component of the :variable:`TFA_VERSION` variable. See
+:variable:`<PROJECT-NAME>_VERSION_TWEAK <variable:<PROJECT-NAME>_VERSION_TWEAK>`.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/cmake/manual/variables.rst b/docs/cmake/manual/variables.rst
new file mode 100644
index 0000000..e61ede6
--- /dev/null
+++ b/docs/cmake/manual/variables.rst
@@ -0,0 +1,63 @@
+Variables
+=========
+
+.. default-domain:: cmake
+
+.. contents::
+
+This page documents variables that are provided by the build system, grouped by
+the component that manages them. For general information on variables in CMake,
+see the :ref:`Variables <CMake Language Variables>` section of the
+:manual:`cmake-language(7) <manual:cmake-language(7)>` manual.
+
+Intrinsic Variables
+-------------------
+
+Variables defined by CMake, but which have a value or meaning defined by the
+Trusted Firmware-A build system. For documentation on *all* intrinsic CMake
+variables, see the :manual:`cmake-variables(7) <manual:cmake-variables(7)>`
+manual.
+
+.. toctree::
+ :glob:
+ :maxdepth: 1
+
+Common Variables
+----------------
+
+Variables which are always defined.
+
+.. toctree::
+ :glob:
+ :maxdepth: 1
+
+ variable/common/*
+
+Bootloader Variables
+--------------------
+
+Variables defined by individual bootloader images. These variables may not be
+defined if the bootloader image is not compatible with the platform.
+
+Library Variables
+-----------------
+
+Variables defined by individual libraries and other non-core components. These
+variables may not be defined if the library or component is not being included
+in the build.
+
+Driver Variables
+----------------
+
+Variables defined by individual drivers. These variables may not be defined if
+the driver is not being included in the build.
+
+Platform Variables
+------------------
+
+Variables defined by individual platforms. These variables may not be defined if
+the platform is not being included in the build.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*