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
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
|
<!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 toplevel system (ocaml)
</TITLE>
</HEAD>
<BODY >
<A HREF="manual022.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual024.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H1 CLASS="chapter"><A NAME="htoc108">Chapter 9</A> The toplevel system (ocaml)</H1> <A NAME="c:camllight"></A>
This chapter describes the toplevel system for Objective Caml, that permits interactive use of the Objective Caml system
through a read-eval-print loop. In this mode, the system repeatedly
reads Caml phrases from the input, then typechecks, compile and
evaluate them, then prints the inferred type and result value, if
any. The system prints a <TT>#</TT> (sharp) prompt before reading each
phrase.<BR>
<BR>
Input to the toplevel can span several lines. It is terminated by <TT>;;</TT> (a
double-semicolon). The toplevel input consists in one or several
toplevel phrases, with the following syntax:<BR>
<BR>
<DIV CLASS="center"><TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD ALIGN=right NOWRAP>
<A NAME="toplevel-input"></A>
<FONT COLOR=maroon><I><TT>toplevel-input</TT></I></FONT></TD>
<TD ALIGN=right NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP>
{ <FONT COLOR=maroon><I><a href="#toplevel-phrase"><font color=maroon><TT>toplevel-phrase</TT></font></a></I></FONT> } <FONT COLOR=blue><TT>;;</TT></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="toplevel-phrase"></A>
<FONT COLOR=maroon><I><TT>toplevel-phrase</TT></I></FONT></TD>
<TD ALIGN=right NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP>
<FONT COLOR=maroon><I><a href="#toplevel-definition"><font color=maroon><TT>toplevel-definition</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=maroon><I><a href="manual015.html#expr"><font color=maroon><TT>expr</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=blue><TT>#</TT></FONT> <FONT COLOR=maroon><I><a href="manual009.html#ident"><font color=maroon><TT>ident</TT></font></a> <a href="#directive-argument"><font color=maroon><TT>directive-argument</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="toplevel-definition"></A>
<FONT COLOR=maroon><I><TT>toplevel-definition</TT></I></FONT></TD>
<TD ALIGN=right NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP>
<FONT COLOR=blue><TT>let</TT></FONT> [<FONT COLOR=blue><TT>rec</TT></FONT>] <FONT COLOR=maroon><I><a href="manual015.html#let-binding"><font color=maroon><TT>let-binding</TT></font></a></I></FONT> { <FONT COLOR=blue><TT>and</TT></FONT> <FONT COLOR=maroon><I><a href="manual015.html#let-binding"><font color=maroon><TT>let-binding</TT></font></a></I></FONT> }</TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=blue><TT>external</TT></FONT> <FONT COLOR=maroon><TT><a href="manual011.html#value-name"><font color=maroon><I>value-name</I></font></a></TT> <FONT COLOR=blue><TT>:</TT></FONT> <TT><a href="manual012.html#typexpr"><font color=maroon><I>typexpr</I></font></a></TT> <FONT COLOR=blue><TT>=</TT></FONT> <TT><I>external-declaration</I></TT></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=maroon><I><a href="manual016.html#type-definition"><font color=maroon><TT>type-definition</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=maroon><I><a href="manual016.html#exception-definition"><font color=maroon><TT>exception-definition</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=blue><TT>module</TT></FONT> <FONT COLOR=maroon><I><a href="manual011.html#module-name"><font color=maroon><TT>module-name</TT></font></a></I></FONT> [ <FONT COLOR=blue><TT>:</TT></FONT> <FONT COLOR=maroon><I><a href="manual018.html#module-type"><font color=maroon><TT>module-type</TT></font></a></I></FONT> ] <FONT COLOR=blue><TT>=</TT></FONT> <FONT COLOR=maroon><I><a href="manual019.html#module-expr"><font color=maroon><TT>module-expr</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=blue><TT>module</TT></FONT> <FONT COLOR=blue><TT>type</TT></FONT> <FONT COLOR=maroon><TT><a href="manual011.html#modtype-name"><font color=maroon><I>modtype-name</I></font></a></TT> <FONT COLOR=blue><TT>=</TT></FONT> <TT><a href="manual018.html#module-type"><font color=maroon><I>module-type</I></font></a></TT></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=blue><TT>open</TT></FONT> <FONT COLOR=maroon><I><a href="manual011.html#module-path"><font color=maroon><TT>module-path</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP>
<A NAME="directive-argument"></A>
<FONT COLOR=maroon><I><TT>directive-argument</TT></I></FONT></TD>
<TD ALIGN=right NOWRAP>::=</TD>
<TD ALIGN=left NOWRAP>
<FONT COLOR=maroon><I><TT>nothing</TT></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=maroon><I><a href="manual009.html#string-literal"><font color=maroon><TT>string-literal</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=maroon><I><a href="manual009.html#integer-literal"><font color=maroon><TT>integer-literal</TT></font></a></I></FONT></TD>
</TR>
<TR><TD ALIGN=right NOWRAP> </TD>
<TD ALIGN=right NOWRAP>∣</TD>
<TD ALIGN=left NOWRAP> <FONT COLOR=maroon><I><a href="manual011.html#value-path"><font color=maroon><TT>value-path</TT></font></a></I></FONT></TD>
</TR></TABLE></DIV><BR>
<BR>
A phrase can consist of a definition, similar to those found in
implementations of compilation units or in <FONT COLOR=blue><TT>struct</TT></FONT> … <FONT COLOR=blue><TT>end</TT></FONT>
module expressions. The definition can bind value names, type names,
an exception, a module name, or a module type name. The toplevel
system performs the bindings, then prints the types and values (if
any) for the names thus defined.<BR>
<BR>
A phrase may also consist in a <TT>open</TT> directive (see
section <A HREF="manual019.html#s:module-expr">6.11</A>), or a value expression
(section <A HREF="manual015.html#s:value-expr">6.7</A>). Expressions are simply evaluated,
without performing any bindings, and the value of the expression is
printed.<BR>
<BR>
Finally, a phrase can also consist in a toplevel directive,
starting with <TT>#</TT> (the sharp sign). These directives control the
behavior of the toplevel; they are listed below in
section <A HREF="#s:toplevel-directives">9.2</A>.<BR>
<BR>
<FONT COLOR=purple>Unix:</FONT>
<BLOCKQUOTE CLASS="quote">
The toplevel system is started by the command <TT>ocaml</TT>, as follows:
<PRE>
ocaml <I>options objects</I> # interactive mode
ocaml <I>options objects scriptfile</I> # script mode
</PRE>
<I>options</I> are described below.
<I>objects</I> are filenames ending in <TT>.cmo</TT> or <TT>.cma</TT>; they are
loaded into the interpreter immediately after <I>options</I> are set.
<I>scriptfile</I> is any file name not ending in <TT>.cmo</TT> or <TT>.cma</TT>.<BR>
<BR>
If no <I>scriptfile</I> is given on the command line, the toplevel system
enters interactive mode: phrases are read on standard input, results
are printed on standard output, errors on standard error. End-of-file
on standard input terminates <TT>ocaml</TT> (see also the <TT>#quit</TT> directive
in section <A HREF="#s:toplevel-directives">9.2</A>).<BR>
<BR>
On start-up (before the first phrase is read), if the file
<TT>.ocamlinit</TT> exists in the current directory,
its contents are read as a sequence of Objective Caml phrases
and executed as per the <TT>#use</TT> directive
described in section <A HREF="#s:toplevel-directives">9.2</A>.
The evaluation outcode for each phrase are not displayed.
If the current directory does not contain an <TT>.ocamlinit</TT> file, but
the user's home directory (environment variable <TT>HOME</TT>) does, the
latter is read and executed as described below.<BR>
<BR>
The toplevel system does not perform line editing, but it can
easily be used in conjunction with an external line editor such as
<TT>ledit</TT>, <TT>ocaml2</TT> or <TT>rlwrap</TT>
(see the
<A HREF="http://caml.inria.fr/humps/index_framed_caml.html">Caml Hump</A>).
Another option is to use <TT>ocaml</TT> under Gnu Emacs, which gives the
full editing power of Emacs (command <TT>run-caml</TT> from library <TT>inf-caml</TT>).<BR>
<BR>
At any point, the parsing, compilation or evaluation of the current
phrase can be interrupted by pressing <TT>ctrl-C</TT> (or, more precisely,
by sending the <TT>INTR</TT> signal to the <TT>ocaml</TT> process). The toplevel
then immediately returns to the <TT>#</TT> prompt.<BR>
<BR>
If <I>scriptfile</I> is given on the command-line to <TT>ocaml</TT>, the toplevel
system enters script mode: the contents of the file are read as a
sequence of Objective Caml phrases and executed, as per the <TT>#use</TT>
directive (section <A HREF="#s:toplevel-directives">9.2</A>). The outcome of the
evaluation is not printed. On reaching the end of file, the <TT>ocaml</TT>
command exits immediately. No commands are read from standard input.
<TT>Sys.argv</TT> is transformed, ignoring all Objective Caml parameters, and
starting with the script file name in <TT>Sys.argv.(0)</TT>.<BR>
<BR>
In script mode, the first line of the script is ignored if it starts
with <TT>#!</TT>. Thus, it should be possible to make the script
itself executable and put as first line <TT>#!/usr/local/bin/ocaml</TT>,
thus calling the toplevel system automatically when the script is
run. However, <TT>ocaml</TT> itself is a <TT>#!</TT> script on most installations
of Objective Caml, and Unix kernels usually do not handle nested <TT>#!</TT>
scripts. A better solution is to put the following as the first line
of the script:
<PRE CLASS="verbatim">
#!/usr/local/bin/ocamlrun /usr/local/bin/ocaml
</PRE></BLOCKQUOTE>
<FONT COLOR=purple>Windows:</FONT>
<BLOCKQUOTE CLASS="quote">
In addition to the text-only command <TT>ocaml.exe</TT>, which works exactly
as under Unix (see above), a graphical user interface for the
toplevel is available under the name <TT>ocamlwin.exe</TT>. It should be
launched from the Windows file manager or program manager.
This interface provides a text window in which commands can be entered
and edited, and the toplevel responses are printed.
</BLOCKQUOTE>
<H2 CLASS="section"><A NAME="htoc109">9.1</A> Options</H2> <A NAME="s:toplevel-options"></A>
The following command-line options are recognized by the <TT>ocaml</TT> command.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><B><TT>-I</TT> <I>directory</I></B><DD CLASS="dd-description">
Add the given directory to the list of directories searched for
source and compiled files. By default, the current directory is
searched first, then the standard library directory. Directories added
with <TT>-I</TT> are searched after the current directory, in the order in
which they were given on the command line, but before the standard
library directory.<BR>
<BR>
If the given directory starts with <TT>+</TT>, it is taken relative to the
standard library directory. For instance, <TT>-I +labltk</TT> adds the
subdirectory <TT>labltk</TT> of the standard library to the search path.<BR>
<BR>
Directories can also be added to the search path once
the toplevel is running with the <TT>#directory</TT> directive
(section <A HREF="#s:toplevel-directives">9.2</A>).<BR>
<BR>
<DT CLASS="dt-description"><TT><B>-nolabels</B></TT><DD CLASS="dd-description">
Ignore non-optional labels in types. Labels cannot be used in
applications, and parameter order becomes strict.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>-principal</B></TT><DD CLASS="dd-description">
Check information path during type-checking, to make sure that all
types are derived in a principal way. All programs accepted in
<TT>-principal</TT> mode are also accepted in default mode with equivalent
types.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>-rectypes</B></TT><DD CLASS="dd-description">
Allow arbitrary recursive types during type-checking. By default,
only recursive types where the recursion goes through an object type
are supported.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>-unsafe</B></TT><DD CLASS="dd-description">
See the corresponding option for <TT>ocamlc</TT>, chapter <A HREF="manual022.html#c:camlc">8</A>.
Turn bound checking off on array and string accesses (the <TT>v.(i)</TT> and
<TT>s.[i]</TT> constructs). Programs compiled with <TT>-unsafe</TT> are therefore
slightly faster, but unsafe: anything can happen if the program
accesses an array or string outside of its bounds.<BR>
<BR>
<DT CLASS="dt-description" style="background-color:yellow; color:red">
<TT><B>-version</B></TT><DD CLASS="dd-description" style="background-color:yellow; color:red">
Print version and exit.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>-w</TT> <I>warning-list</I></B><DD CLASS="dd-description">
Enable or disable warnings according to the argument <I>warning-list</I>.</DL>
<FONT COLOR=purple>Unix:</FONT>
<BLOCKQUOTE CLASS="quote">
The following environment variables are also consulted:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<TT><B>LC_CTYPE</B></TT><DD CLASS="dd-description"> If set to <TT>iso_8859_1</TT>, accented characters (from the
ISO Latin-1 character set) in string and character literals are
printed as is; otherwise, they are printed as decimal escape sequences
(<TT>\</TT><I>ddd</I>).<BR>
<BR>
<DT CLASS="dt-description"><TT><B>TERM</B></TT><DD CLASS="dd-description"> When printing error messages, the toplevel system
attempts to underline visually the location of the error. It
consults the <TT>TERM</TT> variable to determines the type of output terminal
and look up its capabilities in the terminal database.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>HOME</B></TT><DD CLASS="dd-description"> Directory where the <TT>.ocamlinit</TT> file is searched.
</DL>
</BLOCKQUOTE>
<H2 CLASS="section"><A NAME="htoc110">9.2</A> Toplevel directives</H2>
<A NAME="s:toplevel-directives"></A>
The following directives control the toplevel behavior, load files in
memory, and trace program execution.<BR>
<BR>
<B>Note:</B> all directives start with a <TT>#</TT> (sharp) symbol. This <TT>#</TT>
must be typed before the directive, and must not be confused with the
<TT>#</TT> prompt displayed by the interactive loop. For instance,
typing <TT>#quit;;</TT> will exit the toplevel loop, but typing <TT>quit;;</TT>
will result in an “unbound value <TT>quit</TT>” error.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><TT><B>#quit;;</B></TT><DD CLASS="dd-description">
Exit the toplevel loop and terminate the <TT>ocaml</TT> command.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#labels </TT><I>bool</I><TT>;;</TT></B><DD CLASS="dd-description">
Ignore labels in function types if argument is <TT>false</TT>, or switch back
to default behaviour (commuting style) if argument is <TT>true</TT>.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#warnings "</TT><I>warning-list</I><TT>";;</TT></B><DD CLASS="dd-description">
Enable or disable warnings according to the argument.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#directory "</TT><I>dir-name</I><TT>";;</TT></B><DD CLASS="dd-description">
Add the given directory to the list of directories searched for
source and compiled files.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#cd "</TT><I>dir-name</I><TT>";;</TT></B><DD CLASS="dd-description">
Change the current working directory.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#load "</TT><I>file-name</I><TT>";;</TT></B><DD CLASS="dd-description">
Load in memory a bytecode object file (<TT>.cmo</TT> file) produced by
the batch compiler <TT>ocamlc</TT>.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#use "</TT><I>file-name</I><TT>";;</TT></B><DD CLASS="dd-description">
Read, compile and execute source phrases from the given file.
This is textual inclusion: phrases are processed just as if
they were typed on standard input. The reading of the file stops at
the first error encountered.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#install_printer </TT><I>printer-name</I><TT>;;</TT></B><DD CLASS="dd-description">
This directive registers the function named <I>printer-name</I> (a
value path) as a printer for values whose types match the argument
type of the function. That is, the toplevel loop will call
<I>printer-name</I> when it has such a value to print.<BR>
<BR>
The printing function <I>printer-name</I> should have type
<FONT COLOR=blue><TT>Format.formatter</TT> <TT>-></TT> <FONT COLOR=maroon><TT><I>t</I></TT></FONT> <TT>-></TT> <TT>unit</TT></FONT>, where <I>t</I> is the
type for the values to be printed, and should output its textual
representation for the value of type <I>t</I> on the given formatter,
using the functions provided by the <TT>Format</TT> library. For backward
compatibility, <I>printer-name</I> can also have type
<FONT COLOR=maroon><I><TT>t</TT></I></FONT> <FONT COLOR=blue><TT>-></TT> <TT>unit</TT></FONT> and should then output on the standard
formatter, but this usage is deprecated.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#remove_printer </TT><I>printer-name</I><TT>;;</TT></B><DD CLASS="dd-description">
Remove the named function from the table of toplevel printers.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#trace </TT><I>function-name</I><TT>;;</TT></B><DD CLASS="dd-description">
After executing this directive, all calls to the function named
<I>function-name</I> will be “traced”. That is, the argument and the
result are displayed for each call, as well as the exceptions escaping
out of the function, raised either by the function itself or by
another function it calls. If the function is curried, each argument
is printed as it is passed to the function.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#untrace </TT><I>function-name</I><TT>;;</TT></B><DD CLASS="dd-description">
Stop tracing the given function.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>#untrace_all;;</B></TT><DD CLASS="dd-description">
Stop tracing all functions traced so far.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#print_depth </TT><I>n</I><TT>;;</TT></B><DD CLASS="dd-description">
Limit the printing of values to a maximal depth of <I>n</I>.
The parts of values whose depth exceeds <I>n</I> are printed as <TT>...</TT>
(ellipsis).<BR>
<BR>
<DT CLASS="dt-description"><B><TT>#print_length </TT><I>n</I><TT>;;</TT></B><DD CLASS="dd-description">
Limit the number of value nodes printed to at most <I>n</I>.
Remaining parts of values are printed as <TT>...</TT> (ellipsis).</DL>
<H2 CLASS="section"><A NAME="htoc111">9.3</A> The toplevel and the module system</H2> <A NAME="s:toplevel-modules"></A>
Toplevel phrases can refer to identifiers defined in compilation units
with the same mechanisms as for separately compiled units: either by
using qualified names (<TT>Modulename.localname</TT>), or by using
the <TT>open</TT> construct and unqualified names (see section <A HREF="manual011.html#s:names">6.3</A>).<BR>
<BR>
However, before referencing another compilation unit, an
implementation of that unit must be present in memory.
At start-up, the toplevel system contains implementations for all the
modules in the the standard library. Implementations for user modules
can be entered with the <TT>#load</TT> directive described above. Referencing
a unit for which no implementation has been provided
results in the error “Reference to undefined global `...' ”.<BR>
<BR>
Note that entering <TT>open </TT><I>Mod</I> merely accesses the compiled
interface (<TT>.cmi</TT> file) for <I>Mod</I>, but does not load the
implementation of <I>Mod</I>, and does not cause any error if no
implementation of <I>Mod</I> has been loaded. The error
“reference to undefined global <I>Mod</I>” will occur only when
executing a value or module definition that refers to <I>Mod</I>.<BR>
<BR>
<H2 CLASS="section"><A NAME="htoc112">9.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>Cannot find file <I>filename</I></B><DD CLASS="dd-description">
The named file could not be found in the current directory, nor in the
directories of the search path. <BR>
<BR>
If <I>filename</I> has the format <I>mod</I><TT>.cmi</TT>, this
means you have referenced the compilation unit <I>mod</I>, but its
compiled interface could not be found. Fix: compile <I>mod</I><TT>.mli</TT> or
<I>mod</I><TT>.ml</TT> first, to create the compiled interface <I>mod</I><TT>.cmi</TT>.<BR>
<BR>
If <I>filename</I> has the format <I>mod</I><TT>.cmo</TT>, this
means you are trying to load with <TT>#load</TT> a bytecode object file that
does not exist yet. Fix: compile <I>mod</I><TT>.ml</TT> first.<BR>
<BR>
If your program spans several directories, this error can also appear
because you haven't specified the directories to look into. Fix: use
the <TT>#directory</TT> directive to add the correct directories to the
search path.<BR>
<BR>
<DT CLASS="dt-description"><B>This expression has type <I>t</I><SUB>1</SUB>, but is used with type <I>t</I><SUB>2</SUB></B><DD CLASS="dd-description">
See section <A HREF="manual022.html#s:comp-errors">8.4</A>.<BR>
<BR>
<DT CLASS="dt-description"><B>Reference to undefined global <I>mod</I></B><DD CLASS="dd-description">
You have neglected to load in memory an implementation for a module
with <TT>#load</TT>. See section <A HREF="#s:toplevel-modules">9.3</A> above.</DL>
<H2 CLASS="section"><A NAME="htoc113">9.5</A> Building custom toplevel systems: <TT>ocamlmktop</TT></H2>
The <TT>ocamlmktop</TT> command builds Objective Caml toplevels that
contain user code preloaded at start-up. <BR>
<BR>
The <TT>ocamlmktop</TT> command takes as argument a set of <TT>.cmo</TT> and <TT>.cma</TT>
files, and links them with the object files that implement the Objective Caml toplevel. The typical use is:
<PRE CLASS="verbatim">
ocamlmktop -o mytoplevel foo.cmo bar.cmo gee.cmo
</PRE>This creates the bytecode file <TT>mytoplevel</TT>, containing the Objective Caml toplevel system, plus the code from the three <TT>.cmo</TT>
files. This toplevel is directly executable and is started by:
<PRE CLASS="verbatim">
./mytoplevel
</PRE>This enters a regular toplevel loop, except that the code from
<TT>foo.cmo</TT>, <TT>bar.cmo</TT> and <TT>gee.cmo</TT> is already loaded in memory, just as
if you had typed:
<PRE CLASS="verbatim">
#load "foo.cmo";;
#load "bar.cmo";;
#load "gee.cmo";;
</PRE>on entrance to the toplevel. The modules <TT>Foo</TT>, <TT>Bar</TT> and <TT>Gee</TT> are
not opened, though; you still have to do
<PRE CLASS="verbatim">
open Foo;;
</PRE>yourself, if this is what you wish.<BR>
<BR>
<H2 CLASS="section"><A NAME="htoc114">9.6</A> Options</H2>
The following command-line options are recognized by <TT>ocamlmktop</TT>.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><B><TT>-cclib</TT> <I>libname</I></B><DD CLASS="dd-description">
Pass the <TT>-l</TT><I>libname</I> option to the C linker when linking in
“custom runtime” mode. See the corresponding option for
<TT>ocamlc</TT>, in chapter <A HREF="manual022.html#c:camlc">8</A>.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>-ccopt</TT> <I>option</I></B><DD CLASS="dd-description">
Pass the given option to the C compiler and linker, when linking in
“custom runtime” mode. See the corresponding option for
<TT>ocamlc</TT>, in chapter <A HREF="manual022.html#c:camlc">8</A>.<BR>
<BR>
<DT CLASS="dt-description"><TT><B>-custom</B></TT><DD CLASS="dd-description">
Link in “custom runtime” mode. See the corresponding option for
<TT>ocamlc</TT>, in chapter <A HREF="manual022.html#c:camlc">8</A>.<BR>
<BR>
<DT CLASS="dt-description"><B><TT>-I</TT> <I>directory</I></B><DD CLASS="dd-description">
Add the given directory to the list of directories searched for
compiled object code files (<TT>.cmo</TT> and <TT>.cma</TT>).<BR>
<BR>
<DT CLASS="dt-description"><B><TT>-o</TT> <I>exec-file</I></B><DD CLASS="dd-description">
Specify the name of the toplevel file produced by the linker.
The default is <TT>a.out</TT>.</DL>
<HR>
<A HREF="manual022.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="manual024.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
|
