1OCAMLC(1) General Commands Manual OCAMLC(1)
4
8 ocamlc - The Objective Caml bytecode compiler
9
12 ocamlc [ options ] filename ...
13 ocamlc.opt [ options ] filename ...
15
18 The Objective Caml bytecode compiler ocamlc(1) compiles Caml source
19 files to bytecode object files and links these object files to produce
20 standalone bytecode executable files. These executable files are then
21 run by the bytecode interpreter ocamlrun(1).
22 The ocamlc(1) command has a command-line interface similar to the one
24 of most C compilers. It accepts several types of arguments and pro‐
25 cesses them sequentially:
26 Arguments ending in .mli are taken to be source files for compilation
28 unit interfaces. Interfaces specify the names exported by compilation
29 units: they declare value names with their types, define public data
30 types, declare abstract data types, and so on. From the file x.mli, the
31 ocamlc(1) compiler produces a compiled interface in the file x.cmi.
32 Arguments ending in .ml are taken to be source files for compilation
34 unit implementations. Implementations provide definitions for the names
35 exported by the unit, and also contain expressions to be evaluated for
36 their side-effects. From the file x.ml, the ocamlc(1) compiler pro‐
37 duces compiled object bytecode in the file x.cmo.
38 If the interface file x.mli exists, the implementation x.ml is checked
40 against the corresponding compiled interface x.cmi, which is assumed to
41 exist. If no interface x.mli is provided, the compilation of x.ml pro‐
42 duces a compiled interface file x.cmi in addition to the compiled
43 object code file x.cmo. The file x.cmi produced corresponds to an
44 interface that exports everything that is defined in the implementation
45 x.ml.
46 Arguments ending in .cmo are taken to be compiled object bytecode.
48 These files are linked together, along with the object files obtained
49 by compiling .ml arguments (if any), and the Caml Light standard
50 library, to produce a standalone executable program. The order in which
51 .cmo and.ml arguments are presented on the command line is relevant:
52 compilation units are initialized in that order at run-time, and it is
53 a link-time error to use a component of a unit before having initial‐
54 ized it. Hence, a given x.cmo file must come before all .cmo files that
55 refer to the unit x.
56 Arguments ending in .cma are taken to be libraries of object bytecode.
58 A library of object bytecode packs in a single file a set of object
59 bytecode files (.cmo files). Libraries are built with ocamlc -a (see
60 the description of the -a option below). The object files contained in
61 the library are linked as regular .cmo files (see above), in the order
62 specified when the .cma file was built. The only difference is that if
63 an object file contained in a library is not referenced anywhere in the
64 program, then it is not linked in.
65 Arguments ending in .c are passed to the C compiler, which generates a
67 .o object file. This object file is linked with the program if the
68 -custom flag is set (see the description of -custom below).
69 Arguments ending in .o or .a are assumed to be C object files and
71 libraries. They are passed to the C linker when linking in -custom mode
72 (see the description of -custom below).
73 Arguments ending in .so are assumed to be C shared libraries (DLLs).
75 During linking, they are searched for external C functions referenced
76 from the Caml code, and their names are written in the generated byte‐
77 code executable. The run-time system ocamlrun(1) then loads them
78 dynamically at program start-up time.
79 The output of the linking phase is a file containing compiled bytecode
81 that can be executed by the Objective Caml bytecode interpreter: the
82 command ocamlrun(1). If caml.out is the name of the file produced by
83 the linking phase, the command ocamlrun caml.out arg1 arg2 ... argn
84 executes the compiled code contained in caml.out, passing it as argu‐
85 ments the character strings arg1 to argn. (See ocamlrun(1) for more
86 details.)
87 On most systems, the file produced by the linking phase can be run
89 directly, as in: ./caml.out arg1 arg2 ... argn. The produced file has
90 the executable bit set, and it manages to launch the bytecode inter‐
91 preter by itself.
92 ocamlc.opt is the same compiler as ocamlc, but compiled with the
94 native-code compiler ocamlopt(1). Thus, it behaves exactly like
95 ocamlc, but compiles faster. ocamlc.opt may not be available in all
96 installations of Objective Caml.
97
100 The following command-line options are recognized by ocamlc(1).
101 -a Build a library (.cma file) with the object files (.cmo files)
103 given on the command line, instead of linking them into an exe‐
104 cutable file. The name of the library must be set with the -o
105 option.
106 If -custom, -cclib or -ccopt options are passed on the command
108 line, these options are stored in the resulting .cma library.
109 Then, linking with this library automatically adds back the
110 -custom, -cclib and -ccopt options as if they had been provided
111 on the command line, unless the -noautolink option is given.
112 -annot Dump detailed information about the compilation (types, bind‐
114 ings, tail-calls, etc). The information for file src.ml is put
115 into file src.annot. In case of a type error, dump all the
116 information inferred by the type-checker before the error. The
117 src.annot file can be used with the emacs commands given in
118 emacs/caml-types.el to display types and other annotations
119 interactively.
120 -c Compile only. Suppress the linking phase of the compilation.
122 Source code files are turned into compiled files, but no exe‐
123 cutable file is produced. This option is useful to compile mod‐
124 ules separately.
125 -cc ccomp
127 Use ccomp as the C linker when linking in "custom runtime" mode
128 (see the -custom option) and as the C compiler for compiling .c
129 source files.
130 -cclib -llibname
132 Pass the -llibname option to the C linker when linking in "cus‐
133 tom runtime" mode (see the -custom option). This causes the
134 given C library to be linked with the program.
135 -ccopt Pass the given option to the C compiler and linker, when linking
137 in "custom runtime" mode (see the -custom option). For instance,
138 -ccopt -Ldir causes the C linker to search for C libraries in
139 directory dir.
140 -config
142 Print the version number of ocamlc(1) and a detailed summary of
143 its configuration, then exit.
144 -custom
146 Link in "custom runtime" mode. In the default linking mode, the
147 linker produces bytecode that is intended to be executed with
148 the shared runtime system, ocamlrun(1). In the custom runtime
149 mode, the linker produces an output file that contains both the
150 runtime system and the bytecode for the program. The resulting
151 file is larger, but it can be executed directly, even if the
152 ocamlrun(1) command is not installed. Moreover, the "custom run‐
153 time" mode enables linking Caml code with user-defined C func‐
154 tions.
155 Never use the strip(1) command on executables produced by
157 ocamlc -custom, this would remove the bytecode part of the exe‐
158 cutable.
159 -dllib -llibname
161 Arrange for the C shared library dlllibname.so to be loaded
162 dynamically by the run-time system ocamlrun(1) at program start-
163 up time.
164 -dllpath dir
166 Adds the directory dir to the run-time search path for shared C
167 libraries. At link-time, shared libraries are searched in the
168 standard search path (the one corresponding to the -I option).
169 The -dllpath option simply stores dir in the produced executable
170 file, where ocamlrun(1) can find it and use it.
171 -g Add debugging information while compiling and linking. This
173 option is required in order to be able to debug the program with
174 ocamldebug(1) and to produce stack backtraces when the program
175 terminates on an uncaught exception.
176 -i Cause the compiler to print all defined names (with their
178 inferred types or their definitions) when compiling an implemen‐
179 tation (.ml file). No compiled files (.cmo and .cmi files) are
180 produced. This can be useful to check the types inferred by the
181 compiler. Also, since the output follows the syntax of inter‐
182 faces, it can help in writing an explicit interface (.mli file)
183 for a file: just redirect the standard output of the compiler to
184 a .mli file, and edit that file to remove all declarations of
185 unexported names.
186 -I directory
188 Add the given directory to the list of directories searched for
189 compiled interface files (.cmi), compiled object code files
190 (.cmo), libraries (.cma), and C libraries specified with
191 -cclib -l xxx. By default, the current directory is searched
192 first, then the standard library directory. Directories added
193 with -I are searched after the current directory, in the order
194 in which they were given on the command line, but before the
195 standard library directory.
196 If the given directory starts with +, it is taken relative to
198 the standard library directory. For instance, -I +labltk adds
199 the subdirectory labltk of the standard library to the search
200 path.
201 -impl filename
203 Compile the file filename as an implementation file, even if its
204 extension is not .ml.
205 -intf filename
207 Compile the file filename as an interface file, even if its
208 extension is not .mli.
209 -intf-suffix string
211 Recognize file names ending with string as interface files
212 (instead of the default .mli).
213 -labels
215 Labels are not ignored in types, labels may be used in applica‐
216 tions, and labelled parameters can be given in any order. This
217 is the default.
218 -linkall
220 Force all modules contained in libraries to be linked in. If
221 this flag is not given, unreferenced modules are not linked in.
222 When building a library (option -a), setting the -linkall option
223 forces all subsequent links of programs involving that library
224 to link all the modules contained in the library.
225 -make-runtime
227 Build a custom runtime system (in the file specified by option
228 -o) incorporating the C object files and libraries given on the
229 command line. This custom runtime system can be used later to
230 execute bytecode executables produced with the option
231 ocamlc -use-runtime runtime-name.
232 -noassert
234 Do not compile assertion checks. Note that the special form
235 assert false is always compiled because it is typed specially.
236 This flag has no effect when linking already-compiled files.
237 -noautolink
239 When linking .cma libraries, ignore -custom, -cclib and -ccopt
240 options potentially contained in the libraries (if these options
241 were given when building the libraries). This can be useful if
242 a library contains incorrect specifications of C libraries or C
243 options; in this case, during linking, set -noautolink and pass
244 the correct C libraries and options on the command line.
245 -nolabels
247 Ignore non-optional labels in types. Labels cannot be used in
248 applications, and parameter order becomes strict.
249 -o exec-file
251 Specify the name of the output file produced by the linker. The
252 default output name is a.out, in keeping with the Unix tradi‐
253 tion. If the -a option is given, specify the name of the library
254 produced. If the -pack option is given, specify the name of the
255 packed object file produced. If the -output-obj option is
256 given, specify the name of the output file produced.
257 -output-obj
259 Cause the linker to produce a C object file instead of a byte‐
260 code executable file. This is useful to wrap Caml code as a C
261 library, callable from any C program. The name of the output
262 object file is camlprog.o by default; it can be set with the -o
263 option. This option can also be used to produce a C source file
264 (.c extension) or a compiled shared/dynamic library (.so exten‐
265 sion).
266 -pack Build a bytecode object file (.cmo file) and its associated com‐
268 piled interface (.cmi) that combines the object files given on
269 the command line, making them appear as sub-modules of the out‐
270 put .cmo file. The name of the output .cmo file must be given
271 with the -o option. For instance,
272 ocamlc -pack -o p.cmo a.cmo b.cmo c.cmo generates compiled files
273 p.cmo and p.cmi describing a compilation unit having three sub-
274 modules A, B and C, corresponding to the contents of the object
275 files a.cmo, b.cmo and c.cmo. These contents can be referenced
276 as P.A, P.B and P.C in the remainder of the program.
277 -pp command
279 Cause the compiler to call the given command as a preprocessor
280 for each source file. The output of command is redirected to an
281 intermediate file, which is compiled. If there are no compila‐
282 tion errors, the intermediate file is deleted afterwards. The
283 name of this file is built from the basename of the source file
284 with the extension .ppi for an interface (.mli) file and .ppo
285 for an implementation (.ml) file.
286 -principal
288 Check information path during type-checking, to make sure that
289 all types are derived in a principal way. When using labelled
290 arguments and/or polymorphic methods, this flag is required to
291 ensure future versions of the compiler will be able to infer
292 types correctly, even if internal algorithms change. All pro‐
293 grams accepted in -principal mode are also accepted in the
294 default mode with equivalent types, but different binary signa‐
295 tures, and this may slow down type checking; yet it is a good
296 idea to use it once before publishing source code.
297 -rectypes
299 Allow arbitrary recursive types during type-checking. By
300 default, only recursive types where the recursion goes through
301 an object type are supported. Note that once you have created an
302 interface using this flag, you must use it again for all depen‐
303 dencies.
304 -thread
306 Compile or link multithreaded programs, in combination with the
307 system "threads" library described in The Objec‐
308 tive Caml user's manual.
309 -unsafe
311 Turn bound checking off for array and string accesses (the
312 v.(i)ands.[i] constructs). Programs compiled with -unsafe are
313 therefore slightly faster, but unsafe: anything can happen if
314 the program accesses an array or string outside of its bounds.
315 -use-runtime runtime-name
317 Generate a bytecode executable file that can be executed on the
318 custom runtime system runtime-name, built earlier with
319 ocamlc -make-runtime runtime-name.
320 -v Print the version number of the compiler and the location of the
322 standard library directory, then exit.
323 -verbose
325 Print all external commands before they are executed, in partic‐
326 ular invocations of the C compiler and linker in -custom mode.
327 Useful to debug C library problems.
328 -version
330 Print the version number of the compiler in short form (e.g.
331 "3.11.0"), then exit.
332 -vmthread
334 Compile or link multithreaded programs, in combination with the
335 VM-level threads library described in The Objec‐
336 tive Caml user's manual.
337 -w warning-list
339 Enable or disable warnings according to the argument warn‐
340 ing-list. The argument is a set of letters. If a letter is
341 uppercase, it enables the corresponding warnings; lowercase dis‐
342 ables the warnings. The correspondence is the following:
343 A all warnings
345 C start of comments that look like mistakes
347 D use of deprecated features
349 E fragile pattern matchings (matchings that will remain com‐
351 plete even if additional constructors are added to one of the
352 variant types matched)
353 F partially applied functions (expressions whose result has
355 function type and is ignored)
356 L omission of labels in applications
358 M overriding of methods
360 P missing cases in pattern matchings (i.e. partial matchings)
362 S expressions in the left-hand side of a sequence that don't
364 have type unit (and that are not functions, see F above)
365 U redundant cases in pattern matching (unused cases)
367 V overriding of instance variables
369 Y unused variables that are bound with let or as, and don't
371 start with an underscore (_) character
372 Z all other cases of unused variables that don't start with an
374 underscore (_) character
375 X warnings that don't fit in the above categories (except A)
377 The default setting is -w Aelz, enabling all warnings except
379 fragile pattern matchings, omitted labels, and innocuous unused
380 variables. Note that warnings F and S are not always triggered,
381 depending on the internals of the type checker.
382 -warn-error warning-list
384 Turn the warnings indicated in the argument warning-list into
385 errors. The compiler will stop with an error when one of these
386 warnings is emitted. The warning-list has the same meaning as
387 for the "-w" option: an uppercase character turns the corre‐
388 sponding warning into an error, a lowercase character leaves it
389 as a warning. The default setting is -warn-error a (none of the
390 warnings is treated as an error).
391 -where Print the location of the standard library, then exit.
393 - file Process file as a file name, even if it starts with a dash (-)
395 character.
396 -help or --help
398 Display a short usage summary and exit.
399
402 ocamlopt(1), ocamlrun(1), ocaml(1).
403 The Objective Caml user's manual, chapter "Batch compilation".
404 OCAMLC(1)