mirror of
https://github.com/hanzoai/quickjs-emscripten.git
synced 2026-10-30 19:37:29 +00:00
* Update patch
* Fix logging value
* Remove CONFIG_BIGNUM as it was removed from upstream
* Fix build for QuickJS 2025-09-13 with emscripten 5.0.1
- Add forward declarations for EM_JS callback functions (C99 compliance)
- Remove JS_AddIntrinsicBigInt call (BigInt now part of core)
- Replace libbf.o with dtoa.o in build (bignum removed, dtoa added)
- Regenerate variant packages
* Squashed 'vendor/quickjs/' changes from 36911f0..f113949
f113949 regexp: removed alloca() is lre_exec() - added specific opcodes for \s and \S to have a smaller bytecode - optimized \b and \B
7bd1ae2 \x{N} is a syntax error
31ef02b slightly faster lexical variable assignment
c73a435 Don't call well-known Symbol methods for RegExp on primitive values
1dbba8a removed use after free in js_create_module_bytecode_function() (#467)
fcd33c1 removed memory leak in case of error in cpool_add() (#468)
e5fd391 fixed fast array extension optimization when there are multiple realms
24379bf added regexp duplicate named groups - fixed reset of captures with quantizers
b226856 updated to unicode 17.0.0 - updated test262 version
5907aa6 added missing lre_poll_timeout()
47aac8b regexp: cosmetic: make it clearer that there is now a set of registers instead of an auxiliary stack
371c06e regexp: ensure that the bytecode size grows linearly with respect to the input regexp.
a774007 removed buffer overflows introduced in regexp optimizations
728ed94 fixed Worker freeing logic (#462)
9f11034 - optimized Regexp.prototype.exec - optimized String.prototype.replace - optimized 'arguments' object creation - optimized access to non strict 'arguments' elements
7ab2341 faster and simpler implementation of regexp backtracking
fcbf5ea fixed BJSON array serialization (#457)
4bd485d - Added Iterator.concat (initial patch by bnoordhuis) - optimized js_iterator_concat_next() - added more guards against recursion in Iterator.concat operations
3d0cc29 optimized add/sub int32 overflow
125b012 added error checking in JS_InstantiateFunctionListItem()
ae7219b - Closure optimization (go from quadratic to linear time when the number of closure variables is large) - Separated JSVarDef and JSBytecodeVarDef to simplify the code and save memory - fixed debug info stripping with global variables
9688007 Restore a mistakenly removed goto on error in js_build_module_ns() (igorburago)
b07ad11 fixed JS_PROP_AUTOINIT handling in js_closure_define_global_var() (#455)
d10613f fixed exception handling in put_var operation (regression introduced by commit a6816be) (#454)
080c01f More informative "not a constructor" error message (initial patch by bnoordhuis) (#368)
c6fe5a9 Fix length check in ArrayBuffer.prototype.slice (bnoordhuis) (#451)
7cfddd0 fixed DataView resizing
75b5230 Fix use-after-free in ArrayBuffer.prototype.transfer (bnoordhuis) (#450) - use js_array_buffer_update_typed_arrays() in JS_DetachArrayBuffer()
baa186f qjs: added --strict option - don't consider included files as modules - allow module and strict code with -e option
961478d removed duplicate test
e015918 Much faster destructuring at the expense of a slight incompatibility with the spec when direct evals are present (v8 behaves the same way).
a6816be optimized global variable access
eb2c890 removed uninitialized variable
eab6945 updated test results
c31809e fixed operation order in Regexp constructor
af16a97 changed module rejection order according to spec change
9a421b3 optimized Array.prototype.push
3e5f2bb inlined the get_length operation
c720e35 added js_string_eq()
2161640 stricter year parsing in Date
7fb994c fixed argument evaluation order in Date constructor and Date.UTC()
0d4cd2d faster and safer dbuf functions (#443)
2a53de0 test262 update
6345009 fixed regression in error message display introduced in commit 42eb279
eb9fa2b compilation fix for clang
42eb279 Faster context creation and exception checks in JS_NewContext (#404)
7a488f3 update
c8a8cf5 faster appending of elements in arrays
79f3ae2 optimized string_buffer_putc()
e5de89f optimized post_inc and post_dec
8e8eefb optimized array access by inlining get_array_el, get_array_el2, get_array_el3 and put_array_el
64c55c6 removed JS_PROP_NO_ADD
57f8ec0 inlined fast path for get_field, get_field2 and put_field
2c90110 - optimized global variable access
f4951ef optimize the create of arrays - optimized the rest and array_from opcodes
f1253f2 Improve error handling in Promise.withResolvers (bnoordhuis)
31663a9 updated test262
4af5b1e Merge pull request #408 from nickva/run-test262-in-ci
fb14cc6 Run test262 tests in CI
c3e5ae2 simplified math.sumPrecise()
0060876 fixed Date parsing: "1997-03-08 11:19:10-0700" is a valid date and "1997-03-08T11:19:10-07" should yield an error
a6db749 fixed Atomics.pause() in the NaN boxing case (32 bit cpu)
bc753c6 added Math.sumPrecise()
456e016 added Map and WeakMap upsert methods (bnoordhuis)
8807fed - added Atomics.pause (bnoordhuis) - use the pause instruction for x86 and ARM64 in Atomics.pause()
f021d77 - added resizable array buffers (bnoordhuis) - fixed Atomics.wait, Atomics.notify, TypedArray.prototype.lastIndexOf - fixed JS_PreventExtensions() with resizable typed arrays
44d03a8 fixed parsing of computed property name
1e19893 - added ArrayBuffer.prototype.transfer (Divy Srivastava) - fixed transfer when the ArrayBuffer was allocated with a custom allocator
2d99c32 Iterator functions:
cf0e179 Iterator is an abstract class (bnoordhuis)
3dcca0d fix Iterator.prototype.constructor (initial patch by bnoordhuis)
b2ed2e9 added Iterator.prototype.[drop,filter,flatMap,map,take,every,find,forEach,some,reduce,[Symbol.toStringTag]] (saghul)
e924173 added Iterator.prototype.toArray and Iterator.from (bnoordhuis)
982b7aa added the Iterator object
0377dab removed uninitialized values - removed useless init
0cef7f0 set methods: removed memory leaks - fixed ordering of property access - fixed conversion to integer of 'size' in GetSetRecord() - added missing iterator close - factorized code
a1e073e added set methods (bnoordhuis)
de4d392 removed memory leak (#441)
dc7af0a updated release.sh
fa628f8 new release
391cd3f Fix crash on failure to read bytecode (penneryu)
9f6c190 more efficient handling of strings in JSON.stringify()
8a0a6e9 better pretty printing of strings - removed String.prototype.__quote()
20d2b40 qjsc: handle C name conflicts between scripts and modules (#432)
a4e4b43 run-test262: added --count_skipped_features option
0b3c73e removed function cast warnings (initial patch by saghul)
5689f30 fixed handling of 8 bit unicode strings in RegExp (regression introduced by commit a4ac84d)
a4ac84d Adjust lastIndex to leading surrogate when inside a surrogate pair in unicode RegExp (initial patch by auvred)
d9ec8f1 limit function and regexp bytecode to 1G to avoid buffer overflows (the bytecode generators assume that bytecode offsets can fit a 32 bit signed integer
4e0d0b7 avoid side effects in JS_PrintValue() which may lead to crashes in print() and js_std_promise_rejection_check()
c927eca fixed buffer overflow in TypedArray.prototype.lastIndexOf()
9ce5442 fixed buffer overflow in js_bigint_to_string1()
1168c21 fixed crash in OP_add_loc if the variable is modified in JS_ToPrimitiveFree()
e1c18be fixed buffer overflow in js_bigint_from_string()
c942978 TypedArray.prototype.subarray: fixed the step at which '[[ByteOffset]]' is read
bb34e27 test262 update
1fdc768 removed module leak in js_std_eval_binary() (#425)
458c34d fixed GC logic so that a module can live after a JSContext is destroyed (#280) - update the reference count for the realm in jobs and FinalizationRegistry
2fd48bf fixed module async evaluation logic - added DUMP_MODULE_EXEC
f1b1c00 update test262
4d9a27c update Changelog
098f221 added Error.isError() (bnoordhuis)
9b935db Merge pull request #418 from nickva/fix-byteoffset-for-detached-array-buffers
0f7eadf Fix Windows MinGW CI Build
00b1d8d Read byteOffset for detached buffers
638ec8c fixed js_bigint_to_string1() (#412)
bb986e5 update tests
fc524f7 added missing 'Unknown' unicode Script
dfc254a update tests
3d92a9d new keyword cannot be used with an optional chain
02a2643 fixed parsing of function definition
3dc7ef1 more robust out of memory handling (#406)
1572aa8 avoid win32 crash in getTimezoneOffset() if time is < 1970 (#238)
7c487f1 support JSON modules in qjsc - added support of JSON5 modules (using type = "json5")
1dfaa61 improved compatibility of std.parseExtJSON() with JSON5
8b2a124 fixed Regexp.prototype[Symbol.match]
071a4cf use Object.is() in tests
f10ef29 added JSON modules and import attributes
8381245 added JS_AtomToCStringLen()
2f167bb export JS_FreePropertyEnum()
9bce51e improved JSON parser conformity (chqrlie) (#250)
aaa9cea Proxy: fixed prototype comparison in setPrototypeOf() and getPrototypeOf() (#410)
1021e3c compilation fix
a33610d update test results
f95b8ba added regexp modifiers
9c973a8 added Promise.try (saghul)
3c39307 better promise rejection tracker heuristics (#112)
d7cdfdc regexp: added v flag support - fixed corner cases of case insensitive matching
a8b2d7c added Float16Array (bnoordhuis) - optimized float16 conversion functions
c95b024 added RegExp.escape (bnoordhuis)
0a6160d avoid relying on 'FILE *' in JS_PrintValue() API
11d076f added get_array_el3 opcode - removed to_propkey2 opcode
703de06 fixed use of JS_DumpValue()
be06b3e added JS_PrintValue() and use it in console.log(), print() and the REPL (#256)
30fe3de Object.prototype has an immutable prototype
53327c2 simplified uncatchable exception handling
23e2dc9 handle strings as module import and export names
3fbea36 update tests
9bb1d72 fixed operation order in js_obj_to_desc()
2d4e1cc fixed the delete operator with global variables
894ce9d fixed js_std_await() so that it behaves the same way as js_std_loop() (#402)
19abf18 new release
1b13fa6 added more C callbacks for exotic objects (#324)
7645ce5 more precise error location reporting
3306254 Merge pull request #393 from nickva/more-ci-targets-and-windows-fixes
8e9e8e8 update tests
87cf1b0 run-test262: added $262.gc()
3bffe67 fixed TypedArray.prototype.slice() when the buffers overlap
08a28c0 fixed TypedArray.prototype.with with detached ArrayBuffer
a0a760f fixed GeneratorFunction prototype
b32cccb fixed RegExp.prototype[Symbol.split]
1e958ab fixed operation order in Object.prototype.propertyIsEnumerable()
5afd0eb fix property ordering in the object returned by RegExp.prototype.exec()
5e71d14 setters cannot have rest arguments
99a855f future reserved keywords are forbidden in function name and arguments when the function body is in strict mode
c0958ee More CI tragets: Linux 32bit, LTO, Windows and Cosmopolitan
e5e7248 added staging test262 tests
fbf7d8a fixed detached TypedArray handling in Atomics operations
334aa18 fixed iterator close in Map/Set constructor
dbbca3d dtoa fix for minus zero
37cde16 fixed build_arg_list()
e1f6dfe fixed checks in Proxy defineProperty
e7264d6 fixed Array.from() and TypedArray.from()
000db3a the %TypedArray% Intrinsic Object should be a constructor
db3d3f0 fixed memory leak in String constructor
b67c416 fixed Proxy getOwnPropertyDescriptor with getters and setters
82d86b1 removed atom leak introduced in commit 83530ac9
f2b0723 added 'at' in Array.prototype[Symbol.unscopables]
0c5d59f optimized and fixed JS_AtomIsNumericIndex1(): 'NaN' is also a number
3b04c58 fixed 'with' access by adding HasPropery() calls - removed unused 'with_get_ref_undef' opcode
83530ac fixed destructuring operation order when defining variables - optimized more cases of variable definition in destructuring
1d5e7cf fixed destructuring parsing: do it only in assignment expressions
5449fd4 more ToPropertyKey ordering changes
8f99de5 spec update: ToPropertyKey() is now done after the evaluation of the expression in assignments
8bb41b2 enabled os.Worker on Windows (bnoordhuis)
bff5525 Merge pull request #400 from renatahodovan/fix-regexp
f5788c7 Define lre_check_timeout in fuzz_regexp
ecfef71 String.prototype.localeCompare is added in JS_AddIntrinsicStringNormalize() as it requires unicode normalization
c361210 qjsc: added missing -fno-weakref
251a8b2 added column number in error messages - simplified parser
4cc4c6c optimized js_parse_class_default_ctor() (bnoordhuis)
9106fa0 fixed DUMP_BYTECODE
5b0c98a fixed HTML comments (chqrlie)
67b48ae - removed the 'use strip' extension - removed the JS_EVAL_FLAG_STRIP eval flag and replaced it with JS_SetStripInfo() which has simpler semantics. - qjs: added the '-s' and '--strip-source' options - qjsc: added the '-s' and '--keep-source' options
c50de13 indent fix
9918c12 workaround for #282
7adeb5c Fix exporting destructured variables (saghul) (#382)
949c105 fixed class field named get or set
d546fbf changed js_throw_type_error ES5 workaround to be more compatible with test262
c505ac0 fixed JS_IsString() with ropes
25ffdb4 fixed the handling of unicode identifiers
9d3776d fixed break statement in the presence of labels (bnoordhuis) (#275)
00e6f29 added JS_GetAnyOpaque() (oleavr)
1eb05e4 fixed buffer overflow in BJSON String and BigInt reader (#399)
a151ce1 fixed and improved Map/Set hashing
f05760c qjs: added performance.now()
2b6cf57 removed unused slack in hash_map_resize() (saghul)
083b7ba Fix UB in BigInt left shift (saghul)
fa706d5 Fix leak in BigInt unary plus (saghul)
ec83bd2 qjs: allow SI suffixes in memory sizes - set default stack size to 1 MB
c805d4f fixed weakmap gc (#398)
1943101 updated Changelog
00b709d flush stdout in console.log() (#309)
159fe28 fixed module cyclic imports (#329)
c1bf4e9 workaround for overflow test in JS_GetOwnPropertyNamesInternal() (#111)
beeb272 'undefined' is a valid let/const variable name. It gives a SyntaxError at top level because it is already defined (#370)
f121cbd added forgotten js_weakref_is_live() tests
b342502 avoid freeing an object structure in js_weakref_free() if it is about to be freed in free_zero_refcount()
8b5b127 reworked weak references so that cycles are (hopefully) correctly handled - added Symbol as WeakMap key, WeakRef and FinalizationRegistry
bf164d6 fixed eval with empty argument scope (#249)
6ac04e1 removed useless printf() (#257)
0d7aaed ensure that JS_IteratorNext() returns JS_UNDEFINED when done = TRUE (#394)
2634856 removed invalid tests
56c47f7 fixed exception handling in AsyncFromSyncIterator and async for of
67de495 fixed typed array set operation when obj != receiver
b0c1a12 fixed set_date_field()
d045a13 disable rejection tracker in the repl - repl cleanup
e8cfe8f removed memory leak in string padding (issue #274)
d20ffec exit by default on unhandled promise rejections (issue #305)
dec4aca update test262_errors.txt
b31bb20 updated to unicode 16.0.0 (bnoordhuis) - updated test262
29630bc added missing header
2a4f629 added -Wno-infinite-recursion
6cc02b4 more use of js_new_string8 - inlined JS_NewString() (initial patch by Charlie Gordon)
156d981 added string ropes for faster concatenation of long strings (issue #67)
372ad84 more dtoa bench (Charlie Gordon)
a44011e enable dtoa tests on win32
d1bb520 reduced memory usage of Map hash table
4941398 fixed hash_map_resize() - added Map/WeakMap in microbench
9f65ef1 simplified and fixed backtrace_barrier (#306)
978756a protect against printf errors (#319)
9936606 added new dtoa library to print and parse float64 numbers. It is necessary to fix corner cases (e.g. radix != 10) and to have correct behavior regardless of the libc implementation.
9f1864a msan fix (#389)
131408f simplified js_bigint_from_float64()
7399069 fixed examples/hello_module compilation (#240)
6d6893b fixed BigInt hashing - removed -fno-bigint in qjsc and JS_AddIntrinsicBigInt() (BigInt is now considered as a base object)
5a16c0c fixed JS_DumpValue() for BigInt
6de8885 more bignum cleanup
96e7965 removed the ability to do simultaneous 64 and 32 bit x86 builds in order to simplify the Makefile
22dbf49 Merge pull request #391 from nickva/try-to-fix-multiplatform-builds
e9c69f7 Fix multiarch CI builds
ee4cd4d compilation fix
543897a added missing variable
61e8b94 removed bignum support and qjscalc - added optimized BigInt implementation
837a697 regexp: allow [\-] in unicode mode (#373)
1be68b3 fixed CONFIG_ALL_UNICODE compilation
9bd10d8 simplified the handling of closures
dfd9c93 added missing stack overflow check in JSON.stringify()
25aaa77 allow regexp interruption (e.g. with Ctrl-C in the REPL)
027f3cb fix crash when add_property() fails on build arguments (penneryu)
c739deb microbench: use toFixed()
6474793 JS_SetPropertyInternal(): avoid recursing thru the prototypes if the property is found in a prototype
030333c fixed date parsing in case there is more than nine initial digits (initial patch by nickva)
6e2e68f Fix termination in Worker test
012451d Define a fallback PATH_MAX if not available
8624b5c Use ftello() & fseeko() on any OS based on GNU libc
3489493 Use malloc_usable_size() on any OS based on GNU libc
5417ab0 Fix `JS_HasException()` when `null` is thrown (#313)
b3715f7 Fix GC leak in `js_proxy_get()` (#302)
git-subtree-dir: vendor/quickjs
git-subtree-split: f1139494d18a2053630c5ed3384a42bb70db3c53
* revert?
* Revert "revert?"
This reverts commit 32842c343a3a3342e880827170f44f8e34449dc9.
---------
Co-authored-by: Josh Parnham <[email protected]>
Co-authored-by: Hanzo Dev <[email protected]>
1074 lines
33 KiB
Plaintext
1074 lines
33 KiB
Plaintext
\input texinfo
|
|
|
|
@iftex
|
|
@afourpaper
|
|
@headings double
|
|
@end iftex
|
|
|
|
@include version.texi
|
|
|
|
@titlepage
|
|
@afourpaper
|
|
@sp 7
|
|
@center @titlefont{QuickJS Javascript Engine}
|
|
@sp 3
|
|
@center Version: @value{VERSION}
|
|
@end titlepage
|
|
|
|
@setfilename spec.info
|
|
@settitle QuickJS Javascript Engine
|
|
|
|
@contents
|
|
|
|
@chapter Introduction
|
|
|
|
QuickJS (version @value{VERSION}) is a small and embeddable Javascript
|
|
engine. It supports most of the ES2024 specification
|
|
@footnote{@url{https://tc39.es/ecma262/2024 }} including modules,
|
|
asynchronous generators, proxies and BigInt.
|
|
|
|
@section Main Features
|
|
|
|
@itemize
|
|
|
|
@item Small and easily embeddable: just a few C files, no external dependency, 210 KiB of x86 code for a simple ``hello world'' program.
|
|
|
|
@item Fast interpreter with very low startup time: runs the 77000 tests of the ECMAScript Test Suite@footnote{@url{https://github.com/tc39/test262}} in less than 2 minutes on a single core of a desktop PC. The complete life cycle of a runtime instance completes in less than 300 microseconds.
|
|
|
|
@item Almost complete ES2024 support including modules, asynchronous
|
|
generators and full Annex B support (legacy web compatibility). Some
|
|
features from the upcoming ES2024 specification
|
|
@footnote{@url{https://tc39.es/ecma262/}} are also supported.
|
|
|
|
@item Passes nearly 100% of the ECMAScript Test Suite tests when selecting the ES2024 features.
|
|
|
|
@item Compile Javascript sources to executables with no external dependency.
|
|
|
|
@item Garbage collection using reference counting (to reduce memory usage and have deterministic behavior) with cycle removal.
|
|
|
|
@item Command line interpreter with contextual colorization and completion implemented in Javascript.
|
|
|
|
@item Small built-in standard library with C library wrappers.
|
|
|
|
@end itemize
|
|
|
|
@chapter Usage
|
|
|
|
@section Installation
|
|
|
|
A Makefile is provided to compile the engine on Linux or MacOS/X. A
|
|
preliminary Windows support is available thru cross compilation on a
|
|
Linux host with the MingGW tools.
|
|
|
|
Edit the top of the @code{Makefile} if you wish to select specific
|
|
options then run @code{make}.
|
|
|
|
You can type @code{make install} as root if you wish to install the binaries and support files to
|
|
@code{/usr/local} (this is not necessary to use QuickJS).
|
|
|
|
Note: On some OSes atomic operations are not available or need a
|
|
specific library. If you get related errors, you should either add
|
|
@code{-latomics} in the Makefile @code{LIBS} variable or disable
|
|
@code{CONFIG_ATOMICS} in @file{quickjs.c}.
|
|
|
|
@section Quick start
|
|
|
|
@code{qjs} is the command line interpreter (Read-Eval-Print Loop). You can pass
|
|
Javascript files and/or expressions as arguments to execute them:
|
|
|
|
@example
|
|
./qjs examples/hello.js
|
|
@end example
|
|
|
|
@code{qjsc} is the command line compiler:
|
|
|
|
@example
|
|
./qjsc -o hello examples/hello.js
|
|
./hello
|
|
@end example
|
|
|
|
generates a @code{hello} executable with no external dependency.
|
|
|
|
@section Command line options
|
|
|
|
@subsection @code{qjs} interpreter
|
|
|
|
@verbatim
|
|
usage: qjs [options] [file [args]]
|
|
@end verbatim
|
|
|
|
Options are:
|
|
@table @code
|
|
@item -h
|
|
@item --help
|
|
List options.
|
|
|
|
@item -e @code{EXPR}
|
|
@item --eval @code{EXPR}
|
|
Evaluate EXPR.
|
|
|
|
@item -i
|
|
@item --interactive
|
|
Go to interactive mode (it is not the default when files are provided on the command line).
|
|
|
|
@item -m
|
|
@item --module
|
|
Load as ES6 module (default=autodetect). A module is autodetected if
|
|
the filename extension is @code{.mjs} or if the first keyword of the
|
|
source is @code{import}.
|
|
|
|
@item --script
|
|
Load as ES6 script (default=autodetect).
|
|
|
|
@item -I file
|
|
@item --include file
|
|
Include an additional file.
|
|
|
|
@end table
|
|
|
|
Advanced options are:
|
|
|
|
@table @code
|
|
@item --std
|
|
Make the @code{std} and @code{os} modules available to the loaded
|
|
script even if it is not a module.
|
|
|
|
@item -d
|
|
@item --dump
|
|
Dump the memory usage stats.
|
|
|
|
@item -q
|
|
@item --quit
|
|
just instantiate the interpreter and quit.
|
|
|
|
@end table
|
|
|
|
@subsection @code{qjsc} compiler
|
|
|
|
@verbatim
|
|
usage: qjsc [options] [files]
|
|
@end verbatim
|
|
|
|
Options are:
|
|
@table @code
|
|
@item -c
|
|
Only output bytecode in a C file. The default is to output an executable file.
|
|
@item -e
|
|
Output @code{main()} and bytecode in a C file. The default is to output an
|
|
executable file.
|
|
@item -o output
|
|
Set the output filename (default = @file{out.c} or @file{a.out}).
|
|
|
|
@item -N cname
|
|
Set the C name of the generated data.
|
|
|
|
@item -m
|
|
Compile as Javascript module (default=autodetect).
|
|
|
|
@item -D module_name
|
|
Compile a dynamically loaded module and its dependencies. This option
|
|
is needed when your code uses the @code{import} keyword or the
|
|
@code{os.Worker} constructor because the compiler cannot statically
|
|
find the name of the dynamically loaded modules.
|
|
|
|
@item -M module_name[,cname]
|
|
Add initialization code for an external C module. See the
|
|
@code{c_module} example.
|
|
|
|
@item -x
|
|
Byte swapped output (only used for cross compilation).
|
|
|
|
@item -flto
|
|
Use link time optimization. The compilation is slower but the
|
|
executable is smaller and faster. This option is automatically set
|
|
when the @code{-fno-x} options are used.
|
|
|
|
@item -fno-[eval|string-normalize|regexp|json|proxy|map|typedarray|promise|bigint]
|
|
Disable selected language features to produce a smaller executable file.
|
|
|
|
@end table
|
|
|
|
@section Built-in tests
|
|
|
|
Run @code{make test} to run the few built-in tests included in the
|
|
QuickJS archive.
|
|
|
|
@section Test262 (ECMAScript Test Suite)
|
|
|
|
A test262 runner is included in the QuickJS archive. The test262 tests
|
|
can be installed in the QuickJS source directory with:
|
|
|
|
@example
|
|
git clone https://github.com/tc39/test262.git test262
|
|
cd test262
|
|
patch -p1 < ../tests/test262.patch
|
|
cd ..
|
|
@end example
|
|
|
|
The patch adds the implementation specific @code{harness} functions
|
|
and optimizes the inefficient RegExp character classes and Unicode
|
|
property escapes tests (the tests themselves are not modified, only a
|
|
slow string initialization function is optimized).
|
|
|
|
The tests can be run with
|
|
@example
|
|
make test2
|
|
@end example
|
|
|
|
The configuration files @code{test262.conf}
|
|
(resp. @code{test262o.conf} for the old ES5.1 tests@footnote{The old
|
|
ES5.1 tests can be extracted with @code{git clone --single-branch
|
|
--branch es5-tests https://github.com/tc39/test262.git test262o}}))
|
|
contain the options to run the various tests. Tests can be excluded
|
|
based on features or filename.
|
|
|
|
The file @code{test262_errors.txt} contains the current list of
|
|
errors. The runner displays a message when a new error appears or when
|
|
an existing error is corrected or modified. Use the @code{-u} option
|
|
to update the current list of errors (or @code{make test2-update}).
|
|
|
|
The file @code{test262_report.txt} contains the logs of all the
|
|
tests. It is useful to have a clearer analysis of a particular
|
|
error. In case of crash, the last line corresponds to the failing
|
|
test.
|
|
|
|
Use the syntax @code{./run-test262 -c test262.conf -f filename.js} to
|
|
run a single test. Use the syntax @code{./run-test262 -c test262.conf
|
|
N} to start testing at test number @code{N}.
|
|
|
|
For more information, run @code{./run-test262} to see the command line
|
|
options of the test262 runner.
|
|
|
|
@code{run-test262} accepts the @code{-N} option to be invoked from
|
|
@code{test262-harness}@footnote{@url{https://github.com/bterlson/test262-harness}}
|
|
thru @code{eshost}. Unless you want to compare QuickJS with other
|
|
engines under the same conditions, we do not recommend to run the
|
|
tests this way as it is much slower (typically half an hour instead of
|
|
about 100 seconds).
|
|
|
|
@chapter Specifications
|
|
|
|
@section Language support
|
|
|
|
@subsection ES2024 support
|
|
|
|
The ES2024 specification is almost fully supported including the Annex
|
|
B (legacy web compatibility) and the Unicode related features.
|
|
|
|
The following features are not supported yet:
|
|
|
|
@itemize
|
|
|
|
@item Tail calls@footnote{We believe the current specification of tails calls is too complicated and presents limited practical interests.}
|
|
|
|
@item Atomics.waitAsync
|
|
|
|
@end itemize
|
|
|
|
@subsection ECMA402
|
|
|
|
ECMA402 (Internationalization API) is not supported.
|
|
|
|
@section Modules
|
|
|
|
ES6 modules are fully supported. The default name resolution is the
|
|
following:
|
|
|
|
@itemize
|
|
|
|
@item Module names with a leading @code{.} or @code{..} are relative
|
|
to the current module path.
|
|
|
|
@item Module names without a leading @code{.} or @code{..} are system
|
|
modules, such as @code{std} or @code{os}.
|
|
|
|
@item Module names ending with @code{.so} are native modules using the
|
|
QuickJS C API.
|
|
|
|
@end itemize
|
|
|
|
@section Standard library
|
|
|
|
The standard library is included by default in the command line
|
|
interpreter. It contains the two modules @code{std} and @code{os} and
|
|
a few global objects.
|
|
|
|
@subsection Global objects
|
|
|
|
@table @code
|
|
@item scriptArgs
|
|
Provides the command line arguments. The first argument is the script name.
|
|
@item print(...args)
|
|
Print the arguments separated by spaces and a trailing newline.
|
|
@item console.log(...args)
|
|
Same as print().
|
|
|
|
@end table
|
|
|
|
@subsection @code{std} module
|
|
|
|
The @code{std} module provides wrappers to the libc @file{stdlib.h}
|
|
and @file{stdio.h} and a few other utilities.
|
|
|
|
Available exports:
|
|
|
|
@table @code
|
|
|
|
@item exit(n)
|
|
Exit the process.
|
|
|
|
@item evalScript(str, options = undefined)
|
|
Evaluate the string @code{str} as a script (global
|
|
eval). @code{options} is an optional object containing the following
|
|
optional properties:
|
|
|
|
@table @code
|
|
@item backtrace_barrier
|
|
Boolean (default = false). If true, error backtraces do not list the
|
|
stack frames below the evalScript.
|
|
@item async
|
|
Boolean (default = false). If true, @code{await} is accepted in the
|
|
script and a promise is returned. The promise is resolved with an
|
|
object whose @code{value} property holds the value returned by the
|
|
script.
|
|
@end table
|
|
|
|
@item loadScript(filename)
|
|
Evaluate the file @code{filename} as a script (global eval).
|
|
|
|
@item loadFile(filename)
|
|
Load the file @code{filename} and return it as a string assuming UTF-8
|
|
encoding. Return @code{null} in case of I/O error.
|
|
|
|
@item open(filename, flags, errorObj = undefined)
|
|
Open a file (wrapper to the libc @code{fopen()}). Return the FILE
|
|
object or @code{null} in case of I/O error. If @code{errorObj} is not
|
|
undefined, set its @code{errno} property to the error code or to 0 if
|
|
no error occured.
|
|
|
|
@item popen(command, flags, errorObj = undefined)
|
|
Open a process by creating a pipe (wrapper to the libc
|
|
@code{popen()}). Return the FILE
|
|
object or @code{null} in case of I/O error. If @code{errorObj} is not
|
|
undefined, set its @code{errno} property to the error code or to 0 if
|
|
no error occured.
|
|
|
|
@item fdopen(fd, flags, errorObj = undefined)
|
|
Open a file from a file handle (wrapper to the libc
|
|
@code{fdopen()}). Return the FILE
|
|
object or @code{null} in case of I/O error. If @code{errorObj} is not
|
|
undefined, set its @code{errno} property to the error code or to 0 if
|
|
no error occured.
|
|
|
|
@item tmpfile(errorObj = undefined)
|
|
Open a temporary file. Return the FILE
|
|
object or @code{null} in case of I/O error. If @code{errorObj} is not
|
|
undefined, set its @code{errno} property to the error code or to 0 if
|
|
no error occured.
|
|
|
|
@item puts(str)
|
|
Equivalent to @code{std.out.puts(str)}.
|
|
|
|
@item printf(fmt, ...args)
|
|
Equivalent to @code{std.out.printf(fmt, ...args)}.
|
|
|
|
@item sprintf(fmt, ...args)
|
|
Equivalent to the libc sprintf().
|
|
|
|
@item in
|
|
@item out
|
|
@item err
|
|
Wrappers to the libc file @code{stdin}, @code{stdout}, @code{stderr}.
|
|
|
|
@item SEEK_SET
|
|
@item SEEK_CUR
|
|
@item SEEK_END
|
|
Constants for seek().
|
|
|
|
@item Error
|
|
|
|
Enumeration object containing the integer value of common errors
|
|
(additional error codes may be defined):
|
|
|
|
@table @code
|
|
@item EINVAL
|
|
@item EIO
|
|
@item EACCES
|
|
@item EEXIST
|
|
@item ENOSPC
|
|
@item ENOSYS
|
|
@item EBUSY
|
|
@item ENOENT
|
|
@item EPERM
|
|
@item EPIPE
|
|
@end table
|
|
|
|
@item strerror(errno)
|
|
Return a string that describes the error @code{errno}.
|
|
|
|
@item gc()
|
|
Manually invoke the cycle removal algorithm. The cycle removal
|
|
algorithm is automatically started when needed, so this function is
|
|
useful in case of specific memory constraints or for testing.
|
|
|
|
@item getenv(name)
|
|
Return the value of the environment variable @code{name} or
|
|
@code{undefined} if it is not defined.
|
|
|
|
@item setenv(name, value)
|
|
Set the value of the environment variable @code{name} to the string
|
|
@code{value}.
|
|
|
|
@item unsetenv(name)
|
|
Delete the environment variable @code{name}.
|
|
|
|
@item getenviron()
|
|
Return an object containing the environment variables as key-value pairs.
|
|
|
|
@item urlGet(url, options = undefined)
|
|
|
|
Download @code{url} using the @file{curl} command line
|
|
utility. @code{options} is an optional object containing the following
|
|
optional properties:
|
|
|
|
@table @code
|
|
@item binary
|
|
Boolean (default = false). If true, the response is an ArrayBuffer
|
|
instead of a string. When a string is returned, the data is assumed
|
|
to be UTF-8 encoded.
|
|
|
|
@item full
|
|
|
|
Boolean (default = false). If true, return the an object contains
|
|
the properties @code{response} (response content),
|
|
@code{responseHeaders} (headers separated by CRLF), @code{status}
|
|
(status code). @code{response} is @code{null} is case of protocol or
|
|
network error. If @code{full} is false, only the response is
|
|
returned if the status is between 200 and 299. Otherwise @code{null}
|
|
is returned.
|
|
|
|
@end table
|
|
|
|
@item parseExtJSON(str)
|
|
|
|
Parse @code{str} using a superset of @code{JSON.parse}. The superset
|
|
is very close to the JSON5 specification. The following extensions
|
|
are accepted:
|
|
|
|
@itemize
|
|
@item Single line and multiline comments
|
|
@item unquoted properties (ASCII-only Javascript identifiers)
|
|
@item trailing comma in array and object definitions
|
|
@item single quoted strings
|
|
@item @code{\v} escape and multi-line strings with trailing @code{\}
|
|
@item @code{\f} and @code{\v} are accepted as space characters
|
|
@item leading plus or decimal point in numbers
|
|
@item hexadecimal (@code{0x} prefix), octal (@code{0o} prefix) and binary (@code{0b} prefix) integers
|
|
@item @code{NaN} and @code{Infinity} are accepted as numbers
|
|
@end itemize
|
|
@end table
|
|
|
|
FILE prototype:
|
|
|
|
@table @code
|
|
@item close()
|
|
Close the file. Return 0 if OK or @code{-errno} in case of I/O error.
|
|
@item puts(str)
|
|
Outputs the string with the UTF-8 encoding.
|
|
@item printf(fmt, ...args)
|
|
Formatted printf.
|
|
|
|
The same formats as the standard C library @code{printf} are
|
|
supported. Integer format types (e.g. @code{%d}) truncate the Numbers
|
|
or BigInts to 32 bits. Use the @code{l} modifier (e.g. @code{%ld}) to
|
|
truncate to 64 bits.
|
|
|
|
@item flush()
|
|
Flush the buffered file.
|
|
@item seek(offset, whence)
|
|
Seek to a give file position (whence is
|
|
@code{std.SEEK_*}). @code{offset} can be a number or a bigint. Return
|
|
0 if OK or @code{-errno} in case of I/O error.
|
|
@item tell()
|
|
Return the current file position.
|
|
@item tello()
|
|
Return the current file position as a bigint.
|
|
@item eof()
|
|
Return true if end of file.
|
|
@item fileno()
|
|
Return the associated OS handle.
|
|
@item error()
|
|
Return true if there was an error.
|
|
@item clearerr()
|
|
Clear the error indication.
|
|
|
|
@item read(buffer, position, length)
|
|
Read @code{length} bytes from the file to the ArrayBuffer @code{buffer} at byte
|
|
position @code{position} (wrapper to the libc @code{fread}).
|
|
|
|
@item write(buffer, position, length)
|
|
Write @code{length} bytes to the file from the ArrayBuffer @code{buffer} at byte
|
|
position @code{position} (wrapper to the libc @code{fwrite}).
|
|
|
|
@item getline()
|
|
Return the next line from the file, assuming UTF-8 encoding, excluding
|
|
the trailing line feed.
|
|
|
|
@item readAsString(max_size = undefined)
|
|
Read @code{max_size} bytes from the file and return them as a string
|
|
assuming UTF-8 encoding. If @code{max_size} is not present, the file
|
|
is read up its end.
|
|
|
|
@item getByte()
|
|
Return the next byte from the file. Return -1 if the end of file is reached.
|
|
|
|
@item putByte(c)
|
|
Write one byte to the file.
|
|
@end table
|
|
|
|
@subsection @code{os} module
|
|
|
|
The @code{os} module provides Operating System specific functions:
|
|
|
|
@itemize
|
|
@item low level file access
|
|
@item signals
|
|
@item timers
|
|
@item asynchronous I/O
|
|
@item workers (threads)
|
|
@end itemize
|
|
|
|
The OS functions usually return 0 if OK or an OS specific negative
|
|
error code.
|
|
|
|
Available exports:
|
|
|
|
@table @code
|
|
@item open(filename, flags, mode = 0o666)
|
|
Open a file. Return a handle or < 0 if error.
|
|
|
|
@item O_RDONLY
|
|
@item O_WRONLY
|
|
@item O_RDWR
|
|
@item O_APPEND
|
|
@item O_CREAT
|
|
@item O_EXCL
|
|
@item O_TRUNC
|
|
POSIX open flags.
|
|
|
|
@item O_TEXT
|
|
(Windows specific). Open the file in text mode. The default is binary mode.
|
|
|
|
@item close(fd)
|
|
Close the file handle @code{fd}.
|
|
|
|
@item seek(fd, offset, whence)
|
|
Seek in the file. Use @code{std.SEEK_*} for
|
|
@code{whence}. @code{offset} is either a number or a bigint. If
|
|
@code{offset} is a bigint, a bigint is returned too.
|
|
|
|
@item read(fd, buffer, offset, length)
|
|
Read @code{length} bytes from the file handle @code{fd} to the
|
|
ArrayBuffer @code{buffer} at byte position @code{offset}.
|
|
Return the number of read bytes or < 0 if error.
|
|
|
|
@item write(fd, buffer, offset, length)
|
|
Write @code{length} bytes to the file handle @code{fd} from the
|
|
ArrayBuffer @code{buffer} at byte position @code{offset}.
|
|
Return the number of written bytes or < 0 if error.
|
|
|
|
@item isatty(fd)
|
|
Return @code{true} is @code{fd} is a TTY (terminal) handle.
|
|
|
|
@item ttyGetWinSize(fd)
|
|
Return the TTY size as @code{[width, height]} or @code{null} if not available.
|
|
|
|
@item ttySetRaw(fd)
|
|
Set the TTY in raw mode.
|
|
|
|
@item remove(filename)
|
|
Remove a file. Return 0 if OK or @code{-errno}.
|
|
|
|
@item rename(oldname, newname)
|
|
Rename a file. Return 0 if OK or @code{-errno}.
|
|
|
|
@item realpath(path)
|
|
Return @code{[str, err]} where @code{str} is the canonicalized absolute
|
|
pathname of @code{path} and @code{err} the error code.
|
|
|
|
@item getcwd()
|
|
Return @code{[str, err]} where @code{str} is the current working directory
|
|
and @code{err} the error code.
|
|
|
|
@item chdir(path)
|
|
Change the current directory. Return 0 if OK or @code{-errno}.
|
|
|
|
@item mkdir(path, mode = 0o777)
|
|
Create a directory at @code{path}. Return 0 if OK or @code{-errno}.
|
|
|
|
@item stat(path)
|
|
@item lstat(path)
|
|
|
|
Return @code{[obj, err]} where @code{obj} is an object containing the
|
|
file status of @code{path}. @code{err} is the error code. The
|
|
following fields are defined in @code{obj}: dev, ino, mode, nlink,
|
|
uid, gid, rdev, size, blocks, atime, mtime, ctime. The times are
|
|
specified in milliseconds since 1970. @code{lstat()} is the same as
|
|
@code{stat()} excepts that it returns information about the link
|
|
itself.
|
|
|
|
@item S_IFMT
|
|
@item S_IFIFO
|
|
@item S_IFCHR
|
|
@item S_IFDIR
|
|
@item S_IFBLK
|
|
@item S_IFREG
|
|
@item S_IFSOCK
|
|
@item S_IFLNK
|
|
@item S_ISGID
|
|
@item S_ISUID
|
|
Constants to interpret the @code{mode} property returned by
|
|
@code{stat()}. They have the same value as in the C system header
|
|
@file{sys/stat.h}.
|
|
|
|
@item utimes(path, atime, mtime)
|
|
Change the access and modification times of the file @code{path}. The
|
|
times are specified in milliseconds since 1970. Return 0 if OK or @code{-errno}.
|
|
|
|
@item symlink(target, linkpath)
|
|
Create a link at @code{linkpath} containing the string @code{target}. Return 0 if OK or @code{-errno}.
|
|
|
|
@item readlink(path)
|
|
Return @code{[str, err]} where @code{str} is the link target and @code{err}
|
|
the error code.
|
|
|
|
@item readdir(path)
|
|
Return @code{[array, err]} where @code{array} is an array of strings
|
|
containing the filenames of the directory @code{path}. @code{err} is
|
|
the error code.
|
|
|
|
@item setReadHandler(fd, func)
|
|
Add a read handler to the file handle @code{fd}. @code{func} is called
|
|
each time there is data pending for @code{fd}. A single read handler
|
|
per file handle is supported. Use @code{func = null} to remove the
|
|
handler.
|
|
|
|
@item setWriteHandler(fd, func)
|
|
Add a write handler to the file handle @code{fd}. @code{func} is
|
|
called each time data can be written to @code{fd}. A single write
|
|
handler per file handle is supported. Use @code{func = null} to remove
|
|
the handler.
|
|
|
|
@item signal(signal, func)
|
|
Call the function @code{func} when the signal @code{signal}
|
|
happens. Only a single handler per signal number is supported. Use
|
|
@code{null} to set the default handler or @code{undefined} to ignore
|
|
the signal. Signal handlers can only be defined in the main thread.
|
|
|
|
@item SIGINT
|
|
@item SIGABRT
|
|
@item SIGFPE
|
|
@item SIGILL
|
|
@item SIGSEGV
|
|
@item SIGTERM
|
|
POSIX signal numbers.
|
|
|
|
@item kill(pid, sig)
|
|
Send the signal @code{sig} to the process @code{pid}.
|
|
|
|
@item exec(args[, options])
|
|
Execute a process with the arguments @code{args}. @code{options} is an
|
|
object containing optional parameters:
|
|
|
|
@table @code
|
|
@item block
|
|
Boolean (default = true). If true, wait until the process is
|
|
terminated. In this case, @code{exec} return the exit code if positive
|
|
or the negated signal number if the process was interrupted by a
|
|
signal. If false, do not block and return the process id of the child.
|
|
|
|
@item usePath
|
|
Boolean (default = true). If true, the file is searched in the
|
|
@code{PATH} environment variable.
|
|
|
|
@item file
|
|
String (default = @code{args[0]}). Set the file to be executed.
|
|
|
|
@item cwd
|
|
String. If present, set the working directory of the new process.
|
|
|
|
@item stdin
|
|
@item stdout
|
|
@item stderr
|
|
If present, set the handle in the child for stdin, stdout or stderr.
|
|
|
|
@item env
|
|
Object. If present, set the process environment from the object
|
|
key-value pairs. Otherwise use the same environment as the current
|
|
process.
|
|
|
|
@item uid
|
|
Integer. If present, the process uid with @code{setuid}.
|
|
|
|
@item gid
|
|
Integer. If present, the process gid with @code{setgid}.
|
|
|
|
@end table
|
|
|
|
@item getpid()
|
|
Return the current process ID.
|
|
|
|
@item waitpid(pid, options)
|
|
@code{waitpid} Unix system call. Return the array @code{[ret,
|
|
status]}. @code{ret} contains @code{-errno} in case of error.
|
|
|
|
@item WNOHANG
|
|
Constant for the @code{options} argument of @code{waitpid}.
|
|
|
|
@item dup(fd)
|
|
@code{dup} Unix system call.
|
|
|
|
@item dup2(oldfd, newfd)
|
|
@code{dup2} Unix system call.
|
|
|
|
@item pipe()
|
|
@code{pipe} Unix system call. Return two handles as @code{[read_fd,
|
|
write_fd]} or null in case of error.
|
|
|
|
@item sleep(delay_ms)
|
|
Sleep during @code{delay_ms} milliseconds.
|
|
|
|
@item sleepAsync(delay_ms)
|
|
Asynchronouse sleep during @code{delay_ms} milliseconds. Returns a promise. Example:
|
|
@example
|
|
await os.sleepAsync(500);
|
|
@end example
|
|
|
|
@item now()
|
|
Return a timestamp in milliseconds with more precision than
|
|
@code{Date.now()}. The time origin is unspecified and is normally not
|
|
impacted by system clock adjustments.
|
|
|
|
@item setTimeout(func, delay)
|
|
Call the function @code{func} after @code{delay} ms. Return a handle
|
|
to the timer.
|
|
|
|
@item clearTimeout(handle)
|
|
Cancel a timer.
|
|
|
|
@item platform
|
|
Return a string representing the platform: @code{"linux"}, @code{"darwin"},
|
|
@code{"win32"} or @code{"js"}.
|
|
|
|
@item Worker(module_filename)
|
|
Constructor to create a new thread (worker) with an API close to the
|
|
@code{WebWorkers}. @code{module_filename} is a string specifying the
|
|
module filename which is executed in the newly created thread. As for
|
|
dynamically imported module, it is relative to the current script or
|
|
module path. Threads normally don't share any data and communicate
|
|
between each other with messages. Nested workers are not supported. An
|
|
example is available in @file{tests/test_worker.js}.
|
|
|
|
The worker class has the following static properties:
|
|
|
|
@table @code
|
|
@item parent
|
|
In the created worker, @code{Worker.parent} represents the parent
|
|
worker and is used to send or receive messages.
|
|
@end table
|
|
|
|
The worker instances have the following properties:
|
|
|
|
@table @code
|
|
@item postMessage(msg)
|
|
|
|
Send a message to the corresponding worker. @code{msg} is cloned in
|
|
the destination worker using an algorithm similar to the @code{HTML}
|
|
structured clone algorithm. @code{SharedArrayBuffer} are shared
|
|
between workers.
|
|
|
|
Current limitations: @code{Map} and @code{Set} are not supported
|
|
yet.
|
|
|
|
@item onmessage
|
|
|
|
Getter and setter. Set a function which is called each time a
|
|
message is received. The function is called with a single
|
|
argument. It is an object with a @code{data} property containing the
|
|
received message. The thread is not terminated if there is at least
|
|
one non @code{null} @code{onmessage} handler.
|
|
|
|
@end table
|
|
|
|
@end table
|
|
|
|
@section QuickJS C API
|
|
|
|
The C API was designed to be simple and efficient. The C API is
|
|
defined in the header @code{quickjs.h}.
|
|
|
|
@subsection Runtime and contexts
|
|
|
|
@code{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.
|
|
|
|
@code{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.
|
|
|
|
@subsection JSValue
|
|
|
|
@code{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 (@code{JS_DupValue()}, increment the reference
|
|
count) or free (@code{JS_FreeValue()}, decrement the reference count)
|
|
JSValues.
|
|
|
|
@subsection C functions
|
|
|
|
C functions can be created with
|
|
@code{JS_NewCFunction()}. @code{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 @code{JSValue}s as parameters
|
|
(so they don't need to free them) and return a newly allocated (=live)
|
|
@code{JSValue}.
|
|
|
|
@subsection Exceptions
|
|
|
|
Exceptions: most C functions can return a Javascript exception. It
|
|
must be explicitly tested and handled by the C code. The specific
|
|
@code{JSValue} @code{JS_EXCEPTION} indicates that an exception
|
|
occurred. The actual exception object is stored in the
|
|
@code{JSContext} and can be retrieved with @code{JS_GetException()}.
|
|
|
|
@subsection Script evaluation
|
|
|
|
Use @code{JS_Eval()} to evaluate a script or module source.
|
|
|
|
If the script or module was compiled to bytecode with @code{qjsc}, it
|
|
can be evaluated by calling @code{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 @code{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. That's why there is no option to output the bytecode to a
|
|
binary file in @code{qjsc}.
|
|
|
|
@subsection 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 (@code{JSClassID}) of
|
|
the object. Hence the first step is to register a new class ID and JS
|
|
class (@code{JS_NewClassID()}, @code{JS_NewClass()}). Then you can
|
|
create objects of this class with @code{JS_NewObjectClass()} and get or
|
|
set the C opaque point with
|
|
@code{JS_GetOpaque()}/@code{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 @code{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 globally allocated (i.e. for all runtimes). The
|
|
JSClass are allocated per @code{JSRuntime}. @code{JS_SetClassProto()}
|
|
is used to define a prototype for a given class in a given
|
|
JSContext. @code{JS_NewObjectClass()} sets this prototype in the
|
|
created object.
|
|
|
|
Examples are available in @file{quickjs-libc.c}.
|
|
|
|
@subsection C Modules
|
|
|
|
Native ES6 modules are supported and can be dynamically or statically
|
|
linked. Look at the @file{test_bjson} and @file{bjson.so}
|
|
examples. The standard library @file{quickjs-libc.c} is also a good example
|
|
of a native module.
|
|
|
|
@subsection Memory handling
|
|
|
|
Use @code{JS_SetMemoryLimit()} to set a global memory allocation limit
|
|
to a given JSRuntime.
|
|
|
|
Custom memory allocation functions can be provided with
|
|
@code{JS_NewRuntime2()}.
|
|
|
|
The maximum system stack size can be set with @code{JS_SetMaxStackSize()}.
|
|
|
|
@subsection Execution timeout and interrupts
|
|
|
|
Use @code{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
|
|
@code{Ctrl-C} handler.
|
|
|
|
@chapter Internals
|
|
|
|
@section 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 @code{eval} in strict mode is optimized.
|
|
|
|
@section Executable generation
|
|
|
|
@subsection @code{qjsc} compiler
|
|
|
|
The @code{qjsc} compiler generates C sources from Javascript files. By
|
|
default the C sources are compiled with the system compiler
|
|
(@code{gcc} or @code{clang}).
|
|
|
|
The generated C source contains the bytecode of the compiled functions
|
|
or modules. If a full complete executable is needed, it also
|
|
contains a @code{main()} function with the necessary C code to initialize the
|
|
Javascript engine and to load and execute the compiled functions and
|
|
modules.
|
|
|
|
Javascript code can be mixed with C modules.
|
|
|
|
In order to have smaller executables, specific Javascript features can
|
|
be disabled, in particular @code{eval} or the regular expressions. The
|
|
code removal relies on the Link Time Optimization of the system
|
|
compiler.
|
|
|
|
@subsection Binary JSON
|
|
|
|
@code{qjsc} works by compiling scripts or modules and then serializing
|
|
them to a binary format. A subset of this format (without functions or
|
|
modules) can be used as binary JSON. The example @file{test_bjson.js}
|
|
shows how to use it.
|
|
|
|
Warning: the binary JSON format may change without notice, so it
|
|
should not be used to store persistent data. The @file{test_bjson.js}
|
|
example is only used to test the binary object format functions.
|
|
|
|
@section Runtime
|
|
|
|
@subsection 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.
|
|
|
|
@subsection 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.
|
|
|
|
@subsection 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 @math{0} to @math{2^{31}-1}.
|
|
|
|
@subsection 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.
|
|
|
|
@subsection 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.
|
|
|
|
@subsection 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.
|
|
|
|
@subsection Function call
|
|
|
|
The engine is optimized so that function calls are fast. The system
|
|
stack holds the Javascript parameters and local variables.
|
|
|
|
@section RegExp
|
|
|
|
A specific regular expression engine was developed. It is both small
|
|
and efficient and supports all the ES2024 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.
|
|
|
|
The full regexp library weights about 15 KiB (x86 code), excluding the
|
|
Unicode library.
|
|
|
|
@section 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).
|
|
|
|
@section BigInt
|
|
|
|
BigInts are represented using binary two's complement notation. An
|
|
additional short bigint value is used to optimize the performance on
|
|
small BigInt values.
|
|
|
|
@chapter License
|
|
|
|
QuickJS is released under the MIT license.
|
|
|
|
Unless otherwise specified, the QuickJS sources are copyright Fabrice
|
|
Bellard and Charlie Gordon.
|
|
|
|
@bye
|