man/ocamlc.m

   1 .TH OCAMLC 1
   2
   3 .SH NAME
   4 ocamlc \- The Objective Caml bytecode compiler
   5
   6
   7 .SH SYNOPSIS
   8 .B ocamlc
   9 [
  10 .B \-aciv
  11 ]
  12 [
  13 .BI \-cclib \ libname
  14 ]
  15 [
  16 .BI \-ccopt \ option
  17 ]
  18 [
  19 .B \-custom
  20 ]
  21 [
  22 .B \-unsafe
  23 ]
  24 [
  25 .BI \-o \ exec-file
  26 ]
  27 [
  28 .BI \-I \ lib-dir
  29 ]
  30 .I filename ...
  31
  32 .B ocamlc.opt
  33 .I (same options)
  34
  35 .SH DESCRIPTION
  36
  37 The Objective Caml bytecode compiler
  38 .BR ocamlc (1)
  39 compiles Caml source files to bytecode object files and link
  40 these object files to produce standalone bytecode executable files.
  41 These executable files are then run by the bytecode interpreter
  42 .BR ocamlrun (1).
  43
  44 The
  45 .BR ocamlc (1)
  46 command has a command-line interface similar to the one of
  47 most C compilers. It accepts several types of arguments and processes them
  48 sequentially:
  49
  50 Arguments ending in .mli are taken to be source files for
  51 compilation unit interfaces. Interfaces specify the names exported by
  52 compilation units: they declare value names with their types, define
  53 public data types, declare abstract data types, and so on. From the
  54 file
  55 .IR x \&.mli,
  56 the
  57 .BR ocamlc (1)
  58 compiler produces a compiled interface
  59 in the file
  60 .IR x \&.cmi.
  61
  62 Arguments ending in .ml are taken to be source files for compilation
  63 unit implementations. Implementations provide definitions for the
  64 names exported by the unit, and also contain expressions to be
  65 evaluated for their side-effects.  From the file
  66 .IR x \&.ml,
  67 the
  68 .BR ocamlc (1)
  69 compiler produces compiled object bytecode in the file
  70 .IR x \&.cmo.
  71
  72 If the interface file
  73 .IR x \&.mli
  74 exists, the implementation
  75 .IR x \&.ml
  76 is checked against the corresponding compiled interface
  77 .IR x \&.cmi,
  78 which is assumed to exist. If no interface
  79 .IR x \&.mli
  80 is provided, the compilation of
  81 .IR x \&.ml
  82 produces a compiled interface file
  83 .IR x \&.cmi
  84 in addition to the compiled object code file
  85 .IR x \&.cmo.
  86 The file
  87 .IR x \&.cmi
  88 produced
  89 corresponds to an interface that exports everything that is defined in
  90 the implementation
  91 .IR x \&.ml.
  92
  93 Arguments ending in .cmo are taken to be compiled object bytecode.  These
  94 files are linked together, along with the object files obtained
  95 by compiling .ml arguments (if any), and the Caml Light standard
  96 library, to produce a standalone executable program. The order in
  97 which .cmo and.ml arguments are presented on the command line is
  98 relevant: compilation units are initialized in that order at
  99 run-time, and it is a link-time error to use a component of a unit
 100 before having initialized it. Hence, a given
 101 .IR x \&.cmo
 102 file must come before all .cmo files that refer to the unit
 103 .IR x .
 104
 105 Arguments ending in .cma are taken to be libraries of object bytecode.
 106 A library of object bytecode packs in a single file a set of object
 107 bytecode files (.cmo files). Libraries are built with
 108 .B ocamlc \-a
 109 (see the description of the
 110 .B \-a
 111 option below). The object files
 112 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
 113 contained in a library is not referenced anywhere in the program, then
 114 it is not linked in.
 115
 116 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
 117 .B \-custom
 118 flag is set (see the description of
 119 .B \-custom
 120 below).
 121
 122 Arguments ending in .o or .a are assumed to be C object files and
 123 libraries. They are passed to the C linker when linking in
 124 .B \-custom
 125 mode (see the description of
 126 .B \-custom
 127 below).
 128
 129 .B ocamlc.opt
 130 is the same compiler as
 131 .BR ocamlc ,
 132 but compiled with the native-code compiler
 133 .BR ocamlopt (1).
 134 Thus, it behaves exactly like
 135 .BR ocamlc ,
 136 but compiles faster.
 137 .B ocamlc.opt
 138 is not available in all installations of Objective Caml.
 139
 140 .SH OPTIONS
 141
 142 The following command-line options are recognized by
 143 .BR ocamlc (1).
 144
 145 .TP
 146 .B \-a
 147 Build a library (.cma file) with the object files (.cmo files) given on the command line, instead of linking them into an executable
 148 file. The name of the library can be set with the
 149 .B \-o
 150 option. The default name is
 151 .BR library.cma .
 152
 153 .TP
 154 .B \-c
 155 Compile only. Suppress the linking phase of the
 156 compilation. Source code files are turned into compiled files, but no
 157 executable file is produced. This option is useful to
 158 compile modules separately.
 159
 160 .TP
 161 .BI \-cclib\ -l libname
 162 Pass the
 163 .BI \-l libname
 164 option to the C linker when linking in
 165 ``custom runtime'' mode (see the
 166 .B \-custom
 167 option). This causes the
 168 given C library to be linked with the program.
 169
 170 .TP
 171 .B \-ccopt
 172 Pass the given option to the C compiler and linker, when linking in
 173 ``custom runtime'' mode (see the
 174 .B \-custom
 175 option). For instance,
 176 .B -ccopt -L
 177 .I dir
 178 causes the C linker to search for C libraries in
 179 directory
 180 .IR dir .
 181
 182 .TP
 183 .B \-custom
 184 Link in ``custom runtime'' mode. In the default linking mode, the
 185 linker produces bytecode that is intended to be executed with the
 186 shared runtime system,
 187 .BR ocamlrun (1).
 188 In the custom runtime mode, the
 189 linker produces an output file that contains both the runtime system
 190 and the bytecode for the program. The resulting file is larger, but it
 191 can be executed directly, even if the
 192 .BR ocamlrun (1)
 193 command is not
 194 installed. Moreover, the ``custom runtime'' mode enables linking Caml
 195 code with user-defined C functions.
 196
 197 .TP
 198 .B \-i
 199 Cause the compiler to print all defined names (with their inferred
 200 types or their definitions) when compiling an implementation (.ml
 201 file). This can be useful to check the types inferred by the
 202 compiler. Also, since the output follows the syntax of interfaces, it
 203 can help in writing an explicit interface (.mli file) for a file: just
 204 redirect the standard output of the compiler to a .mli file, and edit
 205 that file to remove all declarations of unexported names.
 206
 207 .TP
 208 .BI \-I \ directory
 209 Add the given directory to the list of directories searched for
 210 compiled interface files (.cmi) and compiled object code files
 211 (.cmo). By default, the current directory is searched first, then the
 212 standard library directory. Directories added with
 213 .B -I
 214 are searched
 215 after the current directory, in the order in which they were given on
 216 the command line, but before the standard library directory.
 217
 218 .TP
 219 .BI \-o \ exec-file
 220 Specify the name of the output file produced by the linker. The
 221 default output name is
 222 .BR a.out ,
 223 in keeping with the Unix tradition. If the
 224 .B \-a
 225 option is given, specify the name of the library produced.
 226
 227 .TP
 228 .B \-v
 229 Print the version number of the compiler.
 230
 231 .TP
 232 .B \-unsafe
 233 Turn bound checking off on array and string accesses (the
 234 .B v.(i)
 235 and
 236 .B s.[i]
 237 constructs). Programs compiled with
 238 .B \-unsafe
 239 are therefore
 240 slightly faster, but unsafe: anything can happen if the program
 241 accesses an array or string outside of its bounds.
 242
 243 .SH SEE ALSO
 244 .BR ocaml (1),
 245 .BR ocamlrun (1).
 246 .br
 247 .I The Objective Caml user's manual,
 248 chapter "Batch compilation".