fixup! fixup! Update with gh-2150

Author: hhugo

doc/dev/manual/compilation-modes.wiki

@@ -1,106 +1,93 @@
 = Compilation modes
 
-The js_of_ocaml compiler supports two compilation modes.  Whole program
-compilation that compiles a bytecode executable to a single JavaScript
-file and separate compilation that compiles individual compilation units
-(.cmo) and libraries (.cma) to one or more javascript files.
+Js_of_ocaml supports two compilation modes:
 
-==@@id="why-separate"@@ Why use separate compilation
+* **Whole program compilation** — compiles a bytecode executable to a single JavaScript file
+* **Separate compilation** — compiles individual units ({{{.cmo}}}) and libraries ({{{.cma}}}) to JavaScript files, then links them together
 
-Separate compilation improves the overall compilation times and gives
-(many) incremental build opportunities.
+==@@id="comparison"@@ Choosing a mode
 
-These improvements come at the cost of bigger executable and slower
-runtime.  In particular, separate compilation will disable most cross
-module and cross library optimizations and make the dead-code
-elimination almost useless.
+|= |= Whole program |= Separate |
+| Build speed | Slower (recompiles everything) | Faster (incremental builds) |
+| Output size | Smaller (dead code elimination) | Larger |
+| Runtime speed | Faster (cross-module optimizations) | Slower |
 
+**Recommendation**: Use separate compilation during development for fast iteration,
+and whole program compilation for production releases.
 
-==@@id="scheme"@@ Compilation scheme
+==@@id="whole-program"@@ Whole program compilation
 
-Js_of_ocaml separate compilation is somewhat similar to the OCaml
-separate compilation with some differences.
+This is the simplest mode. Compile your bytecode executable directly:
 
-The general idea is to generate one JavaScript file containing the
-JavaScript runtime and JavaScript files for every compilation unit (or
-library) needed to run the program. One can then link all individual
-JavaScript files together, respecting the order induced by
-dependencies, into a single JavaScript file.
-
-=== 1. Build the runtime
-
-To build a standalone runtime:
 {{{
-js_of_ocaml build-runtime -o my-runtime.js
+js_of_ocaml program.byte -o program.js
 }}}
 
-Additional runtime files are sometimes needed and can be passed on the
-command line.  In particular, some packages/libraries come with their
-own runtime file.
+Some libraries require additional runtime files. See
+<<a_manual chapter="linker" fragment="finding-runtime"|JavaScript primitives>> for how to discover them.
 
-See <<a_manual chapter="linker" fragment="finding-runtime"|Linking JavaScript code>> for how to discover
-these files.
+The compiler performs global dead-code elimination and cross-module optimizations,
+producing smaller and faster output.
 
-=== 2. Build compilation units
+==@@id="separate"@@ Separate compilation
 
-In addition to bytecode executables, the js_of_ocaml compiler can
-process compilation units (.cmo) and libraries (.cma).
+Separate compilation involves three steps: build the runtime, compile units, and link.
 
-One can specify the name of the generated file with {{{-o}}}. By
-default, the name will be inferred from the input file.
-
-By default, the js_of_ocaml compiler will generate a single JavaScript
-file when compiling an ocaml library (.cma). One can choose to
-generate one file per compilation unit by passing the
-{{{--keep-unit-names}}} flag. In that case, the name will be inferred
-from the compilation unit name and {{{-o}}} will be understood as a
-destination directory.
+=== 1. Build the runtime
 
 {{{
-js_of_ocaml modname.cmo
-#generates modname.js
+js_of_ocaml build-runtime -o runtime.js
+}}}
 
-js_of_ocaml libname.cma
-#generates libname.js
+Some libraries require additional runtime files. See
+<<a_manual chapter="linker" fragment="finding-runtime"|JavaScript primitives>> for how to discover them.
 
-js_of_ocaml libname.cma -o name.js
-#generates name.js
+=== 2. Compile units and libraries
 
-mkdir libname
-js_of_ocaml libname.cma --keep-unit-names -o libname/
-#generates libname/Unit1.js libname/Unit2.js
+{{{
+js_of_ocaml mymodule.cmo           # generates mymodule.js
+js_of_ocaml mylib.cma              # generates mylib.js
+js_of_ocaml mylib.cma -o lib.js    # generates lib.js
 }}}
 
 === 3. Link
 
-The final step is to link all individual JavaScript files into a
-single one.  The {{{link}}} command of the js_of_ocaml-compiler takes
-a list of JavaScript filename as input and concatenates them all
-(merging source-maps together if needed).
+Concatenate all JavaScript files in dependency order:
 
 {{{
-js_of_ocaml link my-runtime.js stdlib.js libname.js modname.js std_exit.js -o myexe.js
+js_of_ocaml link runtime.js stdlib.js mylib.js mymodule.js std_exit.js -o program.js
 }}}
 
-Note that, unlike the ocaml compiler, the ocaml stdlib and std_exit need to be
-passed explicitly (here, {stdlib.js} and {std_exit.js} are the result of compiling
-{stdlib.cma} and {std_exit.cmo}).
+**Note**: Unlike OCaml linking, you must explicitly include {{{stdlib.js}}} and {{{std_exit.js}}}.
 
-==@@id="dune"@@ Support in dune
+==@@id="dune"@@ Dune integration
 
-Support for js_of_ocaml separate compilation has been added to dune
-(previously jbuilder). The separate compilation mode is selected when
-the build profile is dev, which is the default.  There is currently no
-other way to control this behavior.
+Dune handles compilation mode automatically based on the build profile:
 
-See [[https://dune.readthedocs.io/en/latest/jsoo.html|dune documentation]]
+|= Profile |= Mode |
+| {{{dev}}} (default) | Separate compilation |
+| {{{release}}} | Whole program compilation |
+
+To build with a specific profile:
+{{{
+dune build --profile release
+}}}
+
+Or configure the default in {{{dune-project}}} or {{{dune-workspace}}}.
+
+See [[https://dune.readthedocs.io/en/latest/jsoo.html|dune documentation]] for details.
+
+==@@id="source-maps"@@ Source maps with separate compilation
+
+For source maps in separate compilation mode, use inline source maps:
+
+{{{
+js_of_ocaml --source-map-inline mymodule.cmo
+}}}
 
-==@@id="source-maps"@@ Source-maps support
+The {{{link}}} command will merge source maps automatically.
 
-Separate compilation can be used together with source-map.  The
-recommended way is to build all individual javascript files with
-inlined source-map by passing {{{--source-map-inline}}} to
-{{{js_of_ocaml}}}.
+== See also
 
-Note that other configurations have not been well tested and might
-require additional tuning.
+* <<a_manual chapter="options"|Command-line options>> — Full list of compiler flags
+* <<a_manual chapter="linker"|JavaScript primitives>> — Runtime files and custom primitives

doc/dev/manual/errors.wiki

@@ -6,7 +6,8 @@ and how to properly handle errors in both directions.
 ==@@id="catching-js-exceptions"@@ Catching JavaScript exceptions in OCaml
 
 When JavaScript code throws an exception and it propagates to OCaml code,
-it is wrapped in the <<a_api subproject="js_of_ocaml"|exception Js_of_ocaml.Js_error.Exn>> exception.
+it is wrapped in the {{{Js_error.Exn}}} exception, which holds a value of type
+{{{Js_error.t}}}:
 
 <<code language="ocaml"|
 open Js_of_ocaml
@@ -15,6 +16,7 @@ let safe_parse json_str =
   try
     Some (Js._JSON##parse (Js.string json_str))
   with Js_error.Exn err ->
+    (* err has type Js_error.t *)
     Printf.eprintf "Parse error: %s\n" (Js_error.to_string err);
     None
 >>