micropython/examples/embedding
Damien George 8f4c108025 all: Remove MICROPY_PY_IO_FILEIO config option.
Since commit e65d1e69e8 there is no longer an
io.FileIO class, so this option is no longer needed.

This option also controlled whether or not files supported being opened in
binary mode (eg 'rb'), and could, if disabled, lead to confusion as to why
opening a file in binary mode silently did the wrong thing (it would just
open in text mode if MICROPY_PY_IO_FILEIO was disabled).

The various VFS implementations (POSIX, FAT, LFS) were the only places
where enabling this option made a difference, and in almost all cases where
one of these filesystems were enabled, MICROPY_PY_IO_FILEIO was also
enabled.  So it makes sense to just unconditionally enable this feature
(ability to open a file in binary mode) in all cases, and so just remove
this config option altogether.  That makes configuration simpler and means
binary file support always exists (and opening a file in binary mode is
arguably more fundamental than opening in text mode, so if anything should
be configurable then it should be the ability to open in text mode).

Signed-off-by: Damien George <damien@micropython.org>
2022-08-18 11:54:17 +10:00
..
Makefile all: Fix paths to mpy-cross and micropython binaries. 2022-08-11 13:31:13 +10:00
Makefile.upylib examples/embedding: Remove obsolete axtls build target. 2022-07-18 23:00:51 +10:00
README.md examples/embedding: Add code markup and fix typo in README.md. 2018-06-18 12:29:22 +10:00
hello-embed.c py/builtin: Clean up and simplify import_stat and builtin_open config. 2022-05-25 13:04:45 +10:00
mpconfigport.h examples/embedding: Replace symlink of mpconfigport.h with real file. 2019-10-29 22:53:34 +11:00
mpconfigport_minimal.h all: Remove MICROPY_PY_IO_FILEIO config option. 2022-08-18 11:54:17 +10:00

README.md

Example of embedding MicroPython in a standalone 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

Building 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 separate 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 require editing though is a 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 the "minimal" Unix port, which should be a good start for minimal embedding. For the list of all available options, see py/mpconfig.h.

  2. Once the MicroPython library is built, your application is compiled and linked it. The main Makefile is very simple and shows that the 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 this 15+ years old standard already, not a 25+ years old one, right?).

b) You need to provide a path to MicroPython's top-level dir, for includes.

c) You need to include -DNO_QSTR compile-time flag.

d) Otherwise, just link with the MicroPython library produced in step 1.

Out of tree build

This example is 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 passes it to Makefile.upylib; in your own Makefile, don't forget to use a 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)