1OCAMLRUN(1)                 General Commands Manual                OCAMLRUN(1)
2
3
4

NAME

6       ocamlrun - The OCaml bytecode interpreter
7
8

SYNOPSIS

10       ocamlrun [ options ] filename argument ...
11
12

DESCRIPTION

14       The ocamlrun(1) command executes bytecode files produced by the linking
15       phase of the ocamlc(1) command.
16
17       The first non-option argument is taken to be the name of the file  con‐
18       taining  the  executable  bytecode.  (That file is searched in the exe‐
19       cutable path as well as in the current directory.) The remaining  argu‐
20       ments  are  passed  to the OCaml program, in the string array Sys.argv.
21       Element 0 of this array is the name of the  bytecode  executable  file;
22       elements 1 to n are the remaining arguments.
23
24       In  most cases, the bytecode executable files produced by the ocamlc(1)
25       command are self-executable, and manage to launch the ocamlrun(1)  com‐
26       mand on themselves automatically.
27
28

OPTIONS

30       The following command-line options are recognized by ocamlrun(1).
31
32       -b     When  the  program  aborts due to an uncaught exception, print a
33              detailed "back trace" of the execution, showing where the excep‐
34              tion  was  raised  and  which function calls were outstanding at
35              this point.  The back trace is printed only if the bytecode exe‐
36              cutable  contains  debugging  information, i.e. was compiled and
37              linked with the -g option to  ocamlc(1)  set.   This  option  is
38              equivalent  to  setting the b flag in the OCAMLRUNPARAM environ‐
39              ment variable (see below).
40
41       -I dir Search the directory dir for  dynamically-loaded  libraries,  in
42              addition to the standard search path.
43
44       -p     Print  the  names  of  the  primitives  known to this version of
45              ocamlrun(1) and exit.
46
47       -v     Direct the memory manager to print verbose messages on  standard
48              error.   This is equivalent to setting v=63 in the OCAMLRUNPARAM
49              environment variable (see below).
50
51       -version
52              Print version string and exit.
53
54       -vnum  Print short version number and exit.
55
56

ENVIRONMENT VARIABLES

58       The following environment variable are also consulted:
59
60       CAML_LD_LIBRARY_PATH
61              Additional directories  to  search  for  dynamically-loaded  li‐
62              braries.
63
64       OCAMLLIB
65              The directory containing the OCaml standard library.  (If OCAML‐
66              LIB is not set, CAMLLIB will be used instead.)  Used  to  locate
67              the ld.conf configuration file for dynamic loading.  If not set,
68              default to the library directory specified when compiling OCaml.
69
70       OCAMLRUNPARAM
71              Set the runtime system options and  garbage  collection  parame‐
72              ters.   (If  OCAMLRUNPARAM is not set, CAMLRUNPARAM will be used
73              instead.)  This variable must be a sequence of parameter  speci‐
74              fications  separated  by commas.  A parameter specification is a
75              letter, optionally followed by an = sign, a decimal number (or a
76              hexadecimal  number prefixed by 0x), and an optional multiplier.
77              If the letter is followed by anything  else,  the  corresponding
78              option  is  set  to 1. Unknown letters are ignored.  The options
79              are documented below; the last six correspond to the  fields  of
80              the  control record documented in The OCaml user's manual, chap‐
81              ter "Standard Library", section "Gc".
82
83
84       b      Trigger the printing of a stack backtrace when an  uncaught  ex‐
85              ception aborts the program.  This option takes no argument.
86
87       p      Turn on debugging support for ocamlyacc-generated parsers.  When
88              this option is on, the  pushdown  automaton  that  executes  the
89              parsers prints a trace of its actions.  This option takes no ar‐
90              gument.
91
92       R      Turn on randomization of all hash tables  by  default  (see  the
93              Hashtbl  module  of  the standard library). This option takes no
94              argument.
95
96       h      The initial size of the major heap (in words).
97
98       a (allocation_policy)
99              The policy used for allocating in the OCaml heap.  Possible val‐
100              ues  are  0 for the next-fit policy, 1 for the first-fit policy,
101              and 2 for the best-fit policy. Best-fit is  still  experimental,
102              but  probably  the best of the three. The default is 0.  See the
103              Gc module documentation for details.
104
105       s (minor_heap_size)
106              The size of the minor heap (in words).
107
108       i (major_heap_increment)
109              The default size increment for the major heap (in words).
110
111       o (space_overhead)
112              The major GC speed setting.
113
114       O (max_overhead)
115              The heap compaction trigger setting.
116
117       l (stack_limit)
118              The limit (in words) of the stack size.
119
120       M (custom_major_ratio)
121              Target ratio of floating garbage to major heap size for  out-of-
122              heap memory held by custom values located in the major heap. The
123              GC speed is adjusted to try to use this  much  memory  for  dead
124              values  that are not yet collected. Expressed as a percentage of
125              major heap size.  The default value keeps the out-of-heap float‐
126              ing  garbage about the same size as the in-heap overhead.  Note:
127              this only applies to values allocated with caml_alloc_custom_mem
128              (e.g. bigarrays).  Default: 44.
129
130       m (custom_minor_ratio)
131              Bound  on floating garbage for out-of-heap memory held by custom
132              values in the minor heap. A minor GC is triggered when this much
133              memory  is  held by custom values located in the minor heap. Ex‐
134              pressed as a percentage of minor heap size.  Note: this only ap‐
135              plies  to  values allocated with caml_alloc_custom_mem (e.g. bi‐
136              garrays).
137               Default: 100.
138
139       n (custom_minor_max_size)
140              Maximum amount of out-of-heap memory for each custom value allo‐
141              cated in the minor heap. When a custom value is allocated on the
142              minor heap and holds more than this many bytes, only this  value
143              is  counted  against custom_minor_ratio and the rest is directly
144              counted against custom_major_ratio.  Note: this only applies  to
145              values  allocated  with  caml_alloc_custom_mem (e.g. bigarrays).
146              Default: 8192 bytes.
147
148       v (verbose)
149              What GC messages to print to stderr.  This is a  sum  of  values
150              selected from the following:
151
152              0x001 Start and end of major GC cycle.
153
154              0x002 Minor collection and major GC slice.
155
156              0x004 Growing and shrinking of the heap.
157
158              0x008 Resizing of stacks and memory manager tables.
159
160              0x010 Heap compaction.
161
162              0x020 Change of GC parameters.
163
164              0x040 Computation of major GC slice size.
165
166              0x080 Calling of finalisation functions.
167
168              0x100  Startup  messages  (loading the bytecode executable file,
169              resolving shared libraries).
170
171              0x200 Computation of compaction-triggering condition.
172
173              0x400 Output GC statistics at program exit, in the  same  format
174              as Gc.print_stat.
175
176              The  multiplier is k, M, or G, for multiplication by 2^10, 2^20,
177              and 2^30 respectively.
178
179              If the option letter is not recognized, the whole  parameter  is
180              ignored;  if  the equal sign or the number is missing, the value
181              is taken as 1; if the multiplier is not recognized,  it  is  ig‐
182              nored.
183
184              For  example, on a 32-bit machine under bash, the command export
185              OCAMLRUNPARAM='s=256k,v=1' tells a subsequent  ocamlrun  to  set
186              its initial minor heap size to 1 megabyte and to print a message
187              at the start of each major GC cycle.
188
189       CAMLRUNPARAM
190              If OCAMLRUNPARAM is not found in the environment, then  CAMLRUN‐
191              PARAM  will be used instead.  If CAMLRUNPARAM is also not found,
192              then the default values will be used.
193
194       PATH   List of directories searched to  find  the  bytecode  executable
195              file.
196
197

SEE ALSO

199       ocamlc(1).
200       The OCaml user's manual, chapter "Runtime system".
201
202
203
204                                                                   OCAMLRUN(1)
Impressum