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
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="manual.css">
<TITLE>
The runtime system (ocamlrun)
</TITLE>
</HEAD>
<BODY >
<A HREF="manual023.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual025.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H1 CLASS="chapter"><A NAME="htoc115">Chapter 10</A> The runtime system (ocamlrun)</H1> <A NAME="c:runtime"></A>
The <TT>ocamlrun</TT> command executes bytecode files produced by the
linking phase of the <TT>ocamlc</TT> command.<BR>
<BR>
<H2 CLASS="section"><A NAME="htoc116">10.1</A> Overview</H2>
The <TT>ocamlrun</TT> command comprises three main parts: the bytecode
interpreter, that actually executes bytecode files; the memory
allocator and garbage collector; and a set of C functions that
implement primitive operations such as input/output.<BR>
<BR>
The usage for <TT>ocamlrun</TT> is:
<PRE>
ocamlrun <I>options bytecode-executable arg</I><SUB>1</SUB> ... <I>arg<SUB>n</SUB></I>
</PRE>
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 Caml program, in the string array
<TT>Sys.argv</TT>. Element 0 of this array is the name of the
bytecode executable file; elements 1 to <I>n</I> are the remaining
arguments <I>arg</I><SUB>1</SUB> to <I>arg<SUB>n</SUB></I>.<BR>
<BR>
As mentioned in chapter <A HREF="manual022.html#c:camlc">8</A>, the bytecode executable files
produced by the <TT>ocamlc</TT> command are self-executable, and manage to
launch the <TT>ocamlrun</TT> command on themselves automatically. That is,
assuming <TT>caml.out</TT> is a bytecode executable file,
<PRE>
caml.out <I>arg</I><SUB>1</SUB> ... <I>arg<SUB>n</SUB></I>
</PRE>
works exactly as
<PRE>
ocamlrun caml.out <I>arg</I><SUB>1</SUB> ... <I>arg<SUB>n</SUB></I>
</PRE>
Notice that it is not possible to pass options to <TT>ocamlrun</TT> when
invoking <TT>caml.out</TT> directly.<BR>
<BR>
<FONT COLOR=purple>Windows:</FONT>
<BLOCKQUOTE CLASS="quote">
Under several versions of Windows, bytecode executable files are
self-executable only if their name ends in <TT>.exe</TT>. It is recommended
to always give <TT>.exe</TT> names to bytecode executables, e.g. compile
with <TT>ocamlc -o myprog.exe ...</TT> rather than <TT>ocamlc -o myprog ...</TT>.
</BLOCKQUOTE>
<H2 CLASS="section"><A NAME="htoc117">10.2</A> Options</H2> <A NAME="ocamlrun-options"></A>
The following command-line options are recognized by <TT>ocamlrun</TT>.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><TT><B>-b</B></TT><DD CLASS="dd-description">
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 <TT>-g</TT>
option to <TT>ocamlc</TT> set. This is equivalent to setting the <TT>b</TT> flag
in the <TT>OCAMLRUNPARAM</TT> environment variable (see below).
<DT CLASS="dt-description"><B><TT>-I</TT> <I>dir</I></B><DD CLASS="dd-description">
Search the directory <I>dir</I> for dynamically-loaded libraries,
in addition to the standard search path (see
section <A HREF="#s-ocamlrun-dllpath">10.3</A>).
<DT CLASS="dt-description"><TT><B>-v</B></TT><DD CLASS="dd-description">
Direct the memory manager to print some progress messages on
standard error. This is equivalent to setting <TT>v=63</TT> in the
<TT>OCAMLRUNPARAM</TT> environment variable (see below).
<DT CLASS="dt-description">
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
<TT><B>-version</B></TT><DD CLASS="dd-description">
Print version and exit.
</div>
</DL>
The following environment variables are also consulted:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<TT><B>CAML_LD_LIBRARY_PATH</B></TT><DD CLASS="dd-description"> Additional directories to search for
dynamically-loaded libraries (see section <A HREF="#s-ocamlrun-dllpath">10.3</A>).<BR>
<BR>
<DT CLASS="dt-description"><TT><B>OCAMLLIB</B></TT><DD CLASS="dd-description"> The directory containing the Objective Caml standard
library. (If <TT>OCAMLLIB</TT> is not set, <TT>CAMLLIB</TT> will be used instead.)
Used to locate the <TT>ld.conf</TT> configuration file for
dynamic loading (see section <A HREF="#s-ocamlrun-dllpath">10.3</A>). If not set,
default to the library directory specified when compiling Objective Caml.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>OCAMLRUNPARAM</B></TT><DD CLASS="dd-description"> Set the runtime system options
and garbage collection parameters.
(If <TT>OCAMLRUNPARAM</TT> is not set, <TT>CAMLRUNPARAM</TT> will be used instead.)
This variable must be a sequence of parameter specifications.
A parameter specification is an option letter followed by an <TT>=</TT>
sign, a decimal number (or an hexadecimal number prefixed by <TT>0x</TT>),
and an optional multiplier. There are
nine options, six of which correspond to the fields of the
<TT>control</TT> record documented in
<A HREF="libref/Gc.html">Module <TT>Gc</TT></A>.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>b</B><DD CLASS="dd-description"> (backtrace) Trigger the printing of a stack backtrace
when an uncaught exception aborts the program.
This option takes no argument.
<DT CLASS="dt-description"><B>p</B><DD CLASS="dd-description"> (parser trace) Turn on debugging support for
<TT>ocamlyacc</TT>-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.
<DT CLASS="dt-description"><B>s</B><DD CLASS="dd-description"> (<TT>minor_heap_size</TT>) Size of the minor heap. (in words)
<DT CLASS="dt-description"><B>i</B><DD CLASS="dd-description"> (<TT>major_heap_increment</TT>) Default size increment for the
major heap. (in words)
<DT CLASS="dt-description"><B>o</B><DD CLASS="dd-description"> (<TT>space_overhead</TT>) The major GC speed setting.
<DT CLASS="dt-description"><B>O</B><DD CLASS="dd-description"> (<TT>max_overhead</TT>) The heap compaction trigger setting.
<DT CLASS="dt-description"><B>v</B><DD CLASS="dd-description"> (<TT>verbose</TT>) What GC messages to print to stderr. This
is a sum of values selected from the following:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>1 (= 0x001)</B><DD CLASS="dd-description"> Start of major GC cycle.
<DT CLASS="dt-description"><B>2 (= 0x002)</B><DD CLASS="dd-description"> Minor collection and major GC slice.
<DT CLASS="dt-description"><B>4 (= 0x004)</B><DD CLASS="dd-description"> Growing and shrinking of the heap.
<DT CLASS="dt-description"><B>8 (= 0x008)</B><DD CLASS="dd-description"> Resizing of stacks and memory manager tables.
<DT CLASS="dt-description"><B>16 (= 0x010)</B><DD CLASS="dd-description"> Heap compaction.
<DT CLASS="dt-description"><B>32 (= 0x020)</B><DD CLASS="dd-description"> Change of GC parameters.
<DT CLASS="dt-description"><B>64 (= 0x040)</B><DD CLASS="dd-description"> Computation of major GC slice size.
<DT CLASS="dt-description"><B>128 (= 0x080)</B><DD CLASS="dd-description"> Calling of finalisation functions
<DT CLASS="dt-description"><B>256 (= 0x100)</B><DD CLASS="dd-description"> Startup messages (loading the bytecode
executable file, resolving shared libraries).
</DL>
<DT CLASS="dt-description"><B>l</B><DD CLASS="dd-description"> (<TT>stack_limit</TT>) The limit (in words) of the stack size.
<DT CLASS="dt-description"><B>h</B><DD CLASS="dd-description"> The initial size of the major heap (in words).
</DL>
The multiplier is <TT>k</TT>, <TT>M</TT>, or <TT>G</TT>, for multiplication by 2<SUP>10</SUP>,
2<SUP>20</SUP>, and 2<SUP>30</SUP> respectively.
For example, on a 32-bit machine, under <TT>bash</TT> the command
<PRE>
export OCAMLRUNPARAM='b,s=256k,v=0x015'
</PRE>
tells a subsequent <TT>ocamlrun</TT> to print backtraces for uncaught exceptions,
set its initial minor heap size to 1 megabyte and
print a message at the start of each major GC cycle, when the heap
size changes, and when compaction is triggered.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>CAMLRUNPARAM</B></TT><DD CLASS="dd-description"> If <TT>OCAMLRUNPARAM</TT> is not found in the
environment, then <TT>CAMLRUNPARAM</TT> will be used instead. If
<TT>CAMLRUNPARAM</TT> is not found, then the default values will be used.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>PATH</B></TT><DD CLASS="dd-description"> List of directories searched to find the bytecode
executable file.
</DL>
<H2 CLASS="section"><A NAME="htoc118">10.3</A> Dynamic loading of shared libraries</H2> <A NAME="s-ocamlrun-dllpath"></A>
On platforms that support dynamic loading, <TT>ocamlrun</TT> can link
dynamically with C shared libraries (DLLs) providing additional C primitives
beyond those provided by the standard runtime system. The names for
these libraries are provided at link time as described in
section <A HREF="manual032.html#dynlink-c-code">18.1.4</A>), and recorded in the bytecode executable
file; <TT>ocamlrun</TT>, then, locates these libraries and resolves references
to their primitives when the bytecode executable program starts.<BR>
<BR>
The <TT>ocamlrun</TT> command searches shared libraries in the following
directories, in the order indicated:
<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
Directories specified on the <TT>ocamlrun</TT> command line with the
<TT>-I</TT> option.
<LI CLASS="li-enumerate">Directories specified in the <TT>CAML_LD_LIBRARY_PATH</TT> environment
variable.
<LI CLASS="li-enumerate">Directories specified at link-time via the <TT>-dllpath</TT> option to
<TT>ocamlc</TT>. (These directories are recorded in the bytecode executable
file.)
<LI CLASS="li-enumerate">Directories specified in the file <TT>ld.conf</TT>. This file resides
in the Objective Caml standard library directory, and lists directory
names (one per line) to be searched. Typically, it contains only one
line naming the <TT>stublibs</TT> subdirectory of the Objective Caml standard
library directory. Users can add there the names of other directories
containing frequently-used shared libraries; however, for consistency
of installation, we recommend that shared libraries are installed
directly in the system <TT>stublibs</TT> directory, rather than adding lines
to the <TT>ld.conf</TT> file.
<LI CLASS="li-enumerate">Default directories searched by the system dynamic loader.
Under Unix, these generally include <TT>/lib</TT> and <TT>/usr/lib</TT>, plus the
directories listed in the file <TT>/etc/ld.so.conf</TT> and the environment
variable <TT>LD_LIBRARY_PATH</TT>. Under Windows, these include the Windows
system directories, plus the directories listed in the <TT>PATH</TT>
environment variable.
</OL>
<H2 CLASS="section"><A NAME="htoc119">10.4</A> Common errors</H2>
This section describes and explains the most frequently encountered
error messages.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><B><I>filename</I><TT>: no such file or directory</TT></B><DD CLASS="dd-description">
If <I>filename</I> is the name of a self-executable bytecode file, this
means that either that file does not exist, or that it failed to run
the <TT>ocamlrun</TT> bytecode interpreter on itself. The second possibility
indicates that Objective Caml has not been properly installed on your
system.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>Cannot exec ocamlrun</B></TT><DD CLASS="dd-description">
(When launching a self-executable bytecode file.) The <TT>ocamlrun</TT>
could not be found in the executable path. Check that Objective Caml
has been properly installed on your system.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>Cannot find the bytecode file</B></TT><DD CLASS="dd-description">
The file that <TT>ocamlrun</TT> is trying to execute (e.g. the file given as
first non-option argument to <TT>ocamlrun</TT>) either does not exist, or is
not a valid executable bytecode file.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>Truncated bytecode file</B></TT><DD CLASS="dd-description">
The file that <TT>ocamlrun</TT> is trying to execute is not a valid executable
bytecode file. Probably it has been truncated or mangled since
created. Erase and rebuild it.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>Uncaught exception</B></TT><DD CLASS="dd-description">
The program being executed contains a “stray” exception. That is,
it raises an exception at some point, and this exception is never
caught. This causes immediate termination of the program. The name of
the exception is printed, along with its string and integer arguments
(arguments of more complex types are not correctly printed).
To locate the context of the uncaught exception, compile the program
with the <TT>-g</TT> option and either run it again under the <TT>ocamldebug</TT>
debugger (see chapter <A HREF="manual030.html#c:debugger">16</A>), or run it with <TT>ocamlrun -b</TT>
or with the <TT>OCAMLRUNPARAM</TT> environment variable set to <TT>b=1</TT>.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>Out of memory</B></TT><DD CLASS="dd-description">
The program being executed requires more memory than available. Either
the program builds excessively large data structures; or the program
contains too many nested function calls, and the stack overflows. In
some cases, your program is perfectly correct, it just requires more
memory than your machine provides. In other cases, the “out of
memory” message reveals an error in your program: non-terminating
recursive function, allocation of an excessively large array or
string, attempts to build an infinite list or other data structure,
...<BR>
<BR>
To help you diagnose this error, run your program with the <TT>-v</TT> option
to <TT>ocamlrun</TT>, or with the <TT>OCAMLRUNPARAM</TT> environment variable set to
<TT>v=63</TT>. If it displays lots of “<TT>Growing stack</TT>...”
messages, this is probably a looping recursive function. If it
displays lots of “<TT>Growing heap</TT>...” messages, with the heap size
growing slowly, this is probably an attempt to construct a data
structure with too many (infinitely many?) cells. If it displays few
“<TT>Growing heap</TT>...” messages, but with a huge increment in the
heap size, this is probably an attempt to build an excessively large
array or string.</DL>
<HR>
<A HREF="manual023.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual025.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
|
