1 files changed, 67 insertions, 0 deletions
diff --git a/examples/embedding/README.md b/examples/embedding/README.md
new file mode 100644
index 0000000000..989ce1fc8f
--- /dev/null
+++ b/examples/embedding/README.md
@@ -0,0 +1,67 @@
+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
+--------------------
+
+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
+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 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)
+~~~