Browse Source

examples/embedding: Rework example to use ports/embed.

Signed-off-by: Damien George <damien@micropython.org>
pull/9529/head
Damien George 2 years ago
parent
commit
4f3780a156
  1. 4
      .github/workflows/examples.yml
  2. 29
      examples/embedding/Makefile
  3. 184
      examples/embedding/Makefile.upylib
  4. 66
      examples/embedding/README.md
  5. 76
      examples/embedding/hello-embed.c
  6. 44
      examples/embedding/main.c
  7. 9
      examples/embedding/micropython_embed.mk
  8. 16
      examples/embedding/mpconfigport.h
  9. 122
      examples/embedding/mpconfigport_minimal.h

4
.github/workflows/examples.yml

@ -20,6 +20,6 @@ jobs:
steps:
- uses: actions/checkout@v3
- name: Build
run: make -C examples/embedding
run: make -C examples/embedding -f micropython_embed.mk && make -C examples/embedding
- name: Run
run: test "$(./examples/embedding/hello-embed)" = "Hello world of easy embedding!"
run: ./examples/embedding/embed | grep "hello world"

29
examples/embedding/Makefile

@ -1,8 +1,25 @@
MPTOP = ../..
CFLAGS += -std=c99 -I. -I$(MPTOP) -DNO_QSTR
LDFLAGS += -L./build
# This file is part of the MicroPython project, http://micropython.org/
# The MIT License (MIT)
# Copyright (c) 2022-2023 Damien P. George
#
# This is a very simple makefile that demonstrates how to build the embed port.
# All it needs to do is build all *.c files in the micropython_embed directory.
# This makefile would be replaced with your custom build system.
hello-embed: hello-embed.o -lmicropython
EMBED_DIR = micropython_embed
PROG = embed
-lmicropython:
$(MAKE) -f $(MPTOP)/examples/embedding/Makefile.upylib MPTOP=$(MPTOP)
CFLAGS += -I.
CFLAGS += -I$(EMBED_DIR)
CFLAGS += -I$(EMBED_DIR)/port
CFLAGS += -Wall -Og
SRC += main.c
SRC += $(wildcard $(EMBED_DIR)/*/*.c) $(wildcard $(EMBED_DIR)/*/*/*.c)
OBJ += $(SRC:.c=.o)
$(PROG): $(OBJ)
$(CC) -o $@ $^
clean:
/bin/rm -f $(OBJ) $(PROG)

184
examples/embedding/Makefile.upylib

@ -1,184 +0,0 @@
MPTOP = ../..
-include mpconfigport.mk
include $(MPTOP)/py/mkenv.mk
all: lib
# OS name, for simple autoconfig
UNAME_S := $(shell uname -s)
# include py core make definitions
include $(MPTOP)/py/py.mk
include $(MPTOP)/extmod/extmod.mk
INC += -I.
INC += -I..
INC += -I$(MPTOP)
INC += -I$(MPTOP)/ports/unix
INC += -I$(BUILD)
# compiler settings
CWARN = -Wall -Werror
CWARN += -Wpointer-arith -Wuninitialized
CFLAGS += $(INC) $(CWARN) -std=gnu99 -DUNIX $(CFLAGS_MOD) $(COPT) $(CFLAGS_EXTRA)
# Some systems (eg MacOS) need -fno-common so that mp_state_ctx is placed in the BSS.
CFLAGS += -fno-common
# Debugging/Optimization
ifdef DEBUG
CFLAGS += -g
COPT = -O0
else
COPT = -Os #-DNDEBUG
# _FORTIFY_SOURCE is a feature in gcc/glibc which is intended to provide extra
# security for detecting buffer overflows. Some distros (Ubuntu at the very least)
# have it enabled by default.
#
# gcc already optimizes some printf calls to call puts and/or putchar. When
# _FORTIFY_SOURCE is enabled and compiling with -O1 or greater, then some
# printf calls will also be optimized to call __printf_chk (in glibc). Any
# printfs which get redirected to __printf_chk are then no longer synchronized
# with printfs that go through mp_printf.
#
# In MicroPython, we don't want to use the runtime library's printf but rather
# go through mp_printf, so that stdout is properly tied into streams, etc.
# This means that we either need to turn off _FORTIFY_SOURCE or provide our
# own implementation of __printf_chk. We've chosen to turn off _FORTIFY_SOURCE.
# It should also be noted that the use of printf in MicroPython is typically
# quite limited anyways (primarily for debug and some error reporting, etc
# in the unix version).
#
# Information about _FORTIFY_SOURCE seems to be rather scarce. The best I could
# find was this: https://securityblog.redhat.com/2014/03/26/fortify-and-you/
# Original patchset was introduced by
# https://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html .
#
# Turning off _FORTIFY_SOURCE is only required when compiling with -O1 or greater
CFLAGS += -U _FORTIFY_SOURCE
endif
# On OSX, 'gcc' is a symlink to clang unless a real gcc is installed.
# The unix port of MicroPython on OSX must be compiled with clang,
# while cross-compile ports require gcc, so we test here for OSX and
# if necessary override the value of 'CC' set in py/mkenv.mk
ifeq ($(UNAME_S),Darwin)
CC = clang
# Use clang syntax for map file
LDFLAGS_ARCH = -Wl,-map,$@.map
else
# Use gcc syntax for map file
LDFLAGS_ARCH = -Wl,-Map=$@.map,--cref
endif
LDFLAGS += $(LDFLAGS_MOD) $(LDFLAGS_ARCH) -lm $(LDFLAGS_EXTRA)
ifeq ($(MICROPY_FORCE_32BIT),1)
# Note: you may need to install i386 versions of dependency packages,
# starting with linux-libc-dev:i386
ifeq ($(MICROPY_PY_FFI),1)
ifeq ($(UNAME_S),Linux)
CFLAGS_MOD += -I/usr/include/i686-linux-gnu
endif
endif
endif
ifeq ($(MICROPY_USE_READLINE),1)
INC += -I$(MPTOP)/shared/readline
CFLAGS_MOD += -DMICROPY_USE_READLINE=1
SHARED_SRC_C_EXTRA += readline/readline.c
endif
ifeq ($(MICROPY_USE_READLINE),2)
CFLAGS_MOD += -DMICROPY_USE_READLINE=2
LDFLAGS_MOD += -lreadline
# the following is needed for BSD
#LDFLAGS_MOD += -ltermcap
endif
ifeq ($(MICROPY_PY_TIME),1)
CFLAGS_MOD += -DMICROPY_PY_TIME=1
SRC_MOD += modtime.c
endif
ifeq ($(MICROPY_PY_TERMIOS),1)
CFLAGS_MOD += -DMICROPY_PY_TERMIOS=1
SRC_MOD += modtermios.c
endif
ifeq ($(MICROPY_PY_SOCKET),1)
CFLAGS_MOD += -DMICROPY_PY_SOCKET=1
SRC_MOD += modsocket.c
endif
ifeq ($(MICROPY_PY_FFI),1)
ifeq ($(MICROPY_STANDALONE),1)
LIBFFI_CFLAGS_MOD := -I$(shell ls -1d $(MPTOP)/lib/libffi/build_dir/out/lib/libffi-*/include)
ifeq ($(MICROPY_FORCE_32BIT),1)
LIBFFI_LDFLAGS_MOD = $(MPTOP)/lib/libffi/build_dir/out/lib32/libffi.a
else
LIBFFI_LDFLAGS_MOD = $(MPTOP)/lib/libffi/build_dir/out/lib/libffi.a
endif
else
LIBFFI_CFLAGS_MOD := $(shell pkg-config --cflags libffi)
LIBFFI_LDFLAGS_MOD := $(shell pkg-config --libs libffi)
endif
ifeq ($(UNAME_S),Linux)
LIBFFI_LDFLAGS_MOD += -ldl
endif
CFLAGS_MOD += $(LIBFFI_CFLAGS_MOD) -DMICROPY_PY_FFI=1
LDFLAGS_MOD += $(LIBFFI_LDFLAGS_MOD)
SRC_MOD += modffi.c
endif
MAIN_C = main.c
# source files
SRC_C = $(addprefix ports/unix/,\
$(MAIN_C) \
gccollect.c \
unix_mphal.c \
input.c \
modmachine.c \
moduselect.c \
alloc.c \
coverage.c \
fatfs_port.c \
$(SRC_MOD) \
)
SHARED_SRC_C = $(addprefix shared/,\
libc/printf.c \
runtime/gchelper_generic.c \
timeutils/timeutils.c \
$(SHARED_SRC_C_EXTRA) \
)
OBJ = $(PY_O)
OBJ += $(addprefix $(BUILD)/, $(SRC_C:.c=.o))
OBJ += $(addprefix $(BUILD)/, $(SHARED_SRC_C:.c=.o))
# List of sources for qstr extraction
SRC_QSTR += $(SRC_C) $(SHARED_SRC_C)
# Append any auto-generated sources that are needed by sources listed in
# SRC_QSTR
SRC_QSTR_AUTO_DEPS +=
include $(MPTOP)/py/mkrules.mk
# Value of configure's --host= option (required for cross-compilation).
# Deduce it from CROSS_COMPILE by default, but can be overridden.
ifneq ($(CROSS_COMPILE),)
CROSS_COMPILE_HOST = --host=$(patsubst %-,%,$(CROSS_COMPILE))
else
CROSS_COMPILE_HOST =
endif
deplibs: libffi
# install-exec-recursive & install-data-am targets are used to avoid building
# docs and depending on makeinfo
libffi:
cd $(MPTOP)/lib/libffi; git clean -d -x -f
cd $(MPTOP)/lib/libffi; ./autogen.sh
mkdir -p $(MPTOP)/lib/libffi/build_dir; cd $(MPTOP)/lib/libffi/build_dir; \
../configure $(CROSS_COMPILE_HOST) --prefix=$$PWD/out CC="$(CC)" CXX="$(CXX)" LD="$(LD)"; \
make install-exec-recursive; make -C include install-data-am

66
examples/embedding/README.md

@ -1,67 +1,37 @@
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.
This directory contains a simple example of how to embed MicroPython in an
existing C application.
A C application is represented here by the file `main.c`. It executes two
simple Python scripts which print things 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`.
First build the embed port using:
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:
$ make -f micropython_embed.mk
a) You would need to use C99 standard (you're using this 15+ years old
standard already, not a 25+ years old one, right?).
This will generate the `micropython_embed` directory which is a self-contained
copy of MicroPython suitable for embedding. The .c files in this directory need
to be compiled into your project, in whatever way your project can do that. The
example here uses make and a provided `Makefile`.
b) You need to provide a path to MicroPython's top-level dir, for includes.
To build the example project, based on `main.c`, use:
c) You need to include `-DNO_QSTR` compile-time flag.
$ make
d) Otherwise, just link with the MicroPython library produced in step 1.
That will create an exacutable called `embed` which you can run:
$ ./embed
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)
~~~
tree. Your application will be outside of this tree, but the only thing you
need to do for that is to change `MICROPYTHON_TOP` (found in `micropython_embed.mk`)
to point to the location of the MicroPython repository. The MicroPython
repository may, for example, be a git submodule in your project.

76
examples/embedding/hello-embed.c

@ -1,76 +0,0 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2016 Paul Sokolovsky
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
#include <string.h>
#include <stdio.h>
#include <stdlib.h>
#include "py/builtin.h"
#include "py/compile.h"
#include "py/runtime.h"
#include "py/gc.h"
#include "py/stackctrl.h"
static char heap[16384];
mp_obj_t execute_from_str(const char *str) {
nlr_buf_t nlr;
if (nlr_push(&nlr) == 0) {
qstr src_name = 1/*MP_QSTR_*/;
mp_lexer_t *lex = mp_lexer_new_from_str_len(src_name, str, strlen(str), false);
mp_parse_tree_t pt = mp_parse(lex, MP_PARSE_FILE_INPUT);
mp_obj_t module_fun = mp_compile(&pt, src_name, false);
mp_call_function_0(module_fun);
nlr_pop();
return 0;
} else {
// uncaught exception
return (mp_obj_t)nlr.ret_val;
}
}
int main() {
// Initialized stack limit
mp_stack_set_limit(40000 * (sizeof(void *) / 4));
// Initialize heap
gc_init(heap, heap + sizeof(heap));
// Initialize interpreter
mp_init();
const char str[] = "print('Hello world of easy embedding!')";
if (execute_from_str(str)) {
printf("Error\n");
}
}
uint mp_import_stat(const char *path) {
return MP_IMPORT_STAT_NO_EXIST;
}
void nlr_jump_fail(void *val) {
printf("FATAL: uncaught NLR %p\n", val);
exit(1);
}

44
examples/embedding/main.c

@ -0,0 +1,44 @@
/* This file is part of the MicroPython project, http://micropython.org/
* The MIT License (MIT)
* Copyright (c) 2022-2023 Damien P. George
*/
#include "port/micropython_embed.h"
// This is example 1 script, which will be compiled and executed.
static const char *example_1 =
"print('hello world!', list(x + 1 for x in range(10)), end='eol\\n')";
// This is example 2 script, which will be compiled and executed.
static const char *example_2 =
"for i in range(10):\n"
" print('iter {:08}'.format(i))\n"
"\n"
"try:\n"
" 1//0\n"
"except Exception as er:\n"
" print('caught exception', repr(er))\n"
"\n"
"import gc\n"
"print('run GC collect')\n"
"gc.collect()\n"
"\n"
"print('finish')\n"
;
// This array is the MicroPython GC heap.
static char heap[8 * 1024];
int main() {
// Initialise MicroPython.
mp_embed_init(&heap[0], sizeof(heap));
// Run the example scripts (they will be compiled first).
mp_embed_exec_str(example_1);
mp_embed_exec_str(example_2);
// Deinitialise MicroPython.
mp_embed_deinit();
return 0;
}

9
examples/embedding/micropython_embed.mk

@ -0,0 +1,9 @@
# This file is part of the MicroPython project, http://micropython.org/
# The MIT License (MIT)
# Copyright (c) 2022-2023 Damien P. George
# Set the location of the top of the MicroPython repository.
MICROPYTHON_TOP = ../..
# Include the main makefile fragment to build the MicroPython component.
include $(MICROPYTHON_TOP)/ports/embed/embed.mk

16
examples/embedding/mpconfigport.h

@ -1 +1,15 @@
#include "mpconfigport_minimal.h"
/* This file is part of the MicroPython project, http://micropython.org/
* The MIT License (MIT)
* Copyright (c) 2022-2023 Damien P. George
*/
// Include common MicroPython embed configuration.
#include <port/mpconfigport_common.h>
// Use the minimal starting configuration (disables all optional features).
#define MICROPY_CONFIG_ROM_LEVEL (MICROPY_CONFIG_ROM_LEVEL_MINIMUM)
// MicroPython configuration.
#define MICROPY_ENABLE_COMPILER (1)
#define MICROPY_ENABLE_GC (1)
#define MICROPY_PY_GC (1)

122
examples/embedding/mpconfigport_minimal.h

@ -1,122 +0,0 @@
/*
* This file is part of the MicroPython project, http://micropython.org/
*
* The MIT License (MIT)
*
* Copyright (c) 2015 Damien P. George
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
// options to control how MicroPython is built
#define MICROPY_ALLOC_PATH_MAX (PATH_MAX)
#define MICROPY_ENABLE_GC (1)
#define MICROPY_ENABLE_FINALISER (0)
#define MICROPY_STACK_CHECK (0)
#define MICROPY_COMP_CONST (0)
#define MICROPY_MEM_STATS (0)
#define MICROPY_DEBUG_PRINTERS (0)
#define MICROPY_READER_POSIX (1)
#define MICROPY_KBD_EXCEPTION (1)
#define MICROPY_HELPER_REPL (1)
#define MICROPY_HELPER_LEXER_UNIX (1)
#define MICROPY_ENABLE_SOURCE_LINE (0)
#define MICROPY_ERROR_REPORTING (MICROPY_ERROR_REPORTING_TERSE)
#define MICROPY_WARNINGS (0)
#define MICROPY_ENABLE_EMERGENCY_EXCEPTION_BUF (0)
#define MICROPY_FLOAT_IMPL (MICROPY_FLOAT_IMPL_NONE)
#define MICROPY_LONGINT_IMPL (MICROPY_LONGINT_IMPL_NONE)
#define MICROPY_STREAMS_NON_BLOCK (0)
#define MICROPY_OPT_COMPUTED_GOTO (0)
#define MICROPY_CAN_OVERRIDE_BUILTINS (0)
#define MICROPY_BUILTIN_METHOD_CHECK_SELF_ARG (0)
#define MICROPY_CPYTHON_COMPAT (0)
#define MICROPY_PY_BUILTINS_BYTEARRAY (0)
#define MICROPY_PY_BUILTINS_MEMORYVIEW (0)
#define MICROPY_PY_BUILTINS_COMPILE (0)
#define MICROPY_PY_BUILTINS_ENUMERATE (0)
#define MICROPY_PY_BUILTINS_FILTER (0)
#define MICROPY_PY_BUILTINS_FROZENSET (0)
#define MICROPY_PY_BUILTINS_REVERSED (0)
#define MICROPY_PY_BUILTINS_SET (0)
#define MICROPY_PY_BUILTINS_SLICE (0)
#define MICROPY_PY_BUILTINS_STR_UNICODE (0)
#define MICROPY_PY_BUILTINS_PROPERTY (0)
#define MICROPY_PY_BUILTINS_MIN_MAX (0)
#define MICROPY_PY___FILE__ (0)
#define MICROPY_PY_MICROPYTHON_MEM_INFO (0)
#define MICROPY_PY_GC (0)
#define MICROPY_PY_GC_COLLECT_RETVAL (0)
#define MICROPY_PY_ARRAY (0)
#define MICROPY_PY_COLLECTIONS (0)
#define MICROPY_PY_MATH (0)
#define MICROPY_PY_CMATH (0)
#define MICROPY_PY_IO (0)
#define MICROPY_PY_STRUCT (0)
#define MICROPY_PY_SYS (1)
#define MICROPY_PY_SYS_EXIT (0)
#define MICROPY_PY_SYS_PLATFORM "linux"
#define MICROPY_PY_SYS_MAXSIZE (0)
#define MICROPY_PY_SYS_PATH_DEFAULT ".frozen"
#define MICROPY_PY_SYS_STDFILES (0)
#define MICROPY_PY_CMATH (0)
#define MICROPY_PY_UCTYPES (0)
#define MICROPY_PY_UZLIB (0)
#define MICROPY_PY_UJSON (0)
#define MICROPY_PY_UOS (1)
#define MICROPY_PY_URE (0)
#define MICROPY_PY_UHEAPQ (0)
#define MICROPY_PY_UHASHLIB (0)
#define MICROPY_PY_UBINASCII (0)
//////////////////////////////////////////
// Do not change anything beyond this line
//////////////////////////////////////////
#if !(defined(MICROPY_GCREGS_SETJMP) || defined(__x86_64__) || defined(__i386__) || defined(__thumb2__) || defined(__thumb__) || defined(__arm__))
// Fall back to setjmp() implementation for discovery of GC pointers in registers.
#define MICROPY_GCREGS_SETJMP (1)
#endif
// type definitions for the specific machine
#ifdef __LP64__
typedef long mp_int_t; // must be pointer size
typedef unsigned long mp_uint_t; // must be pointer size
#else
// These are definitions for machines where sizeof(int) == sizeof(void*),
// regardless for actual size.
typedef int mp_int_t; // must be pointer size
typedef unsigned int mp_uint_t; // must be pointer size
#endif
// Cannot include <sys/types.h>, as it may lead to symbol name clashes
#if _FILE_OFFSET_BITS == 64 && !defined(__LP64__)
typedef long long mp_off_t;
#else
typedef long mp_off_t;
#endif
// We need to provide a declaration/definition of alloca()
#ifdef __FreeBSD__
#include <stdlib.h>
#else
#include <alloca.h>
#endif
Loading…
Cancel
Save