OCAMLRUN(1) User Commands OCAMLRUN(1)

NAME

ocamlrun - The OCaml bytecode interpreter

SYNOPSIS

ocamlrun [ options ] filename argument ...

DESCRIPTION

The ocamlrun(1) command executes bytecode files produced by the
linking phase of the ocamlc(1) command.

The first non-option argument is taken to be 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 are 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.

OPTIONS

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

-b When the program aborts due to an uncaught exception, print a
detailed "back trace" of the execution, showing where the
exception was raised and which function calls were outstanding
at this point. The back trace is printed only if the bytecode
executable contains debugging information, i.e. 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 variable 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 a,
i, l, m, M, n, o, O, s, v, w correspond to the fields of the
control record documented in The OCaml user's manual, chapter
"Standard Library", section "Gc".


a (allocation_policy)
The policy used for allocating in the OCaml heap.
Possible values are 0 for the next-fit policy, 1 for
the first-fit policy, and 2 for the best-fit policy.
The default is 2. See the Gc module documentation for
details.

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.

h The initial size of the major heap (in words).

H Allocate heap chunks by mmapping huge pages. Huge pages
are locked into memory, and are not swapped.

i (major_heap_increment)
The default size increment for the major heap (in words
if greater than 1000, else in percents of the heap
size).

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 major GC speed setting.

O (max_overhead)
The heap compaction trigger 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.

w (window_size)
Set size of the window used by major GC for smoothing
out variations in its workload. This is an integer
between 1 and 50. (Default: 1)

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.

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".

OCAMLRUN(1)