1OCAMLOPT(1)                 General Commands Manual                OCAMLOPT(1)
2
3
4

NAME

6       ocamlopt - The OCaml native-code compiler
7
8

SYNOPSIS

10       ocamlopt [ options ] filename ...
11
12       ocamlopt.opt (same options)
13
14

DESCRIPTION

16       The  OCaml  high-performance  native-code compiler ocamlopt(1) compiles
17       OCaml source files to native code object files and  link  these  object
18       files to produce standalone executables.
19
20       The ocamlopt(1) command has a command-line interface very close to that
21       of ocamlc(1).  It accepts the same types  of  arguments  and  processes
22       them sequentially, after all options have been processed:
23
24       Arguments  ending  in .mli are taken to be source files for compilation
25       unit interfaces. Interfaces specify the names exported  by  compilation
26       units:  they  declare  value names with their types, define public data
27       types, declare abstract data types, and so on. From the file x.mli, the
28       ocamlopt(1)  compiler  produces a compiled interface in the file x.cmi.
29       The interface produced is identical to that produced  by  the  bytecode
30       compiler ocamlc(1).
31
32       Arguments  ending  in  .ml are taken to be source files for compilation
33       unit implementations. Implementations provide definitions for the names
34       exported  by the unit, and also contain expressions to be evaluated for
35       their side-effects.  From the file x.ml, the ocamlopt(1) compiler  pro‐
36       duces  two  files:  x.o, containing native object code, and x.cmx, con‐
37       taining extra information for linking and optimization of  the  clients
38       of  the  unit. The compiled implementation should always be referred to
39       under the name x.cmx (when given a .o file, ocamlopt(1) assumes that it
40       contains code compiled from C, not from OCaml).
41
42       The  implementation  is checked against the interface file x.mli (if it
43       exists) as described in the manual for ocamlc(1).
44
45       Arguments ending in .cmx are taken to be compiled object  code.   These
46       files are linked together, along with the object files obtained by com‐
47       piling .ml arguments (if any), and the OCaml standard library, to  pro‐
48       duce  a native-code executable program. The order in which .cmx and .ml
49       arguments are presented on the command line  is  relevant:  compilation
50       units  are initialized in that order at run-time, and it is a link-time
51       error to use a component of a unit before having initialized it. Hence,
52       a  given  x.cmx  file must come before all .cmx files that refer to the
53       unit x.
54
55       Arguments ending in .cmxa are taken to be  libraries  of  object  code.
56       Such  a  library  packs in two files lib.cmxa and lib.a a set of object
57       files (.cmx/.o files). Libraries are build with ocamlopt  -a  (see  the
58       description  of the -a option below). The object files contained in the
59       library are linked as regular .cmx files  (see  above),  in  the  order
60       specified when the library was built. The only difference is that if an
61       object file contained in a library is not referenced  anywhere  in  the
62       program, then it is not linked in.
63
64       Arguments  ending in .c are passed to the C compiler, which generates a
65       .o object file. This object file is linked with the program.
66
67       Arguments ending in .o or .a are assumed  to  be  C  object  files  and
68       libraries. They are linked with the program.
69
70       The  output  of the linking phase is a regular Unix executable file. It
71       does not need ocamlrun(1) to run.
72
73       ocamlopt.opt is the same compiler as ocamlopt, but compiled with itself
74       instead  of  with  the  bytecode  compiler ocamlc(1).  Thus, it behaves
75       exactly like ocamlopt, but compiles faster.  ocamlopt.opt is not avail‐
76       able in all installations of OCaml.
77
78

OPTIONS

80       The following command-line options are recognized by ocamlopt(1).
81
82       -a     Build  a  library (.cmxa/.a file) with the object files (.cmx/.o
83              files) given on the command line, instead of linking  them  into
84              an executable file. The name of the library must be set with the
85              -o option.
86
87              If -cclib or -ccopt options are  passed  on  the  command  line,
88              these  options are stored in the resulting .cmxa library.  Then,
89              linking  with  this  library   automatically   adds   back   the
90              -cclib and -ccopt  options  as  if they had been provided on the
91              command line, unless the -noautolink option is given.  Addition‐
92              ally,  a  substring $CAMLORIGIN inside a  -ccopt options will be
93              replaced by the full path to the  .cma  library,  excluding  the
94              filename.
95
96       -absname
97              Show absolute filenames in error messages.
98
99       -annot Dump  detailed  information  about the compilation (types, bind‐
100              ings, tail-calls, etc).  The information for file src.ml is  put
101              into  file  src.annot.   In  case  of a type error, dump all the
102              information inferred by the type-checker before the  error.  The
103              src.annot  file  can  be  used  with the emacs commands given in
104              emacs/caml-types.el  to  display  types  and  other  annotations
105              interactively.
106
107       -bin-annot
108              Dump  detailed  information  about the compilation (types, bind‐
109              ings, tail-calls, etc) in binary  format.  The  information  for
110              file  src.ml is put into file src.cmt.  In case of a type error,
111              dump all the information inferred by the type-checker before the
112              error.  The annotation files produced by -bin-annot contain more
113              information and are much more compact than the files produced by
114              -annot.
115
116       -c     Compile  only.  Suppress  the  linking phase of the compilation.
117              Source code files are turned into compiled files,  but  no  exe‐
118              cutable  file is produced. This option is useful to compile mod‐
119              ules separately.
120
121       -cc ccomp
122              Use ccomp as the C linker called to build the  final  executable
123              and as the C compiler for compiling .c source files.
124
125       -cclib -llibname
126              Pass the -llibname option to the linker. This causes the given C
127              library to be linked with the program.
128
129       -ccopt option
130              Pass the  given  option  to  the  C  compiler  and  linker.  For
131              instance,  -ccopt -Ldir  causes  the  C  linker  to search for C
132              libraries in directory dir.
133
134       -color mode
135              Enable or disable colors in compiler messages (especially  warn‐
136              ings and errors).  The following modes are supported:
137
138              auto use heuristics to enable colors only if the output supports
139              them (an ANSI-compatible tty terminal);
140
141              always enable colors unconditionally;
142
143              never disable color output.
144
145              The default setting is auto, and the  current  heuristic  checks
146              that  the "TERM" environment variable exists and is not empty or
147              "dumb", and that isatty(stderr) holds.
148
149              The environment variable "OCAML_COLOR" is considered  if  -color
150              is not provided. Its values are auto/always/never as above.
151
152
153       -error-style mode
154              Control  the  way  error messages and warnings are printed.  The
155              following modes are supported:
156
157              short only print the error and its location;
158
159              contextual like "short", but also display the source code  snip‐
160              pet corresponding to the location of the error.
161
162              The default setting is contextual.
163
164              The  environment  variable  "OCAML_ERROR_STYLE" is considered if
165              -error-style is not provided. Its values are short/contextual as
166              above.
167
168
169       -compact
170              Optimize  the produced code for space rather than for time. This
171              results in smaller but slightly slower programs. The default  is
172              to optimize for speed.
173
174       -config
175              Print  the  version number of ocamlopt(1) and a detailed summary
176              of its configuration, then exit.
177
178       -config-var
179              Print the value of a specific configuration  variable  from  the
180              -config  output,  then exit. If the variable does not exist, the
181              exit code is non-zero.
182
183       -depend ocamldep-args
184              Compute dependencies, as ocamldep would do.
185
186       -for-pack module-path
187              Generate an object file (.cmx and .o files) that  can  later  be
188              included  as a sub-module (with the given access path) of a com‐
189              pilation unit  constructed  with  -pack.   For  instance,  ocam‐
190              lopt -for-pack P -c A.ml  will generate a.cmx and a.o files that
191              can later be used with ocamlopt -pack -o P.cmx a.cmx.
192
193       -g     Add debugging information  while  compiling  and  linking.  This
194              option is required in order to produce stack backtraces when the
195              program terminates on an uncaught exception (see ocamlrun(1)).
196
197       -i     Cause the compiler  to  print  all  defined  names  (with  their
198              inferred types or their definitions) when compiling an implemen‐
199              tation (.ml file). No compiled files (.cmo and .cmi  files)  are
200              produced.  This can be useful to check the types inferred by the
201              compiler. Also, since the output follows the  syntax  of  inter‐
202              faces,  it can help in writing an explicit interface (.mli file)
203              for a file: just redirect the standard output of the compiler to
204              a  .mli  file,  and edit that file to remove all declarations of
205              unexported names.
206
207       -I directory
208              Add the given directory to the list of directories searched  for
209              compiled  interface  files  (.cmi),  compiled  object code files
210              (.cmx), and libraries (.cmxa). By default, the current directory
211              is searched first, then the standard library directory. Directo‐
212              ries added with -I are searched after the current directory,  in
213              the  order  in  which  they  were given on the command line, but
214              before the standard library directory. See  also  option  -nost‐
215              dlib.
216
217              If  the  given  directory starts with +, it is taken relative to
218              the standard library directory. For instance,  -I +compiler-libs
219              adds  the  subdirectory compiler-libs of the standard library to
220              the search path.
221
222       -impl filename
223              Compile the file filename as an implementation file, even if its
224              extension is not .ml.
225
226       -inline n
227              Set aggressiveness of inlining to n, where n is a positive inte‐
228              ger. Specifying -inline 0  prevents  all  functions  from  being
229              inlined,  except those whose body is smaller than the call site.
230              Thus, inlining causes no expansion in  code  size.  The  default
231              aggressiveness,  -inline 1,  allows slightly larger functions to
232              be inlined, resulting in a slight expansion in code size. Higher
233              values  for the -inline option cause larger and larger functions
234              to become candidate for inlining, but can result  in  a  serious
235              increase in code size.
236
237       -insn-sched
238              Enables the instruction scheduling pass in the compiler backend.
239
240       -intf filename
241              Compile  the  file  filename  as  an interface file, even if its
242              extension is not .mli.
243
244       -intf-suffix string
245              Recognize file names  ending  with  string  as  interface  files
246              (instead of the default .mli).
247
248       -keep-docs
249              Keep documentation strings in generated .cmi files.
250
251       -keep-locs
252              Keep locations in generated .cmi files.
253
254       -labels
255              Labels  are not ignored in types, labels may be used in applica‐
256              tions, and labelled parameters can be given in any order.   This
257              is the default.
258
259       -linkall
260              Force  all  modules  contained  in libraries to be linked in. If
261              this flag is not given, unreferenced modules are not linked  in.
262              When  building  a  library  (-a flag), setting the -linkall flag
263              forces all subsequent links of programs involving  that  library
264              to  link all the modules contained in the library.  When compil‐
265              ing a module (option -c), setting the  -linkall  option  ensures
266              that this module will always be linked if it is put in a library
267              and this library is linked.
268
269       -linscan
270              Use linear scan register allocation.  Compiling with this  allo‐
271              cator  is  faster  than with the usual graph coloring allocator,
272              sometimes quite drastically so for long functions  and  modules.
273              On the other hand, the generated code can be a bit slower.
274
275       -match-context-rows
276              Set  number of rows of context used during pattern matching com‐
277              pilation. Lower values cause faster compilation, but less  opti‐
278              mized code. The default value is 32.
279
280       -no-alias-deps
281              Do not record dependencies for module aliases.
282
283       -no-app-funct
284              Deactivates  the  applicative  behaviour  of functors. With this
285              option, each functor application  generates  new  types  in  its
286              result  and applying the same functor twice to the same argument
287              yields two incompatible structures.
288
289       -noassert
290              Do not compile assertion checks.  Note  that  the  special  form
291              assert false  is  always compiled because it is typed specially.
292              This flag has no effect when linking already-compiled files.
293
294       -noautolink
295              When linking .cmxa libraries, ignore  -cclib and -ccopt  options
296              potentially  contained  in  the libraries (if these options were
297              given when building the libraries).  This can  be  useful  if  a
298              library  contains  incorrect  specifications of C libraries or C
299              options; in this case, during linking, set -noautolink and  pass
300              the correct C libraries and options on the command line.
301
302       -nodynlink
303              Allow the compiler to use some optimizations that are valid only
304              for code that is never dynlinked.
305
306       -no-insn-sched
307              Disables the instruction scheduling pass in the  compiler  back‐
308              end.
309
310       -nostdlib
311              Do  not  automatically add the standard library directory to the
312              list  of  directories  searched  for  compiled  interface  files
313              (.cmi),   compiled  object  code  files  (.cmx),  and  libraries
314              (.cmxa). See also option -I.
315
316       -nolabels
317              Ignore non-optional labels in types. Labels cannot  be  used  in
318              applications, and parameter order becomes strict.
319
320       -o exec-file
321              Specify  the name of the output file produced by the linker. The
322              default output name is a.out, in keeping with  the  Unix  tradi‐
323              tion. If the -a option is given, specify the name of the library
324              produced. If the -pack option is given, specify the name of  the
325              packed  object  file  produced.   If  the  -output-obj option is
326              given, specify the name of the  output  file  produced.  If  the
327              -shared  option  is  given, specify the name of plugin file pro‐
328              duced.  This can also be used when  compiling  an  interface  or
329              implementation  file, without linking, in which case it sets the
330              name of the cmi or cmo file, and also sets the  module  name  to
331              the file name up to the first dot.
332
333       -opaque
334              When  compiling  a .mli interface file, this has the same effect
335              as the -opaque option of the bytecode compiler. When compiling a
336              .ml  implementation  file,  this  produces  a  .cmx file without
337              cross-module optimization information, which reduces  recompila‐
338              tion on module change.
339
340       -open module
341              Opens the given module before processing the interface or imple‐
342              mentation files. If several -open options are  given,  they  are
343              processed  in  order,  just as if the statements open! module1;;
344              ... open! moduleN;; were added at the top of each file.
345
346       -output-obj
347              Cause the linker to produce a C object file instead of  an  exe‐
348              cutable  file. This is useful to wrap OCaml code as a C library,
349              callable from any C program. The name of the output object  file
350              must be set with the -o option.  This option can also be used to
351              produce a compiled shared/dynamic library (.so extension).
352
353       -pack  Build an object file (.cmx and .o files) and its associated com‐
354              piled interface (.cmi) that combines the .cmx object files given
355              on the command line, making them appear as  sub-modules  of  the
356              output  .cmx  file.   The  name  of the output .cmx file must be
357              given   with   the   -o    option.     For    instance,    ocam‐
358              lopt -pack -o P.cmx A.cmx B.cmx C.cmx  generates  compiled files
359              P.cmx, P.o and P.cmi describing a compilation unit having  three
360              sub-modules  A,  B  and  C, corresponding to the contents of the
361              object files A.cmx, B.cmx and C.cmx.  These contents can be ref‐
362              erenced as P.A, P.B and P.C in the remainder of the program.
363
364              The  .cmx  object  files  being combined must have been compiled
365              with the appropriate -for-pack option.  In  the  example  above,
366              A.cmx,  B.cmx  and  C.cmx  must  have  been  compiled with ocam‐
367              lopt -for-pack P.
368
369              Multiple levels of packing can be achieved  by  combining  -pack
370              with  -for-pack.   See The OCaml user's manual, chapter "Native-
371              code compilation" for more details.
372
373       -pp command
374              Cause the compiler to call the given command as  a  preprocessor
375              for  each source file. The output of command is redirected to an
376              intermediate file, which is compiled. If there are  no  compila‐
377              tion errors, the intermediate file is deleted afterwards.
378
379       -ppx command
380              After  parsing,  pipe  the abstract syntax tree through the pre‐
381              processor command.   The  module  Ast_mapper(3)  implements  the
382              external interface of a preprocessor.
383
384       -principal
385              Check  information  path during type-checking, to make sure that
386              all types are derived in a principal way. All programs  accepted
387              in -principal mode are also accepted in default mode with equiv‐
388              alent types, but different binary signatures.
389
390       -rectypes
391              Allow  arbitrary  recursive  types  during  type-checking.    By
392              default,  only  recursive types where the recursion goes through
393              an object type are supported. Note that once you have created an
394              interface  using this flag, you must use it again for all depen‐
395              dencies.
396
397       -runtime-variant suffix
398              Add suffix to the name of the runtime library that will be  used
399              by   the   program.    If   OCaml  was  configured  with  option
400              -with-debug-runtime, then the d suffix is supported and gives  a
401              debug version of the runtime.
402
403       -S     Keep  the  assembly  code  produced  during the compilation. The
404              assembly code for the source file x.ml is saved in the file x.s.
405
406       -stop-after pass
407              Stop compilation after the given compilation pass. The currently
408              supported passes are: parsing, typing.
409
410       -safe-string
411              Enforce  the  separation between types string and bytes, thereby
412              making strings read-only. This is the default.
413
414       -shared
415              Build a plugin (usually .cmxs) that can  be  dynamically  loaded
416              with the Dynlink module. The name of the plugin must be set with
417              the -o option. A plugin can include a number  of  OCaml  modules
418              and  libraries, and extra native objects (.o, .a files).  Build‐
419              ing native plugins is only supported for some operating  system.
420              Under some systems (currently, only Linux AMD 64), all the OCaml
421              code linked in a plugin must  have  been  compiled  without  the
422              -nodynlink  flag.  Some  constraints might also apply to the way
423              the extra native objects have been compiled (under Linux AMD 64,
424              they must contain only position-independent code).
425
426       -short-paths
427              When  a  type  is  visible  under  several module-paths, use the
428              shortest one when printing the type's name  in  inferred  inter‐
429              faces and error and warning messages.
430
431       -strict-sequence
432              The left-hand part of a sequence must have type unit.
433
434       -unboxed-types
435              When  a  type is unboxable (i.e. a record with a single argument
436              or a concrete datatype with a single constructor  of  one  argu‐
437              ment) it will be unboxed unless annotated with [@@ocaml.boxed].
438
439       -no-unboxed-types
440              When a type is unboxable  it will be boxed unless annotated with
441              [@@ocaml.unboxed].  This is the default.
442
443       -unsafe
444              Turn bound checking off  for  array  and  string  accesses  (the
445              v.(i)ands.[i]  constructs).  Programs  compiled with -unsafe are
446              therefore faster, but unsafe: anything can happen if the program
447              accesses an array or string outside of its bounds. Additionally,
448              turn off the check for zero divisor in integer division and mod‐
449              ulus operations.  With -unsafe, an integer division (or modulus)
450              by zero can halt the program or  continue  with  an  unspecified
451              result instead of raising a Division_by_zero exception.
452
453       -unsafe-string
454              Identify  the  types  string and bytes,  thereby  making strings
455              writable.  This is intended for compatibility  with  old  source
456              code and should not be used with new software.
457
458       -v     Print the version number of the compiler and the location of the
459              standard library directory, then exit.
460
461       -verbose
462              Print all external commands before they are executed, in partic‐
463              ular invocations of the assembler, C compiler, and linker.
464
465       -version or -vnum
466              Print  the  version  number  of the compiler in short form (e.g.
467              "3.11.0"), then exit.
468
469       -w warning-list
470              Enable, disable, or mark as fatal the warnings specified by  the
471              argument warning-list.  See ocamlc(1) for the syntax of warning-
472              list.
473
474       -warn-error warning-list
475              Mark as fatal the  warnings  specified  in  the  argument  warn‐
476              ing-list.   The  compiler  will  stop  with an error when one of
477              these warnings is emitted.  The warning-list has the same  mean‐
478              ing  as  for  the  -w  option: a + sign (or an uppercase letter)
479              marks the corresponding warnings as fatal, a - sign (or a lower‐
480              case  letter)  turns  them back into non-fatal warnings, and a @
481              sign both enables and marks as fatal the corresponding warnings.
482
483              Note: it is not recommended to use  the  -warn-error  option  in
484              production  code,  because it will almost certainly prevent com‐
485              piling your program with later versions of OCaml when  they  add
486              new warnings or modify existing warnings.
487
488              The  default  setting  is  -warn-error -a+31 (only warning 31 is
489              fatal).
490
491       -warn-help
492              Show the description of all available warning numbers.
493
494       -where Print the location of the standard library, then exit.
495
496       -with-runtime
497              Include the runtime system in the generated program. This is the
498              default.
499
500       -without-runtime
501              The  compiler  does not include the runtime system (nor a refer‐
502              ence to it) in the generated program; it must be supplied  sepa‐
503              rately.
504
505       - file Process  file  as a file name, even if it starts with a dash (-)
506              character.
507
508       -help or --help
509              Display a short usage summary and exit.
510
511

OPTIONS FOR THE IA32 ARCHITECTURE

513       The IA32 code generator (Intel Pentium, AMD Athlon) supports  the  fol‐
514       lowing additional option:
515
516       -ffast-math
517              Use  the IA32 instructions to compute trigonometric and exponen‐
518              tial functions, instead of  calling  the  corresponding  library
519              routines.   The  functions  affected are: atan, atan2, cos, log,
520              log10, sin, sqrt and tan.  The resulting code runs  faster,  but
521              the range of supported arguments and the precision of the result
522              can be reduced.  In particular,  trigonometric  operations  cos,
523              sin, tan have their range reduced to [-2^64, 2^64].
524
525

OPTIONS FOR THE AMD64 ARCHITECTURE

527       The  AMD64  code  generator  (64-bit  versions of Intel Pentium and AMD
528       Athlon) supports the following additional options:
529
530       -fPIC  Generate  position-independent  machine  code.   This   is   the
531              default.
532
533       -fno-PIC
534              Generate position-dependent machine code.
535
536

OPTIONS FOR THE ARM ARCHITECTURE

538       The ARM code generator supports the following additional options:
539
540       -farch=armv4|armv5|armv5te|armv6|armv6t2|armv7
541              Select the ARM target architecture
542
543       -ffpu=soft|vfpv2|vfpv3-d16|vfpv3
544              Select the floating-point hardware
545
546       -fPIC  Generate position-independent machine code.
547
548       -fno-PIC
549              Generate position-dependent machine code.  This is the default.
550
551       -fthumb
552              Enable Thumb/Thumb-2 code generation
553
554       -fno-thumb
555              Disable Thumb/Thumb-2 code generation
556
557       The default values for target architecture, floating-point hardware and
558       thumb usage were selected  at  configure-time  when  building  ocamlopt
559       itself.  This  configuration  can  be inspected using ocamlopt -config.
560       Target architecture depends on the  "model"  setting,  while  floating-
561       point hardware and thumb support are determined from the ABI setting in
562       "system" ( linux_eabiorlinux_eabihf).
563
564

SEE ALSO

566       ocamlc(1).
567       The OCaml user's manual, chapter "Native-code compilation".
568
569
570
571                                                                   OCAMLOPT(1)
Impressum