8
6
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
9
<META name="GENERATOR" content="hevea 1.08">
7
<META name="GENERATOR" content="hevea 1.09">
10
8
<LINK rel="stylesheet" type="text/css" href="manual.css">
12
Batch compilation (ocamlc)
9
<TITLE>Batch compilation (ocamlc)</TITLE>
16
<A HREF="manual021.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
17
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
18
<A HREF="manual023.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
12
<A HREF="manual021.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
13
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
14
<A HREF="manual023.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
21
<H1 CLASS="chapter"><A NAME="htoc103">Chapter 8</A> Batch compilation (ocamlc)</H1> <A NAME="c:camlc"></A>
23
This chapter describes the Objective Caml batch compiler <TT>ocamlc</TT>,
16
<H1 CLASS="chapter"><A NAME="htoc103">Chapter�8</A>��Batch compilation (ocamlc)</H1><P> <A NAME="c:camlc"></A>
17
</P><P>This chapter describes the Objective Caml batch compiler <TT>ocamlc</TT>,
24
18
which compiles Caml source files to bytecode object files and link
25
19
these object files to produce standalone bytecode executable files.
26
20
These executable files are then run by the bytecode interpreter
27
<TT>ocamlrun</TT>.<BR>
30
<H2 CLASS="section"><A NAME="htoc104">8.1</A> Overview of the compiler</H2>
31
The <TT>ocamlc</TT> command has a command-line interface similar to the one of
21
<TT>ocamlrun</TT>.</P><H2 CLASS="section"><A NAME="htoc104">8.1</A>��Overview of the compiler</H2><P>The <TT>ocamlc</TT> command has a command-line interface similar to the one of
32
22
most C compilers. It accepts several types of arguments and processes them
34
<UL CLASS="itemize"><LI CLASS="li-itemize">
23
sequentially:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
35
24
Arguments ending in <TT>.mli</TT> are taken to be source files for
36
25
compilation unit interfaces. Interfaces specify the names exported by
37
26
compilation units: they declare value names with their types, define
38
27
public data types, declare abstract data types, and so on. From the
39
28
file <I>x</I><TT>.mli</TT>, the <TT>ocamlc</TT> compiler produces a compiled interface
40
in the file <I>x</I><TT>.cmi</TT>.<BR>
42
<LI CLASS="li-itemize">Arguments ending in <TT>.ml</TT> are taken to be source files for compilation
29
in the file <I>x</I><TT>.cmi</TT>.</LI><LI CLASS="li-itemize">Arguments ending in <TT>.ml</TT> are taken to be source files for compilation
43
30
unit implementations. Implementations provide definitions for the
44
31
names exported by the unit, and also contain expressions to be
45
32
evaluated for their side-effects. From the file <I>x</I><TT>.ml</TT>, the <TT>ocamlc</TT>
46
compiler produces compiled object bytecode in the file <I>x</I><TT>.cmo</TT>. <BR>
48
If the interface file <I>x</I><TT>.mli</TT> exists, the implementation
33
compiler produces compiled object bytecode in the file <I>x</I><TT>.cmo</TT>. <P>If the interface file <I>x</I><TT>.mli</TT> exists, the implementation
49
34
<I>x</I><TT>.ml</TT> is checked against the corresponding compiled interface
50
35
<I>x</I><TT>.cmi</TT>, which is assumed to exist. If no interface
51
36
<I>x</I><TT>.mli</TT> is provided, the compilation of <I>x</I><TT>.ml</TT> produces a
52
37
compiled interface file <I>x</I><TT>.cmi</TT> in addition to the compiled
53
38
object code file <I>x</I><TT>.cmo</TT>. The file <I>x</I><TT>.cmi</TT> produced
54
39
corresponds to an interface that exports everything that is defined in
55
the implementation <I>x</I><TT>.ml</TT>.<BR>
57
<LI CLASS="li-itemize">Arguments ending in <TT>.cmo</TT> are taken to be compiled object bytecode. These
40
the implementation <I>x</I><TT>.ml</TT>.</P></LI><LI CLASS="li-itemize">Arguments ending in <TT>.cmo</TT> are taken to be compiled object bytecode. These
58
41
files are linked together, along with the object files obtained
59
42
by compiling <TT>.ml</TT> arguments (if any), and the Objective Caml standard
60
43
library, to produce a standalone executable program. The order in
62
45
relevant: compilation units are initialized in that order at
63
46
run-time, and it is a link-time error to use a component of a unit
64
47
before having initialized it. Hence, a given <I>x</I><TT>.cmo</TT> file must come
65
before all <TT>.cmo</TT> files that refer to the unit <I>x</I>.<BR>
67
<LI CLASS="li-itemize">Arguments ending in <TT>.cma</TT> are taken to be libraries of object bytecode.
48
before all <TT>.cmo</TT> files that refer to the unit <I>x</I>.</LI><LI CLASS="li-itemize">Arguments ending in <TT>.cma</TT> are taken to be libraries of object bytecode.
68
49
A library of object bytecode packs in a single file a set of object
69
50
bytecode files (<TT>.cmo</TT> files). Libraries are built with <TT>ocamlc -a</TT>
70
51
(see the description of the <TT>-a</TT> option below). The object files
71
52
contained in the library are linked as regular <TT>.cmo</TT> files (see
72
53
above), in the order specified when the <TT>.cma</TT> file was built. The
73
54
only difference is that if an object file contained in a library is
74
not referenced anywhere in the program, then it is not linked in.<BR>
76
<LI CLASS="li-itemize">Arguments ending in <TT>.c</TT> are passed to the C compiler, which generates
55
not referenced anywhere in the program, then it is not linked in.</LI><LI CLASS="li-itemize">Arguments ending in <TT>.c</TT> are passed to the C compiler, which generates
77
56
a <TT>.o</TT> object file. This object file is linked with the program if the
78
<TT>-custom</TT> flag is set (see the description of <TT>-custom</TT> below).<BR>
80
<LI CLASS="li-itemize">Arguments ending in <TT>.o</TT> or <TT>.a</TT> (<TT>.obj</TT> or <TT>.lib</TT> under Windows)
57
<TT>-custom</TT> flag is set (see the description of <TT>-custom</TT> below).</LI><LI CLASS="li-itemize">Arguments ending in <TT>.o</TT> or <TT>.a</TT> (<TT>.obj</TT> or <TT>.lib</TT> under Windows)
81
58
are assumed to be C object files and libraries. They are passed to the
82
59
C linker when linking in <TT>-custom</TT> mode (see the description of
83
<TT>-custom</TT> below).<BR>
85
<LI CLASS="li-itemize">Arguments ending in <TT>.so</TT> (<TT>.dll</TT> under Windows)
60
<TT>-custom</TT> below).</LI><LI CLASS="li-itemize">Arguments ending in <TT>.so</TT> (<TT>.dll</TT> under Windows)
86
61
are assumed to be C shared libraries (DLLs). During linking, they are
87
62
searched for external C functions referenced from the Caml code,
88
63
and their names are written in the generated bytecode executable.
89
64
The run-time system <TT>ocamlrun</TT> then loads them dynamically at program
91
The output of the linking phase is a file containing compiled bytecode
65
start-up time.</LI></UL><P>The output of the linking phase is a file containing compiled bytecode
92
66
that can be executed by the Objective Caml bytecode interpreter:
93
67
the command named <TT>ocamlrun</TT>. If <TT>caml.out</TT> is the name of the file
94
68
produced by the linking phase, the command
96
ocamlrun caml.out <I>arg</I><SUB>1</SUB> <I>arg</I><SUB>2</SUB> ... <I>arg<SUB>n</SUB></I>
70
ocamlrun caml.out <I>arg</I><SUB>1</SUB> <I>arg</I><SUB>2</SUB> … <I>arg<SUB>n</SUB></I>
98
72
executes the compiled code contained in <TT>caml.out</TT>, passing it as
99
73
arguments the character strings <I>arg</I><SUB>1</SUB> to <I>arg<SUB>n</SUB></I>.
100
(See chapter <A HREF="manual024.html#c:runtime">10</A> for more details.)<BR>
102
On most systems, the file produced by the linking
74
(See chapter�<A HREF="manual024.html#c:runtime">10</A> for more details.)</P><P>On most systems, the file produced by the linking
103
75
phase can be run directly, as in:
105
./caml.out <I>arg</I><SUB>1</SUB> <I>arg</I><SUB>2</SUB> ... <I>arg<SUB>n</SUB></I>
77
./caml.out <I>arg</I><SUB>1</SUB> <I>arg</I><SUB>2</SUB> … <I>arg<SUB>n</SUB></I>
107
79
The produced file has the executable bit set, and it manages to launch
108
the bytecode interpreter by itself.<BR>
111
<H2 CLASS="section"><A NAME="htoc105">8.2</A> Options</H2>
112
The following command-line options are recognized by <TT>ocamlc</TT>.
113
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><TT><B>-a</B></TT><DD CLASS="dd-description">
80
the bytecode interpreter by itself.</P><H2 CLASS="section"><A NAME="htoc105">8.2</A>��Options</H2><P>The following command-line options are recognized by <TT>ocamlc</TT>.</P><DL CLASS="description"><DT CLASS="dt-description"><TT><B>-a</B></TT></DT><DD CLASS="dd-description">
114
81
Build a library (<TT>.cma</TT> file) with the object files (<TT>.cmo</TT> files)
115
82
given on the command line, instead of linking them into an executable
116
file. The name of the library must be set with the <TT>-o</TT> option.<BR>
118
If <TT>-custom</TT>, <TT>-cclib</TT> or <TT>-ccopt</TT> options are passed on the command
83
file. The name of the library must be set with the <TT>-o</TT> option.<P>If <TT>-custom</TT>, <TT>-cclib</TT> or <TT>-ccopt</TT> options are passed on the command
119
84
line, these options are stored in the resulting <TT>.cma</TT> library. Then,
120
85
linking with this library automatically adds back the <TT>-custom</TT>,
121
86
<TT>-cclib</TT> and <TT>-ccopt</TT> options as if they had been provided on the
122
command line, unless the <TT>-noautolink</TT> option is given.<BR>
124
<DT CLASS="dt-description"><TT><B>-c</B></TT><DD CLASS="dd-description">
87
command line, unless the <TT>-noautolink</TT> option is given.</P></DD><DT CLASS="dt-description"><TT><B>-c</B></TT></DT><DD CLASS="dd-description">
125
88
Compile only. Suppress the linking phase of the
126
89
compilation. Source code files are turned into compiled files, but no
127
90
executable file is produced. This option is useful to
128
compile modules separately.<BR>
130
<DT CLASS="dt-description"><B><TT>-cc</TT> <I>ccomp</I></B><DD CLASS="dd-description">
91
compile modules separately.</DD><DT CLASS="dt-description"><B><TT>-cc</TT> <I>ccomp</I></B></DT><DD CLASS="dd-description">
131
92
Use <I>ccomp</I> as the C linker called by <TT>ocamlc -custom</TT>
132
and as the C compiler for compiling <TT>.c</TT> source files.<BR>
134
<DT CLASS="dt-description"><B><TT>-cclib</TT> <TT>-l</TT><I>libname</I></B><DD CLASS="dd-description">
93
and as the C compiler for compiling <TT>.c</TT> source files.</DD><DT CLASS="dt-description"><B><TT>-cclib</TT> <TT>-l</TT><I>libname</I></B></DT><DD CLASS="dd-description">
135
94
Pass the <TT>-l</TT><I>libname</I> option to the C linker when linking in
136
“custom runtime” mode (see the <TT>-custom</TT> option). This causes the
137
given C library to be linked with the program.<BR>
139
<DT CLASS="dt-description"><B><TT>-ccopt</TT> <I>option</I></B><DD CLASS="dd-description">
95
“custom runtime” mode (see the <TT>-custom</TT> option). This causes the
96
given C library to be linked with the program.</DD><DT CLASS="dt-description"><B><TT>-ccopt</TT> <I>option</I></B></DT><DD CLASS="dd-description">
140
97
Pass the given option to the C compiler and linker, when linking in
141
“custom runtime” mode (see the <TT>-custom</TT> option). For instance,
98
“custom runtime” mode (see the <TT>-custom</TT> option). For instance,
142
99
<TT>-ccopt -L</TT><I>dir</I> causes the C linker to search for C libraries in
143
directory <I>dir</I>.<BR>
145
<DT CLASS="dt-description"><TT><B>-custom</B></TT><DD CLASS="dd-description">
146
Link in “custom runtime” mode. In the default linking mode, the
100
directory <I>dir</I>.</DD><DT CLASS="dt-description"><TT><B>-custom</B></TT></DT><DD CLASS="dd-description">
101
Link in “custom runtime” mode. In the default linking mode, the
147
102
linker produces bytecode that is intended to be executed with the
148
103
shared runtime system, <TT>ocamlrun</TT>. In the custom runtime mode, the
149
104
linker produces an output file that contains both the runtime system
150
105
and the bytecode for the program. The resulting file is larger, but it
151
106
can be executed directly, even if the <TT>ocamlrun</TT> command is not
152
installed. Moreover, the “custom runtime” mode enables static
107
installed. Moreover, the “custom runtime” mode enables static
153
108
linking of Caml code with user-defined C functions, as described in
154
chapter <A HREF="manual032.html#c:intf-c">18</A>.
156
<FONT COLOR=purple>Unix:</FONT>
157
<BLOCKQUOTE CLASS="quote">
109
chapter�<A HREF="manual032.html#c:intf-c">18</A>.
110
<BLOCKQUOTE CLASS="quote"><FONT COLOR=purple>Unix:</FONT>��
158
111
Never use the <TT>strip</TT> command on executables produced by <TT>ocamlc -custom</TT>.
159
112
This would remove the bytecode part of the executable.
162
<DT CLASS="dt-description"><B><TT>-dllib</TT> <TT>-l</TT><I>libname</I></B><DD CLASS="dd-description">
113
</BLOCKQUOTE></DD><DT CLASS="dt-description"><B><TT>-dllib</TT> <TT>-l</TT><I>libname</I></B></DT><DD CLASS="dd-description">
163
114
Arrange for the C shared library <TT>dll</TT><I>libname</I><TT>.so</TT>
164
115
(<TT>dll</TT><I>libname</I><TT>.dll</TT> under Windows) to be loaded dynamically
165
by the run-time system <TT>ocamlrun</TT> at program start-up time.<BR>
167
<DT CLASS="dt-description"><B><TT>-dllpath</TT> <I>dir</I></B><DD CLASS="dd-description">
116
by the run-time system <TT>ocamlrun</TT> at program start-up time.</DD><DT CLASS="dt-description"><B><TT>-dllpath</TT> <I>dir</I></B></DT><DD CLASS="dd-description">
168
117
Adds the directory <I>dir</I> to the run-time search path for shared
169
118
C libraries. At link-time, shared libraries are searched in the
170
119
standard search path (the one corresponding to the <TT>-I</TT> option).
171
120
The <TT>-dllpath</TT> option simply stores <I>dir</I> in the produced
172
121
executable file, where <TT>ocamlrun</TT> can find it and exploit it as
173
described in section <A HREF="manual024.html#s-ocamlrun-dllpath">10.3</A>.<BR>
175
<DT CLASS="dt-description"><TT><B>-dtypes</B></TT><DD CLASS="dd-description">
122
described in section�<A HREF="manual024.html#s-ocamlrun-dllpath">10.3</A>.</DD><DT CLASS="dt-description"><TT><B>-dtypes</B></TT></DT><DD CLASS="dd-description">
176
123
Dump detailed type information. The information for file <I>x</I><TT>.ml</TT>
177
124
is put into file <I>x</I><TT>.annot</TT>. In case of a type error, dump
178
125
all the information inferred by the type-checker before the error.
179
126
The <I>x</I><TT>.annot</TT> file can be used with the emacs commands given in
180
<TT>emacs/caml-types.el</TT> to display types interactively.<BR>
182
<DT CLASS="dt-description"><TT><B>-g</B></TT><DD CLASS="dd-description">
127
<TT>emacs/caml-types.el</TT> to display types interactively.</DD><DT CLASS="dt-description"><TT><B>-g</B></TT></DT><DD CLASS="dd-description">
183
128
Add debugging information while compiling and linking. This option is
184
129
required in order to be able to debug the program with <TT>ocamldebug</TT>
185
(see chapter <A HREF="manual030.html#c:debugger">16</A>).<BR>
187
<DT CLASS="dt-description"><TT><B>-i</B></TT><DD CLASS="dd-description">
130
(see chapter�<A HREF="manual030.html#c:debugger">16</A>), and to produce stack backtraces when
131
the program terminates on an uncaught exception (see
132
section�<A HREF="manual024.html#ocamlrun-options">10.2</A>).</DD><DT CLASS="dt-description"><TT><B>-i</B></TT></DT><DD CLASS="dd-description">
188
133
Cause the compiler to print all defined names (with their inferred
189
134
types or their definitions) when compiling an implementation (<TT>.ml</TT>
190
135
file). No compiled files (<TT>.cmo</TT> and <TT>.cmi</TT> files) are produced.
202
145
searched first, then the standard library directory. Directories added
203
146
with <TT>-I</TT> are searched after the current directory, in the order in
204
147
which they were given on the command line, but before the standard
205
library directory.<BR>
207
If the given directory starts with <TT>+</TT>, it is taken relative to the
148
library directory.<P>If the given directory starts with <TT>+</TT>, it is taken relative to the
208
149
standard library directory. For instance, <TT>-I +labltk</TT> adds the
209
subdirectory <TT>labltk</TT> of the standard library to the search path.<BR>
211
<DT CLASS="dt-description"><B><TT>-impl</TT> <I>filename</I></B><DD CLASS="dd-description">
150
subdirectory <TT>labltk</TT> of the standard library to the search path.</P></DD><DT CLASS="dt-description"><B><TT>-impl</TT> <I>filename</I></B></DT><DD CLASS="dd-description">
212
151
Compile the file <I>filename</I> as an implementation file, even if its
213
extension is not <TT>.ml</TT>.<BR>
215
<DT CLASS="dt-description"><B><TT>-intf</TT> <I>filename</I></B><DD CLASS="dd-description">
152
extension is not <TT>.ml</TT>.</DD><DT CLASS="dt-description"><B><TT>-intf</TT> <I>filename</I></B></DT><DD CLASS="dd-description">
216
153
Compile the file <I>filename</I> as an interface file, even if its
217
extension is not <TT>.mli</TT>.<BR>
219
<DT CLASS="dt-description"><TT><B>-linkall</B></TT><DD CLASS="dd-description">
154
extension is not <TT>.mli</TT>.</DD><DT CLASS="dt-description"><TT><B>-linkall</B></TT></DT><DD CLASS="dd-description">
220
155
Force all modules contained in libraries to be linked in. If this
221
156
flag is not given, unreferenced modules are not linked in. When
222
157
building a library (<TT>-a</TT> flag), setting the <TT>-linkall</TT> flag forces all
223
158
subsequent links of programs involving that library to link all the
224
modules contained in the library.<BR>
226
<DT CLASS="dt-description"><TT><B>-make-runtime</B></TT><DD CLASS="dd-description">
159
modules contained in the library.</DD><DT CLASS="dt-description"><TT><B>-make-runtime</B></TT></DT><DD CLASS="dd-description">
227
160
Build a custom runtime system (in the file specified by option <TT>-o</TT>)
228
161
incorporating the C object files and libraries given on the command
229
162
line. This custom runtime system can be used later to execute
230
163
bytecode executables produced with the
231
164
<TT>ocamlc -use-runtime</TT> <I>runtime-name</I> option.
232
See section <A HREF="manual032.html#s:custom-runtime">18.1.6</A> for more information.<BR>
234
<DT CLASS="dt-description"><TT><B>-noassert</B></TT><DD CLASS="dd-description">
165
See section�<A HREF="manual032.html#s:custom-runtime">18.1.6</A> for more information.</DD><DT CLASS="dt-description"><TT><B>-noassert</B></TT></DT><DD CLASS="dd-description">
235
166
Turn assertion checking off: assertions are not compiled.
236
This flag has no effect when linking already compiled files.<BR>
238
<DT CLASS="dt-description"><TT><B>-noautolink</B></TT><DD CLASS="dd-description">
167
This flag has no effect when linking already compiled files.</DD><DT CLASS="dt-description"><TT><B>-noautolink</B></TT></DT><DD CLASS="dd-description">
239
168
When linking <TT>.cma</TT> libraries, ignore <TT>-custom</TT>, <TT>-cclib</TT> and <TT>-ccopt</TT>
240
169
options potentially contained in the libraries (if these options were
241
170
given when building the libraries). This can be useful if a library
242
171
contains incorrect specifications of C libraries or C options; in this
243
172
case, during linking, set <TT>-noautolink</TT> and pass the correct C
244
libraries and options on the command line.<BR>
246
<DT CLASS="dt-description"><TT><B>-nolabels</B></TT><DD CLASS="dd-description">
173
libraries and options on the command line.</DD><DT CLASS="dt-description"><TT><B>-nolabels</B></TT></DT><DD CLASS="dd-description">
247
174
Ignore non-optional labels in types. Labels cannot be used in
248
applications, and parameter order becomes strict.<BR>
250
<DT CLASS="dt-description"><B><TT>-o</TT> <I>exec-file</I></B><DD CLASS="dd-description">
175
applications, and parameter order becomes strict.</DD><DT CLASS="dt-description"><B><TT>-o</TT> <I>exec-file</I></B></DT><DD CLASS="dd-description">
251
176
Specify the name of the output file produced by the linker. The
252
default output name is <TT>a.out</TT>, in keeping with the Unix tradition. If
253
the <TT>-a</TT> option is given, specify the name of the library produced.
254
If the <TT>-output-obj</TT> option is given, specify the name of the output
257
<DT CLASS="dt-description"><TT><B>-output-obj</B></TT><DD CLASS="dd-description">
177
default output name is <TT>a.out</TT> under Unix and <TT>camlprog.exe</TT> under
178
Windows. If the <TT>-a</TT> option is given, specify the name of the library
179
produced. If the <TT>-pack</TT> option is given, specify the name of the
180
packed object file produced. If the <TT>-output-obj</TT> option is given,
181
specify the name of the output file produced.</DD><DT CLASS="dt-description"><TT><B>-output-obj</B></TT></DT><DD CLASS="dd-description">
258
182
Cause the linker to produce a C object file instead of a bytecode
259
183
executable file. This is useful to wrap Caml code as a C library,
260
callable from any C program. See chapter <A HREF="manual032.html#c:intf-c">18</A>,
261
section <A HREF="manual032.html#s:embedded-code">18.7.5</A>. The name of the output object file is
262
<TT>camlprog.o</TT> by default; it can be set with the <TT>-o</TT> option.<BR>
264
<DT CLASS="dt-description"><TT><B>-pack</B></TT><DD CLASS="dd-description">
184
callable from any C program. See chapter�<A HREF="manual032.html#c:intf-c">18</A>,
185
section�<A HREF="manual032.html#s:embedded-code">18.7.5</A>. The name of the output object file is
186
<TT>camlprog.o</TT> by default; it can be set with the <TT>-o</TT> option.</DD><DT CLASS="dt-description"><TT><B>-pack</B></TT></DT><DD CLASS="dd-description">
265
187
Build a bytecode object file (<TT>.cmo</TT> file) and its associated compiled
266
188
interface (<TT>.cmi</TT>) that combines the object
267
189
files given on the command line, making them appear as sub-modules of
268
190
the output <TT>.cmo</TT> file. The name of the output <TT>.cmo</TT> file must be
269
191
given with the <TT>-o</TT> option. For instance,
270
<PRE CLASS="verbatim">
271
ocamlc -pack -o p.cmo a.cmo b.cmo c.cmo
192
<PRE CLASS="verbatim"> ocamlc -pack -o p.cmo a.cmo b.cmo c.cmo
272
193
</PRE>generates compiled files <TT>p.cmo</TT> and <TT>p.cmi</TT> describing a compilation
273
194
unit having three sub-modules <TT>A</TT>, <TT>B</TT> and <TT>C</TT>, corresponding to the
274
195
contents of the object files <TT>a.cmo</TT>, <TT>b.cmo</TT> and <TT>c.cmo</TT>. These
275
196
contents can be referenced as <TT>P.A</TT>, <TT>P.B</TT> and <TT>P.C</TT> in the remainder
278
<DT CLASS="dt-description"><B><TT>-pp</TT> <I>command</I></B><DD CLASS="dd-description">
197
of the program.</DD><DT CLASS="dt-description"><B><TT>-pp</TT> <I>command</I></B></DT><DD CLASS="dd-description">
279
198
Cause the compiler to call the given <I>command</I> as a preprocessor
280
199
for each source file. The output of <I>command</I> is redirected to
281
200
an intermediate file, which is compiled. If there are no compilation
282
201
errors, the intermediate file is deleted afterwards. The name of this
283
202
file is built from the basename of the source file with the extension
284
203
<TT>.ppi</TT> for an interface (<TT>.mli</TT>) file and <TT>.ppo</TT> for an implementation
285
(<TT>.ml</TT>) file.<BR>
287
<DT CLASS="dt-description"><TT><B>-principal</B></TT><DD CLASS="dd-description">
204
(<TT>.ml</TT>) file.</DD><DT CLASS="dt-description"><TT><B>-principal</B></TT></DT><DD CLASS="dd-description">
288
205
Check information path during type-checking, to make sure that all
289
206
types are derived in a principal way. When using labelled arguments
290
207
and/or polymorphic methods, this flag is required to ensure future
293
210
All programs accepted in <TT>-principal</TT> mode are also accepted in
294
211
default mode with equivalent types, but different binary signatures,
295
212
and this may slow down type checking; yet this is a good idea to
296
use it once before publishing source code.<BR>
298
<DT CLASS="dt-description"><TT><B>-rectypes</B></TT><DD CLASS="dd-description">
213
use it once before publishing source code.</DD><DT CLASS="dt-description"><TT><B>-rectypes</B></TT></DT><DD CLASS="dd-description">
299
214
Allow arbitrary recursive types during type-checking. By default,
300
215
only recursive types where the recursion goes through an object type
303
<DT CLASS="dt-description"><TT><B>-thread</B></TT><DD CLASS="dd-description">
216
are supported. Note that once you have created an interface using this
217
flag, you must use it again for all dependencies.</DD><DT CLASS="dt-description"><TT><B>-thread</B></TT></DT><DD CLASS="dd-description">
304
218
Compile or link multithreaded programs, in combination with the
305
system <TT>threads</TT> library described in chapter <A HREF="manual038.html#c:threads">24</A>.<BR>
307
<DT CLASS="dt-description"><TT><B>-unsafe</B></TT><DD CLASS="dd-description">
219
system <TT>threads</TT> library described in chapter�<A HREF="manual038.html#c:threads">24</A>.</DD><DT CLASS="dt-description"><TT><B>-unsafe</B></TT></DT><DD CLASS="dd-description">
308
220
Turn bound checking off on array and string accesses (the <TT>v.(i)</TT> and
309
221
<TT>s.[i]</TT> constructs). Programs compiled with <TT>-unsafe</TT> are therefore
310
222
slightly faster, but unsafe: anything can happen if the program
311
accesses an array or string outside of its bounds.<BR>
313
<DT CLASS="dt-description"><B><TT>-use-runtime</TT> <I>runtime-name</I></B><DD CLASS="dd-description">
223
accesses an array or string outside of its bounds.</DD><DT CLASS="dt-description"><B><TT>-use-runtime</TT> <I>runtime-name</I></B></DT><DD CLASS="dd-description">
314
224
Generate a bytecode executable file that can be executed on the custom
315
225
runtime system <I>runtime-name</I>, built earlier with
316
226
<TT>ocamlc -make-runtime</TT> <I>runtime-name</I>.
317
See section <A HREF="manual032.html#s:custom-runtime">18.1.6</A> for more information.<BR>
319
<DT CLASS="dt-description"><TT><B>-v</B></TT><DD CLASS="dd-description">
227
See section�<A HREF="manual032.html#s:custom-runtime">18.1.6</A> for more information.</DD><DT CLASS="dt-description"><TT><B>-v</B></TT></DT><DD CLASS="dd-description">
320
228
Print the version number of the compiler and the location of the
321
standard library directory, then exit.<BR>
323
<DT CLASS="dt-description"><TT><B>-verbose</B></TT><DD CLASS="dd-description">
229
standard library directory, then exit.</DD><DT CLASS="dt-description"><TT><B>-verbose</B></TT></DT><DD CLASS="dd-description">
324
230
Print all external commands before they are executed, in particular
325
231
invocations of the C compiler and linker in <TT>-custom</TT> mode. Useful to
326
debug C library problems.<BR>
328
<DT CLASS="dt-description"><TT><B>-version</B></TT><DD CLASS="dd-description">
232
debug C library problems.</DD><DT CLASS="dt-description"><TT><B>-version</B></TT></DT><DD CLASS="dd-description">
329
233
Print the version number of the compiler in short form (e.g. <TT>3.06</TT>),
332
<DT CLASS="dt-description"><TT><B>-vmthread</B></TT><DD CLASS="dd-description">
234
then exit.</DD><DT CLASS="dt-description"><TT><B>-vmthread</B></TT></DT><DD CLASS="dd-description">
333
235
Compile or link multithreaded programs, in combination with the
334
VM-level <TT>threads</TT> library described in chapter <A HREF="manual038.html#c:threads">24</A>.<BR>
336
<DT CLASS="dt-description"><B><TT>-w</TT> <I>warning-list</I></B><DD CLASS="dd-description">
236
VM-level <TT>threads</TT> library described in chapter�<A HREF="manual038.html#c:threads">24</A>.</DD><DT CLASS="dt-description"><B><TT>-w</TT> <I>warning-list</I></B></DT><DD CLASS="dd-description">
337
237
Enable or disable warnings according to the argument
338
238
<I>warning-list</I>. The argument is a string of one or several
339
239
characters, with the following meaning for each character:
340
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
341
<B><TT>A</TT>/<TT>a</TT></B><DD CLASS="dd-description"> enable/disable all warnings.
342
<DT CLASS="dt-description"><B><TT>C</TT>/<TT>c</TT></B><DD CLASS="dd-description"> enable/disable warnings for suspicious comments.
343
<DT CLASS="dt-description"><B><TT>D</TT>/<TT>d</TT></B><DD CLASS="dd-description"> enable/disable warnings for deprecated features.
344
<DT CLASS="dt-description"><B><TT>E</TT>/<TT>e</TT></B><DD CLASS="dd-description"> enable/disable warnings for fragile pattern matchings
240
<DL CLASS="description"><DT CLASS="dt-description">
241
<B><TT>A</TT>/<TT>a</TT></B></DT><DD CLASS="dd-description"> enable/disable all warnings.
242
</DD><DT CLASS="dt-description"><B><TT>C</TT>/<TT>c</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for suspicious comments.
243
</DD><DT CLASS="dt-description"><B><TT>D</TT>/<TT>d</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for deprecated features.
244
</DD><DT CLASS="dt-description"><B><TT>E</TT>/<TT>e</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for fragile pattern matchings
345
245
(matchings that would remain complete if additional constructors are
346
added to a variant type involved).
347
<DT CLASS="dt-description"><B><TT>F</TT>/<TT>f</TT></B><DD CLASS="dd-description"> enable/disable warnings for partially applied functions
246
added to a variant type involved).
247
</DD><DT CLASS="dt-description"><B><TT>F</TT>/<TT>f</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for partially applied functions
348
248
(i.e. <TT>f x; </TT><I>expr</I> where the application <TT>f x</TT> has a function type).
349
<DT CLASS="dt-description"><B><TT>L</TT>/<TT>l</TT></B><DD CLASS="dd-description"> enable/disable warnings for labels omitted in application.
350
<DT CLASS="dt-description"><B><TT>M</TT>/<TT>m</TT></B><DD CLASS="dd-description"> enable/disable warnings for overriden methods.
351
<DT CLASS="dt-description"><B><TT>P</TT>/<TT>p</TT></B><DD CLASS="dd-description"> enable/disable warnings for partial matches (missing cases
249
</DD><DT CLASS="dt-description"><B><TT>L</TT>/<TT>l</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for labels omitted in application.
250
</DD><DT CLASS="dt-description"><B><TT>M</TT>/<TT>m</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for overriden methods.
251
</DD><DT CLASS="dt-description"><B><TT>P</TT>/<TT>p</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for partial matches (missing cases
352
252
in pattern matchings).
353
<DT CLASS="dt-description"><B><TT>S</TT>/<TT>s</TT></B><DD CLASS="dd-description"> enable/disable warnings for statements that do not have
253
</DD><DT CLASS="dt-description"><B><TT>S</TT>/<TT>s</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for statements that do not have
354
254
type <TT>unit</TT> (e.g. <I>expr1</I><TT>; </TT><I>expr2</I> when <I>expr1</I> does not
355
have type <TT>unit</TT>).
356
<DT CLASS="dt-description"><B><TT>U</TT>/<TT>u</TT></B><DD CLASS="dd-description"> enable/disable warnings for unused (redundant) match cases.
357
<DT CLASS="dt-description"><B><TT>V</TT>/<TT>v</TT></B><DD CLASS="dd-description"> enable/disable warnings for hidden instance variables.
358
<DT style="background-color:yellow; color:red" CLASS="dt-description"><B><TT>Y</TT>/<TT>y</TT></B><DD CLASS="dd-description" style="background-color:yellow; color:red"> enable/disable warnings for unused variables bound with the
255
have type <TT>unit</TT>), and that are not functions (covered by warning <TT>F</TT>).
256
</DD><DT CLASS="dt-description"><B><TT>U</TT>/<TT>u</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for unused (redundant) match cases.
257
</DD><DT CLASS="dt-description"><B><TT>V</TT>/<TT>v</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for hidden instance variables.
258
</DD><DT CLASS="dt-description"><B><TT>Y</TT>/<TT>y</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for unused variables bound with the
359
259
<TT>let</TT> or <TT>as</TT> keywords and that don't start with an underscore.
360
<DT CLASS="dt-description" style="background-color:yellow; color:red"><B><TT>Z</TT>/<TT>z</TT></B><DD CLASS="dd-description" style="background-color:yellow; color:red"> enable/disable warnings for all unused variables that don't
361
start with an underscore.
362
<DT CLASS="dt-description"><B><TT>X</TT>/<TT>x</TT></B><DD CLASS="dd-description"> enable/disable all other warnings.
364
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
365
The default setting is <TT>-w Aelyz</TT>
367
(all warnings enabled except fragile
368
matchings, omitted labels, unused variables).<BR>
370
<DT CLASS="dt-description"><B><TT>-warn-error</TT> <I>warning-list</I></B><DD CLASS="dd-description">
260
</DD><DT CLASS="dt-description"><B><TT>Z</TT>/<TT>z</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for all other unused variables
261
that don't start with an underscore.
262
</DD><DT CLASS="dt-description"><B><TT>X</TT>/<TT>x</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings that don't fit in the above
265
The default setting is <TT>-w Aelz</TT> (all warnings enabled except fragile
266
matchings, omitted labels, non-suspicious unused variables).
267
Warnings <TT>F</TT> and <TT>S</TT>
268
rely on the type system, thus they are not triggered when the
269
type of the statement is unknown.</DD><DT CLASS="dt-description"><B><TT>-warn-error</TT> <I>warning-list</I></B></DT><DD CLASS="dd-description">
371
270
Turn the warnings indicated in the argument <I>warning-list</I> into
372
errors. The compiler will stop on an error as soon as one of these
373
warnings is emitted, instead of going on. The <I>warning-list</I>
271
errors. The compiler will stop with an error when one of these
272
warnings is emitted. The <I>warning-list</I>
374
273
is a string of one or several characters, with the same meaning as for
375
274
the <TT>-w</TT> option: an uppercase character turns the corresponding
376
275
warning into an error, a lowercase character leaves it as a warning.
377
The default setting is <TT>-warn-error a</TT> (all warnings are not treated
380
<DT CLASS="dt-description"><TT><B>-where</B></TT><DD CLASS="dd-description">
276
The default setting is <TT>-warn-error a</TT> (none of the warnings is treated
277
as an error).</DD><DT CLASS="dt-description"><TT><B>-where</B></TT></DT><DD CLASS="dd-description">
381
278
Print the location of the standard library, then exit.
384
<H2 CLASS="section"><A NAME="htoc106">8.3</A> Modules and the file system</H2>
385
This short section is intended to clarify the relationship between the
279
</DD></DL><H2 CLASS="section"><A NAME="htoc106">8.3</A>��Modules and the file system</H2><P>This short section is intended to clarify the relationship between the
386
280
names of the modules corresponding to compilation units and the names
387
281
of the files that contain their compiled interface and compiled
390
The compiler always derives the module name by taking the capitalized
282
implementation.</P><P>The compiler always derives the module name by taking the capitalized
391
283
base name of the source file (<TT>.ml</TT> or <TT>.mli</TT> file). That is, it
392
284
strips the leading directory name, if any, as well as the <TT>.ml</TT> or
393
285
<TT>.mli</TT> suffix; then, it set the first letter to uppercase, in order to
432
313
means you are trying to compile a file that references identifiers
433
314
from module <I>mod</I>, but you have not yet compiled an interface for
434
315
module <I>mod</I>. Fix: compile <I>mod</I><TT>.mli</TT> or <I>mod</I><TT>.ml</TT>
435
first, to create the compiled interface <I>mod</I><TT>.cmi</TT>. <BR>
437
If <I>filename</I> has the format <I>mod</I><TT>.cmo</TT>, this
316
first, to create the compiled interface <I>mod</I><TT>.cmi</TT>. <P>If <I>filename</I> has the format <I>mod</I><TT>.cmo</TT>, this
438
317
means you are trying to link a bytecode object file that does not
439
exist yet. Fix: compile <I>mod</I><TT>.ml</TT> first.<BR>
441
If your program spans several directories, this error can also appear
318
exist yet. Fix: compile <I>mod</I><TT>.ml</TT> first.</P><P>If your program spans several directories, this error can also appear
442
319
because you haven't specified the directories to look into. Fix: add
443
the correct <TT>-I</TT> options to the command line.<BR>
445
<DT CLASS="dt-description"><B>Corrupted compiled interface <I>filename</I></B><DD CLASS="dd-description">
320
the correct <TT>-I</TT> options to the command line.</P></DD><DT CLASS="dt-description"><B>Corrupted compiled interface <I>filename</I></B></DT><DD CLASS="dd-description">
446
321
The compiler produces this error when it tries to read a compiled
447
322
interface file (<TT>.cmi</TT> file) that has the wrong structure. This means
448
323
something went wrong when this <TT>.cmi</TT> file was written: the disk was
449
324
full, the compiler was interrupted in the middle of the file creation,
450
325
and so on. This error can also appear if a <TT>.cmi</TT> file is modified after
451
326
its creation by the compiler. Fix: remove the corrupted <TT>.cmi</TT> file,
454
<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">
327
and rebuild it.</DD><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></DT><DD CLASS="dd-description">
455
328
This is by far the most common type error in programs. Type <I>t</I><SUB>1</SUB> is
456
329
the type inferred for the expression (the part of the program that is
457
330
displayed in the error message), by looking at the expression itself.
458
331
Type <I>t</I><SUB>2</SUB> is the type expected by the context of the expression; it
459
332
is deduced by looking at how the value of this expression is used in
460
333
the rest of the program. If the two types <I>t</I><SUB>1</SUB> and <I>t</I><SUB>2</SUB> are not
461
compatible, then the error above is produced.<BR>
463
In some cases, it is hard to understand why the two types <I>t</I><SUB>1</SUB> and
334
compatible, then the error above is produced.<P>In some cases, it is hard to understand why the two types <I>t</I><SUB>1</SUB> and
464
335
<I>t</I><SUB>2</SUB> are incompatible. For instance, the compiler can report that
465
“expression of type <TT>foo</TT> cannot be used with type <TT>foo</TT>”, and it
336
“expression of type <TT>foo</TT> cannot be used with type <TT>foo</TT>”, and it
466
337
really seems that the two types <TT>foo</TT> are compatible. This is not
467
338
always true. Two type constructors can have the same name, but
468
339
actually represent different types. This can happen if a type
469
340
constructor is redefined. Example:
470
<PRE CLASS="verbatim">
341
</P><PRE CLASS="verbatim"> type foo = A | B
472
342
let f = function A -> 0 | B -> 1
475
</PRE>This result in the error message “expression <TT>C</TT> of type <TT>foo</TT> cannot
476
be used with type <TT>foo</TT>”. <BR>
478
<DT CLASS="dt-description"><B>The type of this expression, <I>t</I>, contains type variables
479
that cannot be generalized</B><DD CLASS="dd-description">
480
Type variables (<TT>'a</TT>, <TT>'b</TT>, ...) in a type <I>t</I> can be in either
345
</PRE><P>This result in the error message “expression <TT>C</TT> of type <TT>foo</TT> cannot
346
be used with type <TT>foo</TT>”. </P></DD><DT CLASS="dt-description"><B>The type of this expression, <I>t</I>, contains type variables
347
that cannot be generalized</B></DT><DD CLASS="dd-description">
348
Type variables (<TT>'a</TT>, <TT>'b</TT>, …) in a type <I>t</I> can be in either
481
349
of two states: generalized (which means that the type <I>t</I> is valid
482
350
for all possible instantiations of the variables) and not generalized
483
351
(which means that the type <I>t</I> is valid only for one instantiation
505
371
flags an error when a structure or compilation unit defines a value
506
372
<I>name</I> whose type contains non-generalized type variables. There
507
373
are two ways to fix this error:
508
<UL CLASS="itemize"><LI CLASS="li-itemize">
374
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
509
375
Add a type constraint or a <TT>.mli</TT> file to give a monomorphic
510
376
type (without type variables) to <I>name</I>. For instance, instead of
512
<PRE CLASS="verbatim">
513
let sort_int_list = Sort.list (<)
378
<PRE CLASS="verbatim"> let sort_int_list = Sort.list (<)
514
379
(* inferred type 'a list -> 'a list, with 'a not generalized *)
516
<PRE CLASS="verbatim">
517
let sort_int_list = (Sort.list (<) : int list -> int list);;
518
</PRE><LI CLASS="li-itemize">If you really need <I>name</I> to have a polymorphic type, turn
381
<PRE CLASS="verbatim"> let sort_int_list = (Sort.list (<) : int list -> int list);;
382
</PRE></LI><LI CLASS="li-itemize">If you really need <I>name</I> to have a polymorphic type, turn
519
383
its defining expression into a function by adding an extra parameter.
520
384
For instance, instead of writing
521
<PRE CLASS="verbatim">
522
let map_length = List.map Array.length
385
<PRE CLASS="verbatim"> let map_length = List.map Array.length
523
386
(* inferred type 'a array list -> int list, with 'a not generalized *)
525
<PRE CLASS="verbatim">
526
let map_length lv = List.map Array.length lv
529
<DT CLASS="dt-description"><B>Reference to undefined global <I>mod</I></B><DD CLASS="dd-description">
388
<PRE CLASS="verbatim"> let map_length lv = List.map Array.length lv
389
</PRE></LI></UL></DD><DT CLASS="dt-description"><B>Reference to undefined global <I>mod</I></B></DT><DD CLASS="dd-description">
530
390
This error appears when trying to link an incomplete or incorrectly
531
391
ordered set of files. Either you have forgotten to provide an
532
392
implementation for the compilation unit named <I>mod</I> on the command line
536
396
<I>mod</I>, but it comes too late on the command line: the
537
397
implementation of <I>mod</I> must come before all bytecode object files
538
398
that reference <I>mod</I>. Fix: change the order of <TT>.ml</TT> and <TT>.cmo</TT>
539
files on the command line.<BR>
541
Of course, you will always encounter this error if you have mutually
399
files on the command line.<P>Of course, you will always encounter this error if you have mutually
542
400
recursive functions across modules. That is, function <TT>Mod1.f</TT> calls
543
401
function <TT>Mod2.g</TT>, and function <TT>Mod2.g</TT> calls function <TT>Mod1.f</TT>.
544
402
In this case, no matter what permutations you perform on the command
545
403
line, the program will be rejected at link-time. Fixes:
546
<UL CLASS="itemize"><LI CLASS="li-itemize">
404
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
547
405
Put <TT>f</TT> and <TT>g</TT> in the same module.
548
<LI CLASS="li-itemize">Parameterize one function by the other.
406
</LI><LI CLASS="li-itemize">Parameterize one function by the other.
549
407
That is, instead of having
550
<PRE CLASS="verbatim">
551
mod1.ml: let f x = ... Mod2.g ...
408
<PRE CLASS="verbatim">mod1.ml: let f x = ... Mod2.g ...
552
409
mod2.ml: let g y = ... Mod1.f ...
554
<PRE CLASS="verbatim">
555
mod1.ml: let f g x = ... g ...
411
<PRE CLASS="verbatim">mod1.ml: let f g x = ... g ...
556
412
mod2.ml: let rec g y = ... Mod1.f g ...
557
413
</PRE>and link <TT>mod1.cmo</TT> before <TT>mod2.cmo</TT>.
558
<LI CLASS="li-itemize">Use a reference to hold one of the two functions, as in :
559
<PRE CLASS="verbatim">
560
mod1.ml: let forward_g =
414
</LI><LI CLASS="li-itemize">Use a reference to hold one of the two functions, as in :
415
<PRE CLASS="verbatim">mod1.ml: let forward_g =
561
416
ref((fun x -> failwith "forward_g") : <type>)
562
417
let f x = ... !forward_g ...
563
418
mod2.ml: let g y = ... Mod1.f ...
564
419
let _ = Mod1.forward_g := g
567
<DT CLASS="dt-description"><B>The external function <I>f</I> is not available</B><DD CLASS="dd-description">
420
</PRE></LI></UL></DD><DT CLASS="dt-description"><B>The external function <I>f</I> is not available</B></DT><DD CLASS="dd-description">
568
421
This error appears when trying to link code that calls external
569
422
functions written in C. As explained in
570
chapter <A HREF="manual032.html#c:intf-c">18</A>, such code must be linked with C libraries that
423
chapter�<A HREF="manual032.html#c:intf-c">18</A>, such code must be linked with C libraries that
571
424
implement the required <I>f</I> C function. If the C libraries in
572
425
question are not shared libraries (DLLs), the code must be linked in
573
“custom runtime” mode. Fix: add the required C libraries to the
574
command line, and possibly the <TT>-custom</TT> option.</DL>
578
<A HREF="manual021.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
579
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
580
<A HREF="manual023.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
426
“custom runtime” mode. Fix: add the required C libraries to the
427
command line, and possibly the <TT>-custom</TT> option.</DD></DL><HR>
428
<A HREF="manual021.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
429
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
430
<A HREF="manual023.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
added
removed
ocaml.html/manual022.html
