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

OPTIONS FOR THE IA32 ARCHITECTURE

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

OPTIONS FOR THE AMD64 ARCHITECTURE

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

OPTIONS FOR THE POWER ARCHITECTURE

540       The PowerPC code generator supports the following additional options:
541
542       -flarge-toc
543              Enables  the PowerPC large model allowing the TOC (table of con‐
544              tents) to be arbitrarily large.  This is the default since 4.11.
545
546       -fsmall-toc
547              Enables the PowerPC small model allowing the TOC to be up to  64
548              kbytes per compilation unit.  Prior to 4.11 this was the default
549              behaviour.  \nd{options}
550
551

OPTIONS FOR THE ARM ARCHITECTURE

553       The ARM code generator supports the following additional options:
554
555       -farch=armv4|armv5|armv5te|armv6|armv6t2|armv7
556              Select the ARM target architecture
557
558       -ffpu=soft|vfpv2|vfpv3-d16|vfpv3
559              Select the floating-point hardware
560
561       -fPIC  Generate position-independent machine code.
562
563       -fno-PIC
564              Generate position-dependent machine code.  This is the default.
565
566       -fthumb
567              Enable Thumb/Thumb-2 code generation
568
569       -fno-thumb
570              Disable Thumb/Thumb-2 code generation
571
572       The default values for target architecture, floating-point hardware and
573       thumb  usage were selected at configure-time when building ocamlopt it‐
574       self. This configuration can be inspected using ocamlopt -config.  Tar‐
575       get  architecture  depends on the "model" setting, while floating-point
576       hardware and thumb support are determined from the ABI setting in "sys‐
577       tem" ( linux_eabiorlinux_eabihf).
578
579

SEE ALSO

581       ocamlc(1).
582       The OCaml user's manual, chapter "Native-code compilation".
583
584
585
586                                                                   OCAMLOPT(1)
Impressum