1OCAMLRUN(1) General Commands Manual OCAMLRUN(1)
2
6 ocamlrun - The OCaml bytecode interpreter
7
10 ocamlrun [ options ] filename argument ...
11
14 The ocamlrun(1) command executes bytecode files produced by the linking
15 phase of the ocamlc(1) command.
16 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 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
30 The following command-line options are recognized by ocamlrun(1).
31 -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 -I dir Search the directory dir for dynamically-loaded libraries, in
42 addition to the standard search path.
43 -m file
45 Print the magic number of the bytecode executable file and exit.
46 -M Print the magic number expected for bytecode executables by this
48 version of the runtime and exit.
49 -p Print the names of the primitives known to this version of
51 ocamlrun(1) and exit.
52 -t Increment the trace level for the debug runtime (ignored by the
54 standard runtime).
55 -v Direct the memory manager to print verbose messages on standard
57 error. This is equivalent to setting v=63 in the OCAMLRUNPARAM
58 environment variable (see below).
59 -version
61 Print version string and exit.
62 -vnum Print short version number and exit.
64
67 The following environment variable are also consulted:
68 CAML_LD_LIBRARY_PATH
70 Additional directories to search for dynamically-loaded li‐
71 braries.
72 OCAMLLIB
74 The directory containing the OCaml standard library. (If OCAML‐
75 LIB is not set, CAMLLIB will be used instead.) Used to locate
76 the ld.conf configuration file for dynamic loading. If not set,
77 default to the library directory specified when compiling OCaml.
78 OCAMLRUNPARAM
80 Set the runtime system options and garbage collection parame‐
81 ters. (If OCAMLRUNPARAM is not set, CAMLRUNPARAM will be used
82 instead.) This variable must be a sequence of parameter speci‐
83 fications separated by commas. A parameter specification is a
84 letter, optionally followed by an = sign, a decimal number (or a
85 hexadecimal number prefixed by 0x), and an optional multiplier.
86 If the letter is followed by anything else, the corresponding
87 option is set to 1. Unknown letters are ignored. The options
88 are documented below; the options a, i, l, m, M, n, o, O, s, v,
89 w correspond to the fields of the control record documented in
90 The OCaml user's manual, chapter "Standard Library", section
91 "Gc".
92 a (allocation_policy)
95 The policy used for allocating in the OCaml heap. Possi‐
96 ble values are 0 for the next-fit policy, 1 for the
97 first-fit policy, and 2 for the best-fit policy. The de‐
98 fault is 2. See the Gc module documentation for details.
99 b Trigger the printing of a stack backtrace when an un‐
101 caught exception aborts the program. This option takes
102 no argument.
103 c (cleanup_on_exit) Shut the runtime down gracefully on
105 exit. The option also enables pooling (as in
106 caml_startup_pooled). This mode can be used to detect
107 leaks with a third-party memory debugger.
108 h The initial size of the major heap (in words).
110 H Allocate heap chunks by mmapping huge pages. Huge pages
112 are locked into memory, and are not swapped.
113 i (major_heap_increment)
115 The default size increment for the major heap (in words
116 if greater than 1000, else in percents of the heap size).
117 l (stack_limit)
119 The limit (in words) of the stack size.
120 m (custom_minor_ratio)
122 Bound on floating garbage for out-of-heap memory held by
123 custom values in the minor heap. A minor GC is triggered
124 when this much memory is held by custom values located in
125 the minor heap. Expressed as a percentage of minor heap
126 size. Note: this only applies to values allocated with
127 caml_alloc_custom_mem (e.g. bigarrays).
128 Default: 100.
129 M (custom_major_ratio)
131 Target ratio of floating garbage to major heap size for
132 out-of-heap memory held by custom values located in the
133 major heap. The GC speed is adjusted to try to use this
134 much memory for dead values that are not yet collected.
135 Expressed as a percentage of major heap size. The de‐
136 fault value keeps the out-of-heap floating garbage about
137 the same size as the in-heap overhead. Note: this only
138 applies to values allocated with caml_alloc_custom_mem
139 (e.g. bigarrays). Default: 44.
140 n (custom_minor_max_size)
142 Maximum amount of out-of-heap memory for each custom
143 value allocated in the minor heap. When a custom value is
144 allocated on the minor heap and holds more than this many
145 bytes, only this value is counted against custom_mi‐
146 nor_ratio and the rest is directly counted against cus‐
147 tom_major_ratio. Note: this only applies to values allo‐
148 cated with caml_alloc_custom_mem (e.g. bigarrays). De‐
149 fault: 8192 bytes.
150 o (space_overhead)
152 The major GC speed setting.
153 O (max_overhead)
155 The heap compaction trigger setting.
156 p Turn on debugging support for ocamlyacc-generated
158 parsers. When this option is on, the pushdown automaton
159 that executes the parsers prints a trace of its actions.
160 This option takes no argument.
161 R Turn on randomization of all hash tables by default (see
163 the Hashtbl module of the standard library). This option
164 takes no argument.
165 s (minor_heap_size)
167 The size of the minor heap (in words).
168 t Set the trace level for the debug runtime (ignored by the
170 standard runtime).
171 v (verbose)
173 What GC messages to print to stderr. This is a sum of
174 values selected from the following:
175 0x001 Start and end of major GC cycle.
177 0x002 Minor collection and major GC slice.
179 0x004 Growing and shrinking of the heap.
181 0x008 Resizing of stacks and memory manager tables.
183 0x010 Heap compaction.
185 0x020 Change of GC parameters.
187 0x040 Computation of major GC slice size.
189 0x080 Calling of finalisation functions.
191 0x100 Startup messages (loading the bytecode executable
193 file, resolving shared libraries).
194 0x200 Computation of compaction-triggering condition.
196 0x400 Output GC statistics at program exit, in the same
198 format as Gc.print_stat.
199 w (window_size)
201 Set size of the window used by major GC for smoothing out
202 variations in its workload. This is an integer between 1
203 and 50. (Default: 1)
204 W Print runtime warnings to stderr (such as Channel opened
206 on file dies without being closed, unflushed data, etc.)
207 The multiplier is k, M, or G, for multiplication by 2^10, 2^20,
209 and 2^30 respectively.
210 If the option letter is not recognized, the whole parameter is
212 ignored; if the equal sign or the number is missing, the value
213 is taken as 1; if the multiplier is not recognized, it is ig‐
214 nored.
215 For example, on a 32-bit machine under bash, the command export
217 OCAMLRUNPARAM='s=256k,v=1' tells a subsequent ocamlrun to set
218 its initial minor heap size to 1 megabyte and to print a message
219 at the start of each major GC cycle.
220 CAMLRUNPARAM
222 If OCAMLRUNPARAM is not found in the environment, then
223 CAMLRUNPARAM will be used instead. If CAMLRUNPARAM is
224 also not found, then the default values will be used.
225 PATH List of directories searched to find the bytecode exe‐
227 cutable file.
228
231 ocamlc(1).
232 The OCaml user's manual, chapter "Runtime system".
233 OCAMLRUN(1)