New documentation website

Author: saghul

doc/quickjs.texi

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/.gitignore

@@ -0,0 +1 @@
+18

docs/.nvmrc

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/babel.config.js

@@ -0,0 +1,46 @@
+---
+sidebar_position: 2
+---
+
+# Building
+
+QuickJS uses [CMake] as its main build system, with an additional helper [Makefile].
+
+:::note
+Windows users will need to run the CMake commands manually.
+:::
+
+## Compiling everything
+
+```bash
+make
+```
+
+This will build the `qjs` and `qjsc` executables and other test tools. Head over [here](./cli) for
+instructions on how to use them.
+
+## Debug builds
+
+```bash
+make debug
+```
+
+This will produce a debug build without optimizations, suitable for developers.
+
+## Running test262
+
+```bash
+make test262
+```
+
+This will run the test262 suite.
+
+```bash
+make test262-update
+```
+
+This will run the test262 suite and update the error / pass report, useful after
+implementing a new feature that would alter the result of the test suite.
+
+[CMake]: https://cmake.org
+[Makefile]: https://www.gnu.org/software/make/

docs/docs/building.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 4
+---
+
+# The qjs and qjsc CLI tools
+
+## `qjs` - The QuickJS JavaScript interpreter
+
+The `qjs` executable runs the JavaScript interpreter. It includes a simple standard
+library and REPL.
+
+```
+$ qjs
+usage: qjs [options] [file [args]]
+-h  --help         list options
+-e  --eval EXPR    evaluate EXPR
+-i  --interactive  go to interactive mode
+-m  --module       load as ES6 module (default=autodetect)
+    --script       load as ES6 script (default=autodetect)
+-I  --include file include an additional file
+    --std          make 'std' and 'os' available to the loaded script
+-T  --trace        trace memory allocation
+-d  --dump         dump the memory usage stats
+-D  --dump-flags   flags for dumping debug data (see DUMP_* defines)
+    --memory-limit n       limit the memory usage to 'n' Kbytes
+    --stack-size n         limit the stack size to 'n' Kbytes
+    --unhandled-rejection  dump unhandled promise rejections
+-q  --quit         just instantiate the interpreter and quit
+```
+
+The following dump flags are supported:
+
+```
+DUMP_BYTECODE_FINAL   0x01  /* dump pass 3 final byte code */
+DUMP_BYTECODE_PASS2   0x02  /* dump pass 2 code */
+DUMP_BYTECODE_PASS1   0x04  /* dump pass 1 code */
+DUMP_BYTECODE_HEX     0x10  /* dump bytecode in hex */
+DUMP_BYTECODE_PC2LINE 0x20  /* dump line number table */
+DUMP_BYTECODE_STACK   0x40  /* dump compute_stack_size */
+DUMP_BYTECODE_STEP    0x80  /* dump executed bytecode */
+DUMP_READ_OBJECT     0x100  /* dump the marshalled objects at load time */
+DUMP_FREE            0x200  /* dump every object free */
+DUMP_GC              0x400  /* dump the occurrence of the automatic GC */
+DUMP_GC_FREE         0x800  /* dump objects freed by the GC */
+DUMP_MODULE_RESOLVE 0x1000  /* dump module resolution steps */
+DUMP_PROMISE        0x2000  /* dump promise steps */
+DUMP_LEAKS          0x4000  /* dump leaked objects and strings in JS_FreeRuntime */
+DUMP_ATOM_LEAKS     0x8000  /* dump leaked atoms in JS_FreeRuntime */
+DUMP_MEM           0x10000  /* dump memory usage in JS_FreeRuntime */
+DUMP_OBJECTS       0x20000  /* dump objects in JS_FreeRuntime */
+DUMP_ATOMS         0x40000  /* dump atoms in JS_FreeRuntime */
+DUMP_SHAPES        0x80000  /* dump shapes in JS_FreeRuntime */
+```
+
+## `qjsc` - The QuickJS JavaScript compiler
+
+The `qjsc` executable runs the JavaScript compiler, it can generate bytecode from
+source files which can then be embedded in an executable, or it can generate the necessary
+scaffolding to build a C application which embeds QuickJS.
+
+```
+$ qjsc
+usage: qjsc [options] [files]
+
+options are:
+-b          output raw bytecode instead of C code
+-e          output main() and bytecode in a C file
+-o output   set the output filename
+-n script_name    set the script name (as used in stack traces)
+-N cname    set the C name of the generated data
+-m          compile as JavaScript module (default=autodetect)
+-D module_name         compile a dynamically loaded module or worker
+-M module_name[,cname] add initialization code for an external C module
+-p prefix   set the prefix of the generated C names
+-s          strip the source code, specify twice to also strip debug info
+-S n        set the maximum stack size to 'n' bytes (default=262144)
+```

docs/docs/cli.md

@@ -0,0 +1,7 @@
+{
+  "label": "Developer Guide",
+  "position": 6,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/developer-guide/_category_.json

@@ -0,0 +1,3 @@
+# API Reference
+
+WIP.

docs/docs/developer-guide/api.md

@@ -0,0 +1,117 @@
+# Internals
+
+## Bytecode
+
+The compiler generates bytecode directly with no intermediate
+representation such as a parse tree, hence it is very fast. Several
+optimizations passes are done over the generated bytecode.
+
+A stack-based bytecode was chosen because it is simple and generates 
+compact code.
+
+For each function, the maximum stack size is computed at compile time so that
+no runtime stack overflow tests are needed.
+
+A separate compressed line number table is maintained for the debug
+information.
+
+Access to closure variables is optimized and is almost as fast as local
+variables.
+
+Direct `eval` in strict mode is optimized.
+
+## Runtime
+
+### Strings
+
+Strings are stored either as an 8 bit or a 16 bit array of
+characters. Hence random access to characters is always fast.
+
+The C API provides functions to convert JavaScript Strings to C UTF-8 encoded
+strings. The most common case where the JavaScript string contains
+only ASCII characters involves no copying.
+
+### Objects
+
+The object shapes (object prototype, property names and flags) are shared
+between objects to save memory.
+
+Arrays with no holes (except at the end of the array) are optimized.
+
+TypedArray accesses are optimized.
+
+### Atoms
+
+Object property names and some strings are stored as Atoms (unique
+strings) to save memory and allow fast comparison. Atoms are
+represented as a 32 bit integer. Half of the atom range is reserved for
+immediate integer literals from 0 to 2^31-1.
+
+### Numbers
+
+Numbers are represented either as 32-bit signed integers or 64-bit IEEE-754
+floating point values. Most operations have fast paths for the 32-bit
+integer case.
+
+### Garbage collection
+
+Reference counting is used to free objects automatically and
+deterministically. A separate cycle removal pass is done when the allocated
+memory becomes too large. The cycle removal algorithm only uses the
+reference counts and the object content, so no explicit garbage
+collection roots need to be manipulated in the C code.
+
+### JSValue
+
+It is a JavaScript value which can be a primitive type (such as
+Number, String, ...) or an Object. NaN boxing is used in the 32-bit version
+to store 64-bit floating point numbers. The representation is
+optimized so that 32-bit integers and reference counted values can be
+efficiently tested.
+
+In 64-bit code, JSValue are 128-bit large and no NaN boxing is used. The
+rationale is that in 64-bit code memory usage is less critical.
+
+In both cases (32 or 64 bits), JSValue exactly fits two CPU registers,
+so it can be efficiently returned by C functions.
+
+### Function call
+
+The engine is optimized so that function calls are fast. The system
+stack holds the JavaScript parameters and local variables.
+
+### RegExp
+
+A specific regular expression engine was developed. It is both small
+and efficient and supports all the ES2020+ features including the
+Unicode properties. As the JavaScript compiler, it directly generates
+bytecode without a parse tree.
+
+Backtracking with an explicit stack is used so that there is no
+recursion on the system stack. Simple quantifiers are specifically
+optimized to avoid recursions.
+
+Infinite recursions coming from quantifiers with empty terms are
+avoided.
+
+The full regexp library weights about 15 KiB (x86 code), excluding the
+Unicode library.
+
+### Unicode
+
+A specific Unicode library was developed so that there is no
+dependency on an external large Unicode library such as ICU. All the
+Unicode tables are compressed while keeping a reasonable access
+speed.
+
+The library supports case conversion, Unicode normalization, Unicode
+script queries, Unicode general category queries and all Unicode
+binary properties.
+
+The full Unicode library weights about 45 KiB (x86 code).
+
+### BigInt
+
+BigInt is implemented with the [libbf](https://bellard.org/libbf) library.
+It weights about 90 KiB (x86 code) and provides arbitrary precision IEEE 754 floating
+point operations and transcendental functions with exact rounding.

docs/docs/developer-guide/internals.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+---
+
+# The QuickJS C API
+
+The C API was designed to be simple and efficient. The C API is
+defined in the header `quickjs.h`.
+
+## Runtime and contexts
+
+`JSRuntime` represents a JavaScript runtime corresponding to an
+object heap. Several runtimes can exist at the same time but they
+cannot exchange objects. Inside a given runtime, no multi-threading is
+supported.
+
+`JSContext` represents a JavaScript context (or Realm). Each
+JSContext has its own global objects and system objects. There can be
+several JSContexts per JSRuntime and they can share objects, similar
+to frames of the same origin sharing JavaScript objects in a
+web browser.
+
+## JSValue
+
+`JSValue` represents a JavaScript value which can be a primitive
+type or an object. Reference counting is used, so it is important to
+explicitly duplicate (`JS_DupValue()`, increment the reference
+count) or free (`JS_FreeValue()`, decrement the reference count)
+JSValues.
+
+## C functions
+
+C functions can be created with
+`JS_NewCFunction()`. `JS_SetPropertyFunctionList()` is a
+shortcut to easily add functions, setters and getters properties to a
+given object.
+
+Unlike other embedded JavaScript engines, there is no implicit stack,
+so C functions get their parameters as normal C parameters. As a
+general rule, C functions take constant `JSValue`s as parameters
+(so they don't need to free them) and return a newly allocated (=live)
+`JSValue`.
+
+## Exceptions
+
+Most C functions can return a JavaScript exception. It
+must be explicitly tested and handled by the C code. The specific
+`JSValue` `JS_EXCEPTION` indicates that an exception
+occurred. The actual exception object is stored in the
+`JSContext` and can be retrieved with `JS_GetException()`.
+
+## Script evaluation
+
+Use `JS_Eval()` to evaluate a script or module source.
+
+If the script or module was compiled to bytecode with `qjsc`, it
+can be evaluated by calling `js_std_eval_binary()`. The advantage
+is that no compilation is needed so it is faster and smaller because
+the compiler can be removed from the executable if no `eval` is
+required.
+
+Note: the bytecode format is linked to a given QuickJS
+version. Moreover, no security check is done before its
+execution. Hence the bytecode should not be loaded from untrusted
+sources.
+
+## JS Classes
+
+C opaque data can be attached to a JavaScript object. The type of the
+C opaque data is determined with the class ID (`JSClassID`) of
+the object. Hence the first step is to register a new class ID and JS
+class (`JS_NewClassID()`, `JS_NewClass()`). Then you can
+create objects of this class with `JS_NewObjectClass()` and get or
+set the C opaque point with `JS_GetOpaque()` / `JS_SetOpaque()`.
+
+When defining a new JS class, it is possible to declare a finalizer
+which is called when the object is destroyed. The finalizer should be
+used to release C resources. It is invalid to execute JS code from
+it. A `gc_mark` method can be provided so that the cycle removal
+algorithm can find the other objects referenced by this object. Other
+methods are available to define exotic object behaviors.
+
+The Class ID are allocated per-runtime. The
+`JSClass` are allocated per `JSRuntime`. `JS_SetClassProto()`
+is used to define a prototype for a given class in a given
+`JSContext`. `JS_NewObjectClass()` sets this prototype in the
+created object.
+
+Examples are available in `quickjs-libc.c`.
+
+## C Modules
+
+Native ES6 modules are supported and can be dynamically or statically
+linked. The standard library `quickjs-libc.c` is a good example
+of a native module.
+
+## Memory handling
+
+Use `JS_SetMemoryLimit()` to set a global memory allocation limit
+to a given `JSRuntime`.
+
+Custom memory allocation functions can be provided with `JS_NewRuntime2()`.
+
+The maximum system stack size can be set with `JS_SetMaxStackSize()`.
+
+## Execution timeout and interrupts
+
+Use `JS_SetInterruptHandler()` to set a callback which is
+regularly called by the engine when it is executing code. This
+callback can be used to implement an execution timeout.
+
+It is used by the command line interpreter to implement a
+`Ctrl-C` handler.