Command-line options
This page documents the command-line options for the js_of_ocaml compiler.
General options ¶
| Option | Description |
|---|---|
| --version | Display the compiler version |
| -o <file> | Set output filename |
| --opt {1,2,3} | Set optimization profile (default: 1). See Optimizations |
| --enable <opt> | Enable option. See Enable/Disable options |
| --disable <opt> | Disable option. See Enable/Disable options |
| -I <dir> | Add directory to the list of include directories |
Debugging ¶
| Option | Description |
|---|---|
| --pretty | Pretty print JavaScript output, preserve OCaml variable names |
| --no-inline | Disable code inlining |
| --debug-info | Output debug information (source locations) |
| --source-map | Generate source map. See Source maps |
Target environment ¶
| Option | Description |
|---|---|
| --target-env <env> | Build for target environment (default: isomorphic) |
Possible values:
- isomorphic - Runs in both browser and Node.js (default)
- browser - Browser-specific, smaller output
- nodejs - Node.js-specific, smaller output
Effect handlers ¶
| Option | Description |
|---|---|
| --effects <mode> | Select effect handler implementation (default: disabled) |
Possible values:
- disabled - No effect handler support (default)
- cps - CPS transformation for effect support
- double-translation - Keep both direct and CPS versions; choose at runtime
See Effect handlers for details.
Source maps ¶
| Option | Description |
|---|---|
| --source-map | Generate source map (separate file) |
| --no-source-map | Don't generate source map |
| --source-map-inline | Inline source map in the JavaScript output |
| --source-map-no-source | Don't embed source code in source map |
| --source-map-root <dir> | Set root directory for source map paths |
Pseudo filesystem ¶
Js_of_ocaml provides a pseudo filesystem for programs that read files at runtime.
| Option | Description |
|---|---|
| --file <file>[:<target>] | Register file to pseudo filesystem (default target: /static/) |
| --ofs <file> | Write filesystem data to separate file |
| --extern-fs | Allow registering files from outside at runtime (default) |
| --no-extern-fs | Only allow files embedded at compile time |
Environment variables ¶
| Option | Description |
|---|---|
| --setenv <VAR>=<value> | Set environment variable at compile time |
Resolution order
When OCaml code calls Sys.getenv, js_of_ocaml resolves variables in this order:
- If the variable was set at compile time with --setenv VAR=value, return it
- If running in Node.js, check process.env
- Check globalThis.jsoo_env (useful for setting variables in browsers)
- Raise Not_found
Browser example
// Set environment variables before loading the OCaml program
globalThis.jsoo_env = {
DEBUG: "true",
API_URL: "https://api.example.com"
};Toplevel and dynamic linking ¶
| Option | Description |
|---|---|
| --toplevel | Compile an OCaml toplevel (embeds necessary .cmi files) |
| --no-cmis | Don't include .cmi files in toplevel |
| --dynlink | Enable dynamic linking of bytecode |
| --export <file> | File listing units to export for toplevel/dynlink |
| --linkall | Link all compilation units and primitives |
See Building a toplevel for details.
Compilation modes ¶
| Option | Description |
|---|---|
| --noruntime | Don't include the standard runtime |
| --include-runtime | Include partial runtime when compiling .cmo/.cma |
| --keep-unit-names | Preserve unit names (for separate compilation) |
| --wrap-with-fun[=<name>] | Wrap output in a function (default: IIFE) |
| --custom-header <text> | Add custom header (e.g., #!/usr/bin/env node) |
See Compilation modes for details.
Optimizations ¶
Optimization profiles
Use --opt <level> to select a profile:
- --opt 1 - Basic optimizations (default)
- --opt 2 - Standard optimizations
- --opt 3 - Maximum optimizations (iterates until fix-point)
Recommended settings
For debugging:
js_of_ocaml --pretty --no-inline program.byte
For production:
js_of_ocaml --opt 3 program.byte
Enable/Disable options ¶
Use --enable <opt> or --disable <opt> to control these flags:
Output formatting
| Option | Default | Description |
|---|---|---|
| pretty | false | Pretty print JavaScript output |
| shortvar | true | Use short variable names |
| strict | true | Generate "use strict" |
| header | true | Include compiler version header |
| es6 | false | Generate ES6 syntax |
Optimizations
| Option | Default | Description |
|---|---|---|
| deadcode | true | Dead code elimination |
| globaldeadcode | true | Global dead code elimination |
| inline | true | Function inlining |
| staticeval | true | Static evaluation of constants |
| share | true | Share string and number constants |
| optcall | true | JavaScript call optimizations |
Runtime behavior
| Option | Default | Description |
|---|---|---|
| effects | false | Enable effect handlers |
| excwrap | true | Wrap JavaScript exceptions in OCaml exceptions |
| with-js-error | false | Attach JavaScript stack traces to OCaml exceptions |
| debugger | true | Keep debugger statements (stripped if false) |
| genprim | true | Generate dummy primitives when missing |
| use-js-string | true | Use JavaScript strings internally |
Internal debugging
| Option | Default | Description |
|---|---|---|
| debuginfo | false | Include source location comments |
| stable_var | false | Use stable (predictable) variable names |
| auto-link | true | link required compilation units only |
Compiler parameters ¶
Use --set <param>=<value> to tune compiler behavior:
| Parameter | Default | Description |
|---|---|---|
| switch_size | 60 | Max cases before switch becomes if-else chain |
| inlining-limit | 150 | Size threshold for function inlining |
| tc_depth | 50 | Max tail-call depth before trampoline |
| tc | trampoline | Tail-call mode: trampoline or none |
Warnings ¶
| Option | Description |
|---|---|
| --quiet / -q | Suppress non-error messages |
| --Werror | Treat warnings as errors |
| -w <warning> | Enable warning |
| -w no-<warning> | Disable warning |
Available warnings:
| Warning | Default | Description |
|---|---|---|
| missing-primitive | on | Missing JavaScript primitive implementation |
| missing-cmi | on | Missing .cmi file |
| missing-deps | on | Missing dependencies |
| missing-effects-backend | on | Using effects, but not backend was selected |
| integer-overflow | on | Integer overflow in constant |
| overriding-primitive | on | Overriding an existing primitive |
| deprecated-primitive | on | Using deprecated primitive |
| free-variables | on | Free variables in primitive code |
Debug output ¶
Use --debug <section> to enable debug output for compiler internals:
times, stats, deadcode, globaldeadcode, inlining, gen, linker, sourcemap, flow, parser
Subcommands ¶
The js_of_ocaml command has several subcommands:
| Command | Description |
|---|---|
| js_of_ocaml compile | Compile bytecode to JavaScript (default) |
| js_of_ocaml link | Link JavaScript files together |
| js_of_ocaml build-runtime | Build standalone runtime |
| js_of_ocaml build-fs | Build pseudo filesystem |
Link command
js_of_ocaml link -o output.js runtime.js lib1.js lib2.js main.js
Additional options:
| Option | Description |
|---|---|
| -a | Build a library (.cma.js) |
| --resolve-sourcemap-url | Resolve source map URLs |
Build-runtime command
js_of_ocaml build-runtime -o runtime.js
Accepts the same --enable/--disable options as the main command.
Build-fs command
js_of_ocaml build-fs -o fs.js file1.txt file2.dat
Builds a JavaScript file containing filesystem data.