build system: Document --warn-undefined-variables and add a config item for it

diff --git a/Kconfig b/Kconfig
index 9611cf773eab0957af9645d0ad99232d00263d6f..2cf242481247ceb846e26093ea18d56bf19425c3 100644 (file)
--- a/Kconfig
+++ b/Kconfig
@@ -19,7 +19,19 @@ config PYTHON
     help
         The executable name/path that is used to run python. On some systems Python 2.x
         may need to be invoked as python2.
-endmenu
+
+config MAKE_WARN_UNDEFINED_VARIABLES
+    bool "'make' warns on undefined variables"
+    default "y"
+    help
+        Adds --warn-undefined-variables to MAKEFLAGS. This causes make to
+        print a warning any time an undefined variable is referenced.
+
+        This option helps find places where a variable reference is misspelled
+        or otherwise missing, but it can be unwanted if you have Makefiles which
+        depend on undefined variables expanding to an empty string.
+
+endmenu  # SDK tool configuration
 
 source "$COMPONENT_KCONFIGS_PROJBUILD"
 

diff --git a/docs/api-guides/build-system.rst b/docs/api-guides/build-system.rst
index a86698e4ccd790352c3a2999e83805932c24aff2..34e35de3de71ae08aa4dc47cf0c979681fb58281 100644 (file)
--- a/docs/api-guides/build-system.rst
+++ b/docs/api-guides/build-system.rst
@@ -351,6 +351,17 @@ Some tips for debugging the esp-idf build system:
 
 For more debugging tips and general make information, see the `GNU Make Manual`.
 
+.. _warn-undefined-variables:
+
+Warning On Undefined Variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the build process will print a warning if an undefined variable is referenced (like ``$(DOES_NOT_EXIST)``). This can be useful to find errors in variable names.
+
+If you don't want this behaviour, it can be disabled by disabling :ref:`CONFIG_MAKE_WARN_UNDEFINED_VARIABLES`.
+
+Note that this option doesn't trigger a warning if ``ifdef`` or ``ifndef`` are used in Makefiles.
+
 Overriding Parts of the Project
 -------------------------------
 

diff --git a/docs/api-reference/kconfig.rst b/docs/api-reference/kconfig.rst
index 21bcf6b3804fd212d163326bf2e6f3fa7ff25bb4..28c4439aab05aa836251acfc8ece7fb45cc6ca36 100644 (file)
--- a/docs/api-reference/kconfig.rst
+++ b/docs/api-reference/kconfig.rst
@@ -25,4 +25,13 @@ By convention, all option names are upper case with underscores. When Kconfig ge
 
 .. include:: /_build/inc/kconfig.inc
 
-.. _Kconfig: https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt
\ No newline at end of file
+Customisations
+==============
+
+Because IDF builds by default with :ref:`warn-undefined-variables`, when the Kconfig tool generates Makefiles (the ``auto.conf`` file) its behaviour has been customised. In normal Kconfig, a variable which is set to "no" is undefined. In IDF's version of Kconfig, this variable is defined in the Makefile but has an empty value.
+
+(Note that ``ifdef`` and ``ifndef`` can still be used in Makefiles, because they test if a variable is defined *and has a non-empty value*.)
+
+When generating header files for C & C++, the behaviour is not customised - so ``#ifdef`` can be used to test if a boolean config item is set or not.
+
+.. _Kconfig: https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt

diff --git a/make/common.mk b/make/common.mk
index 358c8808890faf8af2c5101c563acd09f673cc84..ea39421cb0dbfa1576ffb63ab9f7212a15492f0d 100644 (file)
--- a/make/common.mk
+++ b/make/common.mk
@@ -27,9 +27,13 @@ details := @echo
 else
 summary := @echo
 details := @true
+endif
 
 # disable echoing of commands, directory names
-MAKEFLAGS += --silent --warn-undefined-variables
+MAKEFLAGS += --silent
+
+ifdef CONFIG_MAKE_WARN_UNDEFINED_VARIABLES
+MAKEFLAGS += --warn-undefined-variables
 endif
 
 # General make utilities