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
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, and 1 for the first-fit pol‐
101              icy.  Next-fit is usually faster, but first-fit  is  better  for
102              avoiding fragmentation and the associated heap compactions.
103
104       s (minor_heap_size)
105              The size of the minor heap (in words).
106
107       i (major_heap_increment)
108              The default size increment for the major heap (in words).
109
110       o (space_overhead)
111              The major GC speed setting.
112
113       O (max_overhead)
114              The heap compaction trigger setting.
115
116       l (stack_limit)
117              The limit (in words) of the stack size.
118
119       M (custom_major_ratio)
120              Target  ratio of floating garbage to major heap size for out-of-
121              heap memory held by custom values located in the major heap. The
122              GC  speed  is  adjusted  to try to use this much memory for dead
123              values that are not yet collected. Expressed as a percentage  of
124              major heap size.  The default value keeps the out-of-heap float‐
125              ing garbage about the same size as the in-heap overhead.   Note:
126              this only applies to values allocated with caml_alloc_custom_mem
127              (e.g. bigarrays).  Default: 44.
128
129       m (custom_minor_ratio)
130              Bound on floating garbage for out-of-heap memory held by  custom
131              values in the minor heap. A minor GC is triggered when this much
132              memory is held by custom  values  located  in  the  minor  heap.
133              Expressed  as  a percentage of minor heap size.  Note: this only
134              applies to values  allocated  with  caml_alloc_custom_mem  (e.g.
135              bigarrays).
136               Default: 100.
137
138       n (custom_minor_max_size)
139              Maximum amount of out-of-heap memory for each custom value allo‐
140              cated in the minor heap. When a custom value is allocated on the
141              minor  heap and holds more than this many bytes, only this value
142              is counted against custom_minor_ratio and the rest  is  directly
143              counted  against custom_major_ratio.  Note: this only applies to
144              values allocated with  caml_alloc_custom_mem  (e.g.  bigarrays).
145              Default: 8192 bytes.
146
147       v (verbose)
148              What  GC  messages  to print to stderr.  This is a sum of values
149              selected from the following:
150
151              0x001 Start of major GC cycle.
152
153              0x002 Minor collection and major GC slice.
154
155              0x004 Growing and shrinking of the heap.
156
157              0x008 Resizing of stacks and memory manager tables.
158
159              0x010 Heap compaction.
160
161              0x020 Change of GC parameters.
162
163              0x040 Computation of major GC slice size.
164
165              0x080 Calling of finalisation functions.
166
167              0x100 Startup messages (loading the  bytecode  executable  file,
168              resolving shared libraries).
169
170              0x200 Computation of compaction-triggering condition.
171
172              0x400  Output  GC statistics at program exit, in the same format
173              as Gc.print_stat.
174
175              The multiplier is k, M, or G, for multiplication by 2^10,  2^20,
176              and 2^30 respectively.
177
178              If  the  option letter is not recognized, the whole parameter is
179              ignored; if the equal sign or the number is missing,  the  value
180              is  taken  as  1;  if  the  multiplier  is not recognized, it is
181              ignored.
182
183              For example, on a 32-bit machine under bash, the command  export
184              OCAMLRUNPARAM='s=256k,v=1'  tells  a  subsequent ocamlrun to set
185              its initial minor heap size to 1 megabyte and to print a message
186              at the start of each major GC cycle.
187
188       CAMLRUNPARAM
189              If  OCAMLRUNPARAM is not found in the environment, then CAMLRUN‐
190              PARAM will be used instead.  If CAMLRUNPARAM is also not  found,
191              then the default values will be used.
192
193       PATH   List  of  directories  searched  to find the bytecode executable
194              file.
195
196

SEE ALSO

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