From e18c7667a5392d91a5340ed7687c3ac0bf34d1c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Wed, 13 Nov 2024 22:55:40 +0100 Subject: [PATCH 1/5] Document how to create standalone executables --- docs/docs/cli.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/docs/cli.md b/docs/docs/cli.md index 1b895dc7..fff81cba 100644 --- a/docs/docs/cli.md +++ b/docs/docs/cli.md @@ -75,3 +75,22 @@ options are: -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 +We have plans to make this process easier, stay tuned! +::: From 71a7abd355bfd1c550bb30cefa0c4391ad66db08 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Wed, 13 Nov 2024 23:34:46 +0100 Subject: [PATCH 2/5] Tweak intro and document differences with bellard/quickjs --- docs/docs/diff.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++ docs/docs/intro.md | 23 +++------------- 2 files changed, 69 insertions(+), 19 deletions(-) create mode 100644 docs/docs/diff.md diff --git a/docs/docs/diff.md b/docs/docs/diff.md new file mode 100644 index 00000000..6b5c083b --- /dev/null +++ b/docs/docs/diff.md @@ -0,0 +1,65 @@ +# Differences with bellard/quickjs + +This project aims to be a drop-in replacement for those already using QuickJS. +Minimal API changes might be necessary. + +## Community development + +NG is developed in the open, interacting with the wider community and through +these interactions many improvements have already been made, including the incorporation +of patches previously maintained in other forks. + +Each PR is reviewed, iterated on, and merged in GitHub. + +To date, NG has had over 40 distinct contributors and over 400 PRs. + +## Consistent release cadence + +As the project moves forward, a steady cadence of releases has been maintained, with an +average of a new release every 2 months. + +## Testing + +Since its inception testing has been a focus. Each PR is tested in over 50 configurations, +involving different operating systems, build types and sanitizers. + +The `test262` suite is also ran for every change. + +## Cross-platform support + +In order to better support other platforms such as Windows the build system was +changed to use [CMake]. + +In addition, Windows is treated as a first class citizen, with the addition of support +for the MSVC compiler. + +[CMake]: https://cmake.org/ + +## Performance + +While being an interpreter limits the performance in comparison with other engines which +use a JIT, several significant performance improvements have been made: + +- Opcode fusion +- Polymorphic inline caching +- Memory allocation improvements +- Improved parse speeds + +## New ECMAScript APIs + +The main focus of NG is to deliver state-of-the-art JavaScript features. Typically once they +are stable (stage 4) but sometimes even at earlier stages. Here is a non-exhaustive list +of ES features present in NG: + +- Resizable ArrayBuffer +- Float16Array +- WeakRef +- FinalizationRegistry +- Iterator Helpers +- Promise.try +- Error.isError +- Set operations + +Some non-standard but widely used APIs have also been added: + +- V8's `Error.prepareStackTrace` and `Error.stackTraceLimit` diff --git a/docs/docs/intro.md b/docs/docs/intro.md index e29ff7c9..cb63ed5d 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -9,29 +9,18 @@ sidebar_label: Welcome QuickJS is a small and embeddable JavaScript engine. It aims to support the latest [ECMAScript] specification. -This project is a _fork_ of the [original QuickJS project] by Fabrice Bellard, after it went -dormant for several years, with the intent of reigniting its development. +This project is a _fork_ of the [original QuickJS project] by Fabrice Bellard and Charlie Gordon, after it went dormant, with the intent of reigniting its development. -In October 2023 [@bnoordhuis] and [@saghul] decided to fork the original project with -the aim of reigniting it. They reached out to the original authors ([@bellard] and [@chqrlie]) -about their intentions. - -As of December 2023 the initial goal was somewhat accomplished. [@bellard] resumed working on -the project and both parties have been pulling patches from each other since. - -As of early 2024 both projects agree the proper path forward involves merging both projects -and combining the efforts. While that may take a while, since both projects diverged in certain -areas, there is willingness to go in this direction from both sides. - -This fork is focused on (but not limited to): +This project is focused on (but not limited to): - Community development - Testing - Cross-platform support - ES features -:::note +You can check the differences with the original project [here.](./diff) +:::note This site is under construction, the entire API is not yet documented. ::: @@ -42,7 +31,3 @@ for installing it from prebuilt binaries. [ECMAScript]: https://tc39.es/ecma262/ [original QuickJS project]: https://bellard.org/quickjs -[@bellard]: https://github.com/bellard -[@bnoordhuis]: https://github.com/bnoordhuis -[@chqrlie]: https://github.com/chqrlie -[@saghul]: https://github.com/saghul From 50f1447b01659799ca4eed316fa9a51133d123b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Wed, 13 Nov 2024 23:35:12 +0100 Subject: [PATCH 3/5] Add list of projects using NG --- docs/docs/projects.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/docs/projects.md diff --git a/docs/docs/projects.md b/docs/docs/projects.md new file mode 100644 index 00000000..ff481c79 --- /dev/null +++ b/docs/docs/projects.md @@ -0,0 +1,24 @@ +# Projects using NG + +Here is a list of projects currently using, supporting or migrating to QuickJS-NG. +If you want yours to be listed here, please open a PR! + +## [txiki.js](https://github.com/saghul/txiki.js) + +A tiny JavaScript runtime. + +## [radare2](https://github.com/radareorg/radare2) + +Reverse engineering framework. + +## [rquickjs](https://github.com/DelSkayn/rquickjs) + +High level Rust bindings. + +## [llrt](https://github.com/awslabs/llrt) + +Lightweight JS runtime for serverless applications. + +## [nx.js](https://github.com/TooTallNate/nx.js) + +JavaScript runtime for Nintendo Switch homebrew applications. From 57b768affc279cb5cb9db79078e5496e1ff88429 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Wed, 13 Nov 2024 23:36:50 +0100 Subject: [PATCH 4/5] Add cloning instructions to building section --- docs/docs/building.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/docs/building.md b/docs/docs/building.md index deaa20df..3737a31a 100644 --- a/docs/docs/building.md +++ b/docs/docs/building.md @@ -10,6 +10,13 @@ QuickJS uses [CMake] as its main build system, with an additional helper [Makefi Windows users will need to run the CMake commands manually. ::: +## Getting the source + +```bash +git clone https://github.com/quickjs-ng/quickjs.git +cd quickjs +``` + ## Compiling everything ```bash From cf54f85924838f1af5fdc11207400759d7fa09ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sa=C3=BAl=20Ibarra=20Corretg=C3=A9?= Date: Wed, 13 Nov 2024 23:41:38 +0100 Subject: [PATCH 5/5] Update README --- README.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 99312e80..4c483e99 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,23 @@ # ⚡️ QuickJS - A mighty JavaScript engine -Friendly [QuickJS] fork focused on reigniting the project. - ## Overview -In October 2023 [@bnoordhuis] and [@saghul] decided to fork the [QuickJS] project with -the aim of reigniting it. They reached out to the original authors ([@bellard] and [@chqrlie]) -about their intentions. +QuickJS is a small and embeddable JavaScript engine. It aims to support the latest +[ECMAScript] specification. + +This project is a _fork_ of the [original QuickJS project] by Fabrice Bellard and Charlie Gordon, after it went dormant, with the intent of reigniting its development. + +## Getting started + +Head over to the [project website] for instructions on how to get started and more +documentation. -As of December 2023 the initial goal was somewhat accomplished. [@bellard] resumed working on -the project and both parties have been pulling patches from each other since. +## Authors -As of early 2024 both projects agree the proper path forward involves merging both projects -and combining the efforts. While that may take a while, since both projects diverged in certain -areas, there is willingness to go in this direction from both sides. +[@bnoordhuis], [@saghul], and many more [contributors]. -[QuickJS]: https://bellard.org/quickjs -[@bellard]: https://github.com/bellard +[original QuickJS project]: https://bellard.org/quickjs [@bnoordhuis]: https://github.com/bnoordhuis -[@chqrlie]: https://github.com/chqrlie [@saghul]: https://github.com/saghul +[contributors]: https://github.com/quickjs-ng/quickjs/graphs/contributors +[project website]: https://quickjs-ng.github.io/quickjs/