From d87f42b0e53829052f17955ba1e17f938ae486fb Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 31 Mar 2021 00:45:43 +1100 Subject: [PATCH] examples/usercmodules: Simplify user C module enabling. 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 #6960, and also #7086. Signed-off-by: Damien George --- docs/develop/cmodules.rst | 20 +++++++++++-------- examples/usercmodule/cexample/examplemodule.c | 5 ++++- .../usercmodule/cexample/micropython.cmake | 6 ------ .../usercmodule/cppexample/examplemodule.c | 5 ++++- .../usercmodule/cppexample/micropython.cmake | 6 ------ .../unix/variants/coverage/mpconfigvariant.mk | 3 +-- tools/ci.sh | 2 +- 7 files changed, 22 insertions(+), 25 deletions(-) diff --git a/docs/develop/cmodules.rst b/docs/develop/cmodules.rst index dd02f1439c..be49485f2c 100644 --- 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__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 index f608823c9e..49ebc7aaaf 100644 --- 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 index 371a3eefa4..ba076a16b2 100644 --- 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 index ceb588bef6..dfb7856837 100644 --- 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 index 43e8d887f5..6da972c94e 100644 --- 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 index ef81975d9d..fac8c0d275 100644 --- 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 index 1a410632cd..3ce96a96a9 100755 --- 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'