From 254e44f890f77f60cc97a53cdb2085c49813242f Mon Sep 17 00:00:00 2001 From: Patrick Stapfer Date: Thu, 11 Feb 2021 17:48:56 +0100 Subject: [PATCH 01/13] Add all relevant changes from previous 2020 bundle API For reference on the previous work in 2020, refer to #4518 --- CONTRIBUTING.md | 52 +- jscomp/refmt/jsoo_refmt_main.ml | 848 ++++++++++++++++++++++--- jscomp/refmt/jsoo_refmt_main.mli | 1 - jscomp/super_errors/super_location.mli | 5 + 4 files changed, 789 insertions(+), 117 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 850712783a..a0c680a672 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -209,13 +209,17 @@ This is usually the file you want to create to test certain compile behavior wit - Verify the output, check in the `jscomp/test/my_file_test.ml` and `jscomp/test/my_file_test.js` to version control. The checked in `.js` file is essential for verifying regressions later on. - Eventually check in other relevant files changed during the rebuild (depends on your compiler changes). -## Contribute to the BS Playground Bundle +## Contribute to the ReScript Playground Bundle > Note: These instructions are designed for building the 4.06 based version of ReScript (ReScript v6). The "Playground bundle" is the BS compiler compiled to JavaScript, including all necessary dependency files (stdlib / belt etc). It is useful for building tools where you want to compile and execute arbitrary Reason / OCaml in the browser. -The ReScript source code is compiled with a tool called [JSOO (js_of_ocaml)](https://ocsigen.org/js_of_ocaml/3.5.1/manual/overview), which uses OCaml bytecode to compile to JavaScript and is part of the bigger OCaml ecosystem. Before we can compile anything, we need to install the required tools (requires [`opam`](https://opam.ocaml.org/doc/Install.html) to be installed): +The ReScript source code is compiled with a tool called [JSOO (js_of_ocaml)](https://ocsigen.org/js_of_ocaml/3.6.0/manual/overview), which uses OCaml bytecode to compile to JavaScript and is part of the bigger OCaml ecosystem. + +We actually ship a bytecode version of `js_of_ocaml`, so you actually don't need to install any third party dependencies. This is usually for basic usage if you don't care about the compilation speed or a fast feedback loop (e.g. CI). + +For faster compilation times, we recommend to install a proper `jsoo` executable: ```sh # Create the right switch, if not created yet (first install) @@ -225,18 +229,25 @@ opam switch create 4.06.1 opam switch 4.06.1 eval `opam config env` -opam install js_of_ocaml.3.5.1 +opam install js_of_ocaml.3.6.0 +``` + +Additionally, make sure to adapt the `scripts/repl.js` file to use the `js_of_ocaml` binary instead (otherwise you'll continue using the slower bytecode version): + +```diff +- e(`${OCAMLRUN} ${JSOO} compile jsc.byte ${jsooFlag}-o exports.js`); ++ e(`js_of_ocaml compile jsc.byte ${jsooFlag}-o exports.js`); ``` -### Build the Bundle +### Building the Bundle -The entry point of the JSOO bundle is located in `jscomp/main/jsoo_main.ml` and the script for running JSOO can be found in `scripts/repl.js`. A full clean build can be done like this: +The entry point of the JSOO bundle is located in `jscomp/main/jsoo_refmt_main.ml` and the script for running JSOO can be found in `scripts/repl.js`. A full clean build can be done like this: ``` # We create a target directory for storing the bundle / stdlib files mkdir playground && mkdir playground/stdlib -# We build the ReScript source code and also the bytecode for jsoo_main.ml +# We build the ReScript source code and also the bytecode for jsoo_refmt_main.ml node scripts/ninja.js config && node scripts/ninja.js build # Now we run the repl.js script pointing to our playground directory (note how it needs to be relative to the repl.js file) @@ -245,7 +256,7 @@ BS_PLAYGROUND=../playground node scripts/repl.js _Troubleshooting: if ninja build step failed with `Error: cannot find file '+runtime.js'`, make sure `ocamlfind` is installed with `opam install ocamlfind`._ -**You should now find following files:** +After a successful compilation, you will find following files in your project: - `playground/exports.js` -> This is the ReScript compiler, which binds the ReScript API to the `window` object. - `playground/stdlib/*.js` -> All the ReScript runtime files. @@ -255,31 +266,28 @@ You can now use the `exports.js` file either directly by using a `