From cc49021799b1fc9e3fb26fafbe65b90c6b2c4a06 Mon Sep 17 00:00:00 2001 From: Hugo Heuzard Date: Mon, 3 Feb 2025 21:58:23 +0100 Subject: [PATCH 1/2] Improve manual --- manual/debug.wiki | 24 ++++++++++++------------ manual/environment-variable.wiki | 8 ++++---- manual/overview.wiki | 7 +++++-- manual/wasm_overview.wiki | 10 +++++----- 4 files changed, 26 insertions(+), 23 deletions(-) diff --git a/manual/debug.wiki b/manual/debug.wiki index 71bc2b15e7..5224bfb858 100644 --- a/manual/debug.wiki +++ b/manual/debug.wiki @@ -2,30 +2,30 @@ == Use the right compiler flags === OCaml flags -Make sure to use "-g" flags when compiling and linking ocaml bytecode. +Make sure to use {{{-g}}} flags when compiling and linking ocaml bytecode. Js_of_ocaml will attempt to preserve variable names. === Js_of_ocaml flags - * [--pretty] - format the generated JavaScript in a readable way and try to keep OCaml variable names. - * [--no-inline] - prevent function inlining. - * [--debug-info] - annotate the JavaScript file with locations from the OCaml sources. - * [--source-map] - enable source-map support + * {{{--pretty}}} - format the generated JavaScript in a readable way and try to keep OCaml variable names. + * {{{--no-inline}}} - prevent function inlining. + * {{{--debug-info}}} - annotate the JavaScript file with locations from the OCaml sources. + * {{{--source-map}}} - enable source-map support == JavaScript stacktrace -Js_of_ocaml can attach a JavaScript [Error] that embed the current -stacktrace to an OCaml exception. The [Error] can be attached with +Js_of_ocaml can attach a JavaScript {{{Error}}} that embed the current +stacktrace to an OCaml exception. The {{{Error}}} can be attached with {{{Js.Js_error.attach_js_backtrace}}} and extracted using {{{Js.Js_error.of_exn}}}. Un-handled OCaml exception will throw any -JavaScript [Error] attached to them, allowing the JS engine to display +JavaScript {{{Error}}} attached to them, allowing the JS engine to display the stacktrace nicely. -Js_of_ocaml will attach an [Error] automatically when raising an OCaml +Js_of_ocaml will attach an {{{Error}}} automatically when raising an OCaml exception (with {{{raise}}}, not with {{{raise_notrace}}}) if {{{Printexc.backtrace_status() = true}}} and either the environment -variable [OCAMLRUNPARAM] is set with [b=1] or the program was compiled -with [--enable with-js-error]. +variable {{{OCAMLRUNPARAM}}} is set with {{{b=1}}} or the program was compiled +with {{{--enable with-js-error}}}. -Note that creating JavaScript [Error]s is costly and can degrade performance a lot. +Note that creating JavaScript {{{Error}}}s is costly and can degrade performance a lot. This is the reason why such feature is not enabled by default. == Breakpoint diff --git a/manual/environment-variable.wiki b/manual/environment-variable.wiki index e45e11b7fc..99edb3ae1b 100644 --- a/manual/environment-variable.wiki +++ b/manual/environment-variable.wiki @@ -3,8 +3,8 @@ To resolve an environment variable, js_of_ocaml will perform the following steps, in the given order: -- If the variable was set at compile time with the [--setenv VAR] flag, return it. -- If running nodejs and the variable is set in the process environment ([process.env]), return it. -- If the variable is set in [globalThis.jsoo_env], return it. This can be used +* If the variable was set at compile time with the {{{--setenv VAR}}} flag, return it. +* If running nodejs and the variable is set in the process environment ({{{process.env}}}), return it. +* If the variable is set in {{{globalThis.jsoo_env}}}, return it. This can be used to set an environment variable inside a web-browser. -- Return Not_found \ No newline at end of file +* Return Not_found \ No newline at end of file diff --git a/manual/overview.wiki b/manual/overview.wiki index 6dce5ca01f..d9eb38742e 100644 --- a/manual/overview.wiki +++ b/manual/overview.wiki @@ -23,6 +23,9 @@ Js_of_ocaml is composed of multiple packages: * js_of_ocaml-toplevel, lib and tools to build an ocaml toplevel to javascript. +There is also a compiler targeting WebAssembly provided by the +wasm_of_ocaml package, see <>. + Note: All code examples in this manual use Js_of_ocaml's ppx syntax. It is, however, possible to use Js_of_ocaml purely as a compiler while using a different package (e.g. gen_js_api, brr) to @@ -87,8 +90,8 @@ functions are optimized: Effect handlers are fully supported with the {{{--enable=effects}}} flag. Effect support is disabled by default for now since effects are not widely used at the moment and the -generated code can be slower, larger and less readable. See the dedicated -manual section about effects for details. +generated code can be slower, larger and less readable. See the [[effects|dedicated +manual section]] for details. Data representation differs from the usual one. Most notably, integers are 32 bits (rather than 31 bits or 63 bits), which is their diff --git a/manual/wasm_overview.wiki b/manual/wasm_overview.wiki index 2a7653bfec..7d89f15fc9 100644 --- a/manual/wasm_overview.wiki +++ b/manual/wasm_overview.wiki @@ -5,7 +5,7 @@ Wasm_of_ocaml is a compiler from OCaml bytecode programs to WebAssembly. It provides an alternative way to run pure OCaml programs in JavaScript environments like browsers and Node.js. -The compiler is provided by the wasm_of_ocaml-package. The <> are compatible with this compiler. +The compiler is provided by the wasm_of_ocaml-compiler package. The <> are compatible with this compiler. == Installation @@ -49,8 +49,8 @@ supported in general. However, Compared to Js_of_ocaml, dynlink is not supported, and it is not possible to build an OCaml toplevel. The virtual filesystem is not implemented either. OCaml 5.x code using effect handlers can be compiled in two different ways: -one can enable the CPS transformation from `js_of_ocaml` by passing the -`--effects=cps` flag. Without the flag `wasm_of_ocaml` will instead default to -`--effects=jspi` and emit code utilizing - [the JavaScript-Promise Integration extension](https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md). +one can enable the CPS transformation from {{{js_of_ocaml}}} by passing the +{{{--effects=cps}}}{ flag. Without the flag {{{wasm_of_ocaml}}} will instead default to +{{{--effects=jspi}}} and emit code utilizing + [[https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md|the JavaScript-Promise Integration extension]]. The CPS transformation is not the default since the generated code is slower, larger and less readable. On the other hand, the JSPI extension is not yet enabled by default in Web browsers, and performing effects is slower when using this extension. From 850c2c46a16c96bc81fc0febb58e15f7b4c70497 Mon Sep 17 00:00:00 2001 From: Hugo Heuzard Date: Tue, 4 Feb 2025 00:21:50 +0100 Subject: [PATCH 2/2] WIP --- manual/effects.wiki | 2 +- manual/linker.wiki | 2 +- manual/options.wiki | 56 ++++++++++++++++---------------- manual/separate-compilation.wiki | 6 ++-- 4 files changed, 33 insertions(+), 33 deletions(-) diff --git a/manual/effects.wiki b/manual/effects.wiki index 5794e8bf43..49669ab15e 100644 --- a/manual/effects.wiki +++ b/manual/effects.wiki @@ -3,7 +3,7 @@ Js_of_ocaml supports effect handlers with the {{{--enable=effects}}} flag. This is based on partially transforming the program to continuation-passing style. -As a consequence, [[tailcall|tail calls]] are also fully optimized. +As a consequence, [[tailcall|tail calls]] could be fully optimized (if CPS transformed). This is not the default for now since the generated code can be slower, larger and less readable. The transformation is based on an analysis to detect parts of the code that cannot involves effects and keep it in direct style. diff --git a/manual/linker.wiki b/manual/linker.wiki index 344ff6b58e..f12de22b11 100644 --- a/manual/linker.wiki +++ b/manual/linker.wiki @@ -35,6 +35,6 @@ function primitive_name(..){ the returned value of the primitive; when no annotation is provided, the linker assumes that the primitive may have side-effects. * **{{{//Requires}}}** is used if other primitives need to be loaded first - * **version_constraint** looks like "{{{< 4.12.0}}}" + * **version_constraint** looks like {{{< 4.12.0}}} * **{{{//Version}}}** is optional and is rarely used All JavaScript code following a **{{{//Provides}}}** annotation is associated to this annotation, until the next **{{{//Provides}}}** annotation. diff --git a/manual/options.wiki b/manual/options.wiki index 7ef4fabb35..bf8a0f76f6 100644 --- a/manual/options.wiki +++ b/manual/options.wiki @@ -1,36 +1,36 @@ = Main Command-Line options -|= Option name |= Description | -| --version | Display the version of the compiler | -| -o | Set the output filename to | -| --source-map | Generate sourcemap | -| --opt {1,2,3} | Set the compilation profile - (default 1). See **Optimization** - section below. | -| --pretty | Pretty print javascript output | -| --target-env | Build javascript for the requested - environment (default "isomorphic"). - Isomorphic javascript runs in both the - browser & nodejs. "nodejs" & "browser" - options bundle less javascript, but - drop support for APIs incompatible with - the selected runtime. | -| --no-inline | Disable code inlining | -| --debug-info | Output debug information | -| -I dir | Add to the list of - include directories | -| --file file[:target] | Register to the pseudo filesystem - and choose the destination . The - can be a directory or a file - (default /static/) | -| --enable