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 <damien@micropython.org>
This commit is contained in:
Damien George 2021-03-31 00:45:43 +11:00
parent ec79e44502
commit d87f42b0e5
7 changed files with 22 additions and 25 deletions

View File

@ -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

View File

@ -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);

View File

@ -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)

View File

@ -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);

View File

@ -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)

View File

@ -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

View File

@ -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'