Add more clarifications on boolean configuration variables
Clarify the values that should be set in makefiles for default enabled/
default disabled CFG_ variables. Also mention the only two acceptable ways
to set such variables.
Signed-off-by: Jerome Forissier <jerome.forissier@linaro.org>
Acked-by: Etienne Carriere <etienne.carriere@linaro.org>
Acked-by: Jens Wiklander <jens.wiklander@linaro.org>
diff --git a/building/gits/optee_os.rst b/building/gits/optee_os.rst
index 732e150..1c19fe3 100644
--- a/building/gits/optee_os.rst
+++ b/building/gits/optee_os.rst
@@ -428,8 +428,9 @@
Boolean configuration variables
-------------------------------
When a configuration variable controls the presence or absence of a feature,
-``y`` means **enabled**, while ``n``, empty value or an undefined variable means
-**disabled**. For instance, the following commands are equivalent and would
+``y`` means **enabled**, while anything else means **disabled**. In particular,
+a variable that is undefined or is defined but has an empty value is also
+disabled. For example, the following commands are equivalent and would
disable feature ``CFG_CRYPTO_GCM``:
.. code-block:: bash
@@ -449,8 +450,45 @@
$ export CFG_CRYPTO_GCM=n
$ make
-Configuration variables may then be used directly in ``sub.mk`` to trigger
-conditional compilation:
+When a configuration variable is introduced, the proper way to enable it by
+default is to write ``CFG_XXX ?= y``. If it should be default disabled
+instead, use ``CFG_XXX ?= n`` rather than leaving the variable undefined,
+and add a description in a comment.
+
+In general, common settings belong in ``mk/config.mk`` while platform-specific
+ones should go in ``core/arch/$(arch)/plat-$(platform)/conf.mk`` (there are
+exceptions, for instance crypto settings have their own ``crypto.mk`` files).
+Both places may be used in case a platform needs to set a default value that
+is different from the one that is set in the global configuration file. For
+example:
+
+.. code-block:: text
+
+ # CFG_FOO is enabled by default except for PLATFORM=xyz
+ # Override with "make CFG_FOO=y" is allowed
+
+ # In core/arch/$(arch)/plat-xyz/conf.mk
+ CFG_FOO ?= n
+
+ # In mk/config.mk
+ CFG_FOO ?= y
+
+.. code-block:: text
+
+ # CFG_FOO is enabled by default except for PLATFORM=xyz that requires
+ # CFG_FOO disabled
+ # Override with "make CFG_FOO=y" is NOT allowed
+
+ # In core/arch/$(arch)/plat-xyz/conf.mk
+ $(call force,CFG_FOO,n)
+
+ # In mk/config.mk
+ CFG_FOO ?= y
+
+``y`` and ``n`` can be swapped to achieve the opposite scenario.
+
+Configuration variables can easily be used in ``sub.mk`` to trigger conditional
+compilation:
.. code-block:: make
@@ -458,6 +496,8 @@
subdirs-$(CFG_CRYPTO_CCM) += ccm
subdirs-$(CFG_CRYPTO_GCM) += gcm
+It is not recommended to set ``CFG_`` values in ``sub.mk``.
+
When a configuration variable is **enabled** (``y``), ``<generated/conf.h>``
contains a macro with the same name as the variable and the value ``1``. If it
is **disabled**, however, no macro definition is output. This allows the C code
@@ -516,6 +556,15 @@
$ make -j10 PLATFORM=hikey CFG_TEE_CORE_NB_CORE=4
core/arch/arm/plat-hikey/conf.mk:5: *** CFG_TEE_CORE_NB_CORE is set to '4' (from command line) but its value must be '8'. Stop.
+There are only two ways...
+--------------------------
+Given what has been explained above, there are only two valid ways to set a ``CFG_``
+variable in a ``.mk`` file: either with ``?=`` if the value is a default that
+may be changed at build time, or with ``$(call force,...)`` if there is only
+one acceptable value. Using ``=`` or ``:=`` in particular is **not** correct
+because they allow overrides on the command line (``make CFG_FOO=foo``) but
+not from the environment (``CFG_FOO=foo make``).
+
Configuration dependencies
--------------------------
Some combinations of configuration variables may not be valid. This should be