README.md
1[![Rust][Rust Badge]][Rust CI Link]
2[![NotImplemented Counter][NotImplemented Badge]][NotImplemented Search]
3[![Fuzzbug days since][Fuzzbug Days Badge]][Fuzzbugs]
4[![Fuzzbug open][Fuzzbug Open Badge]][Open Fuzzbugs]
5
6
7# jsparagus - A JavaScript parser written in Rust
8
9jsparagus is intended to replace the JavaScript parser in Firefox.
10
11Current status:
12
13* jsparagus is not on crates.io yet. The AST design is not stable
14 enough. We do have a build of the JS shell that includes jsparagus
15 as an option (falling back on C++ for features jsparagus doesn't
16 support). See
17 [mozilla-spidermonkey/rust-frontend](https://github.com/mozilla-spidermonkey/rust-frontend).
18
19* It can parse a lot of JS scripts, and will eventually be able to parse everything.
20 See the current limitations below, or our GitHub issues.
21
22* Our immediate goal is to [support parsing everything in Mozilla's JS
23 test suite and the features in test262 that Firefox already
24 supports](https://github.com/mozilla-spidermonkey/jsparagus/milestone/1).
25
26Join us on Discord: https://discord.gg/tUFFk9Y
27
28
29## Building jsparagus
30
31To build the parser by itself:
32
33```sh
34make init
35make all
36```
37
38The build takes about 3 minutes to run on my laptop.
39
40When it's done, you can:
41
42* Run `make check` to make sure things are working.
43
44* `cd crates/driver && cargo run -- -D` to try out the JS parser and bytecode emitter.
45
46
47## Building and running SpiderMonkey with jsparagus
48
49* To build SpiderMonkey with jsparagus, `configure` with `--enable-smoosh`.
50
51 This builds with a specific known-good revision of jsparagus.
52
53* Building SpiderMonkey with your own local jsparagus repo, for
54 development, takes more work; see [the jsparagus + SpiderMonkey wiki
55 page](https://github.com/mozilla-spidermonkey/jsparagus/wiki/SpiderMonkey)
56 for details.
57
58**NOTE: Even after building with jsparagus, you must run the shell with
59`--smoosh`** to enable jsparagus at run time.
60
61
62
63## Benchmarking
64
65### Fine-grain Benchmarks
66
67Fine-grain benchmarks are used to detect regression by focusing on each part of
68the parser at one time, exercising only this one part. The benchmarks are not
69meant to represent any real code sample, but to focus on executing specific
70functions of the parser.
71
72To run this parser, you should execute the following command at the root of the
73repository:
74
75```sh
76cd crates/parser
77cargo bench
78```
79
80### Real-world JavaScript
81
82Real world benchmarks are used to track the overall evolution of performance over
83time. The benchmarks are meant to represent realistic production use cases.
84
85To benchmark the AST generation, we use SpiderMonkey integration to execute the
86parser and compare it against SpiderMonkey's default parser. Therefore, to run
87this benchmark, we have to first compile SpiderMonkey, then execute SpiderMonkey
88shell on the benchmark. (The following instructions assume that `~` is the
89directory where all projects are checked out)
90
91* Generate Parse Tables:
92
93 ```sh
94 cd ~/jsparagus/
95 make init
96 make all
97 ```
98
99* Compile an optimized version of [SpiderMonkey's JavaScript shell](https://github.com/mozilla/gecko-dev):
100
101 ```sh
102 cd ~/mozilla/js/src/
103 # set the jsparagus' path to the abosulte path to ~/jsparagus.
104 $EDITOR frontend/smoosh/Cargo.toml
105 ../../mach vendor rust
106 # Create a build directory
107 mkdir obj.opt
108 cd obj.opt
109 # Build SpiderMonkey
110 ../configure --enable-nspr-build --enable-smoosh --enable-debug-symbols=-ggdb3 --disable-debug --enable-optimize --enable-release --disable-tests
111 make
112 ```
113
114* Execute the [real-js-samples](https://github.com/nbp/real-js-samples/) benchmark:
115
116 ```sh
117 cd ~/real-js-samples/
118 ~/mozilla/js/src/obj.opt/dist/bin/js ./20190416.js
119 ```
120
121This should return the overall time taken to parse all the Script once, in the
122cases where there is no error. The goal is to minimize the number of
123nano-seconds per bytes.
124
125
126## Limitations
127
128It's *all* limitations, but I'll try to list the ones that are relevant
129to parsing JS.
130
131* Features that are not implemented in the parser yet include `let`,
132 `import` and `export`, `async` functions, `yield` expressions, the
133 use of `await` and `yield` as identifiers, template strings,
134 `BigInt`, Unicode escape sequences that evaluate to surrogate code
135 points, legacy octal integer literals, legacy octal escape
136 sequences, some RegExp flags, strict mode code, `__proto__` in
137 object literals, some features of destructuring assignment.
138
139 Many more features are not yet supported in the bytecode emitter.
140
141* Error messages are poor.
142
143We're currently working on parser performance and completeness, as well
144as the bytecode emitter and further integration with SpiderMonkey.
145
146
147[Rust Badge]: https://github.com/mozilla-spidermonkey/jsparagus/workflows/Rust/badge.svg
148[Rust CI Link]: https://github.com/mozilla-spidermonkey/jsparagus/actions?query=branch%3Amaster
149[NotImplemented Badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmozilla-spidermonkey%2Fjsparagus%2Fci_results%2F.metrics%2Fbadges%2Fnot-implemented.json
150[NotImplemented Search]: https://github.com/mozilla-spidermonkey/jsparagus/search?q=notimplemented&unscoped_q=notimplemented
151[Fuzzbug days Badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmozilla-spidermonkey%2Fjsparagus%2Fci_results%2F.metrics%2Fbadges%2Fsince-last-fuzzbug.json
152[Fuzzbug Open Badge]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmozilla-spidermonkey%2Fjsparagus%2Fci_results%2F.metrics%2Fbadges%2Fopen-fuzzbug.json
153[Fuzzbugs]: https://github.com/mozilla-spidermonkey/jsparagus/issues?utf8=%E2%9C%93&q=label%3AlibFuzzer+
154[Open Fuzzbugs]: https://github.com/mozilla-spidermonkey/jsparagus/labels/libFuzzer
155
