Skip to content

Commit 8cd721b

Browse files
hhugohhugo
authored
Improve manual (#1826)
1 parent ad605a8 commit 8cd721b

File tree

8 files changed

+59
-56
lines changed

8 files changed

+59
-56
lines changed

‎manual/debug.wiki‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,30 @@
22

33
== Use the right compiler flags
44
=== OCaml flags
5-
Make sure to use "-g" flags when compiling and linking ocaml bytecode.
5+
Make sure to use {{{-g}}} flags when compiling and linking ocaml bytecode.
66
Js_of_ocaml will attempt to preserve variable names.
77

88
=== Js_of_ocaml flags
9-
* [--pretty] - format the generated JavaScript in a readable way and try to keep OCaml variable names.
10-
* [--no-inline] - prevent function inlining.
11-
* [--debug-info] - annotate the JavaScript file with locations from the OCaml sources.
12-
* [--source-map] - enable source-map support
9+
* {{{--pretty}}} - format the generated JavaScript in a readable way and try to keep OCaml variable names.
10+
* {{{--no-inline}}} - prevent function inlining.
11+
* {{{--debug-info}}} - annotate the JavaScript file with locations from the OCaml sources.
12+
* {{{--source-map}}} - enable source-map support
1313
1414
== JavaScript stacktrace
15-
Js_of_ocaml can attach a JavaScript [Error] that embed the current
16-
stacktrace to an OCaml exception. The [Error] can be attached with
15+
Js_of_ocaml can attach a JavaScript {{{Error}}} that embed the current
16+
stacktrace to an OCaml exception. The {{{Error}}} can be attached with
1717
{{{Js.Js_error.attach_js_backtrace}}} and extracted using
1818
{{{Js.Js_error.of_exn}}}. Un-handled OCaml exception will throw any
19-
JavaScript [Error] attached to them, allowing the JS engine to display
19+
JavaScript {{{Error}}} attached to them, allowing the JS engine to display
2020
the stacktrace nicely.
2121

22-
Js_of_ocaml will attach an [Error] automatically when raising an OCaml
22+
Js_of_ocaml will attach an {{{Error}}} automatically when raising an OCaml
2323
exception (with {{{raise}}}, not with {{{raise_notrace}}}) if
2424
{{{Printexc.backtrace_status() = true}}} and either the environment
25-
variable [OCAMLRUNPARAM] is set with [b=1] or the program was compiled
26-
with [--enable with-js-error].
25+
variable {{{OCAMLRUNPARAM}}} is set with {{{b=1}}} or the program was compiled
26+
with {{{--enable with-js-error}}}.
2727

28-
Note that creating JavaScript [Error]s is costly and can degrade performance a lot.
28+
Note that creating JavaScript {{{Error}}}s is costly and can degrade performance a lot.
2929
This is the reason why such feature is not enabled by default.
3030

3131
== Breakpoint

‎manual/effects.wiki‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
Js_of_ocaml supports effect handlers with the {{{--enable=effects}}}
44
flag. This is based on partially transforming the program to
55
continuation-passing style.
6-
As a consequence, [[tailcall|tail calls]] are also fully optimized.
6+
As a consequence, [[tailcall|tail calls]] could be fully optimized (if CPS transformed).
77
This is not the default for now since the generated code can be slower,
88
larger and less readable.
99
The transformation is based on an analysis to detect parts of the code that cannot involves effects and keep it in direct style.

‎manual/environment-variable.wiki‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
To resolve an environment variable, js_of_ocaml will perform the
44
following steps, in the given order:
55

6-
- If the variable was set at compile time with the [--setenv VAR] flag, return it.
7-
- If running nodejs and the variable is set in the process environment ([process.env]), return it.
8-
- If the variable is set in [globalThis.jsoo_env], return it. This can be used
6+
* If the variable was set at compile time with the {{{--setenv VAR}}} flag, return it.
7+
* If running nodejs and the variable is set in the process environment ({{{process.env}}}), return it.
8+
* If the variable is set in {{{globalThis.jsoo_env}}}, return it. This can be used
99
to set an environment variable inside a web-browser.
10-
- Return Not_found
10+
* Return Not_found

‎manual/linker.wiki‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,6 @@ function primitive_name(..){
3535
the returned value of the primitive; when no annotation is provided,
3636
the linker assumes that the primitive may have side-effects.
3737
* **{{{//Requires}}}** is used if other primitives need to be loaded first
38-
* **version_constraint** looks like "{{{< 4.12.0}}}"
38+
* **version_constraint** looks like {{{< 4.12.0}}}
3939
* **{{{//Version}}}** is optional and is rarely used
4040
All JavaScript code following a **{{{//Provides}}}** annotation is associated to this annotation, until the next **{{{//Provides}}}** annotation.

‎manual/options.wiki‎

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,36 @@
11
= Main Command-Line options
22

3-
|= Option name |= Description |
4-
| --version | Display the version of the compiler |
5-
| -o <file> | Set the output filename to <file> |
6-
| --source-map | Generate sourcemap |
7-
| --opt {1,2,3} | Set the compilation profile
8-
(default 1). See **Optimization**
9-
section below. |
10-
| --pretty | Pretty print javascript output |
11-
| --target-env | Build javascript for the requested
12-
environment (default "isomorphic").
13-
Isomorphic javascript runs in both the
14-
browser & nodejs. "nodejs" & "browser"
15-
options bundle less javascript, but
16-
drop support for APIs incompatible with
17-
the selected runtime. |
18-
| --no-inline | Disable code inlining |
19-
| --debug-info | Output debug information |
20-
| -I dir | Add <dir> to the list of
21-
include directories |
22-
| --file file[:target] | Register <file> to the pseudo filesystem
23-
and choose the destination <target>. The
24-
<target> can be a directory or a file
25-
(default /static/) |
26-
| --enable <option> | Enable option <option> |
27-
| --disable <option> | Disable option <option> |
3+
|= Option name |= Description |
4+
| {{{--version}}} | Display the version of the compiler |
5+
| {{{-o <file>}}} | Set the output filename to <file> |
6+
| {{{--source-map}}} | Generate sourcemap |
7+
| {{{--opt {1,2,3} }}} | Set the compilation profile
8+
(default 1). See **Optimization**
9+
section below. |
10+
| {{{--pretty}}} | Pretty print javascript output |
11+
| {{{--target-env}}} | Build javascript for the requested
12+
environment (default {{{isomorphic}}}).
13+
Isomorphic javascript runs in both the
14+
browser & nodejs. {{{nodejs}}} & {{{browser}}}
15+
options bundle less javascript, but
16+
drop support for APIs incompatible with
17+
the selected runtime. |
18+
| {{{--no-inline}}} | Disable code inlining |
19+
| {{{--debug-info}}} | Output debug information |
20+
| {{{-I dir}}} | Add <dir> to the list of
21+
include directories |
22+
| {{{--file file[:target]}}} | Register <file> to the pseudo filesystem
23+
and choose the destination <target>. The
24+
<target> can be a directory or a file
25+
(default /static/) |
26+
| {{{--enable <option>}}} | Enable option <option> |
27+
| {{{--disable <option>}}} | Disable option <option> |
2828

2929
=Optimizations
30-
* For Debugging: "--pretty --no-inline --debug-info" + eventually "--disable staticeval --disable share"
31-
* For Production: "--opt 3". It minimize the generated javascript by applying
30+
* For Debugging: {{{--pretty --no-inline --debug-info}}} + eventually {{{--disable staticeval --disable share}}}
31+
* For Production: {{{--opt 3}}}. It minimize the generated javascript by applying
3232
various optimizations until a fix-point is reached
33-
==List of option to "--disable" or "--enable"
33+
==List of option to {{{--disable}}} or {{{--enable}}}
3434

3535
|= Option name |= Default |= Description |
3636
| pretty | false | Pretty print the javascript output |

‎manual/overview.wiki‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ Js_of_ocaml is composed of multiple packages:
2323
* js_of_ocaml-toplevel, lib and tools to build an ocaml toplevel to
2424
javascript.
2525

26+
There is also a compiler targeting WebAssembly provided by the
27+
wasm_of_ocaml package, see <<a_manual chapter="wasm_overview" |wasm_of_ocaml>>.
28+
2629
Note: All code examples in this manual use Js_of_ocaml's ppx syntax.
2730
It is, however, possible to use Js_of_ocaml purely as a compiler
2831
while using a different package (e.g. gen_js_api, brr) to
@@ -87,8 +90,8 @@ functions are optimized:
8790
Effect handlers are fully supported with the
8891
{{{--enable=effects}}} flag. Effect support is disabled by
8992
default for now since effects are not widely used at the moment and the
90-
generated code can be slower, larger and less readable. See the dedicated
91-
manual section about effects for details.
93+
generated code can be slower, larger and less readable. See the [[effects|dedicated
94+
manual section]] for details.
9295
9396
Data representation differs from the usual one. Most notably,
9497
integers are 32 bits (rather than 31 bits or 63 bits), which is their

‎manual/separate-compilation.wiki‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@ separate compilation with some differences.
2323

2424
The general idea is generate one JavaScript file containing the
2525
JavaScript runtime and JavaScript files for every compilation unit (or
26-
library) needed to run the program. One can then link (or
27-
"concatenate") all individual JavaScript files together, respecting
28-
the order induced by dependencies, into a single JavaScript file.
26+
library) needed to run the program. One can then link all individual
27+
JavaScript files together, respecting the order induced by
28+
dependencies, into a single JavaScript file.
2929

3030
=== 1. Build the runtime
3131

‎manual/wasm_overview.wiki‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Wasm_of_ocaml is a compiler from OCaml bytecode programs to WebAssembly.
66
It provides an alternative way to run pure OCaml programs in JavaScript environments like browsers and Node.js.
77

8-
The compiler is provided by the wasm_of_ocaml-package. The <<a_manual chapter="overview" |Js_of_ocaml libraries>> are compatible with this compiler.
8+
The compiler is provided by the wasm_of_ocaml-compiler package. The <<a_manual chapter="overview" |Js_of_ocaml libraries>> are compatible with this compiler.
99

1010
== Installation
1111

@@ -49,8 +49,8 @@ supported in general. However,
4949
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.
5050

5151
OCaml 5.x code using effect handlers can be compiled in two different ways:
52-
one can enable the CPS transformation from `js_of_ocaml` by passing the
53-
`--effects=cps` flag. Without the flag `wasm_of_ocaml` will instead default to
54-
`--effects=jspi` and emit code utilizing
55-
[the JavaScript-Promise Integration extension](https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md).
52+
one can enable the CPS transformation from {{{js_of_ocaml}}} by passing the
53+
{{{--effects=cps}}}{ flag. Without the flag {{{wasm_of_ocaml}}} will instead default to
54+
{{{--effects=jspi}}} and emit code utilizing
55+
[[https://github.com/WebAssembly/js-promise-integration/blob/main/proposals/js-promise-integration/Overview.md|the JavaScript-Promise Integration extension]].
5656
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.

0 commit comments

Comments
 (0)