Chapter 10 |
The runtime system (ocamlrun) |
|
The ocamlrun command executes bytecode files produced by the
linking phase of the ocamlc command.
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, in most cases, 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.
The following command-line option is recognized by ocamlrun.
- -v
-
When set, the memory manager prints some verbose messages on
standard error.
The following environment variables are also consulted:
-
OCAMLRUNPARAM
- Set the 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
seven options, the first six correspond to the fields of the
control record documented in section 19.9:
-
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.
- 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='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.
- PATH
- List of directories searched to find the bytecode
executable file.
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, but not its arguments.
- 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. 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.