diff --git a/README.md b/README.md
new file mode 100644
index 00000000..2b79fe39
--- /dev/null
+++ b/README.md
@@ -0,0 +1,80 @@
+# What is JetStream?
+
+JetStream 3 is a JavaScript and WebAssembly benchmark suite.
+For more information see the index and in-depth pages of the deployed benchmark.
+
+A preview of the current main branch is available at [https://webkit-jetstream-preview.netlify.app/](https://webkit-jetstream-preview.netlify.app/).
+
+
+
+## Open Governance
+
+See [Governance.md](Governance.md) for more information.
+
+## Getting Started, Setup Instructions
+
+- Install Node.js and (optionally) [jsvu](https://github.com/GoogleChromeLabs/jsvu) for conveniently getting recent builds of engine shells.
+- `npm install` the necessary dependencies.
+- `npm run server` for starting a local development server, then browse to http://localhost:8010.
+- `npm run test:shell` for running the benchmark in engine shells, or alternatively running directly, e.g., via `jsc cli.js`.
+
+See [package.json](package.json) and [.github/workflows/test.yml](.github/workflows/test.yml) for more details and available commands.
+
+### Shell Runner
+
+For the shell runner, see the available options by passing `--help` to `cli.js`. (Note that this requires `--` for JavaScriptCore and V8 to separate VM arguments from script arguments.):
+
+```
+$ v8 cli.js -- --help
+JetStream Driver Help
+
+Options:
+ --help Print this help message.
+ --iteration-count Set the default iteration count.
+...
+
+Available tags:
+ all
+...
+
+Available tests:
+ 8bitbench-wasm
+...
+```
+
+### Browser Runner
+
+The browser version also supports passing parameters as URL query parameters, e.g., pass the `test` parameter (aliases are `tests` or `testList`) with a comma-separated list to run only specific workloads: [https://webkit-jetstream-preview.netlify.app/?test=8bitbench-wasm,web-ssr](https://webkit-jetstream-preview.netlify.app/?test=8bitbench-wasm,web-ssr).
+See [utils/params.js](utils/params.js) and [JetStreamDriver.js](JetStreamDriver.js) for more details.
+
+## Technical Details
+
+The main file of the benchmark harness is `JetStreamDriver.js`, which lists the individual workloads and their parameters, implements measurement and scoring, etc.
+The individual workloads are in subdirectories.
+
+### Preloading and Compression
+
+The JetStream driver (both in the browser and shell runners) _preloads_ some large assets and source files.
+That is, it reads those files from disk or fetches them from the network before running the workloads.
+This is in order to exclude network latency and disk I/O from the benchmark measurements and reduce variance. Otherwise, OS scheduling or CPU frequency scaling may affect the measurement.
+
+Some workloads also utilize large assets (e.g., ML models, heavy JavaScript bundles in the order of 10s of MBs).
+In order to limit the repository size and network transfers, such large assets are stored as compressed .z files.
+Preloading handles the decompression of these assets (using `DecompressionStream` or a Wasm-based zlib polyfill) upfront so that decompression overhead does not affect the benchmark score.
+
+Both preloading and compression can be disabled, e.g., to inspect raw files or because it sometimes helps with debugging (e.g., proper URLs instead of Blobs for resources).
+
+- Compression: Run `npm run decompress` to decompress all .z files before running the benchmark.
+- No prefetching for shells: Pass the `--no-prefetch` flag, e.g., `jsc cli.js -- --no-prefetch`.
+- No prefetching in browsers: Append the query parameter `?prefetchResources=false` to the URL.
+
+See `JetStreamDriver.js` and `utils/compress.mjs` for more details.
+
+### Score Calculation
+
+Scores in JetStream are dimensionless floats, where a higher score is better.
+When scores are aggregated (e.g., multiple sub-scores for each workload, or to determine the total score of the full benchmark suite), we use the [geometric mean](https://en.wikipedia.org/wiki/Geometric_mean).
+The geometric mean ensures that a multiplicative improvement of any individual score has the same effect on the aggregated score, regardless of the absolute value of the individual score.
+For example, an improvement by 5% of the sub score of benchmark A has the same effect on the total score as an improvement by 5% of the sub score of benchmark B.
+
+See the [in-depth.html](https://webkit-jetstream-preview.netlify.app/in-depth.html) and `JetStreamDriver.js` for more details.
\ No newline at end of file
diff --git a/in-depth.html b/in-depth.html
index 06e99bbe..543eb2e2 100644
--- a/in-depth.html
+++ b/in-depth.html
@@ -29,7 +29,7 @@
JetStream 3 In-Depth Analysis
-
+
@@ -43,7 +43,7 @@
In-Depth Analysis
- JetStream 3 combines together a variety of JavaScript and Web Assembly benchmarks, covering a variety of
+ JetStream 3 combines together a variety of JavaScript and WebAssembly benchmarks, covering a variety of
advanced workloads and programming techniques, and reports a single score that
balances them using a geometric mean.
@@ -56,9 +56,11 @@
In-Depth Analysis
- Each benchmark in JetStream 3 computes its own individual score. JetStream 3 weighs each
- benchmark equally, taking the geometric mean over each individual benchmark's score to compute
- the overall JetStream 3 score.
+ Each benchmark in JetStream 3 computes its own individual score.
+ Scores in JetStream are dimensionless floats, where a higher score is better.
+ JetStream weighs each benchmark equally, taking the geometric mean over each individual benchmark's score to compute the overall JetStream 3 score.
+ The geometric mean ensures that a multiplicative improvement of any individual score has the same effect on the aggregated score, regardless of the absolute value of the individual score.
+ For example, an improvement by 5% of the sub score of benchmark A has the same effect on the total score as an improvement by 5% of the sub score of benchmark B.
@@ -70,7 +72,7 @@
In-Depth Analysis
- For most of the JavaScript benchmarks in JetStream 3, individual scores
+ For most of the JavaScript and WebAssembly benchmarks in JetStream 3, individual scores
equally weigh startup performance, worst case performance, and average case
performance. These three metrics are crucial to running performant JavaScript
in the browser. Fast startup times lead browsers to loading pages more quickly. Good
@@ -79,11 +81,10 @@
In-Depth Analysis
- For JetStream 3's Web Assembly benchmarks, individual scores equally weigh startup time and
- total execution time. An important component of JetStream 1 were the asm.js subset of benchmarks. With the release
- of Web Assembly, the importance of asm.js has lessened since many users of asm.js are
- now using Web Assembly. JetStream 3 has converted many of the asm.js benchmarks from
- JetStream 1 into Web Assembly.
+ An important component of JetStream 1 were the asm.js subset of benchmarks. With the release
+ of WebAssembly, the importance of asm.js has lessened since many users of asm.js are
+ now using WebAssembly. JetStream 3 has converted many of the asm.js benchmarks from
+ JetStream 1 into WebAssembly.
@@ -106,14 +107,13 @@
In-Depth Analysis
JetStream 3 includes parts of these benchmark suites that came before it: SunSpider,
Octane 2, JetStream 1,
- ARES-6, and Web Tooling Benchmark.
- JetStream 3 also includes new benchmarks inspired by Kraken.
- JetStream 3 also includes a new set of benchmarks that measure the performance of Web Assembly, Web Workers,
+ ARES-6, Web Tooling Benchmark, and benchmarks inspired by Kraken.
+ JetStream 3 also includes a new set of benchmarks that measure the performance of WebAssembly, Web Workers,
Promises, async iteration, unicode regular expressions, and JavaScript parsing.
- JetStream 3 runs the same benchmarks as JetStream 3, but updates the benchmark driver to
+ JetStream 3 includes several benchmarks from earlier JetStream versions, but updates the benchmark driver to
improve score stability. This is achieved by pre-fetching network resources prior to running
the benchmarks. This can reduce perturbations on the measurement of JavaScript execution
time due to second order effects of pause times induced by network latency.
@@ -168,7 +168,7 @@
tsf-wasm
Runs Filip Pizlo's — of the WebKit team — implementation of a Typed Stream Format
- in Web Assembly. The original code is compiled from C to Web Assembly using Emscripten.
+ in WebAssembly. The original code is compiled from C to WebAssembly using Emscripten.
Source code: TSF
@@ -179,7 +179,7 @@
argon2-wasm
- Tests Argon2, a password-hashing function (the winner of Password Hashing Competition), in Web Assembly. This is test is based on argon2-browser library. Source code: ARGON2.
+ Tests Argon2, a password-hashing function (the winner of Password Hashing Competition), in WebAssembly. This is test is based on argon2-browser library. Source code: ARGON2.
tagcloud-SP
@@ -246,8 +246,8 @@
richards-wasm
Martin Richard's system language
- benchmark compiled to a hybrid of Web Assembly and JavaScript. It stresses how quickly
- JavaScript can call into Web Assembly code.
+ benchmark compiled to a hybrid of WebAssembly and JavaScript. It stresses how quickly
+ JavaScript can call into WebAssembly code.
Source code: richards.c, richards.js
@@ -302,7 +302,7 @@
quicksort-wasm
- Quicksort benchmark, compiled to Web Assembly with Emscripten.
+ Quicksort benchmark, compiled to WebAssembly with Emscripten.
The original C version of this benchmark was previously published in the LLVM test suite.
Source code: quicksort.c, quicksort.js
@@ -418,8 +418,8 @@
HashSet-wasm
- A Web Assembly benchmark replaying a set of hash table operations performed in WebKit when loading
- a web page. This benchmark was compiled from C++ to Web Assembly using Emscripten.
+ A WebAssembly benchmark replaying a set of hash table operations performed in WebKit when loading
+ a web page. This benchmark was compiled from C++ to WebAssembly using Emscripten.
Source code: HashSet.cpp, HashSet.js
@@ -434,7 +434,7 @@
gcc-loops-wasm
- Example loops used to tune the GCC and LLVM vectorizers, compiled to Web Assembly with
+ Example loops used to tune the GCC and LLVM vectorizers, compiled to WebAssembly with
Emscripten. The original C++ version of this benchmark was previously published in the LLVM test suite.
Source code: gcc-loops.cpp, gcc-loops.js
JetStream 3 is a JavaScript and WebAssembly benchmark suite focused on the most advanced web applications. It rewards browsers that start up quickly, execute code quickly, and run smoothly. For more information, read the in-depth analysis. Bigger scores are better.
+
JetStream 3 is a JavaScript and WebAssembly benchmark suite focused on the most advanced web applications. It rewards browsers that start up quickly, execute code quickly, and run smoothly. For more information, read the in-depth analysis. Bigger scores are better.
Non-standard Parameters
diff --git a/package.json b/package.json
index 599d47c7..5ce7a253 100644
--- a/package.json
+++ b/package.json
@@ -18,7 +18,7 @@
"prepare": "node utils/version-check.mjs",
"server": "npm run prepare --silent && node tests/server.mjs",
"compress": "npm run prepare --silent && node utils/compress.mjs",
- "decompress": "npm run prepare --silent && node utils/compress.mjs --decompress --keep ",
+ "decompress": "npm run prepare --silent && node utils/compress.mjs --decompress --keep",
"lint:check": "npm run prepare --silent && eslint **/*.{js,mjs,jsx,ts,tsx}",
"pretty:check": "npm run prepare --silent && prettier --check ./",
"pretty:format": "npm run prepare --silent && prettier --write ./",
diff --git a/resources/screenshot.png b/resources/screenshot.png
new file mode 100644
index 00000000..57078f8c
Binary files /dev/null and b/resources/screenshot.png differ
+
+## Open Governance
+
+See [Governance.md](Governance.md) for more information.
+
+## Getting Started, Setup Instructions
+
+- Install Node.js and (optionally) [jsvu](https://github.com/GoogleChromeLabs/jsvu) for conveniently getting recent builds of engine shells.
+- `npm install` the necessary dependencies.
+- `npm run server` for starting a local development server, then browse to http://localhost:8010.
+- `npm run test:shell` for running the benchmark in engine shells, or alternatively running directly, e.g., via `jsc cli.js`.
+
+See [package.json](package.json) and [.github/workflows/test.yml](.github/workflows/test.yml) for more details and available commands.
+
+### Shell Runner
+
+For the shell runner, see the available options by passing `--help` to `cli.js`. (Note that this requires `--` for JavaScriptCore and V8 to separate VM arguments from script arguments.):
+
+```
+$ v8 cli.js -- --help
+JetStream Driver Help
+
+Options:
+ --help Print this help message.
+ --iteration-count Set the default iteration count.
+...
+
+Available tags:
+ all
+...
+
+Available tests:
+ 8bitbench-wasm
+...
+```
+
+### Browser Runner
+
+The browser version also supports passing parameters as URL query parameters, e.g., pass the `test` parameter (aliases are `tests` or `testList`) with a comma-separated list to run only specific workloads: [https://webkit-jetstream-preview.netlify.app/?test=8bitbench-wasm,web-ssr](https://webkit-jetstream-preview.netlify.app/?test=8bitbench-wasm,web-ssr).
+See [utils/params.js](utils/params.js) and [JetStreamDriver.js](JetStreamDriver.js) for more details.
+
+## Technical Details
+
+The main file of the benchmark harness is `JetStreamDriver.js`, which lists the individual workloads and their parameters, implements measurement and scoring, etc.
+The individual workloads are in subdirectories.
+
+### Preloading and Compression
+
+The JetStream driver (both in the browser and shell runners) _preloads_ some large assets and source files.
+That is, it reads those files from disk or fetches them from the network before running the workloads.
+This is in order to exclude network latency and disk I/O from the benchmark measurements and reduce variance. Otherwise, OS scheduling or CPU frequency scaling may affect the measurement.
+
+Some workloads also utilize large assets (e.g., ML models, heavy JavaScript bundles in the order of 10s of MBs).
+In order to limit the repository size and network transfers, such large assets are stored as compressed .z files.
+Preloading handles the decompression of these assets (using `DecompressionStream` or a Wasm-based zlib polyfill) upfront so that decompression overhead does not affect the benchmark score.
+
+Both preloading and compression can be disabled, e.g., to inspect raw files or because it sometimes helps with debugging (e.g., proper URLs instead of Blobs for resources).
+
+- Compression: Run `npm run decompress` to decompress all .z files before running the benchmark.
+- No prefetching for shells: Pass the `--no-prefetch` flag, e.g., `jsc cli.js -- --no-prefetch`.
+- No prefetching in browsers: Append the query parameter `?prefetchResources=false` to the URL.
+
+See `JetStreamDriver.js` and `utils/compress.mjs` for more details.
+
+### Score Calculation
+
+Scores in JetStream are dimensionless floats, where a higher score is better.
+When scores are aggregated (e.g., multiple sub-scores for each workload, or to determine the total score of the full benchmark suite), we use the [geometric mean](https://en.wikipedia.org/wiki/Geometric_mean).
+The geometric mean ensures that a multiplicative improvement of any individual score has the same effect on the aggregated score, regardless of the absolute value of the individual score.
+For example, an improvement by 5% of the sub score of benchmark A has the same effect on the total score as an improvement by 5% of the sub score of benchmark B.
+
+See the [in-depth.html](https://webkit-jetstream-preview.netlify.app/in-depth.html) and `JetStreamDriver.js` for more details.
\ No newline at end of file
diff --git a/in-depth.html b/in-depth.html
index 06e99bbe..543eb2e2 100644
--- a/in-depth.html
+++ b/in-depth.html
@@ -29,7 +29,7 @@