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

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"
 

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
 -------------------------------
 

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
+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

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