circuitpython/ports/javascript
Damien George d2384efa80 py: Automatically provide weak links from "foo" to "ufoo" module name.
This commit implements automatic module weak links for all built-in
modules, by searching for "ufoo" in the built-in module list if "foo"
cannot be found.  This means that all modules named "ufoo" are always
available as "foo".  Also, a port can no longer add any other weak links,
which makes strict the definition of a weak link.

It saves some code size (about 100-200 bytes) on ports that previously had
lots of weak links.

Some changes from the previous behaviour:
- It doesn't intern the non-u module names (eg "foo" is not interned),
  which saves code size, but will mean that "import foo" creates a new qstr
  (namely "foo") in RAM (unless the importing module is frozen).
- help('modules') no longer lists non-u module names, only the u-variants;
  this reduces duplication in the help listing.

Weak links are effectively the same as having a set of symbolic links on
the filesystem that is searched last.  So an "import foo" will search
built-in modules first, then all paths in sys.path, then weak links last,
importing "ufoo" if it exists.  Thus a file called "foo.py" somewhere in
sys.path will still have precedence over the weak link of "foo" to "ufoo".

See issues: #1740, #4449, #5229, #5241.
2019-10-22 15:30:52 +11:00
..
JSBackend.patch javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
Makefile javascript: Enable support for frozen bytecode via FROZEN_MPY_DIR. 2019-07-09 13:17:15 +10:00
README.md javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
library.h javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
library.js javascript/library: Print data as raw bytes to stdout so unicode works. 2019-04-28 22:39:41 +10:00
main.c py: Add global default_emit_opt variable to make emit kind persistent. 2019-08-28 12:47:58 +10:00
modutime.c javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
mpconfigport.h py: Automatically provide weak links from "foo" to "ufoo" module name. 2019-10-22 15:30:52 +11:00
mphalport.c javascript: Fix Emscripten async load, and to compile with modern clang. 2019-03-13 23:52:15 +11:00
mphalport.h javascript: Fix Emscripten async load, and to compile with modern clang. 2019-03-13 23:52:15 +11:00
node_run.sh javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +11:00
qstrdefsport.h javascript: Add new port targeting JavaScript via Emscripten. 2019-03-13 23:47:32 +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).

A standard installation of Emscripten should provide functional code, however if memory errors are encountered it may be worthwhile to modify the tool. emscripten-fastcomp/lib/Target/JSBackend.cpp may require the minor fix found in JSBackend.patch. This patch attempts to address situations where C code running through Emscripten is denied access to Javascript variables leading to false-positives in the MicroPython garbage collector as variables with pointers exclusively in Javascript will be erased prematurely. Refer to Emscripten documentation for instructions on building Emscripten from source.

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.