From eb101a2701e5e2159e82a24aedad8911104ef9be Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 15 Feb 2017 13:12:23 +0300 Subject: examples/embedding/README: Convert to markdown, grammar and clarity fixes. --- examples/embedding/README | 66 ------------------------------------------- examples/embedding/README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 66 deletions(-) delete mode 100644 examples/embedding/README create mode 100644 examples/embedding/README.md (limited to 'examples') diff --git a/examples/embedding/README b/examples/embedding/README deleted file mode 100644 index 0475e8739..000000000 --- a/examples/embedding/README +++ /dev/null @@ -1,66 +0,0 @@ -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) -~~~ diff --git a/examples/embedding/README.md b/examples/embedding/README.md new file mode 100644 index 000000000..989ce1fc8 --- /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) +~~~ -- cgit v1.2.3