bpo-40280: Add limited Emscripten REPL (GH-32284)

Co-authored-by: Katie Bell <katie@katharos.id.au>

1 files changed, 44 insertions, 15 deletions

diff --git a/Tools/wasm/README.md b/Tools/wasm/README.md
index 6b1e7b0..40b82e8 100644
--- a/Tools/wasm/README.md
+++ b/Tools/wasm/README.md
@@ -55,9 +55,13 @@ emrun builddir/emscripten-browser/python.html
 or
 
 ```shell
-python3 -m http.server
+./Tools/wasm/wasm_webserver.py
 ```
 
+and open http://localhost:8000/builddir/emscripten-browser/python.html . This
+directory structure enables the *C/C++ DevTools Support (DWARF)* to load C
+and header files with debug builds.
+
 ### Cross compile to wasm32-emscripten for node
 
 ```
@@ -79,17 +83,17 @@ popd
 node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscripten-node/python.js
 ```
 
-## wasm32-emscripten limitations and issues
+# wasm32-emscripten limitations and issues
 
-- Heap and stack are limited.
-- Most stdlib modules with a dependency on external libraries are missing:
-  ``ctypes``, ``readline``, ``sqlite3``, ``ssl``, and more.
-- Shared extension modules are not implemented yet. All extension modules
-  are statically linked into the main binary.
-  The experimental configure option ``--enable-wasm-dynamic-linking`` enables
-  dynamic extensions.
-- Processes are not supported. System calls like fork, popen, and subprocess
-  fail with ``ENOSYS`` or ``ENOSUP``.
+Emscripten before 3.1.8 has known bugs that can cause memory corruption and
+resource leaks. 3.1.8 contains several fixes for bugs in date and time
+functions.
+
+## Network stack
+
+- Python's socket module does not work with Emscripten's emulated POSIX
+  sockets yet. Network modules like ``asyncio``, ``urllib``, ``selectors``,
+  etc. are not available.
 - Only ``AF_INET`` and ``AF_INET6`` with ``SOCK_STREAM`` (TCP) or
   ``SOCK_DGRAM`` (UDP) are available. ``AF_UNIX`` is not supported.
 - ``socketpair`` does not work.
@@ -98,8 +102,21 @@ node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscri
   does not resolve to a real IP address. IPv6 is not available.
 - The ``select`` module is limited. ``select.select()`` crashes the runtime
   due to lack of exectfd support.
+
+## processes, threads, signals
+
+- Processes are not supported. System calls like fork, popen, and subprocess
+  fail with ``ENOSYS`` or ``ENOSUP``.
 - Signal support is limited. ``signal.alarm``, ``itimer``, ``sigaction``
   are not available or do not work correctly. ``SIGTERM`` exits the runtime.
+- Keyboard interrupt (CTRL+C) handling is not implemented yet.
+- Browser builds cannot start new threads. Node's web workers consume
+  extra file descriptors.
+- Resource-related functions like ``os.nice`` and most functions of the
+  ``resource`` module are not available.
+
+## file system
+
 - Most user, group, and permission related function and modules are not
   supported or don't work as expected, e.g.``pwd`` module, ``grp`` module,
   ``os.setgroups``, ``os.chown``, and so on. ``lchown`` and `lchmod`` are
@@ -113,23 +130,35 @@ node --experimental-wasm-threads --experimental-wasm-bulk-memory builddir/emscri
   and are disabled.
 - Large file support crashes the runtime and is disabled.
 - ``mmap`` module is unstable. flush (``msync``) can crash the runtime.
-- Resource-related functions like ``os.nice`` and most functions of the
-  ``resource`` module are not available.
+
+## Misc
+
+- Heap memory and stack size are limited. Recursion or extensive memory
+  consumption can crash Python.
+- Most stdlib modules with a dependency on external libraries are missing,
+  e.g. ``ctypes``, ``readline``, ``sqlite3``, ``ssl``, and more.
+- Shared extension modules are not implemented yet. All extension modules
+  are statically linked into the main binary.
+  The experimental configure option ``--enable-wasm-dynamic-linking`` enables
+  dynamic extensions.
 - glibc extensions for date and time formatting are not available.
 - ``locales`` module is affected by musl libc issues,
   [bpo-46390](https://bugs.python.org/issue46390).
 - Python's object allocator ``obmalloc`` is disabled by default.
 - ``ensurepip`` is not available.
 
-### wasm32-emscripten in browsers
+## wasm32-emscripten in browsers
 
+- The interactive shell does not handle copy 'n paste and unicode support
+  well.
 - The bundled stdlib is limited. Network-related modules,
   distutils, multiprocessing, dbm, tests and similar modules
   are not shipped. All other modules are bundled as pre-compiled
   ``pyc`` files.
 - Threading is not supported.
+- In-memory file system (MEMFS) is not persistent and limited.
 
-### wasm32-emscripten in node
+## wasm32-emscripten in node
 
 Node builds use ``NODERAWFS``, ``USE_PTHREADS`` and ``PROXY_TO_PTHREAD``
 linker options.