(nuttx) branch master updated: Documentation: Add mquickjs documentation

[li...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

linguini pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git


The following commit(s) were added to refs/heads/master by this push:
     new e6a0c6c3773 Documentation: Add mquickjs documentation
e6a0c6c3773 is described below

commit e6a0c6c37735ea70876c9aef6d4a93eb16a2b2e0
Author: Huang Qi <hu...@xiaomi.com>
AuthorDate: Wed Jan 7 22:20:07 2026 +0800

    Documentation: Add mquickjs documentation
    
    Add documentation for MicroQuickJS JavaScript interpreter in
    Documentation/applications/interpreters/mquickjs/index.rst.
    
    The documentation includes:
    - Description of MicroQuickJS (lightweight JS interpreter by Fabrice Bellard)
    - Strict mode restrictions (ES5 subset, no array holes, no value boxing, etc.)
    - Configuration options (CONFIG_INTERPRETERS_MQJS, priority, stack size)
    - Usage instructions with command options and examples
    - Memory limit warning (default 16MB is too large for embedded systems)
    - Feature highlights (minimal footprint, tracing GC, ROM-based stdlib, etc.)
    
    Signed-off-by: Huang Qi <hu...@xiaomi.com>
---
 .../applications/interpreters/mquickjs/index.rst   | 73 ++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/Documentation/applications/interpreters/mquickjs/index.rst b/Documentation/applications/interpreters/mquickjs/index.rst
new file mode 100644
index 00000000000..aeb7b3904fc
--- /dev/null
+++ b/Documentation/applications/interpreters/mquickjs/index.rst
@@ -0,0 +1,73 @@
+================================================
+``mquickjs`` MicroQuickJS JavaScript interpreter
+================================================
+
+This is a port of `MicroQuickJS <https://github.com/bellard/mquickjs>`_, a lightweight JavaScript
+interpreter created by Fabrice Bellard. MicroQuickJS is designed for resource-constrained embedded
+systems, offering a minimal footprint while still providing JavaScript language support.
+
+Strict Mode
+===========
+
+MQuickJS operates in a **stricter mode** where certain error-prone or inefficient JavaScript
+features are disabled. Key restrictions include:
+
+- Only strict mode constructs are supported (no ``with`` keyword, global variables must use ``var``)
+- Arrays cannot have holes; out-of-bounds array writes (except at array end) throw TypeError
+- Only global ``eval`` is supported; indirect eval cannot access local variables
+- No value boxing (e.g., ``new Number(1)`` is not supported)
+
+Configuration Options
+=====================
+
+``CONFIG_INTERPRETERS_MQJS``
+  Enable the MicroQuickJS JavaScript interpreter (default: n)
+
+``CONFIG_INTERPRETERS_MQJS_PRIORITY``
+  Task priority for the interpreter (default: 100)
+
+``CONFIG_INTERPRETERS_MQJS_STACKSIZE``
+  Stack size for the interpreter in bytes (default: 8192)
+
+Usage
+=====
+
+The ``mqjs`` command is available in NSH with the following options::
+
+  mqjs [options] [file [args]]
+
+  Options:
+    -h, --help           List options
+    -e, --eval EXPR      Evaluate expression
+    -i, --interactive    Go to interactive mode
+    -I, --include file   Include additional file
+    -d, --dump           Dump memory usage stats
+    --memory-limit n     Limit memory usage to n bytes
+    --no-column          No column number in debug info
+    -o FILE              Save bytecode to FILE
+    -m32                 Force 32-bit bytecode output
+    -b, --allow-bytecode Allow bytecode in input file
+
+Examples:
+
+- Execute a script: ``mqjs script.js``
+- Interactive REPL: ``mqjs -i``
+- Run with memory limit: ``mqjs --memory-limit 10k script.js``
+- Evaluate expression: ``mqjs -e 'print("Hello")'``
+
+.. warning::
+   **Important**: The default memory limit is 16 MB (``16 << 20`` bytes), which is too large
+   for most embedded systems. **Always set a memory limit** when running mquickjs on NuttX,
+   typically using ``--memory-limit 10k`` or similar small value. For example::
+
+     nsh> mqjs --memory-limit 10k script.js
+
+   Without a memory limit, mquickjs may exhaust system memory and cause instability.
+
+Features
+========
+
+- **JavaScript subset**: Implements a strict ES5-compatible subset of JavaScript with stricter mode that disables error-prone or inefficient constructs
+- **Tracing garbage collector**: Compactive GC for smaller objects and reduced memory fragmentation
+- **ROM-based standard library**: Standard library resides in ROM, generated at compile time for fast instantiation
+- **Bytecode compilation**: Can compile to bytecode and save to persistent storage (file or ROM) for embedded systems