Skip to content

Commit 25c4563

Browse files
stinosdpgeorge
stinos
authored and
dpgeorge
committed
examples: Add example code for user C modules, both C and C++.
Add working example code to provide a starting point for users with files that they can just copy, and include the modules in the coverage test to verify the complete user C module build functionality. The cexample module uses the code originally found in cmodules.rst, which has been updated to reflect this and partially rewritten with more complete information.
1 parent fad4079 commit 25c4563

10 files changed

Lines changed: 192 additions & 86 deletions

File tree

‎docs/develop/cmodules.rst‎

Lines changed: 75 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -49,133 +49,123 @@ A MicroPython user C module is a directory with the following files:
4949
expanded copy of ``$(USERMOD_DIR)`` to ``SRC_USERMOD``, eg
5050
``SRC_USERMOD += $(EXAMPLE_MOD_DIR)/example.c``
5151

52-
If you have custom ``CFLAGS`` settings or include folders to define, these
53-
should be added to ``CFLAGS_USERMOD``, or ``CXXFLAGS_USERMOD``.
52+
If you have custom compiler options (like ``-I`` to add directories to search
53+
for header files), these should be added to ``CFLAGS_USERMOD`` for C code
54+
and to ``CXXFLAGS_USERMOD`` for C++ code.
5455

5556
See below for full usage example.
5657

5758

5859
Basic example
5960
-------------
6061

61-
This simple module named ``example`` provides a single function
62-
``example.add_ints(a, b)`` which adds the two integer args together and returns
63-
the result.
62+
This simple module named ``cexample`` provides a single function
63+
``cexample.add_ints(a, b)`` which adds the two integer args together and returns
64+
the result. It can be found in the MicroPython source tree and has
65+
a source file and a Makefile fragment with content as descibed above::
6466

65-
Directory::
67+
micropython/
68+
└──examples/
69+
└──usercmodule/
70+
└──cexample/
71+
├── examplemodule.c
72+
└── micropython.mk
6673

67-
example/
68-
├── example.c
69-
└── micropython.mk
74+
Refer to the comments in these 2 files for additional explanation.
75+
Next to the ``cexample`` module there's also ``cppexample`` which
76+
works in the same way but shows one way of mixing C and C++ code
77+
in MicroPython.
7078

7179

72-
``example.c``
73-
74-
.. code-block:: c
75-
76-
// Include required definitions first.
77-
#include "py/obj.h"
78-
#include "py/runtime.h"
79-
#include "py/builtin.h"
80-
81-
// This is the function which will be called from Python as example.add_ints(a, b).
82-
STATIC mp_obj_t example_add_ints(mp_obj_t a_obj, mp_obj_t b_obj) {
83-
// Extract the ints from the micropython input objects
84-
int a = mp_obj_get_int(a_obj);
85-
int b = mp_obj_get_int(b_obj);
80+
Compiling the cmodule into MicroPython
81+
--------------------------------------
8682

87-
// Calculate the addition and convert to MicroPython object.
88-
return mp_obj_new_int(a + b);
89-
}
90-
// Define a Python reference to the function above
91-
STATIC MP_DEFINE_CONST_FUN_OBJ_2(example_add_ints_obj, example_add_ints);
83+
To build such a module, compile MicroPython (see `getting started
84+
<https://github.com/micropython/micropython/wiki/Getting-Started>`_),
85+
applying 2 modifications:
9286

93-
// Define all properties of the example module.
94-
// Table entries are key/value pairs of the attribute name (a string)
95-
// and the MicroPython object reference.
96-
// All identifiers and strings are written as MP_QSTR_xxx and will be
97-
// optimized to word-sized integers by the build system (interned strings).
98-
STATIC const mp_rom_map_elem_t example_module_globals_table[] = {
99-
{ MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_example) },
100-
{ MP_ROM_QSTR(MP_QSTR_add_ints), MP_ROM_PTR(&example_add_ints_obj) },
101-
};
102-
STATIC MP_DEFINE_CONST_DICT(example_module_globals, example_module_globals_table);
87+
- an extra ``make`` flag named ``USER_C_MODULES`` set to the directory
88+
containing all modules you want included (not to the module itself).
89+
For building the example modules which come with MicroPython,
90+
set ``USER_C_MODULES`` to the ``examples/usercmodule`` directory.
91+
For your own projects it's more convenient to keep custom code out of
92+
the main source tree so a typical project directory structure will look
93+
like this::
10394

104-
// Define module object.
105-
const mp_obj_module_t example_user_cmodule = {
106-
.base = { &mp_type_module },
107-
.globals = (mp_obj_dict_t*)&example_module_globals,
108-
};
95+
my_project/
96+
├── modules/
97+
│ └──example1/
98+
│ ├──example1.c
99+
│ └──micropython.mk
100+
│ └──example2/
101+
│ ├──example2.c
102+
│ └──micropython.mk
103+
└── micropython/
104+
├──ports/
105+
... ├──stm32/
106+
...
109107

110-
// Register the module to make it available in Python
111-
MP_REGISTER_MODULE(MP_QSTR_example, example_user_cmodule, MODULE_EXAMPLE_ENABLED);
112108

109+
with ``USER_C_MODULES`` set to the ``my_project/modules`` directory.
113110

114-
``micropython.mk``
111+
- all modules found in this directory will be compiled, but only those
112+
which are explicitly enabled will be availabe for importing. Enabling a
113+
module is done by setting the preprocessor define from its module
114+
registration to 1. For example if the source code defines the module with
115115

116-
.. code-block:: make
116+
.. code-block:: c
117117
118-
EXAMPLE_MOD_DIR := $(USERMOD_DIR)
118+
MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);
119119
120-
# Add all C files to SRC_USERMOD.
121-
SRC_USERMOD += $(EXAMPLE_MOD_DIR)/example.c
122120
123-
# We can add our module folder to include paths if needed
124-
# This is not actually needed in this example.
125-
CFLAGS_USERMOD += -I$(EXAMPLE_MOD_DIR)
121+
then ``MODULE_CEXAMPLE_ENABLED`` has to be set to 1 to make the module available.
122+
This can be done by adding ``CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1`` to
123+
the ``make`` command, or editing ``mpconfigport.h`` or ``mpconfigboard.h``
124+
to add
126125

127-
Finally you will need to define ``MODULE_EXAMPLE_ENABLED`` to 1. This
128-
can be done by adding ``CFLAGS_EXTRA=-DMODULE_EXAMPLE_ENABLED=1`` to
129-
the ``make`` command, or editing ``mpconfigport.h`` or
130-
``mpconfigboard.h`` to add
126+
.. code-block:: c
131127
132-
.. code-block:: c
128+
#define MODULE_CEXAMPLE_ENABLED (1)
133129
134-
#define MODULE_EXAMPLE_ENABLED (1)
135130
136-
Note that the exact method depends on the port as they have different
137-
structures. If not done correctly it will compile but importing will
138-
fail to find the module.
131+
Note that the exact method depends on the port as they have different
132+
structures. If not done correctly it will compile but importing will
133+
fail to find the module.
139134

135+
To sum up, here's how the ``cexample`` module from the ``examples/usercmodule``
136+
directory can be built for the unix port:
140137

141-
Compiling the cmodule into MicroPython
142-
--------------------------------------
138+
.. code-block:: bash
143139
144-
To build such a module, compile MicroPython (see `getting started
145-
<https://github.com/micropython/micropython/wiki/Getting-Started>`_) with an
146-
extra ``make`` flag named ``USER_C_MODULES`` set to the directory containing
147-
all modules you want included (not to the module itself). For example:
140+
cd micropython/ports/unix
141+
make USER_C_MODULES=../../examples/usercmodule CFLAGS_EXTRA=-DMODULE_CEXAMPLE_ENABLED=1 all
148142
143+
The build output will show the modules found::
149144

150-
Directory::
145+
...
146+
Including User C Module from ../../examples/usercmodule/cexample
147+
Including User C Module from ../../examples/usercmodule/cppexample
148+
...
151149

152-
my_project/
153-
├── modules/
154-
│ └──example/
155-
│ ├──example.c
156-
│ └──micropython.mk
157-
└── micropython/
158-
├──ports/
159-
... ├──stm32/
160-
...
161150

162-
Building for stm32 port:
151+
Or for your own project with a directory structure as shown above,
152+
including both modules and building the stm32 port for example:
163153

164154
.. code-block:: bash
165155
166156
cd my_project/micropython/ports/stm32
167-
make USER_C_MODULES=../../../modules CFLAGS_EXTRA=-DMODULE_EXAMPLE_ENABLED=1 all
157+
make USER_C_MODULES=../../../modules \
158+
CFLAGS_EXTRA="-DMODULE_EXAMPLE1_ENABLED=1 -DMODULE_EXAMPLE2_ENABLED=1" all
168159
169160
170161
Module usage in MicroPython
171162
---------------------------
172163

173-
Once built into your copy of MicroPython, the module implemented
174-
in ``example.c`` above can now be accessed in Python just
175-
like any other builtin module, eg
164+
Once built into your copy of MicroPython, the module
165+
can now be accessed in Python just like any other builtin module, e.g.
176166

177167
.. code-block:: python
178168
179-
import example
180-
print(example.add_ints(1, 3))
169+
import cexample
170+
print(cexample.add_ints(1, 3))
181171
# should display 4

‎examples/usercmodule/cexample/examplemodule.c‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
// Include MicroPython API.
2+
#include "py/runtime.h"
3+
4+
// This is the function which will be called from Python as cexample.add_ints(a, b).
5+
STATIC mp_obj_t example_add_ints(mp_obj_t a_obj, mp_obj_t b_obj) {
6+
// Extract the ints from the micropython input objects.
7+
int a = mp_obj_get_int(a_obj);
8+
int b = mp_obj_get_int(b_obj);
9+
10+
// Calculate the addition and convert to MicroPython object.
11+
return mp_obj_new_int(a + b);
12+
}
13+
// Define a Python reference to the function above.
14+
STATIC MP_DEFINE_CONST_FUN_OBJ_2(example_add_ints_obj, example_add_ints);
15+
16+
// Define all properties of the module.
17+
// Table entries are key/value pairs of the attribute name (a string)
18+
// and the MicroPython object reference.
19+
// All identifiers and strings are written as MP_QSTR_xxx and will be
20+
// optimized to word-sized integers by the build system (interned strings).
21+
STATIC const mp_rom_map_elem_t example_module_globals_table[] = {
22+
{ MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_cexample) },
23+
{ MP_ROM_QSTR(MP_QSTR_add_ints), MP_ROM_PTR(&example_add_ints_obj) },
24+
};
25+
STATIC MP_DEFINE_CONST_DICT(example_module_globals, example_module_globals_table);
26+
27+
// Define module object.
28+
const mp_obj_module_t example_user_cmodule = {
29+
.base = { &mp_type_module },
30+
.globals = (mp_obj_dict_t *)&example_module_globals,
31+
};
32+
33+
// Register the module to make it available in Python.
34+
MP_REGISTER_MODULE(MP_QSTR_cexample, example_user_cmodule, MODULE_CEXAMPLE_ENABLED);

‎examples/usercmodule/cexample/micropython.mk‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
EXAMPLE_MOD_DIR := $(USERMOD_DIR)
2+
3+
# Add all C files to SRC_USERMOD.
4+
SRC_USERMOD += $(EXAMPLE_MOD_DIR)/examplemodule.c
5+
6+
# We can add our module folder to include paths if needed
7+
# This is not actually needed in this example.
8+
CFLAGS_USERMOD += -I$(EXAMPLE_MOD_DIR)
9+
CEXAMPLE_MOD_DIR := $(USERMOD_DIR)

‎examples/usercmodule/cppexample/example.cpp‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
extern "C" {
2+
#include <examplemodule.h>
3+
4+
// Here we implement the function using C++ code, but since it's
5+
// declaration has to be compatible with C everything goes in extern "C" scope.
6+
mp_obj_t cppfunc(mp_obj_t a_obj, mp_obj_t b_obj) {
7+
// Prove we have (at least) C++11 features.
8+
const auto a = mp_obj_get_int(a_obj);
9+
const auto b = mp_obj_get_int(b_obj);
10+
const auto sum = [&]() {
11+
return mp_obj_new_int(a + b);
12+
} ();
13+
// Prove we're being scanned for QSTRs.
14+
mp_obj_t tup[] = {sum, MP_ROM_QSTR(MP_QSTR_hellocpp)};
15+
return mp_obj_new_tuple(2, tup);
16+
}
17+
}

‎examples/usercmodule/cppexample/examplemodule.c‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
#include <examplemodule.h>
2+
3+
// Define a Python reference to the function we'll make available.
4+
// See example.cpp for the definition.
5+
STATIC MP_DEFINE_CONST_FUN_OBJ_2(cppfunc_obj, cppfunc);
6+
7+
// Define all properties of the module.
8+
// Table entries are key/value pairs of the attribute name (a string)
9+
// and the MicroPython object reference.
10+
// All identifiers and strings are written as MP_QSTR_xxx and will be
11+
// optimized to word-sized integers by the build system (interned strings).
12+
STATIC const mp_rom_map_elem_t cppexample_module_globals_table[] = {
13+
{ MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_cppexample) },
14+
{ MP_ROM_QSTR(MP_QSTR_cppfunc), MP_ROM_PTR(&cppfunc_obj) },
15+
};
16+
STATIC MP_DEFINE_CONST_DICT(cppexample_module_globals, cppexample_module_globals_table);
17+
18+
// Define module object.
19+
const mp_obj_module_t cppexample_user_cmodule = {
20+
.base = { &mp_type_module },
21+
.globals = (mp_obj_dict_t *)&cppexample_module_globals,
22+
};
23+
24+
// Register the module to make it available in Python.
25+
MP_REGISTER_MODULE(MP_QSTR_cppexample, cppexample_user_cmodule, MODULE_CPPEXAMPLE_ENABLED);

‎examples/usercmodule/cppexample/examplemodule.h‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
// Include MicroPython API.
2+
#include "py/runtime.h"
3+
4+
// Declare the function we'll make available in Python as cppexample.cppfunc().
5+
extern mp_obj_t cppfunc(mp_obj_t a_obj, mp_obj_t b_obj);

‎examples/usercmodule/cppexample/micropython.mk‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
CPPEXAMPLE_MOD_DIR := $(USERMOD_DIR)
2+
3+
# Add our source files to the respective variables.
4+
SRC_USERMOD += $(CPPEXAMPLE_MOD_DIR)/examplemodule.c
5+
SRC_USERMOD_CXX += $(CPPEXAMPLE_MOD_DIR)/example.cpp
6+
7+
# Add our module directory to the include path.
8+
CFLAGS_USERMOD += -I$(CPPEXAMPLE_MOD_DIR)
9+
CXXFLAGS_USERMOD += -I$(CPPEXAMPLE_MOD_DIR)
10+
11+
# We use C++ features so have to link against the standard library.
12+
LDFLAGS_USERMOD += -lstdc++

‎ports/unix/variants/coverage/mpconfigvariant.mk‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,13 @@ CFLAGS += \
77
-fprofile-arcs -ftest-coverage \
88
-Wformat -Wmissing-declarations -Wmissing-prototypes \
99
-Wold-style-definition -Wpointer-arith -Wshadow -Wuninitialized -Wunused-parameter \
10-
-DMICROPY_UNIX_COVERAGE
10+
-DMICROPY_UNIX_COVERAGE \
11+
-DMODULE_CEXAMPLE_ENABLED=1 -DMODULE_CPPEXAMPLE_ENABLED=1
1112

1213
LDFLAGS += -fprofile-arcs -ftest-coverage
1314

1415
FROZEN_MANIFEST ?= $(VARIANT_DIR)/manifest.py
16+
USER_C_MODULES = $(TOP)/examples/usercmodule
1517

1618
MICROPY_ROM_TEXT_COMPRESSION = 1
1719
MICROPY_VFS_FAT = 1

‎tests/unix/extra_coverage.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,16 @@
4949
# function defined in C++ code
5050
print("cpp", extra_cpp_coverage())
5151

52+
# test user C module
53+
import cexample
54+
55+
print(cexample.add_ints(3, 2))
56+
57+
# test user C module mixed with C++ code
58+
import cppexample
59+
60+
print(cppexample.cppfunc(1, 2))
61+
5262
# test basic import of frozen scripts
5363
import frzstr1
5464

‎tests/unix/extra_coverage.py.exp‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,8 @@ OSError
145145
None
146146
None
147147
cpp None
148+
5
149+
(3, 'hellocpp')
148150
frzstr1
149151
frzstr1.py
150152
frzmpy1

0 commit comments

Comments
 (0)