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:
parent
ec79e44502
commit
d87f42b0e5
@ -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
|
||||
|
@ -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);
|
||||
|
@ -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)
|
||||
|
||||
|
@ -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);
|
||||
|
@ -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)
|
||||
|
||||
|
@ -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
|
||||
|
||||
|
@ -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'
|
||||
|
Loading…
Reference in New Issue
Block a user