1OCAMLRUN(1) General Commands Manual OCAMLRUN(1)
2
3
4
6 ocamlrun - The OCaml bytecode interpreter
7
8
10 ocamlrun [ options ] filename argument ...
11
12
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
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
58 The following environment variable are also consulted:
59
60 CAML_LD_LIBRARY_PATH
61 Additional directories to search for dynamically-loaded
62 libraries.
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
85 exception 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
90 argument.
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.
134 Expressed as a percentage of minor heap size. Note: this only
135 applies to values allocated with caml_alloc_custom_mem (e.g.
136 bigarrays).
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 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
182 ignored.
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
199 ocamlc(1).
200 The OCaml user's manual, chapter "Runtime system".
201
202
203
204 OCAMLRUN(1)