Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 10, 2021
 
 

ocamlc.opt (1)

Name

ocamlc.opt - The Objective Caml bytecode compiler

Synopsis

ocamlc [ options ] filename ...

ocamlc.opt [ options ] filename ...

Description



OCAMLC(1)                   General Commands Manual                  OCAMLC(1)



NAME
       ocamlc - The Objective Caml bytecode compiler


SYNOPSIS
       ocamlc [ options ] filename ...

       ocamlc.opt [ options ] filename ...


DESCRIPTION
       The  Objective  Caml  bytecode  compiler ocamlc(1) compiles Caml source
       files to bytecode object files and links these object files to  produce
       standalone  bytecode executable files.  These executable files are then
       run by the bytecode interpreter ocamlrun(1).

       The ocamlc(1) command has a command-line interface similar to  the  one
       of  most  C  compilers.  It accepts several types of arguments and pro-
       cesses them sequentially:

       Arguments ending in .mli are taken to be source files  for  compilation
       unit  interfaces.  Interfaces specify the names exported by compilation
       units: they declare value names with their types,  define  public  data
       types, declare abstract data types, and so on. From the file x.mli, the
       ocamlc(1) compiler produces a compiled interface in the file x.cmi.

       Arguments ending in .ml are taken to be source  files  for  compilation
       unit implementations. Implementations provide definitions for the names
       exported by the unit, and also contain expressions to be evaluated  for
       their  side-effects.   From  the file x.ml, the ocamlc(1) compiler pro-
       duces compiled object bytecode in the file x.cmo.

       If the interface file x.mli exists, the implementation x.ml is  checked
       against the corresponding compiled interface x.cmi, which is assumed to
       exist. If no interface x.mli is provided, the compilation of x.ml  pro-
       duces  a  compiled  interface  file  x.cmi  in addition to the compiled
       object code file x.cmo.  The file  x.cmi  produced  corresponds  to  an
       interface that exports everything that is defined in the implementation
       x.ml.

       Arguments ending in .cmo are taken  to  be  compiled  object  bytecode.
       These  files  are linked together, along with the object files obtained
       by compiling .ml arguments  (if  any),  and  the  Caml  Light  standard
       library, to produce a standalone executable program. The order in which
       .cmo and.ml arguments are presented on the command  line  is  relevant:
       compilation  units are initialized in that order at run-time, and it is
       a link-time error to use a component of a unit before  having  initial-
       ized it. Hence, a given x.cmo file must come before all .cmo files that
       refer to the unit x.

       Arguments ending in .cma are taken to be libraries of object  bytecode.
       A  library  of  object  bytecode packs in a single file a set of object
       bytecode files (.cmo files). Libraries are built  with  ocamlc -a  (see
       the  description of the -a option below). The object files contained in
       the library are linked as regular .cmo files (see above), in the  order
       specified  when the .cma file was built. The only difference is that if
       an object file contained in a library is not referenced anywhere in the
       program, then it is not linked in.

       Arguments  ending in .c are passed to the C compiler, which generates a
       .o object file. This object file is linked  with  the  program  if  the
       -custom flag is set (see the description of -custom below).

       Arguments  ending  in  .o  or  .a  are assumed to be C object files and
       libraries. They are passed to the C linker when linking in -custom mode
       (see the description of -custom below).

       Arguments  ending  in  .so are assumed to be C shared libraries (DLLs).
       During linking, they are searched for external C  functions  referenced
       from  the Caml code, and their names are written in the generated byte-
       code executable.  The  run-time  system  ocamlrun(1)  then  loads  them
       dynamically at program start-up time.

       The  output of the linking phase is a file containing compiled bytecode
       that can be executed by the Objective Caml  bytecode  interpreter:  the
       command  ocamlrun(1).   If caml.out is the name of the file produced by
       the linking phase, the command  ocamlrun  caml.out  arg1  arg2 ... argn
       executes  the  compiled code contained in caml.out, passing it as argu-
       ments the character strings arg1 to argn.  (See  ocamlrun(1)  for  more
       details.)

       On  most  systems,  the  file  produced by the linking phase can be run
       directly, as in: ./caml.out arg1  arg2 ... argn.  The produced file has
       the  executable  bit  set, and it manages to launch the bytecode inter-
       preter by itself.

       ocamlc.opt is the same  compiler  as  ocamlc,  but  compiled  with  the
       native-code  compiler  ocamlopt(1).   Thus,  it  behaves  exactly  like
       ocamlc, but compiles faster.  ocamlc.opt may not be  available  in  all
       installations of Objective Caml.


OPTIONS
       The following command-line options are recognized by ocamlc(1).

       -a     Build  a  library (.cma file) with the object files (.cmo files)
              given on the command line, instead of linking them into an  exe-
              cutable  file.  The  name of the library must be set with the -o
              option.

              If -custom, -cclib or -ccopt options are passed on  the  command
              line,  these  options  are stored in the resulting .cma library.
              Then, linking with this  library  automatically  adds  back  the
              -custom, -cclib and -ccopt  options as if they had been provided
              on the command line, unless the -noautolink option is given.

       -annot Dump detailed information about the  compilation  (types,  bind-
              ings,  tail-calls, etc).  The information for file src.ml is put
              into file src.annot.  In case of a  type  error,  dump  all  the
              information  inferred  by the type-checker before the error. The
              src.annot file can be used with  the  emacs  commands  given  in
              emacs/caml-types.el  to  display  types  and  other  annotations
              interactively.

       -c     Compile only. Suppress the linking  phase  of  the  compilation.
              Source  code  files  are turned into compiled files, but no exe-
              cutable file is produced. This option is useful to compile  mod-
              ules separately.

       -cc ccomp
              Use  ccomp as the C linker when linking in "custom runtime" mode
              (see the -custom option) and as the C compiler for compiling  .c
              source files.

       -cclib -llibname
              Pass  the -llibname option to the C linker when linking in "cus-
              tom runtime" mode (see the  -custom  option).  This  causes  the
              given C library to be linked with the program.

       -ccopt Pass the given option to the C compiler and linker, when linking
              in "custom runtime" mode (see the -custom option). For instance,
              -ccopt -Ldir  causes  the  C linker to search for C libraries in
              directory dir.

       -config
              Print the version number of ocamlc(1) and a detailed summary  of
              its configuration, then exit.

       -custom
              Link  in "custom runtime" mode. In the default linking mode, the
              linker produces bytecode that is intended to  be  executed  with
              the  shared  runtime system, ocamlrun(1).  In the custom runtime
              mode, the linker produces an output file that contains both  the
              runtime  system  and the bytecode for the program. The resulting
              file is larger, but it can be executed  directly,  even  if  the
              ocamlrun(1) command is not installed. Moreover, the "custom run-
              time" mode enables linking Caml code with user-defined  C  func-
              tions.

              Never  use  the  strip(1)  command  on  executables  produced by
              ocamlc -custom, this would remove the bytecode part of the  exe-
              cutable.

       -dllib -llibname
              Arrange  for  the  C  shared  library dlllibname.so to be loaded
              dynamically by the run-time system ocamlrun(1) at program start-
              up time.

       -dllpath dir
              Adds  the directory dir to the run-time search path for shared C
              libraries.  At link-time, shared libraries are searched  in  the
              standard  search  path (the one corresponding to the -I option).
              The -dllpath option simply stores dir in the produced executable
              file, where ocamlrun(1) can find it and use it.

       -g     Add  debugging  information  while  compiling  and linking. This
              option is required in order to be able to debug the program with
              ocamldebug(1)  and  to produce stack backtraces when the program
              terminates on an uncaught exception.

       -i     Cause the compiler  to  print  all  defined  names  (with  their
              inferred types or their definitions) when compiling an implemen-
              tation (.ml file). No compiled files (.cmo and .cmi  files)  are
              produced.  This can be useful to check the types inferred by the
              compiler. Also, since the output follows the  syntax  of  inter-
              faces,  it can help in writing an explicit interface (.mli file)
              for a file: just redirect the standard output of the compiler to
              a  .mli  file,  and edit that file to remove all declarations of
              unexported names.

       -I directory
              Add the given directory to the list of directories searched  for
              compiled  interface  files  (.cmi),  compiled  object code files
              (.cmo),  libraries  (.cma),  and  C  libraries  specified   with
              -cclib -l  xxx.   By  default, the current directory is searched
              first, then the standard library  directory.  Directories  added
              with  -I  are searched after the current directory, in the order
              in which they were given on the command  line,  but  before  the
              standard library directory.

              If  the  given  directory starts with +, it is taken relative to
              the standard library directory. For  instance,  -I +labltk  adds
              the  subdirectory  labltk  of the standard library to the search
              path.

       -impl filename
              Compile the file filename as an implementation file, even if its
              extension is not .ml.

       -intf filename
              Compile  the  file  filename  as  an interface file, even if its
              extension is not .mli.

       -intf-suffix string
              Recognize file names  ending  with  string  as  interface  files
              (instead of the default .mli).

       -labels
              Labels  are not ignored in types, labels may be used in applica-
              tions, and labelled parameters can be given in any order.   This
              is the default.

       -linkall
              Force  all  modules  contained  in libraries to be linked in. If
              this flag is not given, unreferenced modules are not linked  in.
              When building a library (option -a), setting the -linkall option
              forces all subsequent links of programs involving  that  library
              to link all the modules contained in the library.

       -make-runtime
              Build  a  custom runtime system (in the file specified by option
              -o) incorporating the C object files and libraries given on  the
              command  line.   This custom runtime system can be used later to
              execute  bytecode   executables   produced   with   the   option
              ocamlc -use-runtime runtime-name.

       -noassert
              Do  not  compile  assertion  checks.  Note that the special form
              assert false is always compiled because it is  typed  specially.
              This flag has no effect when linking already-compiled files.

       -noautolink
              When  linking  .cma libraries, ignore -custom, -cclib and -ccopt
              options potentially contained in the libraries (if these options
              were  given when building the libraries).  This can be useful if
              a library contains incorrect specifications of C libraries or  C
              options;  in this case, during linking, set -noautolink and pass
              the correct C libraries and options on the command line.

       -nolabels
              Ignore non-optional labels in types. Labels cannot  be  used  in
              applications, and parameter order becomes strict.

       -o exec-file
              Specify  the name of the output file produced by the linker. The
              default output name is a.out, in keeping with  the  Unix  tradi-
              tion. If the -a option is given, specify the name of the library
              produced.  If the -pack option is given, specify the name of the
              packed  object  file  produced.   If  the  -output-obj option is
              given, specify the name of the output file produced.

       -output-obj
              Cause the linker to produce a C object file instead of  a  byte-
              code  executable  file.  This is useful to wrap Caml code as a C
              library, callable from any C program. The  name  of  the  output
              object  file is camlprog.o by default; it can be set with the -o
              option. This option can also be used to produce a C source  file
              (.c  extension) or a compiled shared/dynamic library (.so exten-
              sion).

       -pack  Build a bytecode object file (.cmo file) and its associated com-
              piled  interface  (.cmi) that combines the object files given on
              the command line, making them appear as sub-modules of the  out-
              put  .cmo  file.  The name of the output .cmo file must be given
              with       the       -o       option.        For       instance,
              ocamlc -pack -o p.cmo a.cmo b.cmo c.cmo generates compiled files
              p.cmo and p.cmi describing a compilation unit having three  sub-
              modules  A, B and C, corresponding to the contents of the object
              files a.cmo, b.cmo and c.cmo.  These contents can be  referenced
              as P.A, P.B and P.C in the remainder of the program.

       -pp command
              Cause  the  compiler to call the given command as a preprocessor
              for each source file. The output of command is redirected to  an
              intermediate  file,  which is compiled. If there are no compila-
              tion errors, the intermediate file is  deleted  afterwards.  The
              name  of this file is built from the basename of the source file
              with the extension .ppi for an interface (.mli)  file  and  .ppo
              for an implementation (.ml) file.

       -principal
              Check  information  path during type-checking, to make sure that
              all types are derived in a principal way.  When  using  labelled
              arguments  and/or  polymorphic methods, this flag is required to
              ensure future versions of the compiler will  be  able  to  infer
              types  correctly,  even if internal algorithms change.  All pro-
              grams accepted in -principal  mode  are  also  accepted  in  the
              default  mode with equivalent types, but different binary signa-
              tures, and this may slow down type checking; yet it  is  a  good
              idea to use it once before publishing source code.

       -rectypes
              Allow   arbitrary  recursive  types  during  type-checking.   By
              default, only recursive types where the recursion  goes  through
              an object type are supported. Note that once you have created an
              interface using this flag, you must use it again for all  depen-
              dencies.

       -thread
              Compile  or link multithreaded programs, in combination with the
              system    "threads"    library    described    in     The Objec-
              tive Caml user's manual.

       -unsafe
              Turn  bound  checking  off  for  array  and string accesses (the
              v.(i)ands.[i] constructs). Programs compiled  with  -unsafe  are
              therefore  slightly  faster,  but unsafe: anything can happen if
              the program accesses an array or string outside of its bounds.

       -use-runtime runtime-name
              Generate a bytecode executable file that can be executed on  the
              custom   runtime   system   runtime-name,   built  earlier  with
              ocamlc -make-runtime runtime-name.

       -v     Print the version number of the compiler and the location of the
              standard library directory, then exit.

       -verbose
              Print all external commands before they are executed, in partic-
              ular invocations of the C compiler and linker in  -custom  mode.
              Useful to debug C library problems.

       -version
              Print  the  version  number  of the compiler in short form (e.g.
              "3.11.0"), then exit.

       -vmthread
              Compile or link multithreaded programs, in combination with  the
              VM-level     threads    library    described    in    The Objec-
              tive Caml user's manual.

       -w warning-list
              Enable or disable  warnings  according  to  the  argument  warn-
              ing-list.   The  argument  is  a set of letters.  If a letter is
              uppercase, it enables the corresponding warnings; lowercase dis-
              ables the warnings.  The correspondence is the following:

              A   all warnings

              C   start of comments that look like mistakes

              D   use of deprecated features

              E    fragile  pattern matchings (matchings that will remain com-
              plete even if additional constructors are added to  one  of  the
              variant types matched)

              F    partially  applied  functions (expressions whose result has
              function type and is ignored)

              L   omission of labels in applications

              M   overriding of methods

              P   missing cases in pattern matchings (i.e. partial matchings)

              S   expressions in the left-hand side of a sequence  that  don't
              have type unit (and that are not functions, see F above)

              U   redundant cases in pattern matching (unused cases)

              V   overriding of instance variables

              Y    unused  variables  that are bound with let or as, and don't
              start with an underscore (_) character

              Z   all other cases of unused variables that don't start with an
              underscore (_) character

              X   warnings that don't fit in the above categories (except A)

              The  default  setting  is  -w Aelz, enabling all warnings except
              fragile pattern matchings, omitted labels, and innocuous  unused
              variables.  Note that warnings F and S are not always triggered,
              depending on the internals of the type checker.

       -warn-error warning-list
              Turn the warnings indicated in the  argument  warning-list  into
              errors.   The compiler will stop with an error when one of these
              warnings is emitted.  The warning-list has the same  meaning  as
              for  the  "-w"  option:  an uppercase character turns the corre-
              sponding warning into an error, a lowercase character leaves  it
              as a warning.  The default setting is -warn-error a (none of the
              warnings is treated as an error).

       -where Print the location of the standard library, then exit.

       - file Process file as a file name, even if it starts with a  dash  (-)
              character.

       -help or --help
              Display a short usage summary and exit.



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/ocaml    |
       +---------------+------------------+
       |Stability      | Volatile         |
       +---------------+------------------+
SEE ALSO
       ocamlopt(1), ocamlrun(1), ocaml(1).
       The Objective Caml user's manual, chapter "Batch compilation".



NOTES
       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source      was      downloaded     from      http://caml.inria.fr/dis-
       trib/ocaml-3.11/ocaml-3.11.2.tar.bz2

       Further information about this software can be found on the open source
       community website at http://www.ocaml.org.



                                                                     OCAMLC(1)