Compiler: experimental ES module output (--esm) [RFC]

CHANGES.md

@@ -1,6 +1,10 @@
 # dev
 
 ## Features/Changes
+* Compiler: experimental ECMAScript module output: `js_of_ocaml compile --esm`
+  and `build-runtime --esm` emit ES modules (units import the runtime instead
+  of reading `globalThis.jsoo_runtime`); `js_of_ocaml link --esm` links them
+  into an entry module, or a single tree-shaken module with `--bundle` (#2402)
 * Lib: add `WebGL2` — bindings to the WebGL2 rendering context. The context
   inherits every method and constant of `WebGL`, and adds the WebGL2 objects
   (vertex array objects, queries, samplers, syncs, transform feedback), 3D and

compiler/bin-js_of_ocaml/cmd_arg.ml

@@ -63,6 +63,8 @@ type t =
   ; params : (string * string) list
   ; static_env : (string * string) list
   ; wrap_with_fun : [ `Iife | `Named of string | `Anonymous ]
+  ; esm : bool
+  ; esm_runtime_path : string
   ; target_env : Target_env.t
   ; shape_files : string list
   ; (* toplevel *)
@@ -100,6 +102,17 @@ let wrap_with_fun_conv =
   in
   Arg.conv (conv, printer)
 
+let esm_arg =
+  let doc = "Experimental: emit an ECMAScript module instead of a script." in
+  Arg.(value & flag & info [ "esm" ] ~doc)
+
+let esm_runtime_path_arg =
+  let doc =
+    "Experimental: module specifier used by separately compiled units to import the \
+     runtime (only meaningful together with '--esm')."
+  in
+  Arg.(value & opt string "./runtime.js" & info [ "esm-runtime-path" ] ~docv:"PATH" ~doc)
+
 let toplevel_section = "OPTIONS (TOPLEVEL)"
 
 let options =
@@ -292,6 +305,8 @@ let options =
       toplevel
       export_file
       wrap_with_fun
+      esm
+      esm_runtime_path
       include_dirs
       fs_files
       fs_output
@@ -380,6 +395,8 @@ let options =
           ; profile
           ; static_env
           ; wrap_with_fun
+          ; esm
+          ; esm_runtime_path
           ; dynlink
           ; linkall
           ; target_env
@@ -413,6 +430,8 @@ let options =
       $ toplevel
       $ export_file
       $ wrap_with_function
+      $ esm_arg
+      $ esm_runtime_path_arg
       $ include_dirs
       $ fs_files
       $ fs_output
@@ -577,6 +596,8 @@ let options_runtime_only =
       set_param
       set_env
       wrap_with_fun
+      esm
+      esm_runtime_path
       fs_files
       fs_output
       fs_external
@@ -645,6 +666,8 @@ let options_runtime_only =
       ; profile = None
       ; static_env
       ; wrap_with_fun
+      ; esm
+      ; esm_runtime_path
       ; dynlink = false
       ; linkall = false
       ; target_env
@@ -676,6 +699,8 @@ let options_runtime_only =
       $ set_param
       $ set_env
       $ wrap_with_function
+      $ esm_arg
+      $ esm_runtime_path_arg
       $ fs_files
       $ fs_output
       $ fs_external

compiler/bin-js_of_ocaml/cmd_arg.mli

@@ -36,6 +36,8 @@ type t =
       | `Named of string
       | `Anonymous
       ]
+  ; esm : bool
+  ; esm_runtime_path : string
   ; target_env : Target_env.t
   ; shape_files : string list
   ; (* toplevel *)

compiler/bin-js_of_ocaml/compile.ml

@@ -144,6 +144,8 @@ let run
     ; params
     ; static_env
     ; wrap_with_fun
+    ; esm
+    ; esm_runtime_path
     ; dynlink
     ; linkall
     ; target_env
@@ -268,6 +270,15 @@ let run
       ~link
       output_file =
     if check_sourcemap then check_debug one;
+    let esm : Driver.esm option =
+      if esm
+      then
+        (* Standalone programs and the runtime inline the runtime code; only
+           separately compiled units import it. *)
+        Some
+          { Driver.runtime_import = (if standalone then None else Some esm_runtime_path) }
+      else None
+    in
     let init_pseudo_fs = fs_external && standalone in
     let sm, shapes =
       match output_file with
@@ -282,6 +293,7 @@ let run
           let code = Code.prepend one.code instr in
           Driver.f
             ~standalone
+            ?esm
             ~shapes
             ?profile
             ~link
@@ -306,6 +318,7 @@ let run
           let res =
             Driver.f
               ~standalone
+              ?esm
               ~shapes
               ?profile
               ~link