OCAMLRUN(1)

💅 ocamlrun(1) — The OCaml Bytecode Interpreter 💅

Manual name, folded in near the top like a little name tag: General Commands Manual, bestie. 🫶

🌸 NAME 🌸

ocamlrun — The OCaml bytecode interpreter.

✨ SYNOPSIS ✨

ocamlrun [ options ] filename argument ...

💖 DESCRIPTION 💖

Okay so ocamlrun(1) is the command that executes bytecode files made by the linking phase of ocamlc(1). That's the whole vibe. 🦋

The first non-option argument is taken as the name of the file containing the executable bytecode. That file is searched in the executable path as well as in the current directory. The remaining arguments get passed to the OCaml program in the string array Sys.argv. Element 0 of this array is the name of the bytecode executable file; elements 1 to n are the remaining arguments. ✨

In most cases, the bytecode executable files produced by the ocamlc(1) command are self-executable, and manage to launch the ocamlrun(1) command on themselves automatically. Iconic behavior, honestly. 💅

🎀 OPTIONS 🎀

The following command-line options are recognized by ocamlrun(1).

• -b — When your program aborts because an uncaught exception happened, this prints a detailed "back trace" of the execution, showing where the exception was raised and which function calls were outstanding at that point. It only prints if the bytecode executable contains debugging information, i.e. it was compiled and linked with the -g option to ocamlc(1) set. This option is equivalent to setting the b flag in the OCAMLRUNPARAM environment variable (see below).
• -I dir — Search the directory dir for dynamically-loaded libraries, in addition to the standard search path.
• -m file — Print the magic number of the bytecode executable file and exit.
• -M — Print the magic number expected for bytecode executables by this version of the runtime and exit.
• -p — Print the names of the primitives known to this version of ocamlrun(1) and exit.
• -t — Increment the trace level for the debug runtime (ignored by the standard runtime).
• -v — Direct the memory manager to print verbose messages on standard error. This is equivalent to setting v=63 in the OCAMLRUNPARAM environment variable (see below).
• -version — Print version string and exit.
• -vnum — Print short version number and exit.

🦋 ENVIRONMENT VARIABLES 🦋

The following environment variables are also consulted:

• CAML_LD_LIBRARY_PATH — Additional directories to search for dynamically-loaded libraries.
• OCAMLLIB — The directory containing the OCaml standard library. (If OCAMLLIB is not set, CAMLLIB will be used instead.) Used to locate the ld.conf configuration file for dynamic loading. If not set, default to the library directory specified when compiling OCaml.
• OCAMLRUNPARAM — Set the runtime system options and garbage collection parameters. (If OCAMLRUNPARAM is not set, CAMLRUNPARAM will be used instead.) This variable must be a sequence of parameter specifications separated by commas. A parameter specification is a letter, optionally followed by an = sign, a decimal number (or a hexadecimal number prefixed by 0x), and an optional multiplier. If the letter is followed by anything else, the corresponding option is set to 1. Unknown letters are ignored. The options are documented below; the options l,m,M,n,o,s,v correspond to the fields of the control record documented in The OCaml user's manual, chapter "Standard Library", section "Gc".
  • b — Trigger the printing of a stack backtrace when an uncaught exception aborts the program. This option takes no argument.
  • c (cleanup_on_exit) — Shut the runtime down gracefully on exit. The option also enables pooling (as in caml_startup_pooled). This mode can be used to detect leaks with a third-party memory debugger.
  • d (max_domains) — Maximum number of domains that can be active concurrently. Defaults to 128 on 64-bit platforms and 16 on 32-bit platforms.
  • e (runtime_events_log_wsize) — Size of the per-domain runtime events ring buffers in log powers of two words. Defaults to 16, giving 64k word or 512kb buffers on 64-bit systems.
  • l (stack_limit) — The limit (in words) of the stack size.
  • m (custom_minor_ratio) — Bound on floating garbage for out-of-heap memory held by custom values in the minor heap. A minor GC is triggered when this much memory is held by custom values located in the minor heap. Expressed as a percentage of minor heap size. Note: this only applies to values allocated with caml_alloc_custom_mem (e.g. bigarrays). Default: 100.
  • M (custom_major_ratio) — Target ratio of floating garbage to major heap size for out-of-heap memory held by custom values located in the major heap. The GC speed is adjusted to try to use this much memory for dead values that are not yet collected. Expressed as a percentage of major heap size. The default value keeps the out-of-heap floating garbage about the same size as the in-heap overhead. Note: this only applies to values allocated with caml_alloc_custom_mem (e.g. bigarrays). Default: 44.
  • n (custom_minor_max_size) — Maximum amount of out-of-heap memory for each custom value allocated in the minor heap. When a custom value is allocated on the minor heap and holds more than this many bytes, only this value is counted against custom_minor_ratio and the rest is directly counted against custom_major_ratio. Note: this only applies to values allocated with caml_alloc_custom_mem (e.g. bigarrays). Default: 8192 bytes.
  • o (space_overhead) — The main major GC speed setting.
  • p — Turn on debugging support for ocamlyacc-generated parsers. When this option is on, the pushdown automaton that executes the parsers prints a trace of its actions. This option takes no argument.
  • R — Turn on randomization of all hash tables by default (see the Hashtbl module of the standard library). This option takes no argument.
  • s (minor_heap_size) — The size of the minor heap (in words).
  • t — Set the trace level for the debug runtime (ignored by the standard runtime).
  • v (verbose) — What GC messages to print to stderr. This is a sum of values selected from the following:
    • 0x001 — Start and end of major GC cycle.
    • 0x002 — Minor collection and major GC slice.
    • 0x004 — Growing and shrinking of the heap.
    • 0x008 — Resizing of stacks and memory manager tables.
    • 0x010 — Heap compaction.
    • 0x020 — Change of GC parameters.
    • 0x040 — Computation of major GC slice size.
    • 0x080 — Calling of finalisation functions.
    • 0x100 — Startup messages (loading the bytecode executable file, resolving shared libraries).
    • 0x200 — Computation of compaction-triggering condition.
    • 0x400 — Output GC statistics at program exit, in the same format as Gc.print_stat.
    • 0x800 — GC debugging messages.
    • 0x1000 — Address space reservation changes.
  • V (verify_heap) — Runs an integrity check on the heap just after the completion of a major GC cycle.
  • W — Print runtime warnings to stderr (such as Channel opened on file dies without being closed, unflushed data, etc.)

The multiplier is k, M, or G, for multiplication by 2^10, 2^20, and 2^30 respectively.

If the option letter is not recognized, the whole parameter is ignored; if the equal sign or the number is missing, the value is taken as 1; if the multiplier is not recognized, it is ignored.

For example, on a 32-bit machine under bash, the command:

export OCAMLRUNPARAM='s=256k,v=1'

tells a subsequent ocamlrun to set its initial minor heap size to 1 megabyte and to print a message at the start of each major GC cycle. Slay. ✨

• CAMLRUNPARAM — If OCAMLRUNPARAM is not found in the environment, then CAMLRUNPARAM will be used instead. If CAMLRUNPARAM is also not found, then the default values will be used.
• PATH — List of directories searched to find the bytecode executable file.

🌈 SEE ALSO 🌈

• ocamlc(1).
• The OCaml user's manual, chapter "Runtime system".

---

Source/version/date sign-off: this is OCAMLRUN(1) from the General Commands Manual. The original footer didn't print a date, so no fake date here, bestie. 💖