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
Native-code compilation (ocamlopt)
9
<TITLE>Native-code compilation (ocamlopt)</TITLE>
16
<A HREF="manual024.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="manual026.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
12
<A HREF="manual024.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="manual026.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
21
<H1 CLASS="chapter"><A NAME="htoc120">Chapter 11</A> Native-code compilation (ocamlopt)</H1> <A NAME="c:nativecomp"></A>
23
This chapter describes the Objective Caml high-performance
16
<H1 CLASS="chapter"><A NAME="htoc120">Chapter�11</A>��Native-code compilation (ocamlopt)</H1><P> <A NAME="c:nativecomp"></A>
17
</P><P>This chapter describes the Objective Caml high-performance
24
18
native-code compiler <TT>ocamlopt</TT>, which compiles Caml source files to
25
19
native code object files and link these object files to produce
26
standalone executables. <BR>
28
The native-code compiler is only available on certain platforms.
20
standalone executables. </P><P>The native-code compiler is only available on certain platforms.
29
21
It produces code that runs faster than the bytecode produced by
30
22
<TT>ocamlc</TT>, at the cost of increased compilation time and executable code
31
23
size. Compatibility with the bytecode compiler is extremely high: the
32
24
same source code should run identically when compiled with <TT>ocamlc</TT> and
33
<TT>ocamlopt</TT>.<BR>
35
It is not possible to mix native-code object files produced by <TT>ocamlopt</TT>
25
<TT>ocamlopt</TT>.</P><P>It is not possible to mix native-code object files produced by <TT>ocamlopt</TT>
36
26
with bytecode object files produced by <TT>ocamlc</TT>: a program must be
37
27
compiled entirely with <TT>ocamlopt</TT> or entirely with <TT>ocamlc</TT>. Native-code
38
28
object files produced by <TT>ocamlopt</TT> cannot be loaded in the toplevel
39
system <TT>ocaml</TT>.<BR>
42
<H2 CLASS="section"><A NAME="htoc121">11.1</A> Overview of the compiler</H2>
43
The <TT>ocamlopt</TT> command has a command-line interface very close to that
29
system <TT>ocaml</TT>.</P><H2 CLASS="section"><A NAME="htoc121">11.1</A>��Overview of the compiler</H2><P>The <TT>ocamlopt</TT> command has a command-line interface very close to that
44
30
of <TT>ocamlc</TT>. It accepts the same types of arguments, and processes them
46
<UL CLASS="itemize"><LI CLASS="li-itemize">
31
sequentially:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
47
32
Arguments ending in <TT>.mli</TT> are taken to be source files for
48
33
compilation unit interfaces. Interfaces specify the names exported by
49
34
compilation units: they declare value names with their types, define
50
35
public data types, declare abstract data types, and so on. From the
51
36
file <I>x</I><TT>.mli</TT>, the <TT>ocamlopt</TT> compiler produces a compiled interface
52
37
in the file <I>x</I><TT>.cmi</TT>. The interface produced is identical to that
53
produced by the bytecode compiler <TT>ocamlc</TT>.<BR>
55
<LI CLASS="li-itemize">Arguments ending in <TT>.ml</TT> are taken to be source files for compilation
38
produced by the bytecode compiler <TT>ocamlc</TT>.</LI><LI CLASS="li-itemize">Arguments ending in <TT>.ml</TT> are taken to be source files for compilation
56
39
unit implementations. Implementations provide definitions for the
57
40
names exported by the unit, and also contain expressions to be
58
41
evaluated for their side-effects. From the file <I>x</I><TT>.ml</TT>, the <TT>ocamlopt</TT>
75
54
relevant: compilation units are initialized in that order at
76
55
run-time, and it is a link-time error to use a component of a unit
77
56
before having initialized it. Hence, a given <I>x</I><TT>.cmx</TT> file must come
78
before all <TT>.cmx</TT> files that refer to the unit <I>x</I>.<BR>
80
<LI CLASS="li-itemize">Arguments ending in <TT>.cmxa</TT> are taken to be libraries of object code.
57
before all <TT>.cmx</TT> files that refer to the unit <I>x</I>.</LI><LI CLASS="li-itemize">Arguments ending in <TT>.cmxa</TT> are taken to be libraries of object code.
81
58
Such a library packs in two files (<I>lib</I><TT>.cmxa</TT> and <I>lib</I><TT>.a</TT>)
82
59
a set of object files (<TT>.cmx</TT>/<TT>.o</TT> files). Libraries are build with
83
60
<TT>ocamlopt -a</TT> (see the description of the <TT>-a</TT> option below). The object
84
61
files contained in the library are linked as regular <TT>.cmx</TT> files (see
85
62
above), in the order specified when the library was built. The only
86
63
difference is that if an object file contained in a library is not
87
referenced anywhere in the program, then it is not linked in.<BR>
89
<LI CLASS="li-itemize">Arguments ending in <TT>.c</TT> are passed to the C compiler, which generates
90
a <TT>.o</TT> object file. This object file is linked with the program.<BR>
92
<LI CLASS="li-itemize">Arguments ending in <TT>.o</TT>, <TT>.a</TT> or <TT>.so</TT> (<TT>.obj</TT>, <TT>.lib</TT> and <TT>.dll</TT>
64
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
65
a <TT>.o</TT> object file. This object file is linked with the program.</LI><LI CLASS="li-itemize">Arguments ending in <TT>.o</TT>, <TT>.a</TT> or <TT>.so</TT> (<TT>.obj</TT>, <TT>.lib</TT> and <TT>.dll</TT>
93
66
under Windows) are assumed to be C object files and
94
libraries. They are linked with the program.</UL>
95
The output of the linking phase is a regular Unix executable file. It
96
does not need <TT>ocamlrun</TT> to run.<BR>
99
<H2 CLASS="section"><A NAME="htoc122">11.2</A> Options</H2>
100
The following command-line options are recognized by <TT>ocamlopt</TT>.
101
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description"><TT><B>-a</B></TT><DD CLASS="dd-description">
67
libraries. They are linked with the program.</LI></UL><P>The output of the linking phase is a regular Unix or Windows
68
executable file. It does not need <TT>ocamlrun</TT> to run.</P><H2 CLASS="section"><A NAME="htoc122">11.2</A>��Options</H2><P>The following command-line options are recognized by <TT>ocamlopt</TT>.</P><DL CLASS="description"><DT CLASS="dt-description"><TT><B>-a</B></TT></DT><DD CLASS="dd-description">
102
69
Build a library (<TT>.cmxa</TT>/<TT>.a</TT> file) with the object files (<TT>.cmx</TT>/<TT>.o</TT>
103
70
files) given on the command line, instead of linking them into an
104
71
executable file. The name of the library can be set with the <TT>-o</TT>
105
option. The default name is <TT>library.cmxa</TT>.<BR>
107
If <TT>-cclib</TT> or <TT>-ccopt</TT> options are passed on the command
72
option. The default name is <TT>library.cmxa</TT>.<P>If <TT>-cclib</TT> or <TT>-ccopt</TT> options are passed on the command
108
73
line, these options are stored in the resulting <TT>.cmxa</TT> library. Then,
109
74
linking with this library automatically adds back the
110
75
<TT>-cclib</TT> and <TT>-ccopt</TT> options as if they had been provided on the
111
command line, unless the <TT>-noautolink</TT> option is given.<BR>
113
<DT CLASS="dt-description"><TT><B>-c</B></TT><DD CLASS="dd-description">
76
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">
114
77
Compile only. Suppress the linking phase of the
115
78
compilation. Source code files are turned into compiled files, but no
116
79
executable file is produced. This option is useful to
117
compile modules separately.<BR>
119
<DT CLASS="dt-description"><B><TT>-cc</TT> <I>ccomp</I></B><DD CLASS="dd-description">
80
compile modules separately.</DD><DT CLASS="dt-description"><B><TT>-cc</TT> <I>ccomp</I></B></DT><DD CLASS="dd-description">
120
81
Use <I>ccomp</I> as the C linker called to build the final executable
121
and as the C compiler for compiling <TT>.c</TT> source files.<BR>
123
<DT CLASS="dt-description"><B><TT>-cclib</TT> <TT>-l</TT><I>libname</I></B><DD CLASS="dd-description">
82
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">
124
83
Pass the <TT>-l</TT><I>libname</I> option to the linker. This causes the given
125
C library to be linked with the program.<BR>
127
<DT CLASS="dt-description"><B><TT>-ccopt</TT> <I>option</I></B><DD CLASS="dd-description">
84
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">
128
85
Pass the given option to the C compiler and linker. For instance,
129
86
<TT>-ccopt -L</TT><I>dir</I> causes the C linker to search for C libraries in
130
directory <I>dir</I>.<BR>
132
<DT CLASS="dt-description"><TT><B>-compact</B></TT><DD CLASS="dd-description">
87
directory <I>dir</I>.</DD><DT CLASS="dt-description"><TT><B>-compact</B></TT></DT><DD CLASS="dd-description">
133
88
Optimize the produced code for space rather than for time. This
134
89
results in slightly smaller but slightly slower programs. The default is to
135
optimize for speed.<BR>
137
<DT CLASS="dt-description"><TT><B>-dtypes</B></TT><DD CLASS="dd-description">
90
optimize for speed.</DD><DT CLASS="dt-description"><TT><B>-dtypes</B></TT></DT><DD CLASS="dd-description">
138
91
Dump detailed type information. The information for file <I>x</I><TT>.ml</TT>
139
92
is put into file <I>x</I><TT>.annot</TT>. In case of a type error, dump
140
93
all the information inferred by the type-checker before the error.
141
94
The <I>x</I><TT>.annot</TT> file can be used with the emacs commands given in
142
<TT>emacs/caml-types.el</TT> to display types interactively.<BR>
144
<DT CLASS="dt-description" style="background-color:yellow; color:red"><B><TT>-for-pack</TT> <I>module-path</I></B><DD CLASS="dd-description" style="background-color:yellow; color:red">
95
<TT>emacs/caml-types.el</TT> to display types interactively.</DD><DT CLASS="dt-description"><B><TT>-for-pack</TT> <I>module-path</I></B></DT><DD CLASS="dd-description">
145
96
Generate an object file (<TT>.cmx</TT>/<TT>.o</TT> file) that can later be included
146
97
as a sub-module (with the given access path) of a compilation unit
147
98
constructed with <TT>-pack</TT>. For instance, <TT>ocamlopt -for-pack P -c A.ml</TT>
148
99
will generate <TT>a.cmx</TT> and <TT>a.o</TT> files that can later be used with
149
<TT>ocamlopt -pack -o P.cmx a.cmx</TT>.<BR>
151
<DT CLASS="dt-description"><TT><B>-i</B></TT><DD CLASS="dd-description">
100
<TT>ocamlopt -pack -o P.cmx a.cmx</TT>.</DD><DT CLASS="dt-description"><TT><B>-g</B></TT></DT><DD CLASS="dd-description">
101
Add debugging information while compiling and linking. This option is
102
required in order to produce stack backtraces when
103
the program terminates on an uncaught exception (see
104
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">
152
105
Cause the compiler to print all defined names (with their inferred
153
106
types or their definitions) when compiling an implementation (<TT>.ml</TT>
154
107
file). No compiled files (<TT>.cmo</TT> and <TT>.cmi</TT> files) are produced.
179
126
<TT>-inline 1</TT>, allows slightly larger functions to be inlined, resulting
180
127
in a slight expansion in code size. Higher values for the <TT>-inline</TT>
181
128
option cause larger and larger functions to become candidate for
182
inlining, but can result in a serious increase in code size.<BR>
184
<DT CLASS="dt-description"><TT><B>-linkall</B></TT><DD CLASS="dd-description">
129
inlining, but can result in a serious increase in code size.</DD><DT CLASS="dt-description"><TT><B>-linkall</B></TT></DT><DD CLASS="dd-description">
185
130
Forces all modules contained in libraries to be linked in. If this
186
131
flag is not given, unreferenced modules are not linked in. When
187
132
building a library (<TT>-a</TT> flag), setting the <TT>-linkall</TT> flag forces all
188
133
subsequent links of programs involving that library to link all the
189
modules contained in the library.<BR>
191
<DT CLASS="dt-description"><TT><B>-noassert</B></TT><DD CLASS="dd-description">
134
modules contained in the library.</DD><DT CLASS="dt-description"><TT><B>-noassert</B></TT></DT><DD CLASS="dd-description">
192
135
Turn assertion checking off: assertions are not compiled.
193
This flag has no effect when linking already compiled files.<BR>
195
<DT CLASS="dt-description"><TT><B>-noautolink</B></TT><DD CLASS="dd-description">
136
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">
196
137
When linking <TT>.cmxa</TT> libraries, ignore <TT>-cclib</TT> and <TT>-ccopt</TT>
197
138
options potentially contained in the libraries (if these options were
198
139
given when building the libraries). This can be useful if a library
199
140
contains incorrect specifications of C libraries or C options; in this
200
141
case, during linking, set <TT>-noautolink</TT> and pass the correct C
201
libraries and options on the command line.<BR>
203
<DT CLASS="dt-description"><TT><B>-nolabels</B></TT><DD CLASS="dd-description">
142
libraries and options on the command line.</DD><DT CLASS="dt-description"><TT><B>-nolabels</B></TT></DT><DD CLASS="dd-description">
204
143
Ignore non-optional labels in types. Labels cannot be used in
205
applications, and parameter order becomes strict.<BR>
207
<DT CLASS="dt-description"><B><TT>-o</TT> <I>exec-file</I></B><DD CLASS="dd-description">
144
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">
208
145
Specify the name of the output file produced by the linker. The
209
default output name is <TT>a.out</TT>, in keeping with the Unix tradition. If
210
the <TT>-a</TT> option is given, specify the name of the library produced.
211
If the <TT>-output-obj</TT> option is given, specify the name of the output
214
<DT CLASS="dt-description"><TT><B>-output-obj</B></TT><DD CLASS="dd-description">
146
default output name is <TT>a.out</TT> under Unix and <TT>camlprog.exe</TT> under
147
Windows. If the <TT>-a</TT> option is given, specify the name of the library
148
produced. If the <TT>-pack</TT> option is given, specify the name of the
149
packed object file produced. If the <TT>-output-obj</TT> option is given,
150
specify the name of the output file produced.</DD><DT CLASS="dt-description"><TT><B>-output-obj</B></TT></DT><DD CLASS="dd-description">
215
151
Cause the linker to produce a C object file instead of an executable
216
152
file. This is useful to wrap Caml code as a C library,
217
callable from any C program. See chapter <A HREF="manual032.html#c:intf-c">18</A>,
218
section <A HREF="manual032.html#s:embedded-code">18.7.5</A>. The name of the output object file is
219
<TT>camlprog.o</TT> by default; it can be set with the <TT>-o</TT> option.<BR>
221
<DT CLASS="dt-description"><TT><B>-p</B></TT><DD CLASS="dd-description">
153
callable from any C program. See chapter�<A HREF="manual032.html#c:intf-c">18</A>,
154
section�<A HREF="manual032.html#s:embedded-code">18.7.5</A>. The name of the output object file is
155
<TT>camlprog.o</TT> by default; it can be set with the <TT>-o</TT> option.</DD><DT CLASS="dt-description"><TT><B>-p</B></TT></DT><DD CLASS="dd-description">
222
156
Generate extra code to write profile information when the program is
223
157
executed. The profile information can then be examined with the
224
analysis program <TT>gprof</TT>. (See chapter <A HREF="manual031.html#c:profiler">17</A> for more
158
analysis program <TT>gprof</TT>. (See chapter�<A HREF="manual031.html#c:profiler">17</A> for more
225
159
information on profiling.) The <TT>-p</TT> option must be given both at
226
160
compile-time and at link-time. Linking object files not compiled with
227
<TT>-p</TT> is possible, but results in less precise profiling.<BR>
230
<FONT COLOR=purple>Unix:</FONT>
231
<BLOCKQUOTE CLASS="quote"> See the Unix manual page for <TT>gprof(1)</TT> for more
232
information about the profiles.<BR>
234
Full support for <TT>gprof</TT> is only available for certain platforms
161
<TT>-p</TT> is possible, but results in less precise profiling.<BLOCKQUOTE CLASS="quote"><FONT COLOR=purple>Unix:</FONT>�� See the Unix manual page for <TT>gprof(1)</TT> for more
162
information about the profiles.<P>Full support for <TT>gprof</TT> is only available for certain platforms
235
163
(currently: Intel x86/Linux and Alpha/Digital Unix).
236
164
On other platforms, the <TT>-p</TT> option will result in a less precise
237
165
profile (no call graph information, only a time profile).
240
<FONT COLOR=purple>Windows:</FONT>
241
<BLOCKQUOTE CLASS="quote">
166
</P></BLOCKQUOTE><BLOCKQUOTE CLASS="quote"><FONT COLOR=purple>Windows:</FONT>��
242
167
The <TT>-p</TT> option does not work under Windows.
245
<DT CLASS="dt-description"><TT><B>-pack</B></TT><DD CLASS="dd-description">
168
</BLOCKQUOTE></DD><DT CLASS="dt-description"><TT><B>-pack</B></TT></DT><DD CLASS="dd-description">
246
169
Build an object file (<TT>.cmx</TT>/<TT>.o</TT> file) and its associated compiled
247
170
interface (<TT>.cmi</TT>) that combines the <TT>.cmx</TT> object
248
171
files given on the command line, making them appear as sub-modules of
249
172
the output <TT>.cmx</TT> file. The name of the output <TT>.cmx</TT> file must be
250
173
given with the <TT>-o</TT> option. For instance,
251
<PRE CLASS="verbatim">
252
ocamlopt -pack -o P.cmx A.cmx B.cmx C.cmx
174
<PRE CLASS="verbatim"> ocamlopt -pack -o P.cmx A.cmx B.cmx C.cmx
253
175
</PRE>generates compiled files <TT>P.cmx</TT>, <TT>P.o</TT> and <TT>P.cmi</TT> describing a
254
176
compilation unit having three sub-modules <TT>A</TT>, <TT>B</TT> and <TT>C</TT>,
255
177
corresponding to the contents of the object files <TT>A.cmx</TT>, <TT>B.cmx</TT> and
256
178
<TT>C.cmx</TT>. These contents can be referenced as <TT>P.A</TT>, <TT>P.B</TT> and <TT>P.C</TT>
257
in the remainder of the program.<BR>
259
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
260
The <TT>.cmx</TT> object files being combined must have been compiled with
179
in the remainder of the program.<P>The <TT>.cmx</TT> object files being combined must have been compiled with
261
180
the appropriate <TT>-for-pack</TT> option. In the example above,
262
181
<TT>A.cmx</TT>, <TT>B.cmx</TT> and <TT>C.cmx</TT> must have been compiled with
263
<TT>ocamlopt -for-pack P</TT>.<BR>
265
Multiple levels of packing can be achieved by combining <TT>-pack</TT> with
182
<TT>ocamlopt -for-pack P</TT>.</P><P>Multiple levels of packing can be achieved by combining <TT>-pack</TT> with
266
183
<TT>-for-pack</TT>. Consider the following example:
267
<PRE CLASS="verbatim">
268
ocamlopt -for-pack P.Q -c A.ml
184
</P><PRE CLASS="verbatim"> ocamlopt -for-pack P.Q -c A.ml
269
185
ocamlopt -pack -o Q.cmx -for-pack P A.cmx
270
186
ocamlopt -for-pack P -c B.ml
271
187
ocamlopt -pack -o P.cmx Q.cmx B.cmx
272
</PRE>The resulting <TT>P.cmx</TT> object file has sub-modules <TT>P.Q</TT>, <TT>P.Q.A</TT>
273
and <TT>P.B</TT>.<BR>
275
The restriction to systems with GNU binutils has been droped.
278
<DT CLASS="dt-description"><B><TT>-pp</TT> <I>command</I></B><DD CLASS="dd-description">
188
</PRE><P>The resulting <TT>P.cmx</TT> object file has sub-modules <TT>P.Q</TT>, <TT>P.Q.A</TT>
189
and <TT>P.B</TT>.</P></DD><DT CLASS="dt-description"><B><TT>-pp</TT> <I>command</I></B></DT><DD CLASS="dd-description">
279
190
Cause the compiler to call the given <I>command</I> as a preprocessor
280
191
for each source file. The output of <I>command</I> is redirected to
281
192
an intermediate file, which is compiled. If there are no compilation
282
193
errors, the intermediate file is deleted afterwards. The name of this
283
194
file is built from the basename of the source file with the extension
284
195
<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">
196
(<TT>.ml</TT>) file.</DD><DT CLASS="dt-description"><TT><B>-principal</B></TT></DT><DD CLASS="dd-description">
288
197
Check information path during type-checking, to make sure that all
289
198
types are derived in a principal way. All programs accepted in
290
199
<TT>-principal</TT> mode are also accepted in default mode with equivalent
291
types, but different binary signatures.<BR>
293
<DT CLASS="dt-description"><TT><B>-rectypes</B></TT><DD CLASS="dd-description">
200
types, but different binary signatures.</DD><DT CLASS="dt-description"><TT><B>-rectypes</B></TT></DT><DD CLASS="dd-description">
294
201
Allow arbitrary recursive types during type-checking. By default,
295
202
only recursive types where the recursion goes through an object type
298
<DT CLASS="dt-description"><TT><B>-S</B></TT><DD CLASS="dd-description">
203
are supported. Note that once you have created an interface using this
204
flag, you must use it again for all dependencies.</DD><DT CLASS="dt-description"><TT><B>-S</B></TT></DT><DD CLASS="dd-description">
299
205
Keep the assembly code produced during the compilation. The assembly
300
code for the source file <I>x</I><TT>.ml</TT> is saved in the file <I>x</I><TT>.s</TT>.<BR>
302
<DT CLASS="dt-description"><TT><B>-thread</B></TT><DD CLASS="dd-description">
206
code for the source file <I>x</I><TT>.ml</TT> is saved in the file <I>x</I><TT>.s</TT>.</DD><DT CLASS="dt-description"><TT><B>-thread</B></TT></DT><DD CLASS="dd-description">
303
207
Compile or link multithreaded programs, in combination with the
304
system <TT>threads</TT> library described in chapter <A HREF="manual038.html#c:threads">24</A>.<BR>
306
<DT CLASS="dt-description"><TT><B>-unsafe</B></TT><DD CLASS="dd-description">
208
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">
307
209
Turn bound checking off on array and string accesses (the <TT>v.(i)</TT> and
308
210
<TT>s.[i]</TT> constructs). Programs compiled with <TT>-unsafe</TT> are therefore
309
211
faster, but unsafe: anything can happen if the program accesses an
310
array or string outside of its bounds.<BR>
312
<DT CLASS="dt-description"><TT><B>-v</B></TT><DD CLASS="dd-description">
212
array or string outside of its bounds. Additionally, turn off the
213
check for zero divisor in integer division and modulus operations.
214
With <TT>-unsafe</TT>, an integer division (or modulus) by zero can halt the
215
program or continue with an unspecified result instead of raising a
216
<TT>Division_by_zero</TT> exception.</DD><DT CLASS="dt-description"><TT><B>-v</B></TT></DT><DD CLASS="dd-description">
313
217
Print the version number of the compiler and the location of the
314
standard library directory, then exit.<BR>
316
<DT CLASS="dt-description"><TT><B>-verbose</B></TT><DD CLASS="dd-description">
218
standard library directory, then exit.</DD><DT CLASS="dt-description"><TT><B>-verbose</B></TT></DT><DD CLASS="dd-description">
317
219
Print all external commands before they are executed, in particular
318
invocations of the assembler, C compiler, and linker.<BR>
320
<DT CLASS="dt-description"><TT><B>-version</B></TT><DD CLASS="dd-description">
220
invocations of the assembler, C compiler, and linker.</DD><DT CLASS="dt-description"><TT><B>-version</B></TT></DT><DD CLASS="dd-description">
321
221
Print the version number of the compiler in short form (e.g. <TT>3.06</TT>),
324
<DT CLASS="dt-description"><B><TT>-w</TT> <I>warning-list</I></B><DD CLASS="dd-description">
222
then exit.</DD><DT CLASS="dt-description"><B><TT>-w</TT> <I>warning-list</I></B></DT><DD CLASS="dd-description">
325
223
Enable or disable warnings according to the argument
326
224
<I>warning-list</I>. The argument is a string of one or several
327
225
characters, with the following meaning for each character:
328
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
329
<B><TT>A</TT>/<TT>a</TT></B><DD CLASS="dd-description"> enable/disable all warnings.
330
<DT CLASS="dt-description"><B><TT>C</TT>/<TT>c</TT></B><DD CLASS="dd-description"> enable/disable warnings for suspicious comments.
331
<DT CLASS="dt-description"><B><TT>D</TT>/<TT>d</TT></B><DD CLASS="dd-description"> enable/disable warnings for deprecated features.
332
<DT CLASS="dt-description" style="background-color:yellow; color:red"><B><TT>E</TT>/<TT>e</TT></B><DD CLASS="dd-description" style="background-color:yellow; color:red"> enable/disable warnings for fragile pattern matchings
226
<DL CLASS="description"><DT CLASS="dt-description">
227
<B><TT>A</TT>/<TT>a</TT></B></DT><DD CLASS="dd-description"> enable/disable all warnings.
228
</DD><DT CLASS="dt-description"><B><TT>C</TT>/<TT>c</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for suspicious comments.
229
</DD><DT CLASS="dt-description"><B><TT>D</TT>/<TT>d</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for deprecated features.
230
</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
333
231
(matchings that would remain complete if additional constructors are
334
added to a variant type involved).
335
<DT CLASS="dt-description"><B><TT>F</TT>/<TT>f</TT></B><DD CLASS="dd-description"> enable/disable warnings for partially applied functions
232
added to a variant type involved).
233
</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
336
234
(i.e. <TT>f x; </TT><I>expr</I> where the application <TT>f x</TT> has a function type).
337
<DT CLASS="dt-description"><B><TT>L</TT>/<TT>l</TT></B><DD CLASS="dd-description"> enable/disable warnings for labels omitted in application.
338
<DT CLASS="dt-description"><B><TT>M</TT>/<TT>m</TT></B><DD CLASS="dd-description"> enable/disable warnings for overriden methods.
339
<DT CLASS="dt-description"><B><TT>P</TT>/<TT>p</TT></B><DD CLASS="dd-description"> enable/disable warnings for partial matches (missing cases
235
</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.
236
</DD><DT CLASS="dt-description"><B><TT>M</TT>/<TT>m</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for overriden methods.
237
</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
340
238
in pattern matchings).
341
<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
239
</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
342
240
type <TT>unit</TT> (e.g. <I>expr1</I><TT>; </TT><I>expr2</I> when <I>expr1</I> does not
343
241
have type <TT>unit</TT>).
344
<DT CLASS="dt-description"><B><TT>U</TT>/<TT>u</TT></B><DD CLASS="dd-description"> enable/disable warnings for unused (redundant) match cases.
345
<DT CLASS="dt-description"><B><TT>V</TT>/<TT>v</TT></B><DD CLASS="dd-description"> enable/disable warnings for hidden instance variables.
346
<DT CLASS="dt-description" style="background-color:yellow; color:red"><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
242
</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.
243
</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.
244
</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
347
245
<TT>let</TT> or <TT>as</TT> keywords and that don't start with an underscore.
348
<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
246
</DD><DT CLASS="dt-description"><B><TT>Z</TT>/<TT>z</TT></B></DT><DD CLASS="dd-description"> enable/disable warnings for all unused variables that don't
349
247
start with an underscore.
350
<DT CLASS="dt-description"><B><TT>X</TT>/<TT>x</TT></B><DD CLASS="dd-description"> enable/disable all other warnings.
352
<div style="background-color:yellow; color:red; border-style:none; border-width:0.5pt">
353
The default setting is <TT>-w Aelyz</TT>
355
(all warnings enabled except fragile
356
matchings, omitted labels, unused variables).<BR>
358
<DT CLASS="dt-description"><B><TT>-warn-error</TT> <I>warning-list</I></B><DD CLASS="dd-description">
248
</DD><DT CLASS="dt-description"><B><TT>X</TT>/<TT>x</TT></B></DT><DD CLASS="dd-description"> enable/disable all other warnings.
250
The default setting is <TT>-w Aelyz</TT> (all warnings enabled except fragile
251
matchings, omitted labels, unused variables).</DD><DT CLASS="dt-description"><B><TT>-warn-error</TT> <I>warning-list</I></B></DT><DD CLASS="dd-description">
359
252
Turn the warnings indicated in the argument <I>warning-list</I> into
360
253
errors. The compiler will stop on an error as soon as one of these
361
254
warnings is emitted, instead of going on. The <I>warning-list</I>
363
256
the <TT>-w</TT> option: an uppercase character turns the corresponding
364
257
warning into an error, a lowercase character leaves it as a warning.
365
258
The default setting is <TT>-warn-error a</TT> (all warnings are not treated
368
<DT CLASS="dt-description"><TT><B>-where</B></TT><DD CLASS="dd-description">
259
as errors).</DD><DT CLASS="dt-description"><TT><B>-where</B></TT></DT><DD CLASS="dd-description">
369
260
Print the location of the standard library.
372
<H5 CLASS="paragraph">Options for the IA32 architecture</H5>
261
</DD></DL><H5 CLASS="paragraph">Options for the IA32 architecture</H5><P>
373
262
The IA32 code generator (Intel Pentium, AMD Athlon) supports the
374
following additional option:
375
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
376
<TT><B>-ffast-math</B></TT><DD CLASS="dd-description"> Use the IA32 instructions to compute
263
following additional option:</P><DL CLASS="description"><DT CLASS="dt-description">
264
<TT><B>-ffast-math</B></TT></DT><DD CLASS="dd-description"> Use the IA32 instructions to compute
377
265
trigonometric and exponential functions, instead of calling the
378
266
corresponding library routines. The functions affected are:
379
267
<TT>atan</TT>, <TT>atan2</TT>, <TT>cos</TT>, <TT>log</TT>, <TT>log10</TT>, <TT>sin</TT>, <TT>sqrt</TT>, and <TT>tan</TT>.
380
268
The resulting code runs faster, but the range of supported arguments
381
269
and the precision of the result can be reduced. In particular,
382
270
trigonometric operations <TT>cos</TT>, <TT>sin</TT>, <TT>tan</TT> have their range reduced to
383
[−2<SUP>64</SUP>, 2<SUP>64</SUP>].
386
<H5 CLASS="paragraph">Options for the Sparc architecture</H5>
271
[−2<SUP>64</SUP>, 2<SUP>64</SUP>].
272
</DD></DL><H5 CLASS="paragraph">Options for the Sparc architecture</H5><P>
387
273
The Sparc code generator supports the following additional options:
388
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
389
<TT><B>-march=v8</B></TT><DD CLASS="dd-description"> Generate SPARC version 8 code.
390
<DT CLASS="dt-description"><TT><B>-march=v9</B></TT><DD CLASS="dd-description"> Generate SPARC version 9 code.
274
</P><DL CLASS="description"><DT CLASS="dt-description">
275
<TT><B>-march=v8</B></TT></DT><DD CLASS="dd-description"> Generate SPARC version 8 code.
276
</DD><DT CLASS="dt-description"><TT><B>-march=v9</B></TT></DT><DD CLASS="dd-description"> Generate SPARC version 9 code.
392
278
The default is to generate code for SPARC version 7, which runs on all
393
SPARC processors.<BR>
396
<H2 CLASS="section"><A NAME="htoc123">11.3</A> Common errors</H2>
397
The error messages are almost identical to those of <TT>ocamlc</TT>.
398
See section <A HREF="manual022.html#s:comp-errors">8.4</A>.<BR>
401
<H2 CLASS="section"><A NAME="htoc124">11.4</A> Running executables produced by ocamlopt</H2>
402
Executables generated by <TT>ocamlopt</TT> are native, statically-linked,
279
SPARC processors.</P><H2 CLASS="section"><A NAME="htoc123">11.3</A>��Common errors</H2><P>The error messages are almost identical to those of <TT>ocamlc</TT>.
280
See section�<A HREF="manual022.html#s:comp-errors">8.4</A>.</P><H2 CLASS="section"><A NAME="htoc124">11.4</A>��Running executables produced by ocamlopt</H2><P>Executables generated by <TT>ocamlopt</TT> are native, statically-linked,
403
281
stand-alone executable files that can be invoked directly. They do
404
not depend on the <TT>ocamlrun</TT> bytecode runtime system.<BR>
406
During execution of an <TT>ocamlopt</TT>-generated executable,
282
not depend on the <TT>ocamlrun</TT> bytecode runtime system.</P><P>During execution of an <TT>ocamlopt</TT>-generated executable,
407
283
the following environment variables are also consulted:
408
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
409
<TT><B>OCAMLRUNPARAM</B></TT><DD CLASS="dd-description"> Same usage as in <TT>ocamlrun</TT>
410
(see section <A HREF="manual024.html#ocamlrun-options">10.2</A>), except that option <TT>l</TT>
411
is ignored (the operating system's stack size limit
412
is used instead) and option <TT>b</TT> is ignored (stack backtraces on
413
uncaught exceptions are not printed).
414
<DT CLASS="dt-description"><TT><B>CAMLRUNPARAM</B></TT><DD CLASS="dd-description"> If <TT>OCAMLRUNPARAM</TT> is not found in the
415
environment, then <TT>CAMLRUNPARAM</TT> will be used instead. If
416
<TT>CAMLRUNPARAM</TT> is not found, then the default values will be used.
419
<H2 CLASS="section"><A NAME="htoc125">11.5</A> Compatibility with the bytecode compiler</H2>
420
<A NAME="s:compat-native-bytecode"></A>
421
This section lists the known incompatibilities between the bytecode
284
</P><DL CLASS="description"><DT CLASS="dt-description">
285
<TT><B>OCAMLRUNPARAM</B></TT></DT><DD CLASS="dd-description"> Same usage as in <TT>ocamlrun</TT>
286
(see section�<A HREF="manual024.html#ocamlrun-options">10.2</A>), except that option <TT>l</TT>
287
is ignored (the operating system's stack size limit
288
is used instead) and option <TT>b</TT> is ignored (stack backtraces on
289
uncaught exceptions are not printed).
290
</DD><DT CLASS="dt-description"><TT><B>CAMLRUNPARAM</B></TT></DT><DD CLASS="dd-description"> If <TT>OCAMLRUNPARAM</TT> is not found in the
291
environment, then <TT>CAMLRUNPARAM</TT> will be used instead. If
292
<TT>CAMLRUNPARAM</TT> is not found, then the default values will be used.
293
</DD></DL><H2 CLASS="section"><A NAME="htoc125">11.5</A>��Compatibility with the bytecode compiler</H2><P>
294
<A NAME="s:compat-native-bytecode"></A></P><P>This section lists the known incompatibilities between the bytecode
422
295
compiler and the native-code compiler. Except on those points, the two
423
compilers should generate code that behave identically.
424
<UL CLASS="itemize"><LI CLASS="li-itemize">The following operations abort the program (via an hardware trap
425
or fatal Unix signal) instead of raising an exception:
426
<UL CLASS="itemize"><LI CLASS="li-itemize">
427
stack overflow (except on IA32/Linux);
428
<LI CLASS="li-itemize">on the Alpha processor only, floating-point operations involving
429
infinite or denormalized numbers (all other processors supported by
430
<TT>ocamlopt</TT> treat these numbers correctly, as per the IEEE 754 standard).
432
In particular, notice that stack overflow caused by excessively deep
433
recursion is reported by most Unix kernels as a “segmentation
434
violation” signal.<BR>
436
<LI CLASS="li-itemize">Signals are detected only when the program performs an
296
compilers should generate code that behave identically.</P><UL CLASS="itemize"><LI CLASS="li-itemize">Signals are detected only when the program performs an
437
297
allocation in the heap. That is, if a signal is delivered while in a
438
298
piece of code that does not allocate, its handler will not be called
439
until the next heap allocation.</UL>
440
The best way to avoid running into those incompatibilities is to <EM>never</EM> trap the <TT>Stack_overflow</TT> exception, thus treating it
441
as a fatal error both with the bytecode compiler and with the
442
native-code compiler.
447
<A HREF="manual024.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
448
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
449
<A HREF="manual026.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
299
until the next heap allocation.</LI><LI CLASS="li-itemize">Stack overflow, typically caused by excessively deep recursion,
300
is handled in one of the following ways, depending on the
302
<UL CLASS="itemize"><LI CLASS="li-itemize">
303
By raising a <TT>Stack_overflow</TT> exception, like the bytecode
304
compiler does. (IA32/Linux, AMD64/Linux, PowerPC/MacOSX, MS Windows
306
</LI><LI CLASS="li-itemize">By aborting the program on a “segmentation fault” signal.
307
(All other Unix systems.)
308
</LI><LI CLASS="li-itemize">By terminating the program silently.
309
(MS Windows 64 bits).
310
</LI></UL></LI><LI CLASS="li-itemize">On IA32 processors only (Intel Pentium, AMD Athlon, etc, in
311
32-bit mode), some intermediate results in floating-point computations
312
are kept in extended precision rather than being rounded to double
313
precision like the bytecode compiler always does. Floating-point
314
results can therefore differ between bytecode and native code; in
315
general, the results obtained with native code are “more exact”
316
(less affected by rounding errors and loss of precision).</LI><LI CLASS="li-itemize">On the Alpha processor only, floating-point operations involving
317
infinite or denormalized numbers can abort the program on a
318
“floating-point exception” signal.</LI></UL><HR>
319
<A HREF="manual024.html"><IMG SRC="previous_motif.gif" ALT="Previous"></A>
320
<A HREF="index.html"><IMG SRC="contents_motif.gif" ALT="Up"></A>
321
<A HREF="manual026.html"><IMG SRC="next_motif.gif" ALT="Next"></A>
added
removed
ocaml.html/manual025.html
