Previous Contents Next
Chapter 10 The runtime system (ocamlrun)

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

10.1 Overview

The ocamlrun command comprises three main parts: the bytecode interpreter, that actually executes bytecode files; the memory allocator and garbage collector; and a set of C functions that implement primitive operations such as input/output.

The usage for ocamlrun is:
        ocamlrun options bytecode-executable arg1 ... argn
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 Caml Light 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 arg1 to argn.

As mentioned in chapter 8, the bytecode executable files produced by the ocamlc command are self-executable, and manage to launch the ocamlrun command on themselves automatically. That is, assuming caml.out is a bytecode executable file,
        caml.out arg1 ... argn
works exactly as
        ocamlrun caml.out arg1 ... argn
Notice that it is not possible to pass options to ocamlrun when invoking caml.out directly.

  Windows:
Under several versions of Windows, bytecode executable files are self-executable only if their name ends in .exe. It is recommended to always give .exe names to bytecode executables, e.g. compile with ocamlc -o myprog.exe ... rather than ocamlc -o myprog ....
10.2 Options

The following command-line options are recognized by ocamlrun.

-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 set. This is equivalent to setting b=1 in the OCAMLRUNPARAM environment variable (see below).
-v
Direct the memory manager to print some progress messages on standard error. This is equivalent to setting v=63 in the OCAMLRUNPARAM environment variable (see below).
The following environment variables are also consulted:

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. A parameter specification is an option letter followed by an = sign, a decimal number, and an optional multiplier. There are eight options, six of which correspond to the fields of the control record documented in section 19.9.
b
(backtrace) Control the printing of a stack backtrace when an uncaught exception aborts the program. A non-zero argument turn the backtrace facility on; a zero argument turn it off.
s
(minor_heap_size) Size of the minor heap.
i
(major_heap_increment) Minimum size increment for the major heap.
o
(space_overhead) The major GC speed setting.
O
(max_overhead) The heap compaction trigger setting.
v
(verbose) What GC messages to print to stderr. This is a sum of values selected from the following:
1
Start of major GC cycle.
2
Minor collection and major GC slice.
4
Growing and shrinking of the heap.
8
Resizing of stacks and memory manager tables.
16
Heap compaction.
32
Change of GC parameters.
64
Computation of major GC slice size.
128
Calling of finalization functions
256
Startup messages (loading the bytecode executable file).
l
(stack_limit) The limit (in words) of the stack size.
h
The initial size of the major heap (in words).
The multiplier is k, M, or G, for multiplication by 210, 220, and 230 respectively. For example, on a 32-bit machine, under bash the command
        export OCAMLRUNPARAM='b=1,s=256k,v=1'
tells a subsequent ocamlrun to print backtraces for uncaught exceptions, set its initial minor heap size to 1 megabyte and print a message at the start of each major GC cycle.

PATH
List of directories searched to find the bytecode executable file.
10.3 Common errors

This section describes and explains the most frequently encountered error messages.

filename: no such file or directory
If filename is the name of a self-executable bytecode file, this means that either that file does not exist, or that it failed to run the ocamlrun bytecode interpreter on itself. The second possibility indicates that Objective Caml has not been properly installed on your system.

Cannot exec camlrun
(When launching a self-executable bytecode file.) The ocamlrun could not be found in the executable path. Check that Objective Caml has been properly installed on your system.

Cannot find the bytecode file
The file that ocamlrun is trying to execute (e.g. the file given as first non-option argument to ocamlrun) either does not exist, or is not a valid executable bytecode file.

Truncated bytecode file
The file that ocamlrun is trying to execute is not a valid executable bytecode file. Probably it has been truncated or mangled since created. Erase and rebuild it.

Uncaught exception
The program being executed contains a ``stray'' exception. That is, it raises an exception at some point, and this exception is never caught. This causes immediate termination of the program. The name of the exception is printed, along with its string and integer arguments (arguments of more complex types are not correctly printed). To locate the context of the uncaught exception, compile the program with the -g option and either run it again under the ocamldebug debugger (see chapter 15), or run it with ocamlrun -b or with the OCAMLRUNPARAM environment variable set to b=1.

Out of memory
The program being executed requires more memory than available. Either the program builds excessively large data structures; or the program contains too many nested function calls, and the stack overflows. In some cases, your program is perfectly correct, it just requires more memory than your machine provides. In other cases, the ``out of memory'' message reveals an error in your program: non-terminating recursive function, allocation of an excessively large array or string, attempts to build an infinite list or other data structure, ...

To help you diagnose this error, run your program with the -v option to ocamlrun, or with the OCAMLRUNPARAM environment variable set to v=63. If it displays lots of ``Growing stack...'' messages, this is probably a looping recursive function. If it displays lots of ``Growing heap...'' messages, with the heap size growing slowly, this is probably an attempt to construct a data structure with too many (infinitely many?) cells. If it displays few ``Growing heap...'' messages, but with a huge increment in the heap size, this is probably an attempt to build an excessively large array or string.

Previous Contents Next