Add all relevant changes from previous 2020 bundle API

For reference on the previous work in 2020, refer to #4518

Author: ryyppy

CONTRIBUTING.md

@@ -142,13 +142,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)
@@ -158,18 +162,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)
@@ -178,7 +189,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.
@@ -188,31 +199,28 @@ You can now use the `exports.js` file either directly by using a `<script src="/
 ```
 $ node
 > require("./exports.js");
-undefined
-> let compile_result = ocaml.compile(`Js.log Sys.ocaml_version`); // You can change the code here
-undefined
-> eval(compile_result);
+> let compiler = rescript_compiler.make()
+> let result = compiler.rescript.compile(`Js.log(Sys.ocaml_version)`);
+> eval(result);
 4.06.2+BS
-undefined
 ```
 
 ### Playground JS bundle API
 
-As soon as the bundle is loaded, you will get access to following functions (as seen in [`jsoo_main.ml`](jscomp/main/jsoo_main.ml)):
+As soon as the bundle is loaded, you will get access to the functions exposed in [`jsoo_refmt_main.ml`](jscomp/refmt/jsoo_refmt_main.ml). Best way to check out the API is by inspecting a compiler instance it either in node, or in the browser:
 
-- `window.ocaml`:
-  - `compile(code: string)`: Compiles given code
-  - `shake_compile(code: string)`: Compiles given code with tree-shaking
-  - `compile_super_errors(code: string)`: Compiles given code and outputs `super_errors` related messages on `console.error`
-  - `compile_super_errors_ppx_v2(code: string)`: Compiles given code with the React v2 syntax
-  - `compile_super_errors_ppx_v3(code: string)`: Compiles given code with the React v3 syntax
-  - `load_module(cmi_path: string, cmi_content: string, cmj_name: string, cmj_content: string)`: Loads a module into the compiler (see notes on `cmj` / `cmi` below)
+```
+$ node
+require('./exports.js')
+
+> let compiler = rescript_compiler.make()
+> console.log(compiler)
+```
 
-For each compile every successful operation will return `{js_code: string}`. On compile errors, the returned object will be `{js_error_msg: string}`.
 
 ### Working on the Playground JS API
 
-Whenever you are modifying any files in the ReScript compiler, or in the `jsoo_main.ml` file, you'll need to rebuild the source and recreate the JS bundle.
+Whenever you are modifying any files in the ReScript compiler, or in the `jsoo_refmt_main.ml` file, you'll need to rebuild the source and recreate the JS bundle.
 
 ```sh
 node scripts/ninja.js config && node scripts/ninja.js build

jscomp/main/jsoo_common.ml

@@ -1,26 +1,57 @@
+(*
+ * This module extracts most JSOO externals from the upstream jsoo `js.ml` file.
+ * See: https://github.com/ocsigen/js_of_ocaml/blob/master/lib/js_of_ocaml/js.ml
+ *)
 module Js = struct
   module Unsafe = struct
     type any
     external inject : 'a -> any = "%identity"
     external get : 'a -> 'b -> 'c = "caml_js_get"
     external set : 'a -> 'b -> 'c -> unit = "caml_js_set"
     external pure_js_expr : string -> 'a = "caml_pure_js_expr"
+    external fun_call : 'a -> any array -> 'b = "caml_js_fun_call"
     let global = pure_js_expr "joo_global_object"
     type obj
     external obj : (string * any) array -> obj = "caml_js_object"
   end
   type (-'a, +'b) meth_callback
   type 'a callback = (unit, 'a) meth_callback
+
   external wrap_callback : ('a -> 'b) -> ('c, 'a -> 'b) meth_callback = "caml_js_wrap_callback"
   external wrap_meth_callback : ('a -> 'b) -> ('a, 'b) meth_callback = "caml_js_wrap_meth_callback"
+
   type + 'a t
+
   type js_string
   external string : string -> js_string t = "caml_js_from_string"
   external to_string : js_string t -> string = "caml_js_to_string"
+
+  type 'a js_array
+  external array : 'a array -> 'a js_array = "caml_js_from_array"
+
+  external bool : bool -> bool t = "caml_js_from_bool"
+  external to_bool : bool t -> bool = "caml_js_to_bool"
+
+  type number
+  external number_of_float : float -> number t = "caml_js_from_float"
+  external float_of_number : number t -> float = "caml_js_to_float"
+
   external create_file : js_string t -> js_string t -> unit = "caml_create_file"
   external to_bytestring : js_string t -> string = "caml_js_to_byte_string"
 end
 
+module Sys_js = struct
+  external set_channel_output' :
+    out_channel -> (Js.js_string Js.t -> unit) Js.callback -> unit
+    = "caml_ml_set_channel_output"
+
+  let set_channel_flusher (out_channel : out_channel) (f : string -> unit) =
+    let f' : (Js.js_string Js.t -> unit) Js.callback =
+      Js.wrap_callback (fun s -> f (Js.to_bytestring s))
+    in
+    set_channel_output' out_channel f'
+end
+
 let mk_js_error (loc: Location.t) (msg: string) = 
   let (_file,line,startchar) = Location.get_pos_info loc.Location.loc_start in
   let (_file,endline,endchar) = Location.get_pos_info loc.Location.loc_end in
@@ -36,4 +67,4 @@ let mk_js_error (loc: Location.t) (msg: string) =
   "type" , inject @@ Js.string "error"
   |]
   )
-  
+  

jscomp/main/jsoo_common.mli

@@ -10,25 +10,50 @@ module Js :
         external get : 'a -> 'b -> 'c = "caml_js_get"
         external set : 'a -> 'b -> 'c -> unit = "caml_js_set"
         external pure_js_expr : string -> 'a = "caml_pure_js_expr"
+        external fun_call : 'a -> any array -> 'b = "caml_js_fun_call"
         val global : 'a
         type obj
         external obj : (string * any) array -> obj = "caml_js_object"
       end
+
     type (-'a, +'b) meth_callback
     type 'a callback = (unit, 'a) meth_callback
+
     external wrap_callback : ('a -> 'b) -> ('c, 'a -> 'b) meth_callback
       = "caml_js_wrap_callback"
     external wrap_meth_callback : ('a -> 'b) -> ('a, 'b) meth_callback
       = "caml_js_wrap_meth_callback"
+
     type +'a t
+
     type js_string
     external string : string -> js_string t = "caml_js_from_string"
     external to_string : js_string t -> string = "caml_js_to_string"
+
+    type 'a js_array
+    external array : 'a array -> 'a js_array = "caml_js_from_array"
+
+    external bool : bool -> bool t = "caml_js_from_bool"
+    external to_bool : bool t -> bool = "caml_js_to_bool"
+
+    type number
+    external number_of_float : float -> number t = "caml_js_from_float"
+    external float_of_number : number t -> float = "caml_js_to_float"
+
     external create_file : js_string t -> js_string t -> unit
       = "caml_create_file"
     external to_bytestring : js_string t -> string = "caml_js_to_byte_string"
+
   end
 
+module Sys_js :
+sig
+  val set_channel_flusher : out_channel -> (string -> unit) -> unit
+  (** Set a callback to be called when an out_channel flush its buffer.
+        [set_channel_flusher chan cb] install the callback [cb] for [chan] out_channel.
+        [cb] will be called with the string to flush. *)
+end
+
 (*
 Creates a Js Error object for given location with and a certain error message
 *)