# The runtime system (camlrun)

The `camlrun` command executes bytecode files produced by the linking phase of the `camlc` command.

Mac:
  This command is a MPW tool, not a standalone Macintosh application.

## Overview

The `camlrun` 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 `camlrun` is:

            camlrun 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__command_line`. 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 5, in most cases, the bytecode executable files produced by the `camlc` command are self-executable, and manage to launch the `camlrun` command on themselves automatically. That is, assuming `caml.out` is a bytecode executable file,

            caml.out arg1 ... argn

works exactly as

            camlrun caml.out arg1 ... argn

Notice that it is not possible to pass options to `camlrun` when invoking `caml.out` directly.

## Options

The following command-line option is recognized by `camlrun`.

`-V`
  Print out the `camlrun` version number. Exit immediately without executing any byte-code file.

The following environment variable are also consulted:

`CAMLRUNPARAM`
  Set the garbage collection parameters. This variable must be a sequence of parameter specifications. A parameter specification is an option letter followed by an `=` sign and a decimal number. There are four options, corresponding to the four fields of the `control` record documented in section 15.6:

  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.
  v
    (`verbose`) Whether to print GC messages or not. 0 is false; 1 is true; other values may give unexpected results.
  For example, under `csh` the command

              setenv CAMLRUNPARAM 's=250000 v=1'

  tells a subsequent `camlrun` to set its initial minor heap size to about 1 megabyte (on a 32-bit machine) and to print its GC messages.

`PATH`
  List of directories searched to find the bytecode executable file.

## 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 `camlrun` bytecode interpreter on itself. The second possibility indicates that Caml Light has not been properly installed on your system.

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

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

`Truncated bytecode file`
  The file that `camlrun` 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. If you wish to know which exception thus escapes, use the `printexc__f` function from the standard library (and don't forget to link your program with the `-g` option).

`Out of memory`
  The program being executed requires more memory than available. Either the program builds too 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. (This happens quite frequently on small microcomputers, but is unlikely on Unix machines.) 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 `camlrun`. 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.