1
2OCAMLOPT(1) General Commands Manual OCAMLOPT(1)
3
4
5
7 ocamlopt - The Objective Caml native-code compiler
8
9
11 ocamlopt [ options ] filename ...
12
13 ocamlopt.opt (same options)
14
15
17 The Objective Caml high-performance native-code compiler ocamlopt(1)
18 compiles Caml source files to native code object files and link these
19 object files to produce standalone executables.
20
21 The ocamlopt(1) command has a command-line interface very close to that
22 of ocamlc(1). It accepts the same types of arguments and processes
23 them sequentially:
24
25 Arguments ending in .mli are taken to be source files for compilation
26 unit interfaces. Interfaces specify the names exported by compilation
27 units: they declare value names with their types, define public data
28 types, declare abstract data types, and so on. From the file x.mli, the
29 ocamlopt(1) compiler produces a compiled interface in the file x.cmi.
30 The interface produced is identical to that produced by the bytecode
31 compiler ocamlc(1).
32
33 Arguments ending in .ml are taken to be source files for compilation
34 unit implementations. Implementations provide definitions for the names
35 exported by the unit, and also contain expressions to be evaluated for
36 their side-effects. From the file x.ml, the ocamlopt(1) compiler pro‐
37 duces two files: x.o, containing native object code, and x.cmx, con‐
38 taining extra information for linking and optimization of the clients
39 of the unit. The compiled implementation should always be referred to
40 under the name x.cmx (when given a .o file, ocamlopt(1) assumes that it
41 contains code compiled from C, not from Caml).
42
43 The implementation is checked against the interface file x.mli (if it
44 exists) as described in the manual for ocamlc(1).
45
46 Arguments ending in .cmx are taken to be compiled object code. These
47 files are linked together, along with the object files obtained by com‐
48 piling .ml arguments (if any), and the Caml Light standard library, to
49 produce a native-code executable program. The order in which .cmx and
50 .ml arguments are presented on the command line is relevant: compila‐
51 tion units are initialized in that order at run-time, and it is a link-
52 time error to use a component of a unit before having initialized it.
53 Hence, a given x.cmx file must come before all .cmx files that refer to
54 the unit x.
55
56 Arguments ending in .cmxa are taken to be libraries of object code.
57 Such a library packs in two files lib.cmxa and lib.a a set of object
58 files (.cmx/.o files). Libraries are build with ocamlopt -a (see the
59 description of the -a option below). The object files contained in the
60 library are linked as regular .cmx files (see above), in the order
61 specified when the library was built. The only difference is that if an
62 object file contained in a library is not referenced anywhere in the
63 program, then it is not linked in.
64
65 Arguments ending in .c are passed to the C compiler, which generates a
66 .o object file. This object file is linked with the program.
67
68 Arguments ending in .o or .a are assumed to be C object files and
69 libraries. They are linked with the program.
70
71 The output of the linking phase is a regular Unix executable file. It
72 does not need ocamlrun(1) to run.
73
74 ocamlopt.opt is the same compiler as ocamlopt, but compiled with itself
75 instead of with the bytecode compiler ocamlc(1). Thus, it behaves
76 exactly like ocamlopt, but compiles faster. ocamlopt.opt is not avail‐
77 able in all installations of Objective Caml.
78
79
81 The following command-line options are recognized by ocamlopt(1).
82
83 -a Build a library (.cmxa/.a file) with the object files (.cmx/.o
84 files) given on the command line, instead of linking them into
85 an executable file. The name of the library must be set with the
86 -o option.
87
88 If -cclib or -ccopt options are passed on the command line,
89 these options are stored in the resulting .cmxa library. Then,
90 linking with this library automatically adds back the 0 options
91 as if they had been provided on the command line, unless the
92 -noautolink option is given.
93
94 -annot Dump detailed information about the compilation (types, bind‐
95 ings, tail-calls, etc). The information for file src.ml is put
96 into file src.annot. In case of a type error, dump all the
97 information inferred by the type-checker before the error. The
98 src.annot file can be used with the emacs commands given in
99 emacs/caml-types.el to display types and other annotations
100 interactively.
101
102 -c Compile only. Suppress the linking phase of the compilation.
103 Source code files are turned into compiled files, but no exe‐
104 cutable file is produced. This option is useful to compile mod‐
105 ules separately.
106
107 -cc ccomp
108 Use ccomp as the C linker called to build the final executable
109 and as the C compiler for compiling .c source files.
110
111 -cclib -llibname
112 Pass the -llibname option to the linker. This causes the given C
113 library to be linked with the program.
114
115 -ccopt option
116 Pass the given option to the C compiler and linker. For
117 instance, -ccopt -Ldir causes the C linker to search for C
118 libraries in directory dir.
119
120 -compact
121 Optimize the produced code for space rather than for time. This
122 results in smaller but slightly slower programs. The default is
123 to optimize for speed.
124
125 -config
126 Print the version number of ocamlopt(1) and a detailed summary
127 of its configuration, then exit.
128
129 -for-pack module-path
130 Generate an object file (.cmx and .o files) that can later be
131 included as a sub-module (with the given access path) of a com‐
132 pilation unit constructed with -pack. For instance, ocam‐
133 lopt -for-pack P -c A.ml will generate a.cmx and a.o files that
134 can later be used with ocamlopt -pack -o P.cmx a.cmx.
135
136 -g Add debugging information while compiling and linking. This
137 option is required in order to produce stack backtraces when the
138 program terminates on an uncaught exception (see ocamlrun(1)).
139
140 -i Cause the compiler to print all defined names (with their
141 inferred types or their definitions) when compiling an implemen‐
142 tation (.ml file). No compiled files (.cmo and .cmi files) are
143 produced. This can be useful to check the types inferred by the
144 compiler. Also, since the output follows the syntax of inter‐
145 faces, it can help in writing an explicit interface (.mli file)
146 for a file: just redirect the standard output of the compiler to
147 a .mli file, and edit that file to remove all declarations of
148 unexported names.
149
150 -I directory
151 Add the given directory to the list of directories searched for
152 compiled interface files (.cmi) and compiled object code files
153 (.cmo). By default, the current directory is searched first,
154 then the standard library directory. Directories added with -I
155 are searched after the current directory, in the order in which
156 they were given on the command line, but before the standard
157 library directory.
158
159 If the given directory starts with +, it is taken relative to
160 the standard library directory. For instance, -I +labltk adds
161 the subdirectory labltk of the standard library to the search
162 path.
163
164 -inline n
165 Set aggressiveness of inlining to n, where n is a positive inte‐
166 ger. Specifying -inline 0 prevents all functions from being
167 inlined, except those whose body is smaller than the call site.
168 Thus, inlining causes no expansion in code size. The default
169 aggressiveness, -inline 1, allows slightly larger functions to
170 be inlined, resulting in a slight expansion in code size. Higher
171 values for the -inline option cause larger and larger functions
172 to become candidate for inlining, but can result in a serious
173 increase in code size.
174
175 -intf filename
176 Compile the file filename as an interface file, even if its
177 extension is not .mli.
178
179 -intf-suffix string
180 Recognize file names ending with string as interface files
181 (instead of the default .mli).
182
183 -labels
184 Labels are not ignored in types, labels may be used in applica‐
185 tions, and labelled parameters can be given in any order. This
186 is the default.
187
188 -linkall
189 Force all modules contained in libraries to be linked in. If
190 this flag is not given, unreferenced modules are not linked in.
191 When building a library (-a flag), setting the -linkall flag
192 forces all subsequent links of programs involving that library
193 to link all the modules contained in the library.
194
195 -noassert
196 Do not compile assertion checks. Note that the special form
197 assert false is always compiled because it is typed specially.
198 This flag has no effect when linking already-compiled files.
199
200 -noautolink
201 When linking .cmxa libraries, ignore -cclib and -ccopt options
202 potentially contained in the libraries (if these options were
203 given when building the libraries). This can be useful if a
204 library contains incorrect specifications of C libraries or C
205 options; in this case, during linking, set -noautolink and pass
206 the correct C libraries and options on the command line.
207
208 -nodynlink
209 Allow the compiler to use some optimizations that are valid only
210 for code that is never dynlinked.
211
212 -nolabels
213 Ignore non-optional labels in types. Labels cannot be used in
214 applications, and parameter order becomes strict.
215
216 -o exec-file
217 Specify the name of the output file produced by the linker. The
218 default output name is a.out, in keeping with the Unix tradi‐
219 tion. If the -a option is given, specify the name of the library
220 produced. If the -pack option is given, specify the name of the
221 packed object file produced. If the -output-obj option is
222 given, specify the name of the output file produced. If the
223 -shared option is given, specify the name of plugin file pro‐
224 duced.
225
226 -output-obj
227 Cause the linker to produce a C object file instead of an exe‐
228 cutable file. This is useful to wrap Caml code as a C library,
229 callable from any C program. The name of the output object file
230 is camlprog.o by default; it can be set with the -o option.
231 This option can also be used to produce a compiled
232 shared/dynamic library (.so extension).
233
234 -p Generate extra code to write profile information when the pro‐
235 gram is executed. The profile information can then be examined
236 with the analysis program gprof(1). The -p option must be given
237 both at compile-time and at link-time. Linking object files not
238 compiled with -p is possible, but results in less precise pro‐
239 filing.
240
241 See the gprof(1) man page for more information about the pro‐
242 files.
243
244 Full support for gprof(1) is only available for certain plat‐
245 forms (currently: Intel x86/Linux and Alpha/Digital Unix). On
246 other platforms, the -p option will result in a less precise
247 profile (no call graph information, only a time profile).
248
249 -pack Build an object file (.cmx and .o files) and its associated com‐
250 piled interface (.cmi) that combines the .cmx object files given
251 on the command line, making them appear as sub-modules of the
252 output .cmx file. The name of the output .cmx file must be
253 given with the -o option. For instance, ocam‐
254 lopt -pack -o P.cmx A.cmx B.cmx C.cmx generates compiled files
255 P.cmx, P.o and P.cmi describing a compilation unit having three
256 sub-modules A, B and C, corresponding to the contents of the
257 object files A.cmx, B.cmx and C.cmx. These contents can be ref‐
258 erenced as P.A, P.B and P.C in the remainder of the program.
259
260 The .cmx object files being combined must have been compiled
261 with the appropriate -for-pack option. In the example above,
262 A.cmx, B.cmx and C.cmx must have been compiled with ocam‐
263 lopt -for-pack P.
264
265 Multiple levels of packing can be achieved by combining -pack
266 with -for-pack. See The Objective Caml user's manual, chapter
267 "Native-code compilation" for more details.
268
269 -pp command
270 Cause the compiler to call the given command as a preprocessor
271 for each source file. The output of command is redirected to an
272 intermediate file, which is compiled. If there are no compila‐
273 tion errors, the intermediate file is deleted afterwards.
274
275 -principal
276 Check information path during type-checking, to make sure that
277 all types are derived in a principal way. All programs accepted
278 in -principal mode are also accepted in default mode with equiv‐
279 alent types, but different binary signatures.
280
281 -rectypes
282 Allow arbitrary recursive types during type-checking. By
283 default, only recursive types where the recursion goes through
284 an object type are supported. Note that once you have created an
285 interface using this flag, you must use it again for all depen‐
286 dencies.
287
288 -S Keep the assembly code produced during the compilation. The
289 assembly code for the source file x.ml is saved in the file x.s.
290
291 -shared
292 Build a plugin (usually .cmxs) that can be dynamically loaded
293 with the Dynlink module. The name of the plugin must be set with
294 the -o option. A plugin can include a number of Caml modules and
295 libraries, and extra native objects (.o, .a files). Building
296 native plugins is only supported for some operating system.
297 Under some systems (currently, only Linux AMD 64), all the Caml
298 code linked in a plugin must have been compiled without the
299 -nodynlink flag. Some constraints might also apply to the way
300 the extra native objects have been compiled (under Linux AMD 64,
301 they must contain only position-independent code).
302
303 -thread
304 Compile or link multithreaded programs, in combination with the
305 system threads library described in The Objective Caml user's
306 manual.
307
308 -unsafe
309 Turn bound checking off for array and string accesses (the
310 v.(i)ands.[i] constructs). Programs compiled with -unsafe are
311 therefore faster, but unsafe: anything can happen if the program
312 accesses an array or string outside of its bounds. Additionally,
313 turn off the check for zero divisor in integer division and mod‐
314 ulus operations. With -unsafe, an integer division (or modulus)
315 by zero can halt the program or continue with an unspecified
316 result instead of raising a Division_by_zero exception.
317
318 -v Print the version number of the compiler and the location of the
319 standard library directory, then exit.
320
321 -verbose
322 Print all external commands before they are executed, in partic‐
323 ular invocations of the assembler, C compiler, and linker.
324
325 -version
326 Print the version number of the compiler in short form (e.g.
327 "3.11.0"), then exit.
328
329 -w warning-list
330 Enable or disable warnings according to the argument warn‐
331 ing-list. The argument is a set of letters. If a letter is
332 uppercase, it enables the corresponding warnings; lowercase dis‐
333 ables the warnings. The correspondence is the following:
334
335 A all warnings
336
337 C start of comments that look like mistakes
338
339 D use of deprecated features
340
341 E fragile pattern matchings (matchings that will remain com‐
342 plete even if additional constructors are added to one of the
343 variant types matched)
344
345 F partially applied functions (expressions whose result has
346 function type and is ignored)
347
348 L omission of labels in applications
349
350 M overriding of methods
351
352 P missing cases in pattern matchings (i.e. partial matchings)
353
354 S expressions in the left-hand side of a sequence that don't
355 have type unit (and that are not functions, see F above)
356
357 U redundant cases in pattern matching (unused cases)
358
359 V overriding of instance variables
360
361 Y unused variables that are bound with let or as, and don't
362 start with an underscore (_) character
363
364 Z all other cases of unused variables that don't start with an
365 underscore (_) character
366
367 X warnings that don't fit in the above categories (except A)
368
369 The default setting is -w Aelz, enabling all warnings except
370 fragile pattern matchings, omitted labels, and innocuous unused
371 variables. Note that warnings F and S are not always triggered,
372 depending on the internals of the type checker.
373
374 -warn-error warning-list
375 Turn the warnings indicated in the argument warning-list into
376 errors. The compiler will stop with an error when one of these
377 warnings is emitted. The warning-list has the same meaning as
378 for the "-w" option: an uppercase character turns the corre‐
379 sponding warning into an error, a lowercase character leaves it
380 as a warning. The default setting is -warn-error a (none of the
381 warnings is treated as an error).
382
383 -where Print the location of the standard library, then exit.
384
385 - file Process file as a file name, even if it starts with a dash (-)
386 character.
387
388 -help or --help
389 Display a short usage summary and exit.
390
391
393 The IA32 code generator (Intel Pentium, AMD Athlon) supports the fol‐
394 lowing additional option:
395
396 -ffast-math
397 Use the IA32 instructions to compute trigonometric and exponen‐
398 tial functions, instead of calling the corresponding library
399 routines. The functions affected are: atan, atan2, cos, log,
400 log10, sin, sqrt and tan. The resulting code runs faster, but
401 the range of supported arguments and the precision of the result
402 can be reduced. In particular, trigonometric operations cos,
403 sin, tan have their range reduced to [-2^64, 2^64].
404
405
407 The AMD64 code generator (64-bit versions of Intel Pentium and AMD
408 Athlon) supports the following additional options:
409
410 -fPIC Generate position-independent machine code. This is the
411 default.
412
413 -fno-PIC
414 Generate position-dependent machine code.
415
416
418 The Sparc code generator supports the following additional options:
419
420 -march=v8
421 Generate SPARC version 8 code.
422
423 -march=v9
424 Generate SPARC version 9 code.
425
426 The default is to generate code for SPARC version 7, which runs on all
427 SPARC processors.
428
429
431 ocamlc(1).
432 The Objective Caml user's manual, chapter "Native-code compilation".
433
434
435
436 OCAMLOPT(1)