An (unofficial) ECMAScript Reference Interpreter and Double-debugger.
The minimum system dependencies are:
- OCaml (any working version, correct version will be installed via OPAM)
- OPAM 2.0.2
- Nodejs >=8 (Carbon LTS release) and the corresponding npm
- rsync, for uploading builds to deployment servers
- xdg-open, for shortcut Make targets for opening built pages
- Perl / PHP interpreters, for single-use scripts within the tools directory
- Python, for the runtests distributed test execution tool in tools/runtests
Installation and test with OPAM
opam switch create jsexplain 4.04.2 eval $(opam env) opam pin -yn add JS_Parser "https://github.com/resource-reasoning/JS_Parser.git#v0.1.0" opam install -y JS_Parser opam repository add jsexplain https://github.com/jscert/opam-repository.git#add-pkg-fjs_of_fml opam install -y jsexplain firefox .opam/jsexplain/share/jsexplain/driver.html
If you intend to run the test262 test suite:
To build all default targets:
You can run the tool locally by opening the
driver.html page. (
make open is
a shortcut for this).
To test jsjsref using test262:
Toplevel Make Targets
- Initialisation targets
test_init: Initialises the test262 submodule and any other dependencies required for testing the interpreter.
.merlin: Builds the
.merlinIDE configuration file. (Automatically built by
- Build Targets
all(default): Builds the
generator: Builds the
jsjsref: Builds the jsref interpreter using the ml-to-js generator.
mljsref: Builds the jsref interpreter using the standard OCaml compiler.
- Testing targets
test: Tests the generator and jsjsref.
test_generator: Runs the generator testsuite. (See generator directory for detail.
test_jsjsref: Tests jsjsref against the test262 test suite.
- Documentation targets
doc: Builds jsref documentation using ocamldoc with a custom 'esdocgen' output driver.
esdocgen: Builds the custom ocamldoc output driver.
- Distribution targets
dist: Performs a build of jsjsref and documentation and places all files required for distribution into the
publish: Publishes the
distdirectory to the inria-gforge server (requires authentication).
publish-github: Publishes the
distdirectory to the
gh-pagesbranch. This is executed on successful CI build.
- Browser shortcuts
open: Builds jsjsref and opens the
driver.htmlpage in your browser when done.
opendoc: Builds the jsref documentation and opens the documentation index in your browser when done.
clean: Cleans all built files for the entire project, recursively.
To select subsets of tests to run you can use the
-g flag with the
pattern to grep for in the test name. Each test262 test case's path is
a part of the test name. For example, to select only the interpreter
run test cases for the if statement, you could use:
npx mocha -g 'test/language/statements/if.*interprets'
Latest version of jsjsref & debugger is automatically published at: https://jscert.github.io/jsexplain/branch/master/driver.html
The source code for the interpreter is primarily written in a subset of OCaml with supporting runtime libraries written in both OCaml and JS.
The source code is located in the jsref directory. It can either be built using the standard OCaml compiler (to produce a result we term mljsref), or using a custom OCaml-to-JS compiler which is located in the generator directory (we term the resulting product jsjsref).
Details about the custom compilation are provided in the generator directory.
To simplify presentation of the code, a monadic binder syntax extension is used. This is also described in the generator directory.