Commit 4d4cfc2

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)

~~~