circuitpython/ports/javascript
David Lechner c118b5d0e4 extmod/extmod.mk: Separate out extmod file list from py.mk to extmod.mk.
This separates extmod source files from `py.mk`.  Previously, `py.mk`
assumed that every consumer of the py/ directory also wanted to include
extmod/.  However, this is not the case.  For example, building mpy-cross
uses py/ but doesn't need extmod/.

This commit moves all extmod-specific items from `py.mk` to `extmod.mk` and
explicitly includes `extmod.mk` in ports that use it.

Signed-off-by: David Lechner <david@pybricks.com>
2022-06-21 00:14:34 +10:00
..
Makefile extmod/extmod.mk: Separate out extmod file list from py.mk to extmod.mk. 2022-06-21 00:14:34 +10:00
README.md javascript: Rework Makefile and GC so it works with latest Emscripten. 2021-06-25 11:29:39 +10:00
library.h javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
library.js all: Rename mp_keyboard_interrupt to mp_sched_keyboard_interrupt. 2021-04-30 15:13:43 +10:00
main.c py/builtin: Clean up and simplify import_stat and builtin_open config. 2022-05-25 13:04:45 +10:00
modutime.c all: Remove third argument to MP_REGISTER_MODULE. 2022-06-02 16:31:37 +10:00
mpconfigport.h ports: Use default VFS config for import_stat and builtin_open. 2022-05-25 13:04:45 +10:00
mphalport.c javascript: Fix Emscripten async load, and to compile with modern clang. 2019-03-13 23:52:15 +11:00
mphalport.h all: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
node_run.sh javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
qstrdefsport.h all: Add *FORMAT-OFF* in various places. 2020-02-28 10:31:07 +11:00
wrapper.js javascript: Pass (error) exit value out from script to process caller. 2019-04-28 22:16:27 +10:00

README.md

MicroPython.js

MicroPython transmuted into Javascript by Emscripten.

Dependencies

Building micropython.js bears the same requirements as the standard MicroPython ports with the addition of Emscripten (and uglify-js for the minified file).

Build instructions

In order to build micropython.js, run:

$ make

To generate the minified file micropython.min.js, run:

$ make min

Running with Node.js

Access the repl with:

$ node build/micropython.js

Stack size may be modified using:

$ node build/micropython.js -X stack=64K

Where stack size may be represented in Bytes, KiB or MiB.

MicroPython scripts may be executed using:

$ node build/micropython.js hello.py

Alternatively micropython.js may by accessed by other javascript programs in node using the require command and the general API outlined below. For example:

var mp_js = require('./build/micropython.js');

mp_js_init(64 * 1024);
mp_js_do_str("print('hello world')\n");

Running with HTML

The prerequisite for browser operation of micropython.js is an element with the id mp_js_stdout which receives print events. The following code demonstrates basic functionality:

<!doctype html>
<html>
  <head>
    <script src="build/micropython.js"></script>
  </head>
  <body>
    <div id='mp_js_stdout'></div>
    <script>
      mp_js_stdout.addEventListener('print', function(e) {
        document.write(e.data);
      }, false);

      mp_js_init(64 * 1024);
      mp_js_do_str('print(\'hello world\')');
    </script>
  </body>
</html>

MicroPython code execution will suspend the browser so be sure to atomize usage within this environment. Unfortunately interrupts have not been implemented for the browser.

Testing

Run the test suite using:

$ make test

API

The following functions have been exposed to javascript.

mp_js_init(stack_size)

Initialize MicroPython with the given stack size in bytes. This must be called before attempting to interact with MicroPython.

mp_js_do_str(code)

Execute the input code. code must be a string.

mp_js_init_repl()

Initialize MicroPython repl. Must be called before entering characters into the repl.

mp_js_process_char(char)

Input character into MicroPython repl. char must be of type number. This will execute MicroPython code when necessary.