Improve the running-without-Makefile-patch documentation

 - Include an updated list of environment variables, with sample values

 - Give a method for listing all referenced environment variables, via
   Kconfig.env_vars

 - Remove the note that says that Kconfiglib will warn if an unset
   environment variable is referenced. It's not true anymore with the
   preprocessor, which silently expands unset variables to the empty
   string.

   Not setting essential environment variables causes obvious errors at
   least.

1 files changed, 28 insertions, 13 deletions

diff --git a/kconfiglib.py b/kconfiglib.py
index cb194c6..1d6a1e3 100644
--- a/kconfiglib.py
+++ b/kconfiglib.py
@@ -78,23 +78,38 @@ See the examples/ subdirectory for example scripts.
 Using Kconfiglib without the Makefile targets
 =============================================
 
-The make targets are only needed for a trivial reason: The Kbuild makefiles
-export environment variables which are referenced inside the Kconfig files and
-in scripts run from the Kconfig files (via e.g. 'source
-"arch/$(SRCARCH)/Kconfig" and '$(shell,...)').
-
-The environment variables referenced as of writing (Linux 4.2.18-rc4) are
-srctree, ARCH, SRCARCH, CC, and KERNELVERSION.
-
-To run Kconfiglib without the Makefile patch, you can do this:
-
-  $ srctree=. ARCH=x86 SRCARCH=x86 CC=gcc KERNELVERSION=`make kernelversion` python(3)
+The make targets are only needed to pick up environment variables exported from
+the Kbuild makefiles and referenced inside Kconfig files, via e.g.
+'source "arch/$(SRCARCH)/Kconfig" and '$(shell,...)'.
+
+These variables are referenced as of writing (Linux 4.18), together with sample
+values:
+
+  srctree          (.)
+  ARCH             (x86)
+  SRCARCH          (x86)
+  KERNELVERSION    (4.18.0)
+  CC               (gcc)
+  HOSTCC           (gcc)
+  HOSTCXX          (g++)
+  CC_VERSION_TEXT  (gcc (Ubuntu 7.3.0-16ubuntu3) 7.3.0)
+
+To run Kconfiglib without the Makefile patch, set the environment variables
+manually:
+
+  $ srctree=. ARCH=x86 SRCARCH=x86 KERNELVERSION=`make kernelversion` ... python(3)
   >>> import kconfiglib
   >>> kconf = kconfiglib.Kconfig()  # filename defaults to "Kconfig"
 
 Search the top-level Makefile for "Additional ARCH settings" to see other
-possibilities for ARCH and SRCARCH. Kconfiglib will print a warning if an unset
-environment variable is referenced inside the Kconfig files.
+possibilities for ARCH and SRCARCH.
+
+To see a list of all referenced environment variables together with their
+values, run this code from e.g. 'make iscriptconfig':
+
+  import os
+  for var in kconf.env_vars:
+      print(var, os.environ[var])
 
 
 Intro to symbol values