mirror of
https://github.com/DoneJS-Runtime/quickjs-done-nextgen.git
synced 2025-01-09 17:43:15 +00:00
130 lines
4.9 KiB
Markdown
130 lines
4.9 KiB
Markdown
---
|
|
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', 'os' and 'bjson' available to script
|
|
-T --trace trace memory allocation
|
|
-d --dump dump the memory usage stats
|
|
-D --dump-flags flags for dumping debug data (see DUMP_* defines)
|
|
-c --compile FILE compile the given JS file as a standalone executable
|
|
-o --out FILE output file for standalone executables
|
|
--exe select the executable to use as the base, defaults to the current one
|
|
--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 */
|
|
```
|
|
|
|
### Creating standalone executables
|
|
|
|
With the `qjs` CLI it's possible to create standalone executables that will bundle the given JavaScript file
|
|
alongside the binary.
|
|
|
|
```
|
|
$ qjs -c app.js -o app --exe qjs
|
|
```
|
|
|
|
The resulting `app` binary will have the same runtime dependencies as the `qjs` binary. This is acomplished
|
|
by compiling the target JavaScript file to bytecode and adding it a copy of the executable, with a little
|
|
trailer to help locate it. `--exe` expects the absolute path to `qjs`, e.g., `~/bin/qjs` or `$HOME/bin/qjs`.
|
|
|
|
Rather than using the current executable, it's possible to use the `--exe` switch to create standalone
|
|
executables for other platforms.
|
|
|
|
No JavaScript bundling is performed, the specified JS file cannot depend on other files. A bundler such
|
|
as `esbuild` can be used to generate an app bundle which can then be turned into the executable.
|
|
|
|
```
|
|
npx esbuild my-app/index.js \
|
|
--bundle \
|
|
--outfile=app.js \
|
|
--external:qjs:* \
|
|
--minify \
|
|
--target=es2023 \
|
|
--platform=neutral \
|
|
--format=esm \
|
|
--main-fields=main,module
|
|
```
|
|
|
|
## `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)
|
|
```
|
|
|
|
Here is an example on how to create a standalone executable that embeds QuickJS
|
|
and the `examples/hello.js` JavaScript file:
|
|
|
|
```bash
|
|
# Make sure you are in the QuickJS source directory.
|
|
$ cc hello.c cutils.c libbf.c libregexp.c libunicode.c quickjs.c quickjs-libc.c -I. -o hello
|
|
```
|
|
|
|
The resulting binary `hello` will be in the current directory.
|
|
|
|
```bash
|
|
$ ./hello
|
|
Hello World
|
|
```
|
|
|
|
:::note
|
|
See the ["Creating standalone executables"](#creating-standalone-executables) section for a simpler way.
|
|
:::
|