1 \" $Id: ocamlc.m 9111 2008-10-29 12:38:52Z doligez $
6 ocamlc \- The Objective Caml bytecode compiler
23 The Objective Caml bytecode compiler
25 compiles Caml source files to bytecode object files and links
26 these object files to produce standalone bytecode executable files.
27 These executable files are then run by the bytecode interpreter
32 command has a command-line interface similar to the one of
33 most C compilers. It accepts several types of arguments and processes them
36 Arguments ending in .mli are taken to be source files for
37 compilation unit interfaces. Interfaces specify the names exported by
38 compilation units: they declare value names with their types, define
39 public data types, declare abstract data types, and so on. From the
44 compiler produces a compiled interface
48 Arguments ending in .ml are taken to be source files for compilation
49 unit implementations. Implementations provide definitions for the
50 names exported by the unit, and also contain expressions to be
51 evaluated for their side-effects. From the file
55 compiler produces compiled object bytecode in the file
60 exists, the implementation
62 is checked against the corresponding compiled interface
64 which is assumed to exist. If no interface
66 is provided, the compilation of
68 produces a compiled interface file
70 in addition to the compiled object code file
75 corresponds to an interface that exports everything that is defined in
79 Arguments ending in .cmo are taken to be compiled object bytecode. These
80 files are linked together, along with the object files obtained
81 by compiling .ml arguments (if any), and the Caml Light standard
82 library, to produce a standalone executable program. The order in
83 which .cmo and.ml arguments are presented on the command line is
84 relevant: compilation units are initialized in that order at
85 run-time, and it is a link-time error to use a component of a unit
86 before having initialized it. Hence, a given
88 file must come before all .cmo files that refer to the unit
91 Arguments ending in .cma are taken to be libraries of object bytecode.
92 A library of object bytecode packs in a single file a set of object
93 bytecode files (.cmo files). Libraries are built with
95 (see the description of the
97 option below). The object files
98 contained in the library are linked as regular .cmo files (see above),
99 in the order specified when the .cma file was built. The only
100 difference is that if an object file
101 contained in a library is not referenced anywhere in the program, then
104 Arguments ending in .c are passed to the C compiler, which generates
105 a .o object file. This object file is linked with the program if the
107 flag is set (see the description of
111 Arguments ending in .o or .a are assumed to be C object files and
112 libraries. They are passed to the C linker when linking in
114 mode (see the description of
118 Arguments ending in .so
119 are assumed to be C shared libraries (DLLs). During linking, they are
120 searched for external C functions referenced from the Caml code,
121 and their names are written in the generated bytecode executable.
124 then loads them dynamically at program start-up time.
126 The output of the linking phase is a file containing compiled bytecode
127 that can be executed by the Objective Caml bytecode interpreter:
132 is the name of the file produced by the linking phase, the command
134 .IR arg1 \ \ arg2 \ ... \ argn
135 executes the compiled code contained in
137 passing it as arguments the character strings
145 On most systems, the file produced by the linking
146 phase can be run directly, as in:
148 .IR arg1 \ \ arg2 \ ... \ argn .
149 The produced file has the executable bit set, and it manages to launch
150 the bytecode interpreter by itself.
153 is the same compiler as
155 but compiled with the native-code compiler
157 Thus, it behaves exactly like
161 may not be available in all installations of Objective Caml.
165 The following command-line options are recognized by
169 Build a library (.cma file) with the object files (.cmo files) given
170 on the command line, instead of linking them into an executable
171 file. The name of the library must be set with the
176 .BR \-custom , \ \-cclib \ or \ \-ccopt
177 options are passed on the command
178 line, these options are stored in the resulting .cma library. Then,
179 linking with this library automatically adds back the
180 .BR \-custom , \ \-cclib \ and \ \-ccopt
181 options as if they had been provided on the
182 command line, unless the
187 Dump detailed information about the compilation (types, bindings,
188 tail-calls, etc). The information for file
192 In case of a type error, dump all the information inferred by the
193 type-checker before the error. The
195 file can be used with the emacs commands given in
196 .B emacs/caml\-types.el
197 to display types and other annotations interactively.
200 Compile only. Suppress the linking phase of the
201 compilation. Source code files are turned into compiled files, but no
202 executable file is produced. This option is useful to
203 compile modules separately.
208 as the C linker when linking in "custom runtime" mode (see the
210 option) and as the C compiler for compiling .c source files.
212 .BI \-cclib\ -l libname
215 option to the C linker when linking in "custom runtime" mode (see the
217 option). This causes the given C library to be linked with the program.
220 Pass the given option to the C compiler and linker, when linking in
221 "custom runtime" mode (see the
223 option). For instance,
225 causes the C linker to search for C libraries in
230 Print the version number of
232 and a detailed summary of its configuration, then exit.
235 Link in "custom runtime" mode. In the default linking mode, the
236 linker produces bytecode that is intended to be executed with the
237 shared runtime system,
239 In the custom runtime mode, the
240 linker produces an output file that contains both the runtime system
241 and the bytecode for the program. The resulting file is larger, but it
242 can be executed directly, even if the
245 installed. Moreover, the "custom runtime" mode enables linking Caml
246 code with user-defined C functions.
250 command on executables produced by
251 .BR ocamlc\ \-custom ,
252 this would remove the bytecode part of the executable.
254 .BI \-dllib\ \-l libname
255 Arrange for the C shared library
257 to be loaded dynamically by the run-time system
259 at program start-up time.
264 to the run-time search path for shared
265 C libraries. At link-time, shared libraries are searched in the
266 standard search path (the one corresponding to the
274 executable file, where
276 can find it and use it.
279 Add debugging information while compiling and linking. This option is
280 required in order to be able to debug the program with
282 and to produce stack backtraces when
283 the program terminates on an uncaught exception.
286 Cause the compiler to print all defined names (with their inferred
287 types or their definitions) when compiling an implementation (.ml
288 file). No compiled files (.cmo and .cmi files) are produced.
289 This can be useful to check the types inferred by the
290 compiler. Also, since the output follows the syntax of interfaces, it
291 can help in writing an explicit interface (.mli file) for a file: just
292 redirect the standard output of the compiler to a .mli file, and edit
293 that file to remove all declarations of unexported names.
296 Add the given directory to the list of directories searched for
297 compiled interface files (.cmi), compiled object code files
298 (.cmo), libraries (.cma), and C libraries specified with
301 By default, the current directory is searched first, then the
302 standard library directory. Directories added with
305 after the current directory, in the order in which they were given on
306 the command line, but before the standard library directory.
308 If the given directory starts with
310 it is taken relative to the
311 standard library directory. For instance,
313 adds the subdirectory
315 of the standard library to the search path.
317 .BI \-impl \ filename
320 as an implementation file, even if its extension is not .ml.
322 .BI \-intf \ filename
325 as an interface file, even if its extension is not .mli.
327 .BI \-intf\-suffix \ string
328 Recognize file names ending with
330 as interface files (instead of the default .mli).
333 Labels are not ignored in types, labels may be used in applications,
334 and labelled parameters can be given in any order. This is the default.
337 Force all modules contained in libraries to be linked in. If this
338 flag is not given, unreferenced modules are not linked in. When
339 building a library (option
343 option forces all subsequent links of programs involving that library
344 to link all the modules contained in the library.
347 Build a custom runtime system (in the file specified by option
349 incorporating the C object files and libraries given on the command
350 line. This custom runtime system can be used later to execute
351 bytecode executables produced with the option
352 .B ocamlc\ \-use\-runtime
356 Do not compile assertion checks. Note that the special form
358 is always compiled because it is typed specially.
359 This flag has no effect when linking already-compiled files.
362 When linking .cma libraries, ignore
363 .BR \-custom , \ \-cclib \ and \ \-ccopt
364 options potentially contained in the libraries (if these options were
365 given when building the libraries). This can be useful if a library
366 contains incorrect specifications of C libraries or C options; in this
367 case, during linking, set
369 and pass the correct C libraries and options on the command line.
372 Ignore non-optional labels in types. Labels cannot be used in
373 applications, and parameter order becomes strict.
376 Specify the name of the output file produced by the linker. The
377 default output name is
379 in keeping with the Unix tradition. If the
381 option is given, specify the name of the library
384 option is given, specify the name of the
385 packed object file produced. If the
388 specify the name of the output file produced.
391 Cause the linker to produce a C object file instead of a bytecode
392 executable file. This is useful to wrap Caml code as a C library,
393 callable from any C program. The name of the output object file is
395 by default; it can be set with the
398 option can also be used to produce a C source file (.c extension) or
399 a compiled shared/dynamic library (.so extension).
402 Build a bytecode object file (.cmo file) and its associated compiled
403 interface (.cmi) that combines the object
404 files given on the command line, making them appear as sub-modules of
405 the output .cmo file. The name of the output .cmo file must be
408 option. For instance,
409 .B ocamlc\ \-pack\ \-o\ p.cmo\ a.cmo\ b.cmo\ c.cmo
410 generates compiled files p.cmo and p.cmi describing a compilation
411 unit having three sub-modules A, B and C, corresponding to the
412 contents of the object files a.cmo, b.cmo and c.cmo. These
413 contents can be referenced as P.A, P.B and P.C in the remainder
417 Cause the compiler to call the given
419 as a preprocessor for each source file. The output of
422 an intermediate file, which is compiled. If there are no compilation
423 errors, the intermediate file is deleted afterwards. The name of this
424 file is built from the basename of the source file with the extension .ppi
425 for an interface (.mli) file and .ppo for an implementation
429 Check information path during type-checking, to make sure that all
430 types are derived in a principal way. When using labelled arguments
431 and/or polymorphic methods, this flag is required to ensure future
432 versions of the compiler will be able to infer types correctly, even
433 if internal algorithms change.
434 All programs accepted in
436 mode are also accepted in the
437 default mode with equivalent types, but different binary signatures,
438 and this may slow down type checking; yet it is a good idea to
439 use it once before publishing source code.
442 Allow arbitrary recursive types during type-checking. By default,
443 only recursive types where the recursion goes through an object type
444 are supported. Note that once you have created an interface using this
445 flag, you must use it again for all dependencies.
448 Compile or link multithreaded programs, in combination with the
449 system "threads" library described in
450 .IR The\ Objective\ Caml\ user's\ manual .
453 Turn bound checking off for array and string accesses (the
455 constructs). Programs compiled with
458 slightly faster, but unsafe: anything can happen if the program
459 accesses an array or string outside of its bounds.
461 .BI \-use\-runtime \ runtime\-name
462 Generate a bytecode executable file that can be executed on the custom
466 .B ocamlc\ \-make\-runtime
470 Print the version number of the compiler and the location of the
471 standard library directory, then exit.
474 Print all external commands before they are executed, in particular
475 invocations of the C compiler and linker in
477 mode. Useful to debug C library problems.
480 Print the version number of the compiler in short form (e.g. "3.11.0"),
484 Compile or link multithreaded programs, in combination with the
485 VM-level threads library described in
486 .IR The\ Objective\ Caml\ user's\ manual .
488 .BI \-w \ warning\-list
489 Enable or disable warnings according to the argument
491 The argument is a set of letters. If a letter is
492 uppercase, it enables the corresponding warnings; lowercase disables
493 the warnings. The correspondence is the following:
499 \ \ start of comments that look like mistakes
502 \ \ use of deprecated features
505 \ \ fragile pattern matchings (matchings that will remain
506 complete even if additional constructors are added to one of the
507 variant types matched)
510 \ \ partially applied functions (expressions whose result has
511 function type and is ignored)
514 \ \ omission of labels in applications
517 \ \ overriding of methods
520 \ \ missing cases in pattern matchings (i.e. partial matchings)
523 \ \ expressions in the left-hand side of a sequence that don't
526 (and that are not functions, see
531 \ \ redundant cases in pattern matching (unused cases)
534 \ \ overriding of instance variables
537 \ \ unused variables that are bound with
539 and don't start with an underscore (_) character
542 \ \ all other cases of unused variables that don't start with an
543 underscore (_) character
546 \ \ warnings that don't fit in the above categories (except
549 The default setting is
551 enabling all warnings except fragile
552 pattern matchings, omitted labels, and innocuous unused variables.
555 are not always triggered, depending on the internals of the type checker.
557 .BI \-warn\-error \ warning\-list
558 Turn the warnings indicated in the argument
560 into errors. The compiler will stop with an error when one of these
561 warnings is emitted. The
563 has the same meaning as for
564 the "\-w" option: an uppercase character turns the corresponding
565 warning into an error, a lowercase character leaves it as a warning.
566 The default setting is
568 (none of the warnings is treated as an error).
571 Print the location of the standard library, then exit.
576 as a file name, even if it starts with a dash (-) character.
578 .BR \-help \ or \ \-\-help
579 Display a short usage summary and exit.
582 .BR ocamlopt (1), \ ocamlrun (1), \ ocaml (1).
584 .IR "The Objective Caml user's manual" ,
585 chapter "Batch compilation".
projects / l4.git / blob