67 lines
2.5 KiB
Plaintext
67 lines
2.5 KiB
Plaintext
|
Example of embedding MicroPython in a standlone C application
|
||
|
|
=============================================================
|
||
|
|
|
||
|
|
This directory contains a (very simple!) example of how to embed a MicroPython
|
||
|
|
in an existing C application.
|
||
|
|
|
||
|
|
A C application is represented by the file hello-embed.c. It executes a simple
|
||
|
|
Python statement which prints to the standard output.
|
||
|
|
|
||
|
|
|
||
|
|
Building the example
|
||
|
|
--------------------
|
||
|
|
|
||
|
|
Build the example is as simple as running:
|
||
|
|
|
||
|
|
make
|
||
|
|
|
||
|
|
It's worth to trace what's happening behind the scenes though:
|
||
|
|
|
||
|
|
1. As a first step, a MicroPython library is built. This is handled by a
|
||
|
|
seperate makefile, Makefile.upylib. It is more or less complex, but the
|
||
|
|
good news is that you won't need to change anything in it, just use it
|
||
|
|
as is, the main Makefile shows how. What may need editing though is
|
||
|
|
MicroPython configuration file. MicroPython is highly configurable, so
|
||
|
|
you would need to build a library suiting your application well, while
|
||
|
|
not bloating its size. Check the options in the file "mpconfigport.h".
|
||
|
|
Included is a copy of "minimal" Unix port, which should be good start
|
||
|
|
for minimal embedding. For list of all available options, see py/mpconfig.h.
|
||
|
|
|
||
|
|
2. Once the library is built, your application is compiled and linked with
|
||
|
|
the MicroPython library produced in the previous step. The main Makefile
|
||
|
|
is very simple and shows that changes you would need to do to your
|
||
|
|
application's Makefile (or other build configuration) are also simple:
|
||
|
|
|
||
|
|
a) You would need to use C99 standard (you're using 15+ years old standard
|
||
|
|
already, not a 25+ years old one, right?).
|
||
|
|
|
||
|
|
b) You need to provide path to MicroPython's top-level dir, for includes.
|
||
|
|
|
||
|
|
c) You need to include -DNO_QSTR compile-time flag.
|
||
|
|
|
||
|
|
d) Otherwise, just link with micropython library produced in step 1.
|
||
|
|
|
||
|
|
|
||
|
|
Out of tree build
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
This example set up to work out of the box, being part of the MicroPython
|
||
|
|
tree. Your application of course will be outside of its tree, but the
|
||
|
|
only thing you need to do is to pass MPTOP variable pointing to
|
||
|
|
MicroPython directory to both Makefiles (in this example, the main Makefile
|
||
|
|
automatically pass it to Makefile.upylib; in your own Makefile, don't forget
|
||
|
|
to use suitable value).
|
||
|
|
|
||
|
|
A practical way to embed MicroPython in your application is to include it
|
||
|
|
as a git submodule. Suppose you included it as libs/micropython. Then in
|
||
|
|
your main Makefile you would have something like:
|
||
|
|
|
||
|
|
~~~
|
||
|
|
MPTOP = libs/micropython
|
||
|
|
|
||
|
|
my_app: $(MY_OBJS) -lmicropython
|
||
|
|
|
||
|
|
-lmicropython:
|
||
|
|
$(MAKE) -f $(MPTOP)/examples/embedding/Makefile.upylib MPTOP=$(MPTOP)
|
||
|
|
~~~
|