From 5f3cb9f9dc84096562759ddb542f305dd1cb25de Mon Sep 17 00:00:00 2001
From: Angus Gratton <angus@espressif.com>
Date: Tue, 5 Sep 2017 16:10:00 +1000
Subject: [PATCH] build system: Document --warn-undefined-variables and add a
 config item for it

---
 Kconfig                          | 14 +++++++++++++-
 docs/api-guides/build-system.rst | 11 +++++++++++
 docs/api-reference/kconfig.rst   | 11 ++++++++++-
 make/common.mk                   |  6 +++++-
 4 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/Kconfig b/Kconfig
index 9611cf773e..2cf2424812 100644
--- 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 a86698e4cc..34e35de3de 100644
--- 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 21bcf6b380..28c4439aab 100644
--- 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 358c880889..ea39421cb0 100644
--- 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