Add cleaner way to conditionally compile files

docs/api-guides/build-system.rst

@@ -396,7 +396,8 @@ Adding conditional configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The configuration system can be used to conditionally compile some files
-depending on the options selected in ``make menuconfig``:
+depending on the options selected in ``make menuconfig``. For this, ESP-IDF
+has the compile_only_if and compile_only_if_not macros:
 
 ``Kconfig``::
 
@@ -407,14 +408,56 @@ depending on the options selected in ``make menuconfig``:
 
 ``component.mk``::
 
-    COMPONENT_OBJS := foo_a.o foo_b.o
+    $(call compile_only_if,$(CONFIG_FOO_ENABLE_BAR),bar.o)
 
-    ifdef CONFIG_FOO_BAR
-    COMPONENT_OBJS += foo_bar.o foo_bar_interface.o
-    endif
 
-See the `GNU Make Manual` for conditional syntax that can be used use in makefiles.
+As can be seen in the example, the ``compile_only_if`` macro takes a condition and a 
+list of object files as parameters. If the condition is true (in this case: if the
+BAR feature is enabled in menuconfig) the object files (in this case: bar.o) will
+always be compiled. The opposite goes as well: if the condition is not true, bar.o 
+will never be compiled. ``compile_only_if_not`` does the opposite: compile if the 
+condition is false, not compile if the condition is true.
 
+This can also be used to select or stub out an implementation, as such:
+
+``Kconfig``::
+
+    config ENABLE_LCD_OUTPUT
+        bool "Enable LCD output."
+        help
+            Select this if your board has a LCD.
+
+    config ENABLE_LCD_CONSOLE
+        bool "Output console text to LCD"
+        depends on ENABLE_LCD_OUTPUT
+        help
+            Select this to output debugging output to the lcd
+
+    config ENABLE_LCD_PLOT
+        bool "Output temperature plots to LCD"
+        depends on ENABLE_LCD_OUTPUT
+        help
+            Select this to output temperature plots
+
+
+``component.mk``::
+
+    # If LCD is enabled, compile interface to it, otherwise compile dummy interface
+    $(call compile_only_if,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-real.o lcd-spi.o)
+    $(call compile_only_if_not,$(CONFIG_ENABLE_LCD_OUTPUT),lcd-dummy.o)
+
+    #We need font if either console or plot is enabled
+    $(call compile_only_if,$(or $(CONFIG_ENABLE_LCD_CONSOLE),$(CONFIG_ENABLE_LCD_PLOT)), font.o)
+
+Note the use of the Make 'or' function to include the font file. Other substitution functions,
+like 'and' and 'if' will also work here. Variables that do not come from menuconfig can also 
+be used: ESP-IDF uses the default Make policy of judging a variable which is empty or contains 
+only whitespace to be false while a variable with any non-whitespace in it is true.
+
+(Note: Older versions of this document advised conditionally adding object file names to
+``COMPONENT_OBJS``. While this still is possible, this will only work when all object 
+files for a component are named explicitely, and will not clean up deselected object files
+in a ``make clean`` pass.)
 
 Source Code Generation
 ^^^^^^^^^^^^^^^^^^^^^^