1 .\"**************************************************************************
2 .\"* *
3 .\"* OCaml *
4 .\"* *
5 .\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt *
6 .\"* *
7 .\"* Copyright 1996 Institut National de Recherche en Informatique et *
8 .\"* en Automatique. *
9 .\"* *
10 .\"* All rights reserved. This file is distributed under the terms of *
11 .\"* the GNU Lesser General Public License version 2.1, with the *
12 .\"* special exception on linking described in the file LICENSE. *
13 .\"* *
14 .\"**************************************************************************
15 .\"
20 ocamlopt \- The OCaml native-code compiler
24 .B ocamlopt
25 [
26 .I options
27 ]
28 .IR filename \ ...
30 .B ocamlopt.opt
31 (same options)
35 The OCaml high-performance
36 native-code compiler
37 .BR ocamlopt (1)
38 compiles OCaml source files to native code object files and link these
39 object files to produce standalone executables.
41 The
42 .BR ocamlopt (1)
43 command has a command-line interface very close to that
44 of
45 .BR ocamlc (1).
46 It accepts the same types of arguments and processes them
47 sequentially, after all options have been processed:
49 Arguments ending in .mli are taken to be source files for
50 compilation unit interfaces. Interfaces specify the names exported by
51 compilation units: they declare value names with their types, define
52 public data types, declare abstract data types, and so on. From the
53 file
54 .IR x .mli,
55 the
56 .BR ocamlopt (1)
57 compiler produces a compiled interface
58 in the file
59 .IR x .cmi.
60 The interface produced is identical to that
61 produced by the bytecode compiler
62 .BR ocamlc (1).
64 Arguments ending in .ml are taken to be source files for compilation
65 unit implementations. Implementations provide definitions for the
66 names exported by the unit, and also contain expressions to be
67 evaluated for their side-effects. From the file
68 .IR x .ml,
69 the
70 .BR ocamlopt (1)
71 compiler produces two files:
72 .IR x .o,
73 containing native object code, and
74 .IR x .cmx,
75 containing extra information for linking and
76 optimization of the clients of the unit. The compiled implementation
77 should always be referred to under the name
78 .IR x .cmx
79 (when given a .o file,
80 .BR ocamlopt (1)
81 assumes that it contains code compiled from C, not from OCaml).
83 The implementation is checked against the interface file
84 .IR x .mli
85 (if it exists) as described in the manual for
86 .BR ocamlc (1).
88 Arguments ending in .cmx are taken to be compiled object code. These
89 files are linked together, along with the object files obtained
90 by compiling .ml arguments (if any), and the OCaml standard
91 library, to produce a native-code executable program. The order in
92 which .cmx and .ml arguments are presented on the command line is
93 relevant: compilation units are initialized in that order at
94 run-time, and it is a link-time error to use a component of a unit
95 before having initialized it. Hence, a given
96 .IR x .cmx
97 file must come
98 before all .cmx files that refer to the unit
99 .IR x .
101 Arguments ending in .cmxa are taken to be libraries of object code.
102 Such a library packs in two files
103 .IR lib .cmxa
104 and
105 .IR lib .a
106 a set of object files (.cmx/.o files). Libraries are build with
107 .B ocamlopt \-a
108 (see the description of the
109 .B \-a
110 option below). The object
111 files contained in the library are linked as regular .cmx files (see
112 above), in the order specified when the library was built. The only
113 difference is that if an object file contained in a library is not
114 referenced anywhere in the program, then it is not linked in.
116 Arguments ending in .c are passed to the C compiler, which generates
117 a .o object file. This object file is linked with the program.
119 Arguments ending in .o or .a are assumed to be C object files and
120 libraries. They are linked with the program.
122 The output of the linking phase is a regular Unix executable file. It
123 does not need
124 .BR ocamlrun (1)
125 to run.
127 .B ocamlopt.opt
128 is the same compiler as
129 .BR ocamlopt ,
130 but compiled with itself instead of with the bytecode compiler
131 .BR ocamlc (1).
132 Thus, it behaves exactly like
133 .BR ocamlopt ,
134 but compiles faster.
135 .B ocamlopt.opt
136 is not available in all installations of OCaml.
140 The following command-line options are recognized by
141 .BR ocamlopt (1).
142 .TP
143 .B \-a
144 Build a library (.cmxa/.a file) with the object files (.cmx/.o
145 files) given on the command line, instead of linking them into an
146 executable file. The name of the library must be set with the
147 .B \-o
148 option.
150 If
151 .BR \-cclib \ or \ \-ccopt
152 options are passed on the command
153 line, these options are stored in the resulting .cmxa library. Then,
154 linking with this library automatically adds back the
155 .BR \-cclib \ and \ \-ccopt
156 options as if they had been provided on the
157 command line, unless the
158 .B \-noautolink
159 option is given. Additionally, a substring
161 inside a
162 .BR \ \-ccopt
163 options will be replaced by the full path to the .cma library,
164 excluding the filename.
165 .TP
166 .B \-absname
167 Show absolute filenames in error messages.
168 .TP
169 .B \-annot
170 Dump detailed information about the compilation (types, bindings,
171 tail-calls, etc). The information for file
172 .IR src .ml
173 is put into file
174 .IR src .annot.
175 In case of a type error, dump all the information inferred by the
176 type-checker before the error. The
177 .IR src .annot
178 file can be used with the emacs commands given in
179 .B emacs/caml\-types.el
180 to display types and other annotations interactively.
181 .TP
182 .B \-bin\-annot
183 Dump detailed information about the compilation (types, bindings,
184 tail-calls, etc) in binary format. The information for file
185 .IR src .ml
186 is put into file
187 .IR src .cmt.
188 In case of a type error, dump
189 all the information inferred by the type-checker before the error.
190 The annotation files produced by
191 .B \-bin\-annot
192 contain more information
193 and are much more compact than the files produced by
194 .BR \-annot .
195 .TP
196 .B \-c
197 Compile only. Suppress the linking phase of the
198 compilation. Source code files are turned into compiled files, but no
199 executable file is produced. This option is useful to
200 compile modules separately.
201 .TP
202 .BI \-cc \ ccomp
203 Use
204 .I ccomp
205 as the C linker called to build the final executable and as the C
206 compiler for compiling .c source files.
207 .TP
208 .BI \-cclib\ \-l libname
209 Pass the
210 .BI \-l libname
211 option to the linker. This causes the given C library to be linked
212 with the program.
213 .TP
214 .BI \-ccopt \ option
215 Pass the given option to the C compiler and linker. For instance,
216 .BI \-ccopt\ \-L dir
217 causes the C linker to search for C libraries in
218 directory
219 .IR dir .
220 .TP
221 .BI \-color \ mode
222 Enable or disable colors in compiler messages (especially warnings and errors).
223 The following modes are supported:
225 .B auto
226 use heuristics to enable colors only if the output supports them (an
227 ANSI-compatible tty terminal);
229 .B always
230 enable colors unconditionally;
232 .B never
233 disable color output.
235 The default setting is
236 .B auto,
237 and the current heuristic
238 checks that the "TERM" environment variable exists and is
239 not empty or "dumb", and that isatty(stderr) holds.
241 The environment variable "OCAML_COLOR" is considered if \-color is not
242 provided. Its values are auto/always/never as above.
244 .TP
245 .BI \-error\-style \ mode
246 Control the way error messages and warnings are printed.
247 The following modes are supported:
249 .B short
250 only print the error and its location;
252 .B contextual
253 like "short", but also display the source code snippet corresponding
254 to the location of the error.
256 The default setting is
257 .B contextual.
259 The environment variable "OCAML_ERROR_STYLE" is considered if
260 \-error\-style is not provided. Its values are short/contextual as
261 above.
263 .TP
264 .B \-compact
265 Optimize the produced code for space rather than for time. This
266 results in smaller but slightly slower programs. The default is to
267 optimize for speed.
268 .TP
269 .B \-config
270 Print the version number of
271 .BR ocamlopt (1)
272 and a detailed summary of its configuration, then exit.
273 .TP
274 .BI \-config-var
275 Print the value of a specific configuration variable
276 from the
277 .B \-config
278 output, then exit. If the variable does not exist,
279 the exit code is non-zero.
280 .TP
281 .BI \-depend\ ocamldep-args
282 Compute dependencies, as ocamldep would do.
283 .TP
284 .BI \-for\-pack \ module\-path
285 Generate an object file (.cmx and .o files) that can later be included
286 as a sub-module (with the given access path) of a compilation unit
287 constructed with
288 .BR \-pack .
289 For instance,
290 .B ocamlopt\ \-for\-pack\ P\ \-c\ A.ml
291 will generate a.cmx and a.o files that can later be used with
292 .BR "ocamlopt -pack -o P.cmx a.cmx" .
293 .TP
294 .B \-g
295 Add debugging information while compiling and linking. This option is
296 required in order to produce stack backtraces when
297 the program terminates on an uncaught exception (see
298 .BR ocamlrun (1)).
299 .TP
300 .B \-i
301 Cause the compiler to print all defined names (with their inferred
302 types or their definitions) when compiling an implementation (.ml
303 file). No compiled files (.cmo and .cmi files) are produced.
304 This can be useful to check the types inferred by the
305 compiler. Also, since the output follows the syntax of interfaces, it
306 can help in writing an explicit interface (.mli file) for a file:
307 just redirect the standard output of the compiler to a .mli file,
308 and edit that file to remove all declarations of unexported names.
309 .TP
310 .BI \-I \ directory
311 Add the given directory to the list of directories searched for
312 compiled interface files (.cmi), compiled object code files (.cmx),
313 and libraries (.cmxa). By default, the current directory is searched
314 first, then the standard library directory. Directories added with \-I
315 are searched after the current directory, in the order in which they
316 were given on the command line, but before the standard library
317 directory. See also option
318 .BR \-nostdlib .
320 If the given directory starts with
321 .BR + ,
322 it is taken relative to the
323 standard library directory. For instance,
324 .B \-I\ +compiler-libs
325 adds the subdirectory
326 .B compiler-libs
327 of the standard library to the search path.
328 .TP
329 .BI \-impl \ filename
330 Compile the file
331 .I filename
332 as an implementation file, even if its extension is not .ml.
333 .TP
334 .BI \-inline \ n
335 Set aggressiveness of inlining to
336 .IR n ,
337 where
338 .I n
339 is a positive
340 integer. Specifying
341 .B \-inline 0
342 prevents all functions from being
343 inlined, except those whose body is smaller than the call site. Thus,
344 inlining causes no expansion in code size. The default aggressiveness,
345 .BR \-inline\ 1 ,
346 allows slightly larger functions to be inlined, resulting
347 in a slight expansion in code size. Higher values for the
348 .B \-inline
349 option cause larger and larger functions to become candidate for
350 inlining, but can result in a serious increase in code size.
351 .TP
352 .B \-insn\-sched
353 Enables the instruction scheduling pass in the compiler backend.
354 .TP
355 .BI \-intf \ filename
356 Compile the file
357 .I filename
358 as an interface file, even if its extension is not .mli.
359 .TP
360 .BI \-intf\-suffix \ string
361 Recognize file names ending with
362 .I string
363 as interface files (instead of the default .mli).
364 .TP
365 .B \-keep-docs
366 Keep documentation strings in generated .cmi files.
367 .TP
368 .B \-keep-locs
369 Keep locations in generated .cmi files.
370 .TP
371 .B \-labels
372 Labels are not ignored in types, labels may be used in applications,
373 and labelled parameters can be given in any order. This is the default.
374 .TP
375 .B \-linkall
376 Force all modules contained in libraries to be linked in. If this
377 flag is not given, unreferenced modules are not linked in. When
378 building a library
379 .RB ( \-a
380 flag), setting the
381 .B \-linkall
382 flag forces all
383 subsequent links of programs involving that library to link all the
384 modules contained in the library.
385 When compiling a module (option
386 .BR \-c ),
387 setting the
388 .B \-linkall
389 option ensures that this module will
390 always be linked if it is put in a library and this library is linked.
391 .TP
392 .B \-linscan
393 Use linear scan register allocation. Compiling with this allocator is faster
394 than with the usual graph coloring allocator, sometimes quite drastically so for
395 long functions and modules. On the other hand, the generated code can be a bit
396 slower.
397 .TP
398 .B \-match\-context\-rows
399 Set number of rows of context used during pattern matching
400 compilation. Lower values cause faster compilation, but
401 less optimized code. The default value is 32.
402 .TP
403 .B \-no-alias-deps
404 Do not record dependencies for module aliases.
405 .TP
406 .B \-no\-app\-funct
407 Deactivates the applicative behaviour of functors. With this option,
408 each functor application generates new types in its result and
409 applying the same functor twice to the same argument yields two
410 incompatible structures.
411 .TP
412 .B \-noassert
413 Do not compile assertion checks. Note that the special form
414 .B assert\ false
415 is always compiled because it is typed specially.
416 This flag has no effect when linking already-compiled files.
417 .TP
418 .B \-noautolink
419 When linking .cmxa libraries, ignore
420 .BR \-cclib \ and \ \-ccopt
421 options potentially contained in the libraries (if these options were
422 given when building the libraries). This can be useful if a library
423 contains incorrect specifications of C libraries or C options; in this
424 case, during linking, set
425 .B -noautolink
426 and pass the correct C libraries and options on the command line.
427 .TP
428 .B \-nodynlink
429 Allow the compiler to use some optimizations that are valid only for code
430 that is never dynlinked.
431 .TP
432 .B \-no\-insn\-sched
433 Disables the instruction scheduling pass in the compiler backend.
434 .TP
435 .B -nostdlib
436 Do not automatically add the standard library directory to the list of
437 directories searched for compiled interface files (.cmi), compiled
438 object code files (.cmx), and libraries (.cmxa). See also option
439 .BR \-I .
440 .TP
441 .B \-nolabels
442 Ignore non-optional labels in types. Labels cannot be used in
443 applications, and parameter order becomes strict.
444 .TP
445 .BI \-o \ exec\-file
446 Specify the name of the output file produced by the linker. The
447 default output name is a.out, in keeping with the Unix tradition. If the
448 .B \-a
449 option is given, specify the name of the library produced. If the
450 .B \-pack
451 option is given, specify the name of the packed object file produced.
452 If the
453 .B \-output\-obj
454 option is given, specify the name of the output file produced. If the
455 .B \-shared
456 option is given, specify the name of plugin file produced.
457 This can also be used when compiling an interface or implementation
458 file, without linking, in which case it sets the name of the cmi or
459 cmo file, and also sets the module name to the file name up to the
460 first dot.
461 .TP
462 .B \-opaque
463 When compiling a .mli interface file, this has the same effect as the
464 .B \-opaque
465 option of the bytecode compiler. When compiling a .ml implementation
466 file, this produces a .cmx file without cross-module optimization
467 information, which reduces recompilation on module change.
468 .TP
469 .BI \-open \ module
470 Opens the given module before processing the interface or
471 implementation files. If several
472 .B \-open
473 options are given, they are processed in order, just as if
474 the statements open! module1;; ... open! moduleN;; were added
475 at the top of each file.
476 .TP
477 .B \-output\-obj
478 Cause the linker to produce a C object file instead of an executable
479 file. This is useful to wrap OCaml code as a C library,
480 callable from any C program. The name of the output object file
481 must be set with the
482 .B \-o
483 option.
484 This option can also be used to produce a compiled shared/dynamic
485 library (.so extension).
486 .TP
487 .B \-pack
488 Build an object file (.cmx and .o files) and its associated compiled
489 interface (.cmi) that combines the .cmx object
490 files given on the command line, making them appear as sub-modules of
491 the output .cmx file. The name of the output .cmx file must be
492 given with the
493 .B \-o
494 option. For instance,
495 .B ocamlopt\ -pack\ -o\ P.cmx\ A.cmx\ B.cmx\ C.cmx
496 generates compiled files P.cmx, P.o and P.cmi describing a
497 compilation unit having three sub-modules A, B and C,
498 corresponding to the contents of the object files A.cmx, B.cmx and
499 C.cmx. These contents can be referenced as P.A, P.B and P.C
500 in the remainder of the program.
502 The .cmx object files being combined must have been compiled with
503 the appropriate
504 .B \-for\-pack
505 option. In the example above,
506 A.cmx, B.cmx and C.cmx must have been compiled with
507 .BR ocamlopt\ \-for\-pack\ P .
509 Multiple levels of packing can be achieved by combining
510 .B \-pack
511 with
512 .BR \-for\-pack .
513 See
514 .IR "The OCaml user's manual" ,
515 chapter "Native-code compilation" for more details.
516 .TP
517 .BI \-pp \ command
518 Cause the compiler to call the given
519 .I command
520 as a preprocessor for each source file. The output of
521 .I command
522 is redirected to
523 an intermediate file, which is compiled. If there are no compilation
524 errors, the intermediate file is deleted afterwards.
525 .TP
526 .BI \-ppx \ command
527 After parsing, pipe the abstract syntax tree through the preprocessor
528 .IR command .
529 The module
530 .BR Ast_mapper (3)
531 implements the external interface of a preprocessor.
532 .TP
533 .B \-principal
534 Check information path during type-checking, to make sure that all
535 types are derived in a principal way. All programs accepted in
536 .B \-principal
537 mode are also accepted in default mode with equivalent
538 types, but different binary signatures.
539 .TP
540 .B \-rectypes
541 Allow arbitrary recursive types during type-checking. By default,
542 only recursive types where the recursion goes through an object type
543 are supported. Note that once you have created an interface using this
544 flag, you must use it again for all dependencies.
545 .TP
546 .BI \-runtime\-variant \ suffix
547 Add
548 .I suffix
549 to the name of the runtime library that will be used by the program.
550 If OCaml was configured with option
551 .BR \-with\-debug\-runtime ,
552 then the
553 .B d
554 suffix is supported and gives a debug version of the runtime.
555 .TP
556 .B \-S
557 Keep the assembly code produced during the compilation. The assembly
558 code for the source file
559 .IR x .ml
560 is saved in the file
561 .IR x .s.
562 .TP
563 .BI \-stop\-after \ pass
564 Stop compilation after the given compilation pass. The currently
565 supported passes are:
566 .BR parsing ,
567 .BR typing .
568 .TP
569 .B \-safe\-string
570 Enforce the separation between types
571 .BR string \ and\ bytes ,
572 thereby making strings read-only. This is the default.
573 .TP
574 .B \-shared
575 Build a plugin (usually .cmxs) that can be dynamically loaded with
576 the
577 .B Dynlink
578 module. The name of the plugin must be
579 set with the
580 .B \-o
581 option. A plugin can include a number of OCaml
582 modules and libraries, and extra native objects (.o, .a files).
583 Building native plugins is only supported for some
584 operating system. Under some systems (currently,
585 only Linux AMD 64), all the OCaml code linked in a plugin must have
586 been compiled without the
587 .B \-nodynlink
588 flag. Some constraints might also
589 apply to the way the extra native objects have been compiled (under
590 Linux AMD 64, they must contain only position-independent code).
591 .TP
592 .B \-short\-paths
593 When a type is visible under several module-paths, use the shortest
594 one when printing the type's name in inferred interfaces and error and
595 warning messages.
596 .TP
597 .B \-strict\-sequence
598 The left-hand part of a sequence must have type unit.
599 .TP
600 .B \-unboxed\-types
601 When a type is unboxable (i.e. a record with a single argument or a
602 concrete datatype with a single constructor of one argument) it will
603 be unboxed unless annotated with
604 .BR [@@ocaml.boxed] .
605 .TP
606 .B \-no-unboxed\-types
607 When a type is unboxable it will be boxed unless annotated with
608 .BR [@@ocaml.unboxed] .
609 This is the default.
610 .TP
611 .B \-unsafe
612 Turn bound checking off for array and string accesses (the
613 .BR v.(i) and s.[i]
614 constructs). Programs compiled with
615 .B \-unsafe
616 are therefore
617 faster, but unsafe: anything can happen if the program accesses an
618 array or string outside of its bounds. Additionally, turn off the
619 check for zero divisor in integer division and modulus operations.
620 With
621 .BR \-unsafe ,
622 an integer division (or modulus) by zero can halt the
623 program or continue with an unspecified result instead of raising a
624 .B Division_by_zero
625 exception.
626 .TP
627 .B \-unsafe\-string
628 Identify the types
629 .BR string \ and\ bytes ,
630 thereby making strings writable.
631 This is intended for compatibility with old source code and should not
632 be used with new software.
633 .TP
634 .B \-v
635 Print the version number of the compiler and the location of the
636 standard library directory, then exit.
637 .TP
638 .B \-verbose
639 Print all external commands before they are executed, in particular
640 invocations of the assembler, C compiler, and linker.
641 .TP
642 .BR \-version \ or\ \-vnum
643 Print the version number of the compiler in short form (e.g. "3.11.0"),
644 then exit.
645 .TP
646 .BI \-w \ warning\-list
647 Enable, disable, or mark as fatal the warnings specified by the argument
648 .IR warning\-list .
649 See
650 .BR ocamlc (1)
651 for the syntax of
652 .IR warning-list .
653 .TP
654 .BI \-warn\-error \ warning\-list
655 Mark as fatal the warnings specified in the argument
656 .IR warning\-list .
657 The compiler will stop with an error when one of these
658 warnings is emitted. The
659 .I warning\-list
660 has the same meaning as for
661 the
662 .B \-w
663 option: a
664 .B +
665 sign (or an uppercase letter) marks the corresponding warnings as fatal, a
666 .B \-
667 sign (or a lowercase letter) turns them back into non-fatal warnings, and a
668 .B @
669 sign both enables and marks as fatal the corresponding warnings.
671 Note: it is not recommended to use the
672 .B \-warn\-error
673 option in production code, because it will almost certainly prevent
674 compiling your program with later versions of OCaml when they add new
675 warnings or modify existing warnings.
677 The default setting is
678 .B \-warn\-error \-a+31
679 (only warning 31 is fatal).
680 .TP
681 .B \-warn\-help
682 Show the description of all available warning numbers.
683 .TP
684 .B \-where
685 Print the location of the standard library, then exit.
686 .TP
687 .B \-with-runtime
688 Include the runtime system in the generated program. This is the default.
689 .TP
690 .B \-without-runtime
691 The compiler does not include the runtime system (nor a reference to it) in the
692 generated program; it must be supplied separately.
693 .TP
694 .BI \- \ file
695 Process
696 .I file
697 as a file name, even if it starts with a dash (-) character.
698 .TP
699 .BR \-help \ or \ \-\-help
700 Display a short usage summary and exit.
704 The IA32 code generator (Intel Pentium, AMD Athlon) supports the
705 following additional option:
706 .TP
707 .B \-ffast\-math
708 Use the IA32 instructions to compute
709 trigonometric and exponential functions, instead of calling the
710 corresponding library routines. The functions affected are:
711 .BR atan ,
712 .BR atan2 ,
713 .BR cos ,
714 .BR log ,
715 .BR log10 ,
716 .BR sin ,
717 .B sqrt
718 and
719 .BR tan .
720 The resulting code runs faster, but the range of supported arguments
721 and the precision of the result can be reduced. In particular,
722 trigonometric operations
723 .BR cos ,
724 .BR sin ,
725 .B tan
726 have their range reduced to [\-2^64, 2^64].
730 The AMD64 code generator (64-bit versions of Intel Pentium and AMD
731 Athlon) supports the following additional options:
732 .TP
733 .B \-fPIC
734 Generate position-independent machine code. This is the default.
735 .TP
736 .B \-fno\-PIC
737 Generate position-dependent machine code.
740 The ARM code generator supports the following additional options:
741 .TP
742 .B \-farch=armv4|armv5|armv5te|armv6|armv6t2|armv7
743 Select the ARM target architecture
744 .TP
745 .B \-ffpu=soft|vfpv2|vfpv3\-d16|vfpv3
746 Select the floating-point hardware
747 .TP
748 .B \-fPIC
749 Generate position-independent machine code.
750 .TP
751 .B \-fno\-PIC
752 Generate position-dependent machine code. This is the default.
753 .TP
754 .B \-fthumb
755 Enable Thumb/Thumb-2 code generation
756 .TP
757 .B \-fno\-thumb
758 Disable Thumb/Thumb-2 code generation
759 .P
760 The default values for target architecture, floating-point hardware
761 and thumb usage were selected at configure-time when building
762 .B ocamlopt
763 itself. This configuration can be inspected using
764 .BR ocamlopt\ \-config .
765 Target architecture depends on the "model" setting, while
766 floating-point hardware and thumb support are determined from the ABI
767 setting in "system" (
768 .BR linux_eabi or linux_eabihf ).
771 .BR ocamlc (1).
772 .br
773 .IR "The OCaml user's manual" ,
774 chapter "Native-code compilation".