examples/usercmodules: Simplify user C module enabling.

dpgeorge · dpgeorge · commit d87f42b0e538 · 2021-04-01T16:27:38.000+11:00
It's a bit of a pitfall with user C modules that including them in the build does not automatically enable them. This commit changes the docs and examples for user C modules to encourage writers of user C modules to enable them unconditionally. This makes things simpler and covers most use cases. See discussion in issue adafruit#6960, and also adafruit#7086. Signed-off-by: Damien George <damien@micropython.org>
diff --git a/docs/develop/cmodules.rst b/docs/develop/cmodules.rst
@@ -149,17 +149,23 @@ applying 2 modifications:
 
 - all modules found in this directory (or added via ``include`` in the top-level
   ``micropython.cmake`` when using CMake) will be compiled, but only those which are
-  explicitly enabled will be available for importing. Enabling a module is done
-  by setting the preprocessor define from its module registration to 1.
+  enabled will be available for importing.  If a module is to always be enabled,
+  which is usually the case for custom modules and custom builds, then it is
+  enough to supply "1" as the third parameter to the registration macro, like:
 
-  For example if the source code defines the module with
+  .. code-block:: c
+
+      MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, 1);
+
+  Alternatively, to make the module disabled by default but selectable through
+  a preprocessor configuration option, use:
 
   .. code-block:: c
 
       MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);
 
 
-  then ``MODULE_CEXAMPLE_ENABLED`` has to be set to 1 to make the module available.
+  Then ``MODULE_CEXAMPLE_ENABLED`` has to be set to 1 to make the module available.
   This can be done by adding ``CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1`` to
   the ``make`` command, or editing ``mpconfigport.h`` or ``mpconfigboard.h``
   to add
@@ -179,7 +185,7 @@ directory can be built for the unix port:
 .. code-block:: bash
 
     cd micropython/ports/unix
-    make USER_C_MODULES=../../examples/usercmodule CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1 all
+    make USER_C_MODULES=../../examples/usercmodule all
 
 The build output will show the modules found::
 
@@ -205,7 +211,6 @@ The CMake build output lists the modules by name::
     ...
 
 
-Note that the ``micropython.cmake`` files define ``DMODULE_<name>_ENABLED=1`` automatically.
 The top-level ``micropython.cmake`` can be used to control which modules are enabled.
 
 
@@ -215,8 +220,7 @@ including both modules and building the stm32 port for example:
 .. code-block:: bash
 
     cd my_project/micropython/ports/stm32
-    make USER_C_MODULES=../../../modules \
-      CFLAGS_EXTRA="-DMODULE_EXAMPLE1_ENABLED=1 -DMODULE_EXAMPLE2_ENABLED=1" all
+    make USER_C_MODULES=../../../modules all
 
 
 Module usage in MicroPython
diff --git a/examples/usercmodule/cexample/examplemodule.c b/examples/usercmodule/cexample/examplemodule.c
@@ -31,4 +31,7 @@ const mp_obj_module_t example_user_cmodule = {
 };
 
 // Register the module to make it available in Python.
-MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);
+// Note: the "1" in the third argument means this module is always enabled.
+// This "1" can be optionally replaced with a macro like MODULE_CEXAMPLE_ENABLED
+// which can then be used to conditionally enable this module.
+MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, 1);
diff --git a/examples/usercmodule/cexample/micropython.cmake b/examples/usercmodule/cexample/micropython.cmake
@@ -11,11 +11,5 @@ target_include_directories(usermod_cexample INTERFACE
     ${CMAKE_CURRENT_LIST_DIR}
 )
 
-# Enable the module automatically by adding the relevant compile definitions.
-target_compile_definitions(usermod_cexample INTERFACE
-    MODULE_CEXAMPLE_ENABLED=1
-)
-
 # Link our INTERFACE library to the usermod target.
 target_link_libraries(usermod INTERFACE usermod_cexample)
-
diff --git a/examples/usercmodule/cppexample/examplemodule.c b/examples/usercmodule/cppexample/examplemodule.c
@@ -22,4 +22,7 @@ const mp_obj_module_t cppexample_user_cmodule = {
 };
 
 // Register the module to make it available in Python.
-MP_REGISTER_MODULE(MP_QSTR_cppexample, cppexample_user_cmodule, MODULE_CPPEXAMPLE_ENABLED);
+// Note: the "1" in the third argument means this module is always enabled.
+// This "1" can be optionally replaced with a macro like MODULE_CPPEXAMPLE_ENABLED
+// which can then be used to conditionally enable this module.
+MP_REGISTER_MODULE(MP_QSTR_cppexample, cppexample_user_cmodule, 1);
diff --git a/examples/usercmodule/cppexample/micropython.cmake b/examples/usercmodule/cppexample/micropython.cmake
@@ -12,11 +12,5 @@ target_include_directories(usermod_cppexample INTERFACE
     ${CMAKE_CURRENT_LIST_DIR}
 )
 
-# Enable the module automatically by adding the relevant compile definitions.
-target_compile_definitions(usermod_cppexample INTERFACE
-    MODULE_CPPEXAMPLE_ENABLED=1
-)
-
 # Link our INTERFACE library to the usermod target.
 target_link_libraries(usermod INTERFACE usermod_cppexample)
-
diff --git a/ports/unix/variants/coverage/mpconfigvariant.mk b/ports/unix/variants/coverage/mpconfigvariant.mk
@@ -7,8 +7,7 @@ CFLAGS += \
 	-fprofile-arcs -ftest-coverage \
 	-Wformat -Wmissing-declarations -Wmissing-prototypes \
 	-Wold-style-definition -Wpointer-arith -Wshadow -Wuninitialized -Wunused-parameter \
-	-DMICROPY_UNIX_COVERAGE \
-	-DMODULE_CEXAMPLE_ENABLED=1 -DMODULE_CPPEXAMPLE_ENABLED=1
+	-DMICROPY_UNIX_COVERAGE
 
 LDFLAGS += -fprofile-arcs -ftest-coverage
 
diff --git a/tools/ci.sh b/tools/ci.sh
@@ -211,7 +211,7 @@ function ci_stm32_pyb_build {
     make ${MAKEOPTS} -C mpy-cross
     make ${MAKEOPTS} -C ports/stm32 submodules
     git submodule update --init lib/btstack
-    make ${MAKEOPTS} -C ports/stm32 BOARD=PYBV11 MICROPY_PY_WIZNET5K=5200 MICROPY_PY_CC3K=1 USER_C_MODULES=../../examples/usercmodule CFLAGS_EXTRA="-DMODULE_CEXAMPLE_ENABLED=1 -DMODULE_CPPEXAMPLE_ENABLED=1"
+    make ${MAKEOPTS} -C ports/stm32 BOARD=PYBV11 MICROPY_PY_WIZNET5K=5200 MICROPY_PY_CC3K=1 USER_C_MODULES=../../examples/usercmodule
     make ${MAKEOPTS} -C ports/stm32 BOARD=PYBD_SF2
     make ${MAKEOPTS} -C ports/stm32 BOARD=PYBD_SF6 NANBOX=1 MICROPY_BLUETOOTH_NIMBLE=0 MICROPY_BLUETOOTH_BTSTACK=1
     make ${MAKEOPTS} -C ports/stm32/mboot BOARD=PYBV10 CFLAGS_EXTRA='-DMBOOT_FSLOAD=1 -DMBOOT_VFS_LFS2=1'
