/
ocamlrun.m
276 lines (252 loc) · 8.13 KB
/
ocamlrun.m
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
.\"**************************************************************************
.\"* *
.\"* OCaml *
.\"* *
.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt *
.\"* *
.\"* Copyright 1996 Institut National de Recherche en Informatique et *
.\"* en Automatique. *
.\"* *
.\"* All rights reserved. This file is distributed under the terms of *
.\"* the GNU Lesser General Public License version 2.1, with the *
.\"* special exception on linking described in the file LICENSE. *
.\"* *
.\"**************************************************************************
.\"
.TH OCAMLRUN 1
.SH NAME
ocamlrun \- The OCaml bytecode interpreter
.SH SYNOPSIS
.B ocamlrun
[
.I options
]
.I filename argument ...
.SH DESCRIPTION
The
.BR ocamlrun (1)
command executes bytecode files produced by the
linking phase of the
.BR ocamlc (1)
command.
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 OCaml program, in the string array
.BR Sys.argv .
Element 0 of this array is the name of the
bytecode executable file; elements 1 to
.I n
are the remaining arguments.
In most cases, the bytecode
executable files produced by the
.BR ocamlc (1)
command are self-executable,
and manage to launch the
.BR ocamlrun (1)
command on themselves automatically.
.SH OPTIONS
The following command-line options are recognized by
.BR ocamlrun (1).
.TP
.B \-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
.B \-g
option to
.BR ocamlc (1)
set. This option is equivalent to setting the
.B b
flag in the OCAMLRUNPARAM environment variable (see below).
.TP
.BI \-I \ dir
Search the directory
.I dir
for dynamically-loaded libraries, in addition to the standard search path.
.TP
.B \-p
Print the names of the primitives known to this version of
.BR ocamlrun (1)
and exit.
.TP
.B \-v
Direct the memory manager to print verbose messages on standard error.
This is equivalent to setting
.B v=63
in the OCAMLRUNPARAM environment variable (see below).
.TP
.B \-version
Print version string and exit.
.TP
.B \-vnum
Print short version number and exit.
.SH ENVIRONMENT VARIABLES
The following environment variable are also consulted:
.TP
.B CAML_LD_LIBRARY_PATH
Additional directories to search for dynamically-loaded libraries.
.TP
.B OCAMLLIB
The directory containing the OCaml standard
library. (If
.B OCAMLLIB
is not set,
.B CAMLLIB
will be used instead.) Used to locate the ld.conf configuration file for
dynamic loading. If not set,
default to the library directory specified when compiling OCaml.
.TP
.B 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 separated
by commas.
A parameter specification is a letter, optionally followed by an =
sign, a decimal number (or a hexadecimal number prefixed by
.BR 0x ),
and an optional multiplier. If the letter is followed by anything
else, the corresponding option is set to 1. Unknown letters
are ignored.
The options are documented below; the
last six correspond to the fields of the
.B control
record documented in
.IR "The OCaml user's manual",
chapter "Standard Library", section "Gc".
\" FIXME missing: c, H, t, w, W see MPR#7870
.TP
.B b
Trigger the printing of a stack backtrace
when an uncaught exception aborts the program.
This option takes no argument.
.TP
.B p
Turn on debugging support for
.BR ocamlyacc -generated
parsers. When this option is on,
the pushdown automaton that executes the parsers prints a
trace of its actions. This option takes no argument.
.TP
.BR R
Turn on randomization of all hash tables by default (see the
.B Hashtbl
module of the standard library). This option takes no
argument.
.TP
.BR h
The initial size of the major heap (in words).
.TP
.BR a \ (allocation_policy)
The policy used for allocating in the OCaml heap. Possible values
are 0 for the next-fit policy, 1 for the first-fit
policy, and 2 for the best-fit policy. Best-fit is still experimental,
but probably the best of the three. The default is 0.
See the Gc module documentation for details.
.TP
.BR s \ (minor_heap_size)
The size of the minor heap (in words).
.TP
.BR i \ (major_heap_increment)
The default size increment for the major heap (in words).
.TP
.BR o \ (space_overhead)
The major GC speed setting.
.TP
.BR O \ (max_overhead)
The heap compaction trigger setting.
.TP
.BR l \ (stack_limit)
The limit (in words) of the stack size.
.TP
.BR M \ (custom_major_ratio)
Target ratio of floating garbage to
major heap size for out-of-heap memory held by custom values
located in the major heap. The GC speed is adjusted
to try to use this much memory for dead values that are not yet
collected. Expressed as a percentage of major heap size.
The default value keeps the out-of-heap floating garbage about the
same size as the in-heap overhead.
Note: this only applies to values allocated with
.B caml_alloc_custom_mem
(e.g. bigarrays).
Default: 44.
.TP
.BR m \ (custom_minor_ratio)
Bound on floating garbage for out-of-heap memory
held by custom values in the minor heap. A minor GC is triggered
when this much memory is held by custom values located in the minor
heap. Expressed as a percentage of minor heap size.
Note: this only applies to values allocated with
.B caml_alloc_custom_mem
(e.g. bigarrays).
Default: 100.
.TP
.BR n \ (custom_minor_max_size)
Maximum amount of out-of-heap
memory for each custom value allocated in the minor heap. When a custom
value is allocated on the minor heap and holds more than this many
bytes, only this value is counted against
.B custom_minor_ratio
and the rest is directly counted against
.BR custom_major_ratio .
Note: this only applies to values allocated with
.B caml_alloc_custom_mem
(e.g. bigarrays).
Default: 8192 bytes.
.TP
.BR v \ (verbose)
What GC messages to print to stderr. This is a sum of values selected
from the following:
.B 0x001
Start and end of major GC cycle.
.B 0x002
Minor collection and major GC slice.
.B 0x004
Growing and shrinking of the heap.
.B 0x008
Resizing of stacks and memory manager tables.
.B 0x010
Heap compaction.
.BR 0x020
Change of GC parameters.
.BR 0x040
Computation of major GC slice size.
.BR 0x080
Calling of finalisation functions.
.BR 0x100
Startup messages (loading the bytecode executable file, resolving
shared libraries).
.BR 0x200
Computation of compaction-triggering condition.
.BR 0x400
Output GC statistics at program exit, in the same format as Gc.print_stat.
The multiplier is
.BR k ,
.BR M ,\ or
.BR G ,
for multiplication by 2^10, 2^20, and 2^30 respectively.
If the option letter is not recognized, the whole parameter is ignored;
if the equal sign or the number is missing, the value is taken as 1;
if the multiplier is not recognized, it is ignored.
For example, on a 32-bit machine under bash, the command
.B export OCAMLRUNPARAM='s=256k,v=1'
tells a subsequent
.B ocamlrun
to set its initial minor heap size to 1 megabyte and to print
a message at the start of each major GC cycle.
.TP
.B CAMLRUNPARAM
If OCAMLRUNPARAM is not found in the environment, then CAMLRUNPARAM
will be used instead. If CAMLRUNPARAM is also not found, then the default
values will be used.
.TP
.B PATH
List of directories searched to find the bytecode executable file.
.SH SEE ALSO
.BR ocamlc (1).
.br
.IR "The OCaml user's manual" ,
chapter "Runtime system".