From e2c2611f531a158926250b896603e3eba6aaa9d8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Hinderer?= Date: Wed, 20 Oct 2021 12:16:14 +0200 Subject: Simplify the installation of man pages --- man/Makefile | 18 +- man/ocaml.1 | 346 +++++++++++++++++ man/ocaml.m | 346 ----------------- man/ocamlc.1 | 1087 ++++++++++++++++++++++++++++++++++++++++++++++++++++ man/ocamlc.m | 1087 ---------------------------------------------------- man/ocamlc.opt.1 | 1 + man/ocamlcp.1 | 142 +++++++ man/ocamlcp.m | 142 ------- man/ocamldebug.1 | 124 ++++++ man/ocamldebug.m | 124 ------ man/ocamldep.1 | 196 ++++++++++ man/ocamldep.m | 196 ---------- man/ocamldoc.1 | 477 +++++++++++++++++++++++ man/ocamldoc.m | 477 ----------------------- man/ocamllex.1 | 101 +++++ man/ocamllex.m | 101 ----- man/ocamlmktop.1 | 97 +++++ man/ocamlmktop.m | 97 ----- man/ocamlopt.1 | 794 ++++++++++++++++++++++++++++++++++++++ man/ocamlopt.m | 794 -------------------------------------- man/ocamlopt.opt.1 | 1 + man/ocamloptp.1 | 1 + man/ocamlprof.1 | 87 +++++ man/ocamlprof.m | 87 ----- man/ocamlrun.1 | 313 +++++++++++++++ man/ocamlrun.m | 313 --------------- man/ocamlyacc.1 | 112 ++++++ man/ocamlyacc.m | 112 ------ 28 files changed, 3886 insertions(+), 3887 deletions(-) create mode 100644 man/ocaml.1 delete mode 100644 man/ocaml.m create mode 100644 man/ocamlc.1 delete mode 100644 man/ocamlc.m create mode 100644 man/ocamlc.opt.1 create mode 100644 man/ocamlcp.1 delete mode 100644 man/ocamlcp.m create mode 100644 man/ocamldebug.1 delete mode 100644 man/ocamldebug.m create mode 100644 man/ocamldep.1 delete mode 100644 man/ocamldep.m create mode 100644 man/ocamldoc.1 delete mode 100644 man/ocamldoc.m create mode 100644 man/ocamllex.1 delete mode 100644 man/ocamllex.m create mode 100644 man/ocamlmktop.1 delete mode 100644 man/ocamlmktop.m create mode 100644 man/ocamlopt.1 delete mode 100644 man/ocamlopt.m create mode 100644 man/ocamlopt.opt.1 create mode 100644 man/ocamloptp.1 create mode 100644 man/ocamlprof.1 delete mode 100644 man/ocamlprof.m create mode 100644 man/ocamlrun.1 delete mode 100644 man/ocamlrun.m create mode 100644 man/ocamlyacc.1 delete mode 100644 man/ocamlyacc.m (limited to 'man') diff --git a/man/Makefile b/man/Makefile index 52d1c19f53..36d3126563 100644 --- a/man/Makefile +++ b/man/Makefile @@ -14,17 +14,13 @@ #************************************************************************** ROOTDIR = .. -include $(ROOTDIR)/Makefile.config +include $(ROOTDIR)/Makefile.common -DESTDIR ?= -INSTALL_DIR=$(DESTDIR)$(MANDIR)/man$(PROGRAMS_MAN_SECTION) +MANPAGES = $(addsuffix .1,\ + ocaml ocamlc ocamlc.opt ocamlcp ocamldebug ocamldep ocamldoc ocamllex \ + ocamlmktop ocamlopt ocamlopt.opt ocamloptp ocamlprof ocamlrun ocamlyacc) +.PHONY: install install: - for i in *.m; do cp \ - $$i $(INSTALL_DIR)/`basename $$i .m`.$(PROGRAMS_MAN_SECTION); done - echo '.so man$(PROGRAMS_MAN_SECTION)/ocamlc.$(PROGRAMS_MAN_SECTION)' \ - > $(INSTALL_DIR)/ocamlc.opt.$(PROGRAMS_MAN_SECTION) - echo '.so man$(PROGRAMS_MAN_SECTION)/ocamlopt.$(PROGRAMS_MAN_SECTION)' \ - > $(INSTALL_DIR)/ocamlopt.opt.$(PROGRAMS_MAN_SECTION) - echo '.so man$(PROGRAMS_MAN_SECTION)/ocamlcp.$(PROGRAMS_MAN_SECTION)' \ - > $(INSTALL_DIR)/ocamloptp.$(PROGRAMS_MAN_SECTION) + $(MKDIR) $(INSTALL_PROGRAMS_MAN_DIR) + $(INSTALL_DATA) $(MANPAGES) $(INSTALL_PROGRAMS_MAN_DIR) diff --git a/man/ocaml.1 b/man/ocaml.1 new file mode 100644 index 0000000000..9d19f1b3c5 --- /dev/null +++ b/man/ocaml.1 @@ -0,0 +1,346 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAML 1 + +.SH NAME +ocaml \- The OCaml interactive toplevel + +.SH SYNOPSIS +.B ocaml +[ +.I options +] +[ +.I object-files +] +[ +.I script-file +] +.SH DESCRIPTION + +The +.BR ocaml (1) +command is the toplevel system for OCaml, +that permits interactive use of the OCaml system through a +read-eval-print loop. In this mode, the system repeatedly reads OCaml +phrases from the input, then typechecks, compiles and evaluates +them, then prints the inferred type and result value, if any. The +system prints a # (hash) prompt before reading each phrase. + +A toplevel phrase can span several lines. It is terminated by ;; (a +double-semicolon). The syntax of toplevel phrases is as follows. + +The toplevel system is started by the command +.BR ocaml (1). +Phrases are read on standard input, results are printed on standard +output, errors on standard error. End-of-file on standard input +terminates +.BR ocaml (1). + +If one or more +.I object-files +(ending in .cmo or .cma) are given, they are loaded silently before +starting the toplevel. + +If a +.I script-file +is given, phrases are read silently from the file, errors printed on +standard error. +.BR ocaml (1) +exits after the execution of the last phrase. + +.SH OPTIONS + +The following command-line options are recognized by +.BR ocaml (1). +.TP +.B \-absname +Show absolute filenames in error messages. +.TP +.BI \-I \ directory +Add the given directory to the list of directories searched for +source and compiled files. By default, the current directory is +searched first, then the standard library directory. Directories added +with +.B \-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. +.IP +If the given directory starts with +.BR + , +it is taken relative to the +standard library directory. For instance, +.B \-I\ +compiler-libs +adds the subdirectory +.B compiler-libs +of the standard library to the search path. +.IP +Directories can also be added to the search path once the toplevel +is running with the +.B #directory +directive. +.TP +.BI \-init \ file +Load the given file instead of the default initialization file. +See the "Initialization file" section below. +.TP +.B \-labels +Labels are not ignored in types, labels may be used in applications, +and labelled parameters can be given in any order. This is the default. +.TP +.B \-no\-app\-funct +Deactivates the applicative behaviour of functors. With this option, +each functor application generates new types in its result and +applying the same functor twice to the same argument yields two +incompatible structures. +.TP +.B \-noassert +Do not compile assertion checks. Note that the special form +.B assert\ false +is always compiled because it is typed specially. +.TP +.B \-noinit +Do not load any initialization file. +See the "Initialization file" section below. +.TP +.B \-nolabels +Ignore non-optional labels in types. Labels cannot be used in +applications, and parameter order becomes strict. +.TP +.B \-noprompt +Do not display any prompt when waiting for input. +.TP +.B \-nopromptcont +Do not display the secondary prompt when waiting for continuation lines in +multi-line inputs. This should be used e.g. when running +.BR ocaml (1) +in an +.BR emacs (1) +window. +.TP +.B \-nostdlib +Do not include the standard library directory in the list of +directories searched for source and compiled files. +.TP +.BI \-open \ module +Opens the given module before starting the toplevel. If several +.B \-open +options are given, they are processed in order, just as if +the statements open! module1;; ... open! moduleN;; were input. +.TP +.BI \-ppx \ command +After parsing, pipe the abstract syntax tree through the preprocessor +.IR command . +The module +.BR Ast_mapper (3) +implements the external interface of a preprocessor. +.TP +.B \-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 programs accepted in +.B \-principal +mode are also accepted in the +default mode with equivalent types, but different binary signatures, +and this may slow down type checking; yet it is a good idea to +use it once before publishing source code. +.TP +.B \-rectypes +Allow arbitrary recursive types during type-checking. By default, +only recursive types where the recursion goes through an object type +are supported. +.TP +.B \-safe\-string +Enforce the separation between types +.BR string \ and\ bytes , +thereby making strings read-only. This is the default. +.TP +.B \-short\-paths +When a type is visible under several module-paths, use the shortest +one when printing the type's name in inferred interfaces and error and +warning messages. +.TP +.B \-stdin +Read the standard input as a script file rather than starting an +interactive session. +.TP +.B \-strict\-sequence +Force the left-hand part of each sequence to have type unit. +.TP +.B \-unboxed\-types +When a type is unboxable (i.e. a record with a single argument or a +concrete datatype with a single constructor of one argument) it will +be unboxed unless annotated with +.BR [@@ocaml.boxed] . +.TP +.B \-no-unboxed\-types +When a type is unboxable it will be boxed unless annotated with +.BR [@@ocaml.unboxed] . +This is the default. +.TP +.B \-unsafe +Turn bound checking off on array and string accesses (the +.BR v.(i) and s.[i] +constructs). Programs compiled with +.B \-unsafe +are therefore slightly faster, but unsafe: anything can happen if the program +accesses an array or string outside of its bounds. +.TP +.B \-unsafe\-string +Identify the types +.BR string \ and\ bytes , +thereby making strings writable. +This is intended for compatibility with old source code and should not +be used with new software. +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.B \-no\-version +Do not print the version banner at startup. +.TP +.BI \-w \ warning\-list +Enable or disable warnings according to the argument +.IR warning-list . +See +.BR ocamlc (1) +for the syntax of the +.I warning\-list +argument. +.TP +.BI \-warn\-error \ warning\-list +Mark as fatal the warnings described by the argument +.IR warning\-list . +Note that a warning is not triggered (and does not trigger an error) if +it is disabled by the +.B \-w +option. See +.BR ocamlc (1) +for the syntax of the +.I warning\-list +argument. +.TP +.BI \-color \ mode +Enable or disable colors in compiler messages (especially warnings and errors). +The following modes are supported: + +.B auto +use heuristics to enable colors only if the output supports them (an +ANSI-compatible tty terminal); + +.B always +enable colors unconditionally; + +.B never +disable color output. + +The environment variable "OCAML_COLOR" is considered if \-color is not +provided. Its values are auto/always/never as above. + +If \-color is not provided, "OCAML_COLOR" is not set and the environment +variable "NO_COLOR" is set, then color output is disabled. Otherwise, +the default setting is +.B auto, +and the current heuristic +checks that the "TERM" environment variable exists and is +not empty or "dumb", and that isatty(stderr) holds. + +.TP +.BI \-error\-style \ mode +Control the way error messages and warnings are printed. +The following modes are supported: + +.B short +only print the error and its location; + +.B contextual +like "short", but also display the source code snippet corresponding +to the location of the error. + +The default setting is +.B contextual. + +The environment variable "OCAML_ERROR_STYLE" is considered if +\-error\-style is not provided. Its values are short/contextual as +above. + +.TP +.B \-warn\-help +Show the description of all available warning numbers. +.TP +.BI \- \ file +Use +.I file +as a script file name, even when it starts with a hyphen (-). +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH INITIALIZATION FILE + +When +.BR ocaml (1) +is invoked, it will read phrases from an initialization file before +giving control to the user. The default file is +.B .ocamlinit +in the current directory if it exists, otherwise +.B XDG_CONFIG_HOME/ocaml/init.ml +according to the XDG base directory specification lookup if it exists (on +Windows this is skipped), otherwise +.B .ocamlinit +in the user's home directory ( +.B HOME +variable). +You can specify a different initialization file +by using the +.BI \-init \ file +option, and disable initialization files by using the +.B \-noinit +option. + +Note that you can also use the +.B #use +directive to read phrases from a file. + +.SH ENVIRONMENT VARIABLES +.TP +.B OCAMLTOP_UTF_8 +When printing string values, non-ascii bytes (>0x7E) are printed as +decimal escape sequence if +.B OCAMLTOP_UTF_8 +is set to false. Otherwise they are printed unescaped. +.TP +.B TERM +When printing error messages, the toplevel system +attempts to underline visually the location of the error. It +consults the TERM variable to determines the type of output terminal +and look up its capabilities in the terminal database. +.TP +.B XDG_CONFIG_HOME HOME +.B .ocamlinit +lookup procedure (see above). +.SH SEE ALSO +.BR ocamlc (1), \ ocamlopt (1), \ ocamlrun (1). +.br +.IR The\ OCaml\ user's\ manual , +chapter "The toplevel system". diff --git a/man/ocaml.m b/man/ocaml.m deleted file mode 100644 index 9d19f1b3c5..0000000000 --- a/man/ocaml.m +++ /dev/null @@ -1,346 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAML 1 - -.SH NAME -ocaml \- The OCaml interactive toplevel - -.SH SYNOPSIS -.B ocaml -[ -.I options -] -[ -.I object-files -] -[ -.I script-file -] -.SH DESCRIPTION - -The -.BR ocaml (1) -command is the toplevel system for OCaml, -that permits interactive use of the OCaml system through a -read-eval-print loop. In this mode, the system repeatedly reads OCaml -phrases from the input, then typechecks, compiles and evaluates -them, then prints the inferred type and result value, if any. The -system prints a # (hash) prompt before reading each phrase. - -A toplevel phrase can span several lines. It is terminated by ;; (a -double-semicolon). The syntax of toplevel phrases is as follows. - -The toplevel system is started by the command -.BR ocaml (1). -Phrases are read on standard input, results are printed on standard -output, errors on standard error. End-of-file on standard input -terminates -.BR ocaml (1). - -If one or more -.I object-files -(ending in .cmo or .cma) are given, they are loaded silently before -starting the toplevel. - -If a -.I script-file -is given, phrases are read silently from the file, errors printed on -standard error. -.BR ocaml (1) -exits after the execution of the last phrase. - -.SH OPTIONS - -The following command-line options are recognized by -.BR ocaml (1). -.TP -.B \-absname -Show absolute filenames in error messages. -.TP -.BI \-I \ directory -Add the given directory to the list of directories searched for -source and compiled files. By default, the current directory is -searched first, then the standard library directory. Directories added -with -.B \-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. -.IP -If the given directory starts with -.BR + , -it is taken relative to the -standard library directory. For instance, -.B \-I\ +compiler-libs -adds the subdirectory -.B compiler-libs -of the standard library to the search path. -.IP -Directories can also be added to the search path once the toplevel -is running with the -.B #directory -directive. -.TP -.BI \-init \ file -Load the given file instead of the default initialization file. -See the "Initialization file" section below. -.TP -.B \-labels -Labels are not ignored in types, labels may be used in applications, -and labelled parameters can be given in any order. This is the default. -.TP -.B \-no\-app\-funct -Deactivates the applicative behaviour of functors. With this option, -each functor application generates new types in its result and -applying the same functor twice to the same argument yields two -incompatible structures. -.TP -.B \-noassert -Do not compile assertion checks. Note that the special form -.B assert\ false -is always compiled because it is typed specially. -.TP -.B \-noinit -Do not load any initialization file. -See the "Initialization file" section below. -.TP -.B \-nolabels -Ignore non-optional labels in types. Labels cannot be used in -applications, and parameter order becomes strict. -.TP -.B \-noprompt -Do not display any prompt when waiting for input. -.TP -.B \-nopromptcont -Do not display the secondary prompt when waiting for continuation lines in -multi-line inputs. This should be used e.g. when running -.BR ocaml (1) -in an -.BR emacs (1) -window. -.TP -.B \-nostdlib -Do not include the standard library directory in the list of -directories searched for source and compiled files. -.TP -.BI \-open \ module -Opens the given module before starting the toplevel. If several -.B \-open -options are given, they are processed in order, just as if -the statements open! module1;; ... open! moduleN;; were input. -.TP -.BI \-ppx \ command -After parsing, pipe the abstract syntax tree through the preprocessor -.IR command . -The module -.BR Ast_mapper (3) -implements the external interface of a preprocessor. -.TP -.B \-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 programs accepted in -.B \-principal -mode are also accepted in the -default mode with equivalent types, but different binary signatures, -and this may slow down type checking; yet it is a good idea to -use it once before publishing source code. -.TP -.B \-rectypes -Allow arbitrary recursive types during type-checking. By default, -only recursive types where the recursion goes through an object type -are supported. -.TP -.B \-safe\-string -Enforce the separation between types -.BR string \ and\ bytes , -thereby making strings read-only. This is the default. -.TP -.B \-short\-paths -When a type is visible under several module-paths, use the shortest -one when printing the type's name in inferred interfaces and error and -warning messages. -.TP -.B \-stdin -Read the standard input as a script file rather than starting an -interactive session. -.TP -.B \-strict\-sequence -Force the left-hand part of each sequence to have type unit. -.TP -.B \-unboxed\-types -When a type is unboxable (i.e. a record with a single argument or a -concrete datatype with a single constructor of one argument) it will -be unboxed unless annotated with -.BR [@@ocaml.boxed] . -.TP -.B \-no-unboxed\-types -When a type is unboxable it will be boxed unless annotated with -.BR [@@ocaml.unboxed] . -This is the default. -.TP -.B \-unsafe -Turn bound checking off on array and string accesses (the -.BR v.(i) and s.[i] -constructs). Programs compiled with -.B \-unsafe -are therefore slightly faster, but unsafe: anything can happen if the program -accesses an array or string outside of its bounds. -.TP -.B \-unsafe\-string -Identify the types -.BR string \ and\ bytes , -thereby making strings writable. -This is intended for compatibility with old source code and should not -be used with new software. -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.B \-no\-version -Do not print the version banner at startup. -.TP -.BI \-w \ warning\-list -Enable or disable warnings according to the argument -.IR warning-list . -See -.BR ocamlc (1) -for the syntax of the -.I warning\-list -argument. -.TP -.BI \-warn\-error \ warning\-list -Mark as fatal the warnings described by the argument -.IR warning\-list . -Note that a warning is not triggered (and does not trigger an error) if -it is disabled by the -.B \-w -option. See -.BR ocamlc (1) -for the syntax of the -.I warning\-list -argument. -.TP -.BI \-color \ mode -Enable or disable colors in compiler messages (especially warnings and errors). -The following modes are supported: - -.B auto -use heuristics to enable colors only if the output supports them (an -ANSI-compatible tty terminal); - -.B always -enable colors unconditionally; - -.B never -disable color output. - -The environment variable "OCAML_COLOR" is considered if \-color is not -provided. Its values are auto/always/never as above. - -If \-color is not provided, "OCAML_COLOR" is not set and the environment -variable "NO_COLOR" is set, then color output is disabled. Otherwise, -the default setting is -.B auto, -and the current heuristic -checks that the "TERM" environment variable exists and is -not empty or "dumb", and that isatty(stderr) holds. - -.TP -.BI \-error\-style \ mode -Control the way error messages and warnings are printed. -The following modes are supported: - -.B short -only print the error and its location; - -.B contextual -like "short", but also display the source code snippet corresponding -to the location of the error. - -The default setting is -.B contextual. - -The environment variable "OCAML_ERROR_STYLE" is considered if -\-error\-style is not provided. Its values are short/contextual as -above. - -.TP -.B \-warn\-help -Show the description of all available warning numbers. -.TP -.BI \- \ file -Use -.I file -as a script file name, even when it starts with a hyphen (-). -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH INITIALIZATION FILE - -When -.BR ocaml (1) -is invoked, it will read phrases from an initialization file before -giving control to the user. The default file is -.B .ocamlinit -in the current directory if it exists, otherwise -.B XDG_CONFIG_HOME/ocaml/init.ml -according to the XDG base directory specification lookup if it exists (on -Windows this is skipped), otherwise -.B .ocamlinit -in the user's home directory ( -.B HOME -variable). -You can specify a different initialization file -by using the -.BI \-init \ file -option, and disable initialization files by using the -.B \-noinit -option. - -Note that you can also use the -.B #use -directive to read phrases from a file. - -.SH ENVIRONMENT VARIABLES -.TP -.B OCAMLTOP_UTF_8 -When printing string values, non-ascii bytes (>0x7E) are printed as -decimal escape sequence if -.B OCAMLTOP_UTF_8 -is set to false. Otherwise they are printed unescaped. -.TP -.B TERM -When printing error messages, the toplevel system -attempts to underline visually the location of the error. It -consults the TERM variable to determines the type of output terminal -and look up its capabilities in the terminal database. -.TP -.B XDG_CONFIG_HOME HOME -.B .ocamlinit -lookup procedure (see above). -.SH SEE ALSO -.BR ocamlc (1), \ ocamlopt (1), \ ocamlrun (1). -.br -.IR The\ OCaml\ user's\ manual , -chapter "The toplevel system". diff --git a/man/ocamlc.1 b/man/ocamlc.1 new file mode 100644 index 0000000000..adbfe3ec8b --- /dev/null +++ b/man/ocamlc.1 @@ -0,0 +1,1087 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLC 1 + +.SH NAME +ocamlc \- The OCaml bytecode compiler + +.SH SYNOPSIS +.B ocamlc +[ +.I options +] +.I filename ... + +.B ocamlc.opt +[ +.I options +] +.I filename ... + +.SH DESCRIPTION + +The OCaml bytecode compiler +.BR ocamlc (1) +compiles OCaml 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 +.BR ocamlrun (1). + +The +.BR ocamlc (1) +command has a command-line interface similar to the one of +most C compilers. It accepts several types of arguments and processes them +sequentially, after all options have been processed: + +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 +.IR x \&.mli, +the +.BR ocamlc (1) +compiler produces a compiled interface +in the file +.IR 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 +.IR x \&.ml, +the +.BR ocamlc (1) +compiler produces compiled object bytecode in the file +.IR x \&.cmo. + +If the interface file +.IR x \&.mli +exists, the implementation +.IR x \&.ml +is checked against the corresponding compiled interface +.IR x \&.cmi, +which is assumed to exist. If no interface +.IR x \&.mli +is provided, the compilation of +.IR x \&.ml +produces a compiled interface file +.IR x \&.cmi +in addition to the compiled object code file +.IR x \&.cmo. +The file +.IR x \&.cmi +produced +corresponds to an interface that exports everything that is defined in +the implementation +.IR 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 OCaml 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 initialized it. Hence, a given +.IR x \&.cmo +file must come before all .cmo files that refer to the unit +.IR 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 +.B ocamlc\ \-a +(see the description of the +.B \-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 +.B \-custom +flag is set (see the description of +.B \-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 +.B \-custom +mode (see the description of +.B \-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 OCaml code, +and their names are written in the generated bytecode executable. +The run-time system +.BR 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 OCaml bytecode interpreter: +the command +.BR ocamlrun (1). +If +.B caml.out +is the name of the file produced by the linking phase, the command +.B ocamlrun caml.out +.IR arg1 \ \ arg2 \ ... \ argn +executes the compiled code contained in +.BR caml.out , +passing it as arguments the character strings +.I arg1 +to +.IR argn . +(See +.BR ocamlrun (1) +for more details.) + +On most systems, the file produced by the linking +phase can be run directly, as in: +.B ./caml.out +.IR arg1 \ \ arg2 \ ... \ argn . +The produced file has the executable bit set, and it manages to launch +the bytecode interpreter by itself. + +.B ocamlc.opt +is the same compiler as +.BR ocamlc , +but compiled with the native-code compiler +.BR ocamlopt (1). +Thus, it behaves exactly like +.BR ocamlc , +but compiles faster. +.B ocamlc.opt +may not be available in all installations of OCaml. + +.SH OPTIONS + +The following command-line options are recognized by +.BR ocamlc (1). +.TP +.B \-a +Build a library (.cma file) with the object files (.cmo files) given +on the command line, instead of linking them into an executable +file. The name of the library must be set with the +.B \-o +option. +.IP +If +.BR \-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 +.BR \-custom , \ \-cclib \ and \ \-ccopt +options as if they had been provided on the +command line, unless the +.B \-noautolink +option is given. Additionally, a substring +.B $CAMLORIGIN +inside a +.BR \ \-ccopt +options will be replaced by the full path to the .cma library, +excluding the filename. +.B \-absname +Show absolute filenames in error messages. +.TP +.B \-annot +Deprecated since 4.11. Please use +.BR \-bin-annot +instead. +.TP +.B \-bin\-annot +Dump detailed information about the compilation (types, bindings, +tail-calls, etc) in binary format. The information for file +.IR src .ml +is put into file +.IR src .cmt. +In case of a type error, dump +all the information inferred by the type-checker before the error. +The annotation files produced by +.B \-bin\-annot +contain more information +and are much more compact than the files produced by +.BR \-annot . +.TP +.B \-c +Compile only. Suppress the linking phase of the +compilation. Source code files are turned into compiled files, but no +executable file is produced. This option is useful to +compile modules separately. +.TP +.BI \-cc \ ccomp +Use +.I ccomp +as the C linker when linking in "custom runtime" mode (see the +.B \-custom +option) and as the C compiler for compiling .c source files. +.TP +.BI \-cclib\ -l libname +Pass the +.BI \-l libname +option to the C linker when linking in "custom runtime" mode (see the +.B \-custom +option). This causes the given C library to be linked with the program. +.TP +.BI \-ccopt \ option +Pass the given +.I option +to the C compiler and linker, when linking in +"custom runtime" mode (see the +.B \-custom +option). For instance, +.BI \-ccopt\ \-L dir +causes the C linker to search for C libraries in +directory +.IR dir . +.TP +.BI \-color \ mode +Enable or disable colors in compiler messages (especially warnings and errors). +The following modes are supported: + +.B auto +use heuristics to enable colors only if the output supports them (an +ANSI-compatible tty terminal); + +.B always +enable colors unconditionally; + +.B never +disable color output. + +The environment variable "OCAML_COLOR" is considered if \-color is not +provided. Its values are auto/always/never as above. + +If \-color is not provided, "OCAML_COLOR" is not set and the environment +variable "NO_COLOR" is set, then color output is disabled. Otherwise, +the default setting is +.B auto, +and the current heuristic +checks that the "TERM" environment variable exists and is +not empty or "dumb", and that isatty(stderr) holds. + +.TP +.BI \-error\-style \ mode +Control the way error messages and warnings are printed. +The following modes are supported: + +.B short +only print the error and its location; + +.B contextual +like "short", but also display the source code snippet corresponding +to the location of the error. + +The default setting is +.B contextual. + +The environment variable "OCAML_ERROR_STYLE" is considered if +\-error\-style is not provided. Its values are short/contextual as +above. + +.TP +.B \-compat\-32 +Check that the generated bytecode executable can run on 32-bit +platforms and signal an error if it cannot. This is useful when +compiling bytecode on a 64-bit machine. +.TP +.B \-config +Print the version number of +.BR ocamlc (1) +and a detailed summary of its configuration, then exit. +.TP +.BI \-config-var +Print the value of a specific configuration variable +from the +.B \-config +output, then exit. If the variable does not exist, +the exit code is non-zero. +.TP +.B \-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, +.BR 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 +.BR ocamlrun (1) +command is not +installed. Moreover, the "custom runtime" mode enables linking OCaml +code with user-defined C functions. + +Never use the +.BR strip (1) +command on executables produced by +.BR ocamlc\ \-custom , +this would remove the bytecode part of the executable. + +Security warning: never set the "setuid" or "setgid" bits on +executables produced by +.BR ocamlc\ \-custom , +this would make them vulnerable to attacks. +.TP +.BI \-depend\ ocamldep-args +Compute dependencies, as ocamldep would do. +.TP +.BI \-dllib\ \-l libname +Arrange for the C shared library +.BI dll libname .so +to be loaded dynamically by the run-time system +.BR ocamlrun (1) +at program start-up time. +.TP +.BI \-dllpath \ dir +Adds the directory +.I 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 +.B \-I +option). +The +.B \-dllpath +option simply stores +.I dir +in the produced +executable file, where +.BR ocamlrun (1) +can find it and use it. +.TP +.BI \-for\-pack \ module\-path +Generate an object file (.cmo file) that can later be included +as a sub-module (with the given access path) of a compilation unit +constructed with +.BR \-pack . +For instance, +.B ocamlc\ \-for\-pack\ P\ \-c\ A.ml +will generate a.cmo that can later be used with +.BR "ocamlc -pack -o P.cmo a.cmo" . +Note: you can still pack a module that was compiled without +.B \-for\-pack +but in this case exceptions will be printed with the wrong names. +.TP +.B \-g +Add debugging information while compiling and linking. This option is +required in order to be able to debug the program with +.BR ocamldebug (1) +and to produce stack backtraces when +the program terminates on an uncaught exception. +.TP +.B \-i +Cause the compiler to print all defined names (with their inferred +types or their definitions) when compiling an implementation (.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 interfaces, 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. +.TP +.BI \-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 +.BI \-cclib\ \-l xxx +.RB . +By default, the current directory is searched first, then the +standard library directory. Directories added with +.B \-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. See also +option +.BR \-nostdlib . + +If the given directory starts with +.BR + , +it is taken relative to the +standard library directory. For instance, +.B \-I\ +compiler-libs +adds the subdirectory +.B compiler-libs +of the standard library to the search path. +.TP +.BI \-impl \ filename +Compile the file +.I filename +as an implementation file, even if its extension is not .ml. +.TP +.BI \-intf \ filename +Compile the file +.I filename +as an interface file, even if its extension is not .mli. +.TP +.BI \-intf\-suffix \ string +Recognize file names ending with +.I string +as interface files (instead of the default .mli). +.TP +.B \-keep-docs +Keep documentation strings in generated .cmi files. +.TP +.B \-keep-locs +Keep locations in generated .cmi files. +.TP +.B \-labels +Labels are not ignored in types, labels may be used in applications, +and labelled parameters can be given in any order. This is the default. +.TP +.B \-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 +.BR \-a ), +setting the +.B \-linkall +option forces all subsequent links of programs involving that library +to link all the modules contained in the library. +When compiling a module (option +.BR \-c ), +setting the +.B \-linkall +option ensures that this module will +always be linked if it is put in a library and this library is linked. +.TP +.B \-make\-runtime +Build a custom runtime system (in the file specified by option +.BR \-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 +.B ocamlc\ \-use\-runtime +.IR runtime-name . +.TP +.B \-match\-context\-rows +Set number of rows of context used during pattern matching +compilation. Lower values cause faster compilation, but +less optimized code. The default value is 32. +.TP +.B \-no-alias-deps +Do not record dependencies for module aliases. +.TP +.B \-no\-app\-funct +Deactivates the applicative behaviour of functors. With this option, +each functor application generates new types in its result and +applying the same functor twice to the same argument yields two +incompatible structures. +.TP +.B \-noassert +Do not compile assertion checks. Note that the special form +.B assert\ false +is always compiled because it is typed specially. +This flag has no effect when linking already-compiled files. +.TP +.B \-noautolink +When linking .cma libraries, ignore +.BR \-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 +.B \-noautolink +and pass the correct C libraries and options on the command line. +.TP +.B \-nolabels +Ignore non-optional labels in types. Labels cannot be used in +applications, and parameter order becomes strict. +.TP +.B \-nostdlib +Do not automatically add the standard library directory to the list of +directories searched for compiled interface files (.cmi), compiled +object code files (.cmo), libraries (.cma), and C libraries specified +with +.BI \-cclib\ \-l xxx +.RB . +See also option +.BR \-I . +.TP +.BI \-o \ exec\-file +Specify the name of the output file produced by the linker. The +default output name is +.BR a.out , +in keeping with the Unix tradition. If the +.B \-a +option is given, specify the name of the library +produced. If the +.B \-pack +option is given, specify the name of the +packed object file produced. If the +.B \-output\-obj +or +.B \-output\-complete\-obj +option is given, +specify the name of the output file produced. +This can also be used when compiling an interface or implementation +file, without linking, in which case it sets the name of the cmi or +cmo file, and also sets the module name to the file name up to the +first dot. +.TP +.B \-opaque +Interface file compiled with this option are marked so that other +compilation units depending on it will not rely on any implementation +details of the compiled implementation. The native compiler will not +access the .cmx file of this unit -- nor warn if it is absent. This can +improve speed of compilation, for both initial and incremental builds, +at the expense of performance of the generated code. +.TP +.BI \-open \ module +Opens the given module before processing the interface or +implementation files. If several +.B \-open +options are given, they are processed in order, just as if +the statements open! module1;; ... open! moduleN;; were added +at the top of each file. +.TP +.B \-output\-obj +Cause the linker to produce a C object file instead of a bytecode +executable file. This is useful to wrap OCaml code as a C library, +callable from any C program. The name of the output object file +must be set with the +.B \-o +option. This +option can also be used to produce a C source file (.c extension) or +a compiled shared/dynamic library (.so extension). +.TP +.B \-output\-complete\-obj +Same as +.B \-output\-obj +except when creating an object file where it includes the runtime and +autolink libraries. +.TP +.B \-pack +Build a bytecode object file (.cmo file) and its associated compiled +interface (.cmi) that combines the object +files given on the command line, making them appear as sub-modules of +the output .cmo file. The name of the output .cmo file must be +given with the +.B \-o +option. For instance, +.B 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. +.TP +.BI \-pp \ command +Cause the compiler to call the given +.I command +as a preprocessor for each source file. The output of +.I command +is redirected to +an intermediate file, which is compiled. If there are no compilation +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. +.TP +.BI \-ppx \ command +After parsing, pipe the abstract syntax tree through the preprocessor +.IR command . +The module +.BR Ast_mapper (3) +implements the external interface of a preprocessor. +.TP +.B \-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 programs accepted in +.B \-principal +mode are also accepted in the +default mode with equivalent types, but different binary signatures, +and this may slow down type checking; yet it is a good idea to +use it once before publishing source code. +.TP +.B \-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 dependencies. +.TP +.BI \-runtime\-variant \ suffix +Add +.I suffix +to the name of the runtime library that will be used by the program. +If OCaml was configured with option +.BR \-with\-debug\-runtime , +then the +.B d +suffix is supported and gives a debug version of the runtime. +.TP +.BI \-stop\-after \ pass +Stop compilation after the given compilation pass. The currently +supported passes are: +.BR parsing , +.BR typing . +.TP +.B \-safe\-string +Enforce the separation between types +.BR string \ and\ bytes , +thereby making strings read-only. This is the default. +.TP +.B \-short\-paths +When a type is visible under several module-paths, use the shortest +one when printing the type's name in inferred interfaces and error and +warning messages. +.TP +.B \-strict\-sequence +Force the left-hand part of each sequence to have type unit. +.TP +.B \-unboxed\-types +When a type is unboxable (i.e. a record with a single argument or a +concrete datatype with a single constructor of one argument) it will +be unboxed unless annotated with +.BR [@@ocaml.boxed] . +.TP +.B \-no-unboxed\-types +When a type is unboxable it will be boxed unless annotated with +.BR [@@ocaml.unboxed] . +This is the default. +.TP +.B \-unsafe +Turn bound checking off for array and string accesses (the +.BR v.(i) and s.[i] +constructs). Programs compiled with +.B \-unsafe +are therefore +slightly faster, but unsafe: anything can happen if the program +accesses an array or string outside of its bounds. +.TP +.B \-unsafe\-string +Identify the types +.BR string \ and\ bytes , +thereby making strings writable. +This is intended for compatibility with old source code and should not +be used with new software. +.TP +.BI \-use\-runtime \ runtime\-name +Generate a bytecode executable file that can be executed on the custom +runtime system +.IR runtime\-name , +built earlier with +.B ocamlc\ \-make\-runtime +.IR runtime\-name . +.TP +.B \-v +Print the version number of the compiler and the location of the +standard library directory, then exit. +.TP +.B \-verbose +Print all external commands before they are executed, in particular +invocations of the C compiler and linker in +.B \-custom +mode. Useful to debug C library problems. +.TP +.BR \-vnum \ or\ \-version +Print the version number of the compiler in short form (e.g. "3.11.0"), +then exit. +.TP +.BI \-w \ warning\-list +Enable, disable, or mark as fatal the warnings specified by the argument +.IR warning\-list . + +Each warning can be +.IR enabled \ or\ disabled , +and each warning can be +.IR fatal \ or +.IR non-fatal . +If a warning is disabled, it isn't displayed and doesn't affect +compilation in any way (even if it is fatal). If a warning is enabled, +it is displayed normally by the compiler whenever the source code +triggers it. If it is enabled and fatal, the compiler will also stop +with an error after displaying it. + +The +.I warning\-list +argument is a sequence of warning specifiers, with no separators +between them. A warning specifier is one of the following: + +.BI + num +\ \ Enable warning number +.IR num . + +.BI \- num +\ \ Disable warning number +.IR num . + +.BI @ num +\ \ Enable and mark as fatal warning number +.IR num . + +.BI + num1 .. num2 +\ \ Enable all warnings between +.I num1 +and +.I num2 +(inclusive). + +.BI \- num1 .. num2 +\ \ Disable all warnings between +.I num1 +and +.I num2 +(inclusive). + +.BI @ num1 .. num2 +\ \ Enable and mark as fatal all warnings between +.I num1 +and +.I num2 +(inclusive). + +.BI + letter +\ \ Enable the set of warnings corresponding to +.IR letter . +The letter may be uppercase or lowercase. + +.BI \- letter +\ \ Disable the set of warnings corresponding to +.IR letter . +The letter may be uppercase or lowercase. + +.BI @ letter +\ \ Enable and mark as fatal the set of warnings corresponding to +.IR letter . +The letter may be uppercase or lowercase. + +.I uppercase\-letter +\ \ Enable the set of warnings corresponding to +.IR uppercase\-letter . + +.I lowercase\-letter +\ \ Disable the set of warnings corresponding to +.IR lowercase\-letter . + +The warning numbers are as follows. + +1 +\ \ \ Suspicious-looking start-of-comment mark. + +2 +\ \ \ Suspicious-looking end-of-comment mark. + +3 +\ \ \ Deprecated feature. + +4 +\ \ \ Fragile pattern matching: matching that will remain +complete even if additional constructors are added to one of the +variant types matched. + +5 +\ \ \ Partially applied function: expression whose result has +function type and is ignored. + +6 +\ \ \ Label omitted in function application. + +7 +\ \ \ Method overridden without using the "method!" keyword. + +8 +\ \ \ Partial match: missing cases in pattern-matching. + +9 +\ \ \ Missing fields in a record pattern. + +10 +\ \ Expression on the left-hand side of a sequence that doesn't +have type +.B unit +(and that is not a function, see warning number 5). + +11 +\ \ Redundant case in a pattern matching (unused match case). + +12 +\ \ Redundant sub-pattern in a pattern-matching. + +13 +\ \ Override of an instance variable. + +14 +\ \ Illegal backslash escape in a string constant. + +15 +\ \ Private method made public implicitly. + +16 +\ \ Unerasable optional argument. + +17 +\ \ Undeclared virtual method. + +18 +\ \ Non-principal type. + +19 +\ \ Type without principality. + +20 +\ \ Unused function argument. + +21 +\ \ Non-returning statement. + +22 +\ \ Preprocessor warning. + +23 +\ \ Useless record +.B with +clause. + +24 +\ \ Bad module name: the source file name is not a valid OCaml module name. + +25 +\ \ Deprecated: now part of warning 8. + +26 +\ \ Suspicious unused variable: unused variable that is bound with +.BR let \ or \ as , +and doesn't start with an underscore (_) character. + +27 +\ \ Innocuous unused variable: unused variable that is not bound with +.BR let \ nor \ as , +and doesn't start with an underscore (_) character. + +28 +\ \ A pattern contains a constant constructor applied to the underscore (_) +pattern. + +29 +\ \ A non-escaped end-of-line was found in a string constant. This may +cause portability problems between Unix and Windows. + +30 +\ \ Two labels or constructors of the same name are defined in two +mutually recursive types. + +31 +\ \ A module is linked twice in the same executable. + +32 +\ \ Unused value declaration. + +33 +\ \ Unused open statement. + +34 +\ \ Unused type declaration. + +35 +\ \ Unused for-loop index. + +36 +\ \ Unused ancestor variable. + +37 +\ \ Unused constructor. + +38 +\ \ Unused extension constructor. + +39 +\ \ Unused rec flag. + +40 +\ \ Constructor or label name used out of scope. + +41 +\ \ Ambiguous constructor or label name. + +42 +\ \ Disambiguated constructor or label name. + +43 +\ \ Nonoptional label applied as optional. + +44 +\ \ Open statement shadows an already defined identifier. + +45 +\ \ Open statement shadows an already defined label or constructor. + +46 +\ \ Error in environment variable. + +47 +\ \ Illegal attribute payload. + +48 +\ \ Implicit elimination of optional arguments. + +49 +\ \ Missing cmi file when looking up module alias. + +50 +\ \ Unexpected documentation comment. + +59 +\ \ Assignment on non-mutable value. + +60 +\ \ Unused module declaration. + +61 +\ \ Unannotated unboxable type in primitive declaration. + +62 +\ \ Type constraint on GADT type declaration. + +63 +\ \ Erroneous printed signature. + +64 +\ \ -unsafe used with a preprocessor returning a syntax tree. + +65 +\ \ Type declaration defining a new '()' constructor. + +66 +\ \ Unused open! statement. + +67 +\ \ Unused functor parameter. + +68 +\ \ Pattern-matching depending on mutable state prevents the remaining +arguments from being uncurried. + +The letters stand for the following sets of warnings. Any letter not +mentioned here corresponds to the empty set. + +.B A +\ all warnings + +.B C +\ 1, 2 + +.B D +\ 3 + +.B E +\ 4 + +.B F +\ 5 + +.B K +\ 32, 33, 34, 35, 36, 37, 38, 39 + +.B L +\ 6 + +.B M +\ 7 + +.B P +\ 8 + +.B R +\ 9 + +.B S +\ 10 + +.B U +\ 11, 12 + +.B V +\ 13 + +.B X +\ 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 30 + +.B Y +\ 26 + +.B Z +\ 27 + +.IP +The default setting is +.BR \-w\ +a\-4\-7\-9\-27\-29\-30\-32..42\-44\-45\-48\-50\-60\-66..70 . +Note that warnings +.BR 5 \ and \ 10 +are not always triggered, depending on the internals of the type checker. +.TP +.BI \-warn\-error \ warning\-list +Mark as errors the warnings specified in the argument +.IR warning\-list . +The compiler will stop with an error when one of these +warnings is emitted. The +.I warning\-list +has the same meaning as for +the +.B \-w +option: a +.B + +sign (or an uppercase letter) marks the corresponding warnings as fatal, a +.B \- +sign (or a lowercase letter) turns them back into non-fatal warnings, and a +.B @ +sign both enables and marks as fatal the corresponding warnings. + +Note: it is not recommended to use the +.B \-warn\-error +option in production code, because it will almost certainly prevent +compiling your program with later versions of OCaml when they add new +warnings or modify existing warnings. + +The default setting is +.B \-warn\-error \-a+31 +(only warning 31 is fatal). +.TP +.B \-warn\-help +Show the description of all available warning numbers. +.TP +.B \-where +Print the location of the standard library, then exit. +.TP +.B \-with-runtime +Include the runtime system in the generated program. This is the default. +.TP +.B \-without-runtime +The compiler does not include the runtime system (nor a reference to it) in the +generated program; it must be supplied separately. +.TP +.BI \- \ file +Process +.I file +as a file name, even if it starts with a dash (-) character. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH SEE ALSO +.BR ocamlopt (1), \ ocamlrun (1), \ ocaml (1). +.br +.IR "The OCaml user's manual" , +chapter "Batch compilation". diff --git a/man/ocamlc.m b/man/ocamlc.m deleted file mode 100644 index adbfe3ec8b..0000000000 --- a/man/ocamlc.m +++ /dev/null @@ -1,1087 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLC 1 - -.SH NAME -ocamlc \- The OCaml bytecode compiler - -.SH SYNOPSIS -.B ocamlc -[ -.I options -] -.I filename ... - -.B ocamlc.opt -[ -.I options -] -.I filename ... - -.SH DESCRIPTION - -The OCaml bytecode compiler -.BR ocamlc (1) -compiles OCaml 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 -.BR ocamlrun (1). - -The -.BR ocamlc (1) -command has a command-line interface similar to the one of -most C compilers. It accepts several types of arguments and processes them -sequentially, after all options have been processed: - -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 -.IR x \&.mli, -the -.BR ocamlc (1) -compiler produces a compiled interface -in the file -.IR 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 -.IR x \&.ml, -the -.BR ocamlc (1) -compiler produces compiled object bytecode in the file -.IR x \&.cmo. - -If the interface file -.IR x \&.mli -exists, the implementation -.IR x \&.ml -is checked against the corresponding compiled interface -.IR x \&.cmi, -which is assumed to exist. If no interface -.IR x \&.mli -is provided, the compilation of -.IR x \&.ml -produces a compiled interface file -.IR x \&.cmi -in addition to the compiled object code file -.IR x \&.cmo. -The file -.IR x \&.cmi -produced -corresponds to an interface that exports everything that is defined in -the implementation -.IR 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 OCaml 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 initialized it. Hence, a given -.IR x \&.cmo -file must come before all .cmo files that refer to the unit -.IR 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 -.B ocamlc\ \-a -(see the description of the -.B \-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 -.B \-custom -flag is set (see the description of -.B \-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 -.B \-custom -mode (see the description of -.B \-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 OCaml code, -and their names are written in the generated bytecode executable. -The run-time system -.BR 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 OCaml bytecode interpreter: -the command -.BR ocamlrun (1). -If -.B caml.out -is the name of the file produced by the linking phase, the command -.B ocamlrun caml.out -.IR arg1 \ \ arg2 \ ... \ argn -executes the compiled code contained in -.BR caml.out , -passing it as arguments the character strings -.I arg1 -to -.IR argn . -(See -.BR ocamlrun (1) -for more details.) - -On most systems, the file produced by the linking -phase can be run directly, as in: -.B ./caml.out -.IR arg1 \ \ arg2 \ ... \ argn . -The produced file has the executable bit set, and it manages to launch -the bytecode interpreter by itself. - -.B ocamlc.opt -is the same compiler as -.BR ocamlc , -but compiled with the native-code compiler -.BR ocamlopt (1). -Thus, it behaves exactly like -.BR ocamlc , -but compiles faster. -.B ocamlc.opt -may not be available in all installations of OCaml. - -.SH OPTIONS - -The following command-line options are recognized by -.BR ocamlc (1). -.TP -.B \-a -Build a library (.cma file) with the object files (.cmo files) given -on the command line, instead of linking them into an executable -file. The name of the library must be set with the -.B \-o -option. -.IP -If -.BR \-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 -.BR \-custom , \ \-cclib \ and \ \-ccopt -options as if they had been provided on the -command line, unless the -.B \-noautolink -option is given. Additionally, a substring -.B $CAMLORIGIN -inside a -.BR \ \-ccopt -options will be replaced by the full path to the .cma library, -excluding the filename. -.B \-absname -Show absolute filenames in error messages. -.TP -.B \-annot -Deprecated since 4.11. Please use -.BR \-bin-annot -instead. -.TP -.B \-bin\-annot -Dump detailed information about the compilation (types, bindings, -tail-calls, etc) in binary format. The information for file -.IR src .ml -is put into file -.IR src .cmt. -In case of a type error, dump -all the information inferred by the type-checker before the error. -The annotation files produced by -.B \-bin\-annot -contain more information -and are much more compact than the files produced by -.BR \-annot . -.TP -.B \-c -Compile only. Suppress the linking phase of the -compilation. Source code files are turned into compiled files, but no -executable file is produced. This option is useful to -compile modules separately. -.TP -.BI \-cc \ ccomp -Use -.I ccomp -as the C linker when linking in "custom runtime" mode (see the -.B \-custom -option) and as the C compiler for compiling .c source files. -.TP -.BI \-cclib\ -l libname -Pass the -.BI \-l libname -option to the C linker when linking in "custom runtime" mode (see the -.B \-custom -option). This causes the given C library to be linked with the program. -.TP -.BI \-ccopt \ option -Pass the given -.I option -to the C compiler and linker, when linking in -"custom runtime" mode (see the -.B \-custom -option). For instance, -.BI \-ccopt\ \-L dir -causes the C linker to search for C libraries in -directory -.IR dir . -.TP -.BI \-color \ mode -Enable or disable colors in compiler messages (especially warnings and errors). -The following modes are supported: - -.B auto -use heuristics to enable colors only if the output supports them (an -ANSI-compatible tty terminal); - -.B always -enable colors unconditionally; - -.B never -disable color output. - -The environment variable "OCAML_COLOR" is considered if \-color is not -provided. Its values are auto/always/never as above. - -If \-color is not provided, "OCAML_COLOR" is not set and the environment -variable "NO_COLOR" is set, then color output is disabled. Otherwise, -the default setting is -.B auto, -and the current heuristic -checks that the "TERM" environment variable exists and is -not empty or "dumb", and that isatty(stderr) holds. - -.TP -.BI \-error\-style \ mode -Control the way error messages and warnings are printed. -The following modes are supported: - -.B short -only print the error and its location; - -.B contextual -like "short", but also display the source code snippet corresponding -to the location of the error. - -The default setting is -.B contextual. - -The environment variable "OCAML_ERROR_STYLE" is considered if -\-error\-style is not provided. Its values are short/contextual as -above. - -.TP -.B \-compat\-32 -Check that the generated bytecode executable can run on 32-bit -platforms and signal an error if it cannot. This is useful when -compiling bytecode on a 64-bit machine. -.TP -.B \-config -Print the version number of -.BR ocamlc (1) -and a detailed summary of its configuration, then exit. -.TP -.BI \-config-var -Print the value of a specific configuration variable -from the -.B \-config -output, then exit. If the variable does not exist, -the exit code is non-zero. -.TP -.B \-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, -.BR 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 -.BR ocamlrun (1) -command is not -installed. Moreover, the "custom runtime" mode enables linking OCaml -code with user-defined C functions. - -Never use the -.BR strip (1) -command on executables produced by -.BR ocamlc\ \-custom , -this would remove the bytecode part of the executable. - -Security warning: never set the "setuid" or "setgid" bits on -executables produced by -.BR ocamlc\ \-custom , -this would make them vulnerable to attacks. -.TP -.BI \-depend\ ocamldep-args -Compute dependencies, as ocamldep would do. -.TP -.BI \-dllib\ \-l libname -Arrange for the C shared library -.BI dll libname .so -to be loaded dynamically by the run-time system -.BR ocamlrun (1) -at program start-up time. -.TP -.BI \-dllpath \ dir -Adds the directory -.I 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 -.B \-I -option). -The -.B \-dllpath -option simply stores -.I dir -in the produced -executable file, where -.BR ocamlrun (1) -can find it and use it. -.TP -.BI \-for\-pack \ module\-path -Generate an object file (.cmo file) that can later be included -as a sub-module (with the given access path) of a compilation unit -constructed with -.BR \-pack . -For instance, -.B ocamlc\ \-for\-pack\ P\ \-c\ A.ml -will generate a.cmo that can later be used with -.BR "ocamlc -pack -o P.cmo a.cmo" . -Note: you can still pack a module that was compiled without -.B \-for\-pack -but in this case exceptions will be printed with the wrong names. -.TP -.B \-g -Add debugging information while compiling and linking. This option is -required in order to be able to debug the program with -.BR ocamldebug (1) -and to produce stack backtraces when -the program terminates on an uncaught exception. -.TP -.B \-i -Cause the compiler to print all defined names (with their inferred -types or their definitions) when compiling an implementation (.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 interfaces, 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. -.TP -.BI \-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 -.BI \-cclib\ \-l xxx -.RB . -By default, the current directory is searched first, then the -standard library directory. Directories added with -.B \-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. See also -option -.BR \-nostdlib . - -If the given directory starts with -.BR + , -it is taken relative to the -standard library directory. For instance, -.B \-I\ +compiler-libs -adds the subdirectory -.B compiler-libs -of the standard library to the search path. -.TP -.BI \-impl \ filename -Compile the file -.I filename -as an implementation file, even if its extension is not .ml. -.TP -.BI \-intf \ filename -Compile the file -.I filename -as an interface file, even if its extension is not .mli. -.TP -.BI \-intf\-suffix \ string -Recognize file names ending with -.I string -as interface files (instead of the default .mli). -.TP -.B \-keep-docs -Keep documentation strings in generated .cmi files. -.TP -.B \-keep-locs -Keep locations in generated .cmi files. -.TP -.B \-labels -Labels are not ignored in types, labels may be used in applications, -and labelled parameters can be given in any order. This is the default. -.TP -.B \-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 -.BR \-a ), -setting the -.B \-linkall -option forces all subsequent links of programs involving that library -to link all the modules contained in the library. -When compiling a module (option -.BR \-c ), -setting the -.B \-linkall -option ensures that this module will -always be linked if it is put in a library and this library is linked. -.TP -.B \-make\-runtime -Build a custom runtime system (in the file specified by option -.BR \-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 -.B ocamlc\ \-use\-runtime -.IR runtime-name . -.TP -.B \-match\-context\-rows -Set number of rows of context used during pattern matching -compilation. Lower values cause faster compilation, but -less optimized code. The default value is 32. -.TP -.B \-no-alias-deps -Do not record dependencies for module aliases. -.TP -.B \-no\-app\-funct -Deactivates the applicative behaviour of functors. With this option, -each functor application generates new types in its result and -applying the same functor twice to the same argument yields two -incompatible structures. -.TP -.B \-noassert -Do not compile assertion checks. Note that the special form -.B assert\ false -is always compiled because it is typed specially. -This flag has no effect when linking already-compiled files. -.TP -.B \-noautolink -When linking .cma libraries, ignore -.BR \-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 -.B \-noautolink -and pass the correct C libraries and options on the command line. -.TP -.B \-nolabels -Ignore non-optional labels in types. Labels cannot be used in -applications, and parameter order becomes strict. -.TP -.B \-nostdlib -Do not automatically add the standard library directory to the list of -directories searched for compiled interface files (.cmi), compiled -object code files (.cmo), libraries (.cma), and C libraries specified -with -.BI \-cclib\ \-l xxx -.RB . -See also option -.BR \-I . -.TP -.BI \-o \ exec\-file -Specify the name of the output file produced by the linker. The -default output name is -.BR a.out , -in keeping with the Unix tradition. If the -.B \-a -option is given, specify the name of the library -produced. If the -.B \-pack -option is given, specify the name of the -packed object file produced. If the -.B \-output\-obj -or -.B \-output\-complete\-obj -option is given, -specify the name of the output file produced. -This can also be used when compiling an interface or implementation -file, without linking, in which case it sets the name of the cmi or -cmo file, and also sets the module name to the file name up to the -first dot. -.TP -.B \-opaque -Interface file compiled with this option are marked so that other -compilation units depending on it will not rely on any implementation -details of the compiled implementation. The native compiler will not -access the .cmx file of this unit -- nor warn if it is absent. This can -improve speed of compilation, for both initial and incremental builds, -at the expense of performance of the generated code. -.TP -.BI \-open \ module -Opens the given module before processing the interface or -implementation files. If several -.B \-open -options are given, they are processed in order, just as if -the statements open! module1;; ... open! moduleN;; were added -at the top of each file. -.TP -.B \-output\-obj -Cause the linker to produce a C object file instead of a bytecode -executable file. This is useful to wrap OCaml code as a C library, -callable from any C program. The name of the output object file -must be set with the -.B \-o -option. This -option can also be used to produce a C source file (.c extension) or -a compiled shared/dynamic library (.so extension). -.TP -.B \-output\-complete\-obj -Same as -.B \-output\-obj -except when creating an object file where it includes the runtime and -autolink libraries. -.TP -.B \-pack -Build a bytecode object file (.cmo file) and its associated compiled -interface (.cmi) that combines the object -files given on the command line, making them appear as sub-modules of -the output .cmo file. The name of the output .cmo file must be -given with the -.B \-o -option. For instance, -.B 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. -.TP -.BI \-pp \ command -Cause the compiler to call the given -.I command -as a preprocessor for each source file. The output of -.I command -is redirected to -an intermediate file, which is compiled. If there are no compilation -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. -.TP -.BI \-ppx \ command -After parsing, pipe the abstract syntax tree through the preprocessor -.IR command . -The module -.BR Ast_mapper (3) -implements the external interface of a preprocessor. -.TP -.B \-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 programs accepted in -.B \-principal -mode are also accepted in the -default mode with equivalent types, but different binary signatures, -and this may slow down type checking; yet it is a good idea to -use it once before publishing source code. -.TP -.B \-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 dependencies. -.TP -.BI \-runtime\-variant \ suffix -Add -.I suffix -to the name of the runtime library that will be used by the program. -If OCaml was configured with option -.BR \-with\-debug\-runtime , -then the -.B d -suffix is supported and gives a debug version of the runtime. -.TP -.BI \-stop\-after \ pass -Stop compilation after the given compilation pass. The currently -supported passes are: -.BR parsing , -.BR typing . -.TP -.B \-safe\-string -Enforce the separation between types -.BR string \ and\ bytes , -thereby making strings read-only. This is the default. -.TP -.B \-short\-paths -When a type is visible under several module-paths, use the shortest -one when printing the type's name in inferred interfaces and error and -warning messages. -.TP -.B \-strict\-sequence -Force the left-hand part of each sequence to have type unit. -.TP -.B \-unboxed\-types -When a type is unboxable (i.e. a record with a single argument or a -concrete datatype with a single constructor of one argument) it will -be unboxed unless annotated with -.BR [@@ocaml.boxed] . -.TP -.B \-no-unboxed\-types -When a type is unboxable it will be boxed unless annotated with -.BR [@@ocaml.unboxed] . -This is the default. -.TP -.B \-unsafe -Turn bound checking off for array and string accesses (the -.BR v.(i) and s.[i] -constructs). Programs compiled with -.B \-unsafe -are therefore -slightly faster, but unsafe: anything can happen if the program -accesses an array or string outside of its bounds. -.TP -.B \-unsafe\-string -Identify the types -.BR string \ and\ bytes , -thereby making strings writable. -This is intended for compatibility with old source code and should not -be used with new software. -.TP -.BI \-use\-runtime \ runtime\-name -Generate a bytecode executable file that can be executed on the custom -runtime system -.IR runtime\-name , -built earlier with -.B ocamlc\ \-make\-runtime -.IR runtime\-name . -.TP -.B \-v -Print the version number of the compiler and the location of the -standard library directory, then exit. -.TP -.B \-verbose -Print all external commands before they are executed, in particular -invocations of the C compiler and linker in -.B \-custom -mode. Useful to debug C library problems. -.TP -.BR \-vnum \ or\ \-version -Print the version number of the compiler in short form (e.g. "3.11.0"), -then exit. -.TP -.BI \-w \ warning\-list -Enable, disable, or mark as fatal the warnings specified by the argument -.IR warning\-list . - -Each warning can be -.IR enabled \ or\ disabled , -and each warning can be -.IR fatal \ or -.IR non-fatal . -If a warning is disabled, it isn't displayed and doesn't affect -compilation in any way (even if it is fatal). If a warning is enabled, -it is displayed normally by the compiler whenever the source code -triggers it. If it is enabled and fatal, the compiler will also stop -with an error after displaying it. - -The -.I warning\-list -argument is a sequence of warning specifiers, with no separators -between them. A warning specifier is one of the following: - -.BI + num -\ \ Enable warning number -.IR num . - -.BI \- num -\ \ Disable warning number -.IR num . - -.BI @ num -\ \ Enable and mark as fatal warning number -.IR num . - -.BI + num1 .. num2 -\ \ Enable all warnings between -.I num1 -and -.I num2 -(inclusive). - -.BI \- num1 .. num2 -\ \ Disable all warnings between -.I num1 -and -.I num2 -(inclusive). - -.BI @ num1 .. num2 -\ \ Enable and mark as fatal all warnings between -.I num1 -and -.I num2 -(inclusive). - -.BI + letter -\ \ Enable the set of warnings corresponding to -.IR letter . -The letter may be uppercase or lowercase. - -.BI \- letter -\ \ Disable the set of warnings corresponding to -.IR letter . -The letter may be uppercase or lowercase. - -.BI @ letter -\ \ Enable and mark as fatal the set of warnings corresponding to -.IR letter . -The letter may be uppercase or lowercase. - -.I uppercase\-letter -\ \ Enable the set of warnings corresponding to -.IR uppercase\-letter . - -.I lowercase\-letter -\ \ Disable the set of warnings corresponding to -.IR lowercase\-letter . - -The warning numbers are as follows. - -1 -\ \ \ Suspicious-looking start-of-comment mark. - -2 -\ \ \ Suspicious-looking end-of-comment mark. - -3 -\ \ \ Deprecated feature. - -4 -\ \ \ Fragile pattern matching: matching that will remain -complete even if additional constructors are added to one of the -variant types matched. - -5 -\ \ \ Partially applied function: expression whose result has -function type and is ignored. - -6 -\ \ \ Label omitted in function application. - -7 -\ \ \ Method overridden without using the "method!" keyword. - -8 -\ \ \ Partial match: missing cases in pattern-matching. - -9 -\ \ \ Missing fields in a record pattern. - -10 -\ \ Expression on the left-hand side of a sequence that doesn't -have type -.B unit -(and that is not a function, see warning number 5). - -11 -\ \ Redundant case in a pattern matching (unused match case). - -12 -\ \ Redundant sub-pattern in a pattern-matching. - -13 -\ \ Override of an instance variable. - -14 -\ \ Illegal backslash escape in a string constant. - -15 -\ \ Private method made public implicitly. - -16 -\ \ Unerasable optional argument. - -17 -\ \ Undeclared virtual method. - -18 -\ \ Non-principal type. - -19 -\ \ Type without principality. - -20 -\ \ Unused function argument. - -21 -\ \ Non-returning statement. - -22 -\ \ Preprocessor warning. - -23 -\ \ Useless record -.B with -clause. - -24 -\ \ Bad module name: the source file name is not a valid OCaml module name. - -25 -\ \ Deprecated: now part of warning 8. - -26 -\ \ Suspicious unused variable: unused variable that is bound with -.BR let \ or \ as , -and doesn't start with an underscore (_) character. - -27 -\ \ Innocuous unused variable: unused variable that is not bound with -.BR let \ nor \ as , -and doesn't start with an underscore (_) character. - -28 -\ \ A pattern contains a constant constructor applied to the underscore (_) -pattern. - -29 -\ \ A non-escaped end-of-line was found in a string constant. This may -cause portability problems between Unix and Windows. - -30 -\ \ Two labels or constructors of the same name are defined in two -mutually recursive types. - -31 -\ \ A module is linked twice in the same executable. - -32 -\ \ Unused value declaration. - -33 -\ \ Unused open statement. - -34 -\ \ Unused type declaration. - -35 -\ \ Unused for-loop index. - -36 -\ \ Unused ancestor variable. - -37 -\ \ Unused constructor. - -38 -\ \ Unused extension constructor. - -39 -\ \ Unused rec flag. - -40 -\ \ Constructor or label name used out of scope. - -41 -\ \ Ambiguous constructor or label name. - -42 -\ \ Disambiguated constructor or label name. - -43 -\ \ Nonoptional label applied as optional. - -44 -\ \ Open statement shadows an already defined identifier. - -45 -\ \ Open statement shadows an already defined label or constructor. - -46 -\ \ Error in environment variable. - -47 -\ \ Illegal attribute payload. - -48 -\ \ Implicit elimination of optional arguments. - -49 -\ \ Missing cmi file when looking up module alias. - -50 -\ \ Unexpected documentation comment. - -59 -\ \ Assignment on non-mutable value. - -60 -\ \ Unused module declaration. - -61 -\ \ Unannotated unboxable type in primitive declaration. - -62 -\ \ Type constraint on GADT type declaration. - -63 -\ \ Erroneous printed signature. - -64 -\ \ -unsafe used with a preprocessor returning a syntax tree. - -65 -\ \ Type declaration defining a new '()' constructor. - -66 -\ \ Unused open! statement. - -67 -\ \ Unused functor parameter. - -68 -\ \ Pattern-matching depending on mutable state prevents the remaining -arguments from being uncurried. - -The letters stand for the following sets of warnings. Any letter not -mentioned here corresponds to the empty set. - -.B A -\ all warnings - -.B C -\ 1, 2 - -.B D -\ 3 - -.B E -\ 4 - -.B F -\ 5 - -.B K -\ 32, 33, 34, 35, 36, 37, 38, 39 - -.B L -\ 6 - -.B M -\ 7 - -.B P -\ 8 - -.B R -\ 9 - -.B S -\ 10 - -.B U -\ 11, 12 - -.B V -\ 13 - -.B X -\ 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 30 - -.B Y -\ 26 - -.B Z -\ 27 - -.IP -The default setting is -.BR \-w\ +a\-4\-7\-9\-27\-29\-30\-32..42\-44\-45\-48\-50\-60\-66..70 . -Note that warnings -.BR 5 \ and \ 10 -are not always triggered, depending on the internals of the type checker. -.TP -.BI \-warn\-error \ warning\-list -Mark as errors the warnings specified in the argument -.IR warning\-list . -The compiler will stop with an error when one of these -warnings is emitted. The -.I warning\-list -has the same meaning as for -the -.B \-w -option: a -.B + -sign (or an uppercase letter) marks the corresponding warnings as fatal, a -.B \- -sign (or a lowercase letter) turns them back into non-fatal warnings, and a -.B @ -sign both enables and marks as fatal the corresponding warnings. - -Note: it is not recommended to use the -.B \-warn\-error -option in production code, because it will almost certainly prevent -compiling your program with later versions of OCaml when they add new -warnings or modify existing warnings. - -The default setting is -.B \-warn\-error \-a+31 -(only warning 31 is fatal). -.TP -.B \-warn\-help -Show the description of all available warning numbers. -.TP -.B \-where -Print the location of the standard library, then exit. -.TP -.B \-with-runtime -Include the runtime system in the generated program. This is the default. -.TP -.B \-without-runtime -The compiler does not include the runtime system (nor a reference to it) in the -generated program; it must be supplied separately. -.TP -.BI \- \ file -Process -.I file -as a file name, even if it starts with a dash (-) character. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH SEE ALSO -.BR ocamlopt (1), \ ocamlrun (1), \ ocaml (1). -.br -.IR "The OCaml user's manual" , -chapter "Batch compilation". diff --git a/man/ocamlc.opt.1 b/man/ocamlc.opt.1 new file mode 100644 index 0000000000..3d957b581d --- /dev/null +++ b/man/ocamlc.opt.1 @@ -0,0 +1 @@ +.so man1/ocamlc.1 diff --git a/man/ocamlcp.1 b/man/ocamlcp.1 new file mode 100644 index 0000000000..d6c983d167 --- /dev/null +++ b/man/ocamlcp.1 @@ -0,0 +1,142 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH "OCAMLCP" 1 + +.SH NAME +ocamlcp, ocamloptp \- The OCaml profiling compilers + +.SH SYNOPSIS +.B ocamlcp +[ +.I ocamlc options +] +[ +.BI \-P \ flags +] +.I filename ... + +.B ocamloptp +[ +.I ocamlopt options +] +[ +.BI \-P \ flags +] +.I filename ... + +.SH DESCRIPTION +The +.B ocamlcp +and +.B ocamloptp +commands are front-ends to +.BR ocamlc (1) +and +.BR ocamlopt (1) +that instrument the source code, adding code to record how many times +functions are called, branches of conditionals are taken, etc. +Execution of instrumented code produces an execution profile in the +file ocamlprof.dump, which can be read using +.BR ocamlprof (1). + +.B ocamlcp +accepts the same arguments and options as +.BR ocamlc (1) +and +.B ocamloptp +accepts the same arguments and options as +.BR ocamlopt (1). +There is only one exception: in both cases, the +.B \-pp +option is not supported. If you need to preprocess your source files, +you will have to do it separately before calling +.B ocamlcp +or +.BR ocamloptp . + +.SH OPTIONS + +In addition to the +.BR ocamlc (1) +or +.BR ocamlopt (1) +options, +.B ocamlcp +and +.B ocamloptp +accept one option to control the kind of profiling information, the +.BI \-P \ letters +option. The +.I letters +indicate which parts of the program should be profiled: +.TP +.B a +all options +.TP +.B f +function calls : a count point is set at the beginning of each function body +.TP +.B i +.BR if \ ... \ then \ ... \ else : +count points are set in both +.BR then \ and \ else +branches +.TP +.B l +.BR while , \ for +loops: a count point is set at the beginning of the loop body +.TP +.B m +.B match +branches: a count point is set at the beginning of the +body of each branch of a pattern-matching +.TP +.B t +.BR try \ ... \ with +branches: a count point is set at the beginning of the body of each +branch of an exception catcher + +.PP +For instance, compiling with +.B ocamlcp \-P film +profiles function calls, +.BR if \ ... \ then \ ... \ else \ ..., +loops, and pattern matching. + +Calling +.BR ocamlcp (1) +or +.BR ocamloptp (1) +without the +.B \-P +option defaults to +.BR \-P\ fm , +meaning that only function calls and pattern matching are profiled. + +Note: for compatibility with previous versions, +.BR ocamlcp (1) +also accepts the option +.B \-p +with the same argument and meaning as +.BR \-P . + +.SH SEE ALSO +.BR ocamlc (1), +.BR ocamlopt (1), +.BR ocamlprof (1). +.br +.IR "The OCaml user's manual" , +chapter "Profiling". diff --git a/man/ocamlcp.m b/man/ocamlcp.m deleted file mode 100644 index d6c983d167..0000000000 --- a/man/ocamlcp.m +++ /dev/null @@ -1,142 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH "OCAMLCP" 1 - -.SH NAME -ocamlcp, ocamloptp \- The OCaml profiling compilers - -.SH SYNOPSIS -.B ocamlcp -[ -.I ocamlc options -] -[ -.BI \-P \ flags -] -.I filename ... - -.B ocamloptp -[ -.I ocamlopt options -] -[ -.BI \-P \ flags -] -.I filename ... - -.SH DESCRIPTION -The -.B ocamlcp -and -.B ocamloptp -commands are front-ends to -.BR ocamlc (1) -and -.BR ocamlopt (1) -that instrument the source code, adding code to record how many times -functions are called, branches of conditionals are taken, etc. -Execution of instrumented code produces an execution profile in the -file ocamlprof.dump, which can be read using -.BR ocamlprof (1). - -.B ocamlcp -accepts the same arguments and options as -.BR ocamlc (1) -and -.B ocamloptp -accepts the same arguments and options as -.BR ocamlopt (1). -There is only one exception: in both cases, the -.B \-pp -option is not supported. If you need to preprocess your source files, -you will have to do it separately before calling -.B ocamlcp -or -.BR ocamloptp . - -.SH OPTIONS - -In addition to the -.BR ocamlc (1) -or -.BR ocamlopt (1) -options, -.B ocamlcp -and -.B ocamloptp -accept one option to control the kind of profiling information, the -.BI \-P \ letters -option. The -.I letters -indicate which parts of the program should be profiled: -.TP -.B a -all options -.TP -.B f -function calls : a count point is set at the beginning of each function body -.TP -.B i -.BR if \ ... \ then \ ... \ else : -count points are set in both -.BR then \ and \ else -branches -.TP -.B l -.BR while , \ for -loops: a count point is set at the beginning of the loop body -.TP -.B m -.B match -branches: a count point is set at the beginning of the -body of each branch of a pattern-matching -.TP -.B t -.BR try \ ... \ with -branches: a count point is set at the beginning of the body of each -branch of an exception catcher - -.PP -For instance, compiling with -.B ocamlcp \-P film -profiles function calls, -.BR if \ ... \ then \ ... \ else \ ..., -loops, and pattern matching. - -Calling -.BR ocamlcp (1) -or -.BR ocamloptp (1) -without the -.B \-P -option defaults to -.BR \-P\ fm , -meaning that only function calls and pattern matching are profiled. - -Note: for compatibility with previous versions, -.BR ocamlcp (1) -also accepts the option -.B \-p -with the same argument and meaning as -.BR \-P . - -.SH SEE ALSO -.BR ocamlc (1), -.BR ocamlopt (1), -.BR ocamlprof (1). -.br -.IR "The OCaml user's manual" , -chapter "Profiling". diff --git a/man/ocamldebug.1 b/man/ocamldebug.1 new file mode 100644 index 0000000000..f03ad60f39 --- /dev/null +++ b/man/ocamldebug.1 @@ -0,0 +1,124 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 2001 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLDEBUG 1 + +.SH NAME +ocamldebug \- the OCaml source-level replay debugger. +.SH SYNOPSIS +.B ocamldebug +.RI [\ options \ ]\ program \ [\ arguments \ ] +.SH DESCRIPTION +.B ocamldebug +is the OCaml source-level replay debugger. + +Before the debugger can be used, the program must be compiled and +linked with the +.B \-g +option: all .cmo and .cma files that are part +of the program should have been created with +.BR ocamlc\ \-g , +and they must be linked together with +.BR ocamlc\ \-g . + +Compiling with +.B \-g +entails no penalty on the running time of +programs: object files and bytecode executable files are bigger and +take longer to produce, but the executable files run at +exactly the same speed as if they had been compiled without +.BR \-g . + +.SH OPTIONS +A summary of options are included below. +For a complete description, see the html documentation in the ocaml-doc +package. +.TP +.BI \-c \ count +Set the maximum number of simultaneously live checkpoints to +.IR count . +.TP +.BI \-cd \ dir +Run the debugger program from the working directory +.IR dir , +instead of the current working directory. (See also the +.B cd +command.) +.TP +.B \-emacs +Tell the debugger it is executed under Emacs. (See +.I "The OCaml user's manual" +for information on how to run the debugger under Emacs.) +Implies +.BR \-machine-readable . +.TP +.BI \-I \ directory +Add +.I directory +to the list of directories searched for source files and +compiled files. (See also the +.B directory +command.) +.TP +.BI -machine-readable +Print information in a format more suitable for machines instead of human +operators where applicable. For example, when describing a location in a +program, such as when printing a backtrace, print the program counter and +character offset in a file instead of the filename, line number, and character +offset in that line. +.TP +.BI \-s \ socket +Use +.I socket +for communicating with the debugged program. See the description +of the command +.B set\ socket +in +.I "The OCaml user's manual" +for the format of +.IR socket . +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH INITIALIZATION FILE + +When +.BR ocamldebug (1) +is invoked, it will read commands from an initialization file before +giving control to the user. The default file is +.B .ocamldebug +in the current directory if it exists, otherwise +.B .ocamldebug +in the user's home directory. + +Note that you can also use the +.B source file +command to read commands from a file. + +.SH SEE ALSO +.BR ocamlc (1) +.br +.IR "The OCaml user's manual" , +chapter "The debugger". +.SH AUTHOR +This manual page was written by Sven LUTHER , +for the Debian GNU/Linux system (but may be used by others). diff --git a/man/ocamldebug.m b/man/ocamldebug.m deleted file mode 100644 index f03ad60f39..0000000000 --- a/man/ocamldebug.m +++ /dev/null @@ -1,124 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 2001 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLDEBUG 1 - -.SH NAME -ocamldebug \- the OCaml source-level replay debugger. -.SH SYNOPSIS -.B ocamldebug -.RI [\ options \ ]\ program \ [\ arguments \ ] -.SH DESCRIPTION -.B ocamldebug -is the OCaml source-level replay debugger. - -Before the debugger can be used, the program must be compiled and -linked with the -.B \-g -option: all .cmo and .cma files that are part -of the program should have been created with -.BR ocamlc\ \-g , -and they must be linked together with -.BR ocamlc\ \-g . - -Compiling with -.B \-g -entails no penalty on the running time of -programs: object files and bytecode executable files are bigger and -take longer to produce, but the executable files run at -exactly the same speed as if they had been compiled without -.BR \-g . - -.SH OPTIONS -A summary of options are included below. -For a complete description, see the html documentation in the ocaml-doc -package. -.TP -.BI \-c \ count -Set the maximum number of simultaneously live checkpoints to -.IR count . -.TP -.BI \-cd \ dir -Run the debugger program from the working directory -.IR dir , -instead of the current working directory. (See also the -.B cd -command.) -.TP -.B \-emacs -Tell the debugger it is executed under Emacs. (See -.I "The OCaml user's manual" -for information on how to run the debugger under Emacs.) -Implies -.BR \-machine-readable . -.TP -.BI \-I \ directory -Add -.I directory -to the list of directories searched for source files and -compiled files. (See also the -.B directory -command.) -.TP -.BI -machine-readable -Print information in a format more suitable for machines instead of human -operators where applicable. For example, when describing a location in a -program, such as when printing a backtrace, print the program counter and -character offset in a file instead of the filename, line number, and character -offset in that line. -.TP -.BI \-s \ socket -Use -.I socket -for communicating with the debugged program. See the description -of the command -.B set\ socket -in -.I "The OCaml user's manual" -for the format of -.IR socket . -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH INITIALIZATION FILE - -When -.BR ocamldebug (1) -is invoked, it will read commands from an initialization file before -giving control to the user. The default file is -.B .ocamldebug -in the current directory if it exists, otherwise -.B .ocamldebug -in the user's home directory. - -Note that you can also use the -.B source file -command to read commands from a file. - -.SH SEE ALSO -.BR ocamlc (1) -.br -.IR "The OCaml user's manual" , -chapter "The debugger". -.SH AUTHOR -This manual page was written by Sven LUTHER , -for the Debian GNU/Linux system (but may be used by others). diff --git a/man/ocamldep.1 b/man/ocamldep.1 new file mode 100644 index 0000000000..1c39e9d52a --- /dev/null +++ b/man/ocamldep.1 @@ -0,0 +1,196 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLDEP 1 + +.SH NAME +ocamldep \- Dependency generator for OCaml + +.SH SYNOPSIS +.B ocamldep +[ +.I options +] +.I filename ... + +.SH DESCRIPTION + +The +.BR ocamldep (1) +command scans a set of OCaml source files +(.ml and .mli files) for references to external compilation units, +and outputs dependency lines in a format suitable for the +.BR make (1) +utility. This ensures that make will compile the source files in the +correct order, and recompile those files that need to when a source +file is modified. + +The typical usage is: +.P +ocamldep +.I options +*.mli *.ml > .depend +.P +where .depend is the file that should contain the +dependencies. + +Dependencies are generated both for compiling with the bytecode +compiler +.BR ocamlc (1) +and with the native-code compiler +.BR ocamlopt (1). + +.SH OPTIONS + +The following command-line options are recognized by +.BR ocamldep (1). +.TP +.B \-absname +Show absolute filenames in error messages. +.TP +.B \-all +Generate dependencies on all required files, rather than assuming +implicit dependencies. +.TP +.B \-allow\-approx +Allow falling back on a lexer-based approximation when parsing fails. +.TP +.B \-as\-map +For the following files, do not include delayed dependencies for +module aliases. +This option assumes that they are compiled using options +"\-no\-alias\-deps \-w \-49", and that those files or their interface are +passed with the "\-map" option when computing dependencies for other +files. Note also that for dependencies to be correct in the +implementation of a map file, its interface should not coerce any of +the aliases it contains. +.TP +.B \-debug\-map +Dump the delayed dependency map for each map file. +.TP +.BI \-I \ directory +Add the given directory to the list of directories searched for +source files. If a source file foo.ml mentions an external +compilation unit Bar, a dependency on that unit's interface +bar.cmi is generated only if the source for bar is found in the +current directory or in one of the directories specified with +.BR \-I . +Otherwise, Bar is assumed to be a module from the standard library, +and no dependencies are generated. For programs that span multiple +directories, it is recommended to pass +.BR ocamldep (1) +the same +.B \-I +options that are passed to the compiler. +.TP +.B \-nocwd +Do not add current working directory to the list of include directories. +.TP +.BI \-impl \ file +Process +.IR file +as a .ml file. +.TP +.BI \-intf \ file +Process +.IR file +as a .mli file. +.TP +.BI \-map \ file +Read an propagate the delayed dependencies for module aliases in +.IR file , +so that the following files will depend on the +exported aliased modules if they use them. +.TP +.BI \-ml\-synonym \ .ext +Consider the given extension (with leading dot) to be a synonym for .ml. +.TP +.BI \-mli\-synonym \ .ext +Consider the given extension (with leading dot) to be a synonym for .mli. +.TP +.B \-modules +Output raw dependencies of the form +.IR filename : \ Module1\ Module2 \ ... \ ModuleN +where +.IR Module1 ,\ ..., \ ModuleN +are the names of the compilation +units referenced within the file +.IR filename , +but these names are not +resolved to source file names. Such raw dependencies cannot be used +by +.BR make (1), +but can be post-processed by other tools such as +.BR Omake (1). +.TP +.BI \-native +Generate dependencies for a pure native-code program (no bytecode +version). When an implementation file (.ml file) has no explicit +interface file (.mli file), +.BR ocamldep (1) +generates dependencies on the +bytecode compiled file (.cmo file) to reflect interface changes. +This can cause unnecessary bytecode recompilations for programs that +are compiled to native-code only. The flag +.B \-native +causes dependencies on native compiled files (.cmx) to be generated instead +of on .cmo files. (This flag makes no difference if all source files +have explicit .mli interface files.) +.TP +.B \-one-line +Output one line per file, regardless of the length. +.TP +.BI \-open \ module +Assume that module +.IR module +is opened before parsing each of the +following files. +.TP +.BI \-pp \ command +Cause +.BR ocamldep (1) +to call the given +.I command +as a preprocessor for each source file. +.TP +.BI \-ppx \ command +Pipe abstract syntax tree through preprocessor +.IR command . +.TP +.B \-shared +Generate dependencies for native plugin files (.cmxs) in addition to +native compiled files (.cmx). +.TP +.B \-slash +Under Unix, this option does nothing. +.TP +.B \-sort +Sort files according to their dependencies. +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH SEE ALSO +.BR ocamlc (1), +.BR ocamlopt (1). +.br +.IR The\ OCaml\ user's\ manual , +chapter "Dependency generator". diff --git a/man/ocamldep.m b/man/ocamldep.m deleted file mode 100644 index 1c39e9d52a..0000000000 --- a/man/ocamldep.m +++ /dev/null @@ -1,196 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLDEP 1 - -.SH NAME -ocamldep \- Dependency generator for OCaml - -.SH SYNOPSIS -.B ocamldep -[ -.I options -] -.I filename ... - -.SH DESCRIPTION - -The -.BR ocamldep (1) -command scans a set of OCaml source files -(.ml and .mli files) for references to external compilation units, -and outputs dependency lines in a format suitable for the -.BR make (1) -utility. This ensures that make will compile the source files in the -correct order, and recompile those files that need to when a source -file is modified. - -The typical usage is: -.P -ocamldep -.I options -*.mli *.ml > .depend -.P -where .depend is the file that should contain the -dependencies. - -Dependencies are generated both for compiling with the bytecode -compiler -.BR ocamlc (1) -and with the native-code compiler -.BR ocamlopt (1). - -.SH OPTIONS - -The following command-line options are recognized by -.BR ocamldep (1). -.TP -.B \-absname -Show absolute filenames in error messages. -.TP -.B \-all -Generate dependencies on all required files, rather than assuming -implicit dependencies. -.TP -.B \-allow\-approx -Allow falling back on a lexer-based approximation when parsing fails. -.TP -.B \-as\-map -For the following files, do not include delayed dependencies for -module aliases. -This option assumes that they are compiled using options -"\-no\-alias\-deps \-w \-49", and that those files or their interface are -passed with the "\-map" option when computing dependencies for other -files. Note also that for dependencies to be correct in the -implementation of a map file, its interface should not coerce any of -the aliases it contains. -.TP -.B \-debug\-map -Dump the delayed dependency map for each map file. -.TP -.BI \-I \ directory -Add the given directory to the list of directories searched for -source files. If a source file foo.ml mentions an external -compilation unit Bar, a dependency on that unit's interface -bar.cmi is generated only if the source for bar is found in the -current directory or in one of the directories specified with -.BR \-I . -Otherwise, Bar is assumed to be a module from the standard library, -and no dependencies are generated. For programs that span multiple -directories, it is recommended to pass -.BR ocamldep (1) -the same -.B \-I -options that are passed to the compiler. -.TP -.B \-nocwd -Do not add current working directory to the list of include directories. -.TP -.BI \-impl \ file -Process -.IR file -as a .ml file. -.TP -.BI \-intf \ file -Process -.IR file -as a .mli file. -.TP -.BI \-map \ file -Read an propagate the delayed dependencies for module aliases in -.IR file , -so that the following files will depend on the -exported aliased modules if they use them. -.TP -.BI \-ml\-synonym \ .ext -Consider the given extension (with leading dot) to be a synonym for .ml. -.TP -.BI \-mli\-synonym \ .ext -Consider the given extension (with leading dot) to be a synonym for .mli. -.TP -.B \-modules -Output raw dependencies of the form -.IR filename : \ Module1\ Module2 \ ... \ ModuleN -where -.IR Module1 ,\ ..., \ ModuleN -are the names of the compilation -units referenced within the file -.IR filename , -but these names are not -resolved to source file names. Such raw dependencies cannot be used -by -.BR make (1), -but can be post-processed by other tools such as -.BR Omake (1). -.TP -.BI \-native -Generate dependencies for a pure native-code program (no bytecode -version). When an implementation file (.ml file) has no explicit -interface file (.mli file), -.BR ocamldep (1) -generates dependencies on the -bytecode compiled file (.cmo file) to reflect interface changes. -This can cause unnecessary bytecode recompilations for programs that -are compiled to native-code only. The flag -.B \-native -causes dependencies on native compiled files (.cmx) to be generated instead -of on .cmo files. (This flag makes no difference if all source files -have explicit .mli interface files.) -.TP -.B \-one-line -Output one line per file, regardless of the length. -.TP -.BI \-open \ module -Assume that module -.IR module -is opened before parsing each of the -following files. -.TP -.BI \-pp \ command -Cause -.BR ocamldep (1) -to call the given -.I command -as a preprocessor for each source file. -.TP -.BI \-ppx \ command -Pipe abstract syntax tree through preprocessor -.IR command . -.TP -.B \-shared -Generate dependencies for native plugin files (.cmxs) in addition to -native compiled files (.cmx). -.TP -.B \-slash -Under Unix, this option does nothing. -.TP -.B \-sort -Sort files according to their dependencies. -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH SEE ALSO -.BR ocamlc (1), -.BR ocamlopt (1). -.br -.IR The\ OCaml\ user's\ manual , -chapter "Dependency generator". diff --git a/man/ocamldoc.1 b/man/ocamldoc.1 new file mode 100644 index 0000000000..ffdee529a8 --- /dev/null +++ b/man/ocamldoc.1 @@ -0,0 +1,477 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Maxence Guesdon, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 2004 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLDOC 1 + +\" .de Sh \" Subsection heading +\" .br +\" .if t .Sp +\" .ne 5 +\" .PP +\" \fB\\$1\fR +\" .PP +\" .. + +.SH NAME +ocamldoc \- The OCaml documentation generator + + +.SH SYNOPSIS +.B ocamldoc +[ +.I options +] +.IR filename \ ... + +.SH DESCRIPTION + +The OCaml documentation generator +.BR ocamldoc (1) +generates documentation from special comments embedded in source files. The +comments used by +.B ocamldoc +are of the form +.I (** ... *) +and follow the format described in the +.IR "The OCaml user's manual" . + +.B ocamldoc +can produce documentation in various formats: HTML, LaTeX, TeXinfo, +Unix man pages, and +.BR dot (1) +dependency graphs. Moreover, users can add their own +custom generators. + +In this manpage, we use the word +.I element +to refer to any of the following parts of an OCaml source file: a type +declaration, a value, a module, an exception, a module type, a type +constructor, a record field, a class, a class type, a class method, a class +value or a class inheritance clause. + +.SH OPTIONS + +The following command-line options determine the format for the generated +documentation generated by +.BR ocamldoc (1). +.SS "Options for choosing the output format" +.TP +.B \-html +Generate documentation in HTML default format. The generated HTML pages are +stored in the current directory, or in the directory specified with the +.B \-d +option. You can customize the style of the generated pages by editing the +generated +.I style.css +file, or by providing your own style sheet using option +.BR \-css\-style . +The file +.I style.css +is not generated if it already exists. +.TP +.B \-latex +Generate documentation in LaTeX default format. The generated LaTeX document +is saved in file +.IR ocamldoc.out , +or in the file specified with the +.B -o +option. The document uses the style file +.IR ocamldoc.sty . +This file is generated when using the +.B \-latex +option, if it does not already exist. You can change this file to customize +the style of your LaTeX documentation. +.TP +.B \-texi +Generate documentation in TeXinfo default format. The generated LaTeX document +is saved in file +.IR ocamldoc.out , +or in the file specified with the +.B -o +option. +.TP +.B \-man +Generate documentation as a set of Unix man pages. The generated pages are +stored in the current directory, or in the directory specified with the +.B \-d +option. +.TP +.B \-dot +Generate a dependency graph for the toplevel modules, in a format suitable for +displaying and processing by +.IR dot (1). +The +.IR dot (1) +tool is available from +.IR https://graphviz.org/ . +The textual representation of the graph is written to the file +.IR ocamldoc.out , +or to the file specified with the +.B -o +option. Use +.BI dot \ ocamldoc.out +to display it. +.TP +.BI \-g \ file +Dynamically load the given file (which extension usually is .cmo or .cma), +which defines a custom documentation generator. +If the given file is a simple one and does not exist in +the current directory, then +.B ocamldoc +looks for it in the custom +generators default directory, and in the directories specified with the +.B \-i +option. +.TP +.BI \-customdir +Display the custom generators default directory. +.TP +.BI \-i \ directory +Add the given directory to the path where to look for custom generators. +.SS "General options" +.TP +.BI \-d \ dir +Generate files in directory +.IR dir , +rather than the current directory. +.TP +.BI \-dump \ file +Dump collected information into +.IR file . +This information can be read with the +.B \-load +option in a subsequent invocation of +.BR ocamldoc (1). +.TP +.BI \-hide \ modules +Hide the given complete module names in the generated documentation. +.I modules +is a list of complete module names are separated by commas (,), +without blanks. For instance: +.IR Stdlib,M2.M3 . +.TP +.B \-inv\-merge\-ml\-mli +Reverse the precedence of implementations and interfaces when merging. +All elements in implementation files are kept, and the +.B \-m +option indicates which parts of the comments in interface files are merged with +the comments in implementation files. +.TP +.B \-keep\-code +Always keep the source code for values, methods and instance variables, when +available. The source code is always kept when a .ml +file is given, but is by default discarded when a .mli +is given. This option allows the source code to be always kept. +.TP +.BI \-load \ file +Load information from +.IR file , +which has been produced by +.BR ocamldoc\ \-dump . +Several +.B -load +options can be given. +.TP +.BI \-m \ flags +Specify merge options between interfaces and implementations. +.I flags +can be one or several of the following characters: + +.B d +merge description + +.B a +merge @author + +.B v +merge @version + +.B l +merge @see + +.B s +merge @since + +.B o +merge @deprecated + +.B p +merge @param + +.B e +merge @raise + +.B r +merge @return + +.B A +merge everything +.TP +.B \-no\-custom\-tags +Do not allow custom @-tags. +.TP +.B \-no\-stop +Keep elements placed after the +.B (**/**) +special comment. +.TP +.BI \-o \ file +Output the generated documentation to +.I file +instead of +.IR ocamldoc.out . +This option is meaningful only in conjunction with the +.BR \-latex , \ \-texi ,\ or \ \-dot +options. +.TP +.BI \-open \ module +Opens +.I module +before typing. +.TP +.BI \-pp \ command +Pipe sources through preprocessor +.IR command . +.TP +.BI \-ppx \ command +Pipe abstract syntax tree through preprocessor +.IR command . +.TP +.BR \-show\-missed\-crossref +Show missed cross-reference opportunities. +.TP +.B \-sort +Sort the list of top-level modules before generating the documentation. +.TP +.B \-stars +Remove blank characters until the first asterisk ('*') in each line of comments. +.TP +.BI \-t \ title +Use +.I title +as the title for the generated documentation. +.TP +.BI \-text \ file +Consider \fIfile\fR as a .txt file. +.TP +.BI \-intro \ file +Use content of +.I file +as +.B ocamldoc +text to use as introduction (HTML, LaTeX and TeXinfo only). +For HTML, the file is used to create the whole "index.html" file. +.TP +.B \-v +Verbose mode. Display progress information. +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.B \-warn\-error +Treat +.B ocamldoc +warnings as errors. +.TP +.B \-hide\-warnings +Do not print +.B ocamldoc +warnings. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. +.SS "Type-checking options" +.BR ocamldoc (1) +calls the OCaml type-checker to obtain type information. The +following options impact the type-checking phase. They have the same meaning +as for the +.BR ocamlc (1)\ and \ ocamlopt (1) +commands. +.TP +.BI \-I \ directory +Add +.I directory +to the list of directories search for compiled interface files (.cmi files). +.TP +.B \-nolabels +Ignore non-optional labels in types. +.TP +.B \-rectypes + Allow arbitrary recursive types. (See the +.B \-rectypes +option to +.BR ocamlc (1).) +.SS "Options for generating HTML pages" +The following options apply in conjunction with the +.B \-html +option: +.TP +.B \-all\-params +Display the complete list of parameters for functions and methods. +.TP +.BI \-charset \ s +Add information about character encoding being \fIs\fR +(default is \fBiso-8859-1\fR). +.TP +.BI \-css\-style \ filename +Use +.I filename +as the Cascading Style Sheet file. +.TP +.B \-colorize\-code +Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize +keywords, etc. If the code fragments are not syntactically correct, no color +is added. +.TP +.B \-index\-only +Generate only index files. +.TP +.B \-short\-functors +Use a short form to display functors: +.B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end" +is displayed as +.BR "module M (A:Module) (B:Module2) : sig .. end" . +.SS "Options for generating LaTeX files" +The following options apply in conjunction with the +.B \-latex +option: +.TP +.B \-latex\-value\-prefix prefix +Give a prefix to use for the labels of the values in the generated LaTeX +document. The default prefix is the empty string. You can also use the options +.BR -latex-type-prefix , +.BR -latex-exception-prefix , +.BR -latex-module-prefix , +.BR -latex-module-type-prefix , +.BR -latex-class-prefix , +.BR -latex-class-type-prefix , +.BR -latex-attribute-prefix ,\ and +.BR -latex-method-prefix . + +These options are useful when you have, for example, a type and a value +with the same name. If you do not specify prefixes, LaTeX will complain about +multiply defined labels. +.TP +.BI \-latextitle \ n,style +Associate style number +.I n +to the given LaTeX sectioning command +.IR style , +e.g. +.BR section or subsection . +(LaTeX only.) This is useful when including the generated document in another +LaTeX document, at a given sectioning level. The default association is 1 for +section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for +subparagraph. +.TP +.B \-noheader +Suppress header in generated documentation. +.TP +.B \-notoc +Do not generate a table of contents. +.TP +.B \-notrailer +Suppress trailer in generated documentation. +.TP +.B \-sepfiles +Generate one .tex file per toplevel module, instead of the global +.I ocamldoc.out +file. +.SS "Options for generating TeXinfo files" +The following options apply in conjunction with the +.B -texi +option: +.TP +.B \-esc8 +Escape accented characters in Info files. +.TP +.B +\-info\-entry +Specify Info directory entry. +.TP +.B \-info\-section +Specify section of Info directory. +.TP +.B \-noheader +Suppress header in generated documentation. +.TP +.B \-noindex +Do not build index for Info files. +.TP +.B \-notrailer +Suppress trailer in generated documentation. +.SS "Options for generating dot graphs" +The following options apply in conjunction with the +.B \-dot +option: +.TP +.BI \-dot\-colors \ colors +Specify the colors to use in the generated dot code. When generating module +dependencies, +.BR ocamldoc (1) +uses different colors for modules, depending on the directories in which they +reside. When generating types dependencies, +.BR ocamldoc (1) +uses different colors for types, depending on the modules in which they are +defined. +.I colors +is a list of color names separated by commas (,), as in +.BR Red,Blue,Green . +The available colors are the ones supported by the +.BR dot (1) +tool. +.TP +.B \-dot\-include\-all +Include all modules in the +.BR dot (1) +output, not only modules given on the command line or loaded with the +.B \-load +option. +.TP +.B \-dot\-reduce +Perform a transitive reduction of the dependency graph before outputting the +dot code. This can be useful if there are a lot of transitive dependencies +that clutter the graph. +.TP +.B \-dot\-types +Output dot code describing the type dependency graph instead of the module +dependency graph. +.SS "Options for generating man files" +The following options apply in conjunction with the +.B \-man +option: +.TP +.B \-man\-mini +Generate man pages only for modules, module types, classes and class types, +instead of pages for all elements. +.TP +.BI \-man\-suffix \ suffix +Set the suffix used for generated man filenames. Default is o, as in +.IR List.o . +.TP +.BI \-man\-section \ section +Set the section number used for generated man filenames. Default is 3. + + +.SH SEE ALSO +.BR ocaml (1), +.BR ocamlc (1), +.BR ocamlopt (1). +.br +.IR "The OCaml user's manual", +chapter "The documentation generator". diff --git a/man/ocamldoc.m b/man/ocamldoc.m deleted file mode 100644 index ffdee529a8..0000000000 --- a/man/ocamldoc.m +++ /dev/null @@ -1,477 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Maxence Guesdon, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 2004 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLDOC 1 - -\" .de Sh \" Subsection heading -\" .br -\" .if t .Sp -\" .ne 5 -\" .PP -\" \fB\\$1\fR -\" .PP -\" .. - -.SH NAME -ocamldoc \- The OCaml documentation generator - - -.SH SYNOPSIS -.B ocamldoc -[ -.I options -] -.IR filename \ ... - -.SH DESCRIPTION - -The OCaml documentation generator -.BR ocamldoc (1) -generates documentation from special comments embedded in source files. The -comments used by -.B ocamldoc -are of the form -.I (** ... *) -and follow the format described in the -.IR "The OCaml user's manual" . - -.B ocamldoc -can produce documentation in various formats: HTML, LaTeX, TeXinfo, -Unix man pages, and -.BR dot (1) -dependency graphs. Moreover, users can add their own -custom generators. - -In this manpage, we use the word -.I element -to refer to any of the following parts of an OCaml source file: a type -declaration, a value, a module, an exception, a module type, a type -constructor, a record field, a class, a class type, a class method, a class -value or a class inheritance clause. - -.SH OPTIONS - -The following command-line options determine the format for the generated -documentation generated by -.BR ocamldoc (1). -.SS "Options for choosing the output format" -.TP -.B \-html -Generate documentation in HTML default format. The generated HTML pages are -stored in the current directory, or in the directory specified with the -.B \-d -option. You can customize the style of the generated pages by editing the -generated -.I style.css -file, or by providing your own style sheet using option -.BR \-css\-style . -The file -.I style.css -is not generated if it already exists. -.TP -.B \-latex -Generate documentation in LaTeX default format. The generated LaTeX document -is saved in file -.IR ocamldoc.out , -or in the file specified with the -.B -o -option. The document uses the style file -.IR ocamldoc.sty . -This file is generated when using the -.B \-latex -option, if it does not already exist. You can change this file to customize -the style of your LaTeX documentation. -.TP -.B \-texi -Generate documentation in TeXinfo default format. The generated LaTeX document -is saved in file -.IR ocamldoc.out , -or in the file specified with the -.B -o -option. -.TP -.B \-man -Generate documentation as a set of Unix man pages. The generated pages are -stored in the current directory, or in the directory specified with the -.B \-d -option. -.TP -.B \-dot -Generate a dependency graph for the toplevel modules, in a format suitable for -displaying and processing by -.IR dot (1). -The -.IR dot (1) -tool is available from -.IR https://graphviz.org/ . -The textual representation of the graph is written to the file -.IR ocamldoc.out , -or to the file specified with the -.B -o -option. Use -.BI dot \ ocamldoc.out -to display it. -.TP -.BI \-g \ file -Dynamically load the given file (which extension usually is .cmo or .cma), -which defines a custom documentation generator. -If the given file is a simple one and does not exist in -the current directory, then -.B ocamldoc -looks for it in the custom -generators default directory, and in the directories specified with the -.B \-i -option. -.TP -.BI \-customdir -Display the custom generators default directory. -.TP -.BI \-i \ directory -Add the given directory to the path where to look for custom generators. -.SS "General options" -.TP -.BI \-d \ dir -Generate files in directory -.IR dir , -rather than the current directory. -.TP -.BI \-dump \ file -Dump collected information into -.IR file . -This information can be read with the -.B \-load -option in a subsequent invocation of -.BR ocamldoc (1). -.TP -.BI \-hide \ modules -Hide the given complete module names in the generated documentation. -.I modules -is a list of complete module names are separated by commas (,), -without blanks. For instance: -.IR Stdlib,M2.M3 . -.TP -.B \-inv\-merge\-ml\-mli -Reverse the precedence of implementations and interfaces when merging. -All elements in implementation files are kept, and the -.B \-m -option indicates which parts of the comments in interface files are merged with -the comments in implementation files. -.TP -.B \-keep\-code -Always keep the source code for values, methods and instance variables, when -available. The source code is always kept when a .ml -file is given, but is by default discarded when a .mli -is given. This option allows the source code to be always kept. -.TP -.BI \-load \ file -Load information from -.IR file , -which has been produced by -.BR ocamldoc\ \-dump . -Several -.B -load -options can be given. -.TP -.BI \-m \ flags -Specify merge options between interfaces and implementations. -.I flags -can be one or several of the following characters: - -.B d -merge description - -.B a -merge @author - -.B v -merge @version - -.B l -merge @see - -.B s -merge @since - -.B o -merge @deprecated - -.B p -merge @param - -.B e -merge @raise - -.B r -merge @return - -.B A -merge everything -.TP -.B \-no\-custom\-tags -Do not allow custom @-tags. -.TP -.B \-no\-stop -Keep elements placed after the -.B (**/**) -special comment. -.TP -.BI \-o \ file -Output the generated documentation to -.I file -instead of -.IR ocamldoc.out . -This option is meaningful only in conjunction with the -.BR \-latex , \ \-texi ,\ or \ \-dot -options. -.TP -.BI \-open \ module -Opens -.I module -before typing. -.TP -.BI \-pp \ command -Pipe sources through preprocessor -.IR command . -.TP -.BI \-ppx \ command -Pipe abstract syntax tree through preprocessor -.IR command . -.TP -.BR \-show\-missed\-crossref -Show missed cross-reference opportunities. -.TP -.B \-sort -Sort the list of top-level modules before generating the documentation. -.TP -.B \-stars -Remove blank characters until the first asterisk ('*') in each line of comments. -.TP -.BI \-t \ title -Use -.I title -as the title for the generated documentation. -.TP -.BI \-text \ file -Consider \fIfile\fR as a .txt file. -.TP -.BI \-intro \ file -Use content of -.I file -as -.B ocamldoc -text to use as introduction (HTML, LaTeX and TeXinfo only). -For HTML, the file is used to create the whole "index.html" file. -.TP -.B \-v -Verbose mode. Display progress information. -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.B \-warn\-error -Treat -.B ocamldoc -warnings as errors. -.TP -.B \-hide\-warnings -Do not print -.B ocamldoc -warnings. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. -.SS "Type-checking options" -.BR ocamldoc (1) -calls the OCaml type-checker to obtain type information. The -following options impact the type-checking phase. They have the same meaning -as for the -.BR ocamlc (1)\ and \ ocamlopt (1) -commands. -.TP -.BI \-I \ directory -Add -.I directory -to the list of directories search for compiled interface files (.cmi files). -.TP -.B \-nolabels -Ignore non-optional labels in types. -.TP -.B \-rectypes - Allow arbitrary recursive types. (See the -.B \-rectypes -option to -.BR ocamlc (1).) -.SS "Options for generating HTML pages" -The following options apply in conjunction with the -.B \-html -option: -.TP -.B \-all\-params -Display the complete list of parameters for functions and methods. -.TP -.BI \-charset \ s -Add information about character encoding being \fIs\fR -(default is \fBiso-8859-1\fR). -.TP -.BI \-css\-style \ filename -Use -.I filename -as the Cascading Style Sheet file. -.TP -.B \-colorize\-code -Colorize the OCaml code enclosed in [ ] and \\{[ ]\\}, using colors to emphasize -keywords, etc. If the code fragments are not syntactically correct, no color -is added. -.TP -.B \-index\-only -Generate only index files. -.TP -.B \-short\-functors -Use a short form to display functors: -.B "module M : functor (A:Module) -> functor (B:Module2) -> sig .. end" -is displayed as -.BR "module M (A:Module) (B:Module2) : sig .. end" . -.SS "Options for generating LaTeX files" -The following options apply in conjunction with the -.B \-latex -option: -.TP -.B \-latex\-value\-prefix prefix -Give a prefix to use for the labels of the values in the generated LaTeX -document. The default prefix is the empty string. You can also use the options -.BR -latex-type-prefix , -.BR -latex-exception-prefix , -.BR -latex-module-prefix , -.BR -latex-module-type-prefix , -.BR -latex-class-prefix , -.BR -latex-class-type-prefix , -.BR -latex-attribute-prefix ,\ and -.BR -latex-method-prefix . - -These options are useful when you have, for example, a type and a value -with the same name. If you do not specify prefixes, LaTeX will complain about -multiply defined labels. -.TP -.BI \-latextitle \ n,style -Associate style number -.I n -to the given LaTeX sectioning command -.IR style , -e.g. -.BR section or subsection . -(LaTeX only.) This is useful when including the generated document in another -LaTeX document, at a given sectioning level. The default association is 1 for -section, 2 for subsection, 3 for subsubsection, 4 for paragraph and 5 for -subparagraph. -.TP -.B \-noheader -Suppress header in generated documentation. -.TP -.B \-notoc -Do not generate a table of contents. -.TP -.B \-notrailer -Suppress trailer in generated documentation. -.TP -.B \-sepfiles -Generate one .tex file per toplevel module, instead of the global -.I ocamldoc.out -file. -.SS "Options for generating TeXinfo files" -The following options apply in conjunction with the -.B -texi -option: -.TP -.B \-esc8 -Escape accented characters in Info files. -.TP -.B -\-info\-entry -Specify Info directory entry. -.TP -.B \-info\-section -Specify section of Info directory. -.TP -.B \-noheader -Suppress header in generated documentation. -.TP -.B \-noindex -Do not build index for Info files. -.TP -.B \-notrailer -Suppress trailer in generated documentation. -.SS "Options for generating dot graphs" -The following options apply in conjunction with the -.B \-dot -option: -.TP -.BI \-dot\-colors \ colors -Specify the colors to use in the generated dot code. When generating module -dependencies, -.BR ocamldoc (1) -uses different colors for modules, depending on the directories in which they -reside. When generating types dependencies, -.BR ocamldoc (1) -uses different colors for types, depending on the modules in which they are -defined. -.I colors -is a list of color names separated by commas (,), as in -.BR Red,Blue,Green . -The available colors are the ones supported by the -.BR dot (1) -tool. -.TP -.B \-dot\-include\-all -Include all modules in the -.BR dot (1) -output, not only modules given on the command line or loaded with the -.B \-load -option. -.TP -.B \-dot\-reduce -Perform a transitive reduction of the dependency graph before outputting the -dot code. This can be useful if there are a lot of transitive dependencies -that clutter the graph. -.TP -.B \-dot\-types -Output dot code describing the type dependency graph instead of the module -dependency graph. -.SS "Options for generating man files" -The following options apply in conjunction with the -.B \-man -option: -.TP -.B \-man\-mini -Generate man pages only for modules, module types, classes and class types, -instead of pages for all elements. -.TP -.BI \-man\-suffix \ suffix -Set the suffix used for generated man filenames. Default is o, as in -.IR List.o . -.TP -.BI \-man\-section \ section -Set the section number used for generated man filenames. Default is 3. - - -.SH SEE ALSO -.BR ocaml (1), -.BR ocamlc (1), -.BR ocamlopt (1). -.br -.IR "The OCaml user's manual", -chapter "The documentation generator". diff --git a/man/ocamllex.1 b/man/ocamllex.1 new file mode 100644 index 0000000000..58e0362764 --- /dev/null +++ b/man/ocamllex.1 @@ -0,0 +1,101 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLLEX 1 + +.SH NAME +ocamllex \- The OCaml lexer generator + +.SH SYNOPSIS +.B ocamllex +[ +.BI \-o \ output-file +] +[ +.B \-ml +] +.I filename.mll + +.SH DESCRIPTION + +The +.BR ocamllex (1) +command generates OCaml lexers from a set of regular +expressions with associated semantic actions, in the style of +.BR lex (1). + +Running +.BR ocamllex (1) +on the input file +.IR lexer \&.mll +produces OCaml code for a lexical analyzer in file +.IR lexer \&.ml. + +This file defines one lexing function per entry point in the lexer +definition. These functions have the same names as the entry +points. Lexing functions take as argument a lexer buffer, and return +the semantic attribute of the corresponding entry point. + +Lexer buffers are an abstract data type implemented in the standard +library module Lexing. The functions Lexing.from_channel, +Lexing.from_string and Lexing.from_function create +lexer buffers that read from an input channel, a character string, or +any reading function, respectively. + +When used in conjunction with a parser generated by +.BR ocamlyacc (1), +the semantic actions compute a value belonging to the type token defined +by the generated parsing module. + +.SH OPTIONS + +The +.BR ocamllex (1) +command recognizes the following options: +.TP +.B \-ml +Output code that does not use OCaml's built-in automata +interpreter. Instead, the automaton is encoded by OCaml functions. +This option is mainly useful for debugging +.BR ocamllex (1), +using it for production lexers is not recommended. +.TP +.BI \-o \ output\-file +Specify the name of the output file produced by +.BR ocamllex (1). +The default is the input file name, with its extension replaced by .ml. +.TP +.B \-q +Quiet mode. +.BR ocamllex (1) +normally outputs informational messages +to standard output. They are suppressed if option +.B \-q +is used. +.TP +.BR \-v \ or \ \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH SEE ALSO +.BR ocamlyacc (1). +.br +.IR "The OCaml user's manual" , +chapter "Lexer and parser generators". diff --git a/man/ocamllex.m b/man/ocamllex.m deleted file mode 100644 index 58e0362764..0000000000 --- a/man/ocamllex.m +++ /dev/null @@ -1,101 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLLEX 1 - -.SH NAME -ocamllex \- The OCaml lexer generator - -.SH SYNOPSIS -.B ocamllex -[ -.BI \-o \ output-file -] -[ -.B \-ml -] -.I filename.mll - -.SH DESCRIPTION - -The -.BR ocamllex (1) -command generates OCaml lexers from a set of regular -expressions with associated semantic actions, in the style of -.BR lex (1). - -Running -.BR ocamllex (1) -on the input file -.IR lexer \&.mll -produces OCaml code for a lexical analyzer in file -.IR lexer \&.ml. - -This file defines one lexing function per entry point in the lexer -definition. These functions have the same names as the entry -points. Lexing functions take as argument a lexer buffer, and return -the semantic attribute of the corresponding entry point. - -Lexer buffers are an abstract data type implemented in the standard -library module Lexing. The functions Lexing.from_channel, -Lexing.from_string and Lexing.from_function create -lexer buffers that read from an input channel, a character string, or -any reading function, respectively. - -When used in conjunction with a parser generated by -.BR ocamlyacc (1), -the semantic actions compute a value belonging to the type token defined -by the generated parsing module. - -.SH OPTIONS - -The -.BR ocamllex (1) -command recognizes the following options: -.TP -.B \-ml -Output code that does not use OCaml's built-in automata -interpreter. Instead, the automaton is encoded by OCaml functions. -This option is mainly useful for debugging -.BR ocamllex (1), -using it for production lexers is not recommended. -.TP -.BI \-o \ output\-file -Specify the name of the output file produced by -.BR ocamllex (1). -The default is the input file name, with its extension replaced by .ml. -.TP -.B \-q -Quiet mode. -.BR ocamllex (1) -normally outputs informational messages -to standard output. They are suppressed if option -.B \-q -is used. -.TP -.BR \-v \ or \ \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH SEE ALSO -.BR ocamlyacc (1). -.br -.IR "The OCaml user's manual" , -chapter "Lexer and parser generators". diff --git a/man/ocamlmktop.1 b/man/ocamlmktop.1 new file mode 100644 index 0000000000..09a4126c01 --- /dev/null +++ b/man/ocamlmktop.1 @@ -0,0 +1,97 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1999 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLMKTOP 1 + +.SH NAME +ocamlmktop \- Building custom toplevel systems + +.SH SYNOPSIS +.B ocamlmktop +[ +.BR \-v | \-version | \-vnum +] +[ +.BI \-cclib \ libname +] +[ +.BI \-ccopt \ option +] +[ +.B \-custom +[ +.BI \-o \ exec-file +] +[ +.BI \-I \ lib-dir +] +.I filename ... + +.SH DESCRIPTION + +The +.BR ocamlmktop (1) +command builds OCaml toplevels that +contain user code preloaded at start-up. +The +.BR ocamlmktop (1) +command takes as argument a set of +.IR x .cmo +and +.IR x .cma +files, and links them with the object files that implement the +OCaml toplevel. If the +.B \-custom +flag is given, C object files and libraries (.o and .a files) can also +be given on the command line and are linked in the resulting toplevel. + +.SH OPTIONS + +The following command-line options are recognized by +.BR ocamlmktop (1). +.TP +.B \-v +Print the version string of the compiler and exit. +.TP +.BR \-vnum \ or\ \-version +Print the version number of the compiler in short form and exit. +.TP +.BI \-cclib\ \-l libname +Pass the +.BI \-l libname +option to the C linker when linking in +``custom runtime'' mode (see the corresponding option for +.BR ocamlc (1). +.TP +.B \-ccopt +Pass the given option to the C compiler and linker, when linking in +``custom runtime'' mode. See the corresponding option for +.BR ocamlc (1). +.TP +.B \-custom +Link in ``custom runtime'' mode. See the corresponding option for +.BR ocamlc (1). +.TP +.BI \-I \ directory +Add the given directory to the list of directories searched for +compiled interface files (.cmo and .cma). +.TP +.BI \-o \ exec\-file +Specify the name of the toplevel file produced by the linker. +The default is is +.BR a.out . + +.SH SEE ALSO +.BR ocamlc (1). diff --git a/man/ocamlmktop.m b/man/ocamlmktop.m deleted file mode 100644 index 09a4126c01..0000000000 --- a/man/ocamlmktop.m +++ /dev/null @@ -1,97 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1999 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLMKTOP 1 - -.SH NAME -ocamlmktop \- Building custom toplevel systems - -.SH SYNOPSIS -.B ocamlmktop -[ -.BR \-v | \-version | \-vnum -] -[ -.BI \-cclib \ libname -] -[ -.BI \-ccopt \ option -] -[ -.B \-custom -[ -.BI \-o \ exec-file -] -[ -.BI \-I \ lib-dir -] -.I filename ... - -.SH DESCRIPTION - -The -.BR ocamlmktop (1) -command builds OCaml toplevels that -contain user code preloaded at start-up. -The -.BR ocamlmktop (1) -command takes as argument a set of -.IR x .cmo -and -.IR x .cma -files, and links them with the object files that implement the -OCaml toplevel. If the -.B \-custom -flag is given, C object files and libraries (.o and .a files) can also -be given on the command line and are linked in the resulting toplevel. - -.SH OPTIONS - -The following command-line options are recognized by -.BR ocamlmktop (1). -.TP -.B \-v -Print the version string of the compiler and exit. -.TP -.BR \-vnum \ or\ \-version -Print the version number of the compiler in short form and exit. -.TP -.BI \-cclib\ \-l libname -Pass the -.BI \-l libname -option to the C linker when linking in -``custom runtime'' mode (see the corresponding option for -.BR ocamlc (1). -.TP -.B \-ccopt -Pass the given option to the C compiler and linker, when linking in -``custom runtime'' mode. See the corresponding option for -.BR ocamlc (1). -.TP -.B \-custom -Link in ``custom runtime'' mode. See the corresponding option for -.BR ocamlc (1). -.TP -.BI \-I \ directory -Add the given directory to the list of directories searched for -compiled interface files (.cmo and .cma). -.TP -.BI \-o \ exec\-file -Specify the name of the toplevel file produced by the linker. -The default is is -.BR a.out . - -.SH SEE ALSO -.BR ocamlc (1). diff --git a/man/ocamlopt.1 b/man/ocamlopt.1 new file mode 100644 index 0000000000..8540a08c1e --- /dev/null +++ b/man/ocamlopt.1 @@ -0,0 +1,794 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLOPT 1 + +.SH NAME + +ocamlopt \- The OCaml native-code compiler + +.SH SYNOPSIS + +.B ocamlopt +[ +.I options +] +.IR filename \ ... + +.B ocamlopt.opt +(same options) + +.SH DESCRIPTION + +The OCaml high-performance +native-code compiler +.BR ocamlopt (1) +compiles OCaml source files to native code object files and link these +object files to produce standalone executables. + +The +.BR ocamlopt (1) +command has a command-line interface very close to that +of +.BR ocamlc (1). +It accepts the same types of arguments and processes them +sequentially, after all options have been processed: + +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 +.IR x .mli, +the +.BR ocamlopt (1) +compiler produces a compiled interface +in the file +.IR x .cmi. +The interface produced is identical to that +produced by the bytecode compiler +.BR ocamlc (1). + +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 +.IR x .ml, +the +.BR ocamlopt (1) +compiler produces two files: +.IR x .o, +containing native object code, and +.IR x .cmx, +containing extra information for linking and +optimization of the clients of the unit. The compiled implementation +should always be referred to under the name +.IR x .cmx +(when given a .o file, +.BR ocamlopt (1) +assumes that it contains code compiled from C, not from OCaml). + +The implementation is checked against the interface file +.IR x .mli +(if it exists) as described in the manual for +.BR ocamlc (1). + +Arguments ending in .cmx are taken to be compiled object code. These +files are linked together, along with the object files obtained +by compiling .ml arguments (if any), and the OCaml standard +library, to produce a native-code executable program. The order in +which .cmx 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 initialized it. Hence, a given +.IR x .cmx +file must come +before all .cmx files that refer to the unit +.IR x . + +Arguments ending in .cmxa are taken to be libraries of object code. +Such a library packs in two files +.IR lib .cmxa +and +.IR lib .a +a set of object files (.cmx/.o files). Libraries are build with +.B ocamlopt \-a +(see the description of the +.B \-a +option below). The object +files contained in the library are linked as regular .cmx files (see +above), in the order specified when the library 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. + +Arguments ending in .o or .a are assumed to be C object files and +libraries. They are linked with the program. + +The output of the linking phase is a regular Unix executable file. It +does not need +.BR ocamlrun (1) +to run. + +.B ocamlopt.opt +is the same compiler as +.BR ocamlopt , +but compiled with itself instead of with the bytecode compiler +.BR ocamlc (1). +Thus, it behaves exactly like +.BR ocamlopt , +but compiles faster. +.B ocamlopt.opt +is not available in all installations of OCaml. + +.SH OPTIONS + +The following command-line options are recognized by +.BR ocamlopt (1). +.TP +.B \-a +Build a library (.cmxa/.a file) with the object files (.cmx/.o +files) given on the command line, instead of linking them into an +executable file. The name of the library must be set with the +.B \-o +option. + +If +.BR \-cclib \ or \ \-ccopt +options are passed on the command +line, these options are stored in the resulting .cmxa library. Then, +linking with this library automatically adds back the +.BR \-cclib \ and \ \-ccopt +options as if they had been provided on the +command line, unless the +.B \-noautolink +option is given. Additionally, a substring +.B $CAMLORIGIN +inside a +.BR \ \-ccopt +options will be replaced by the full path to the .cma library, +excluding the filename. +.TP +.B \-absname +Show absolute filenames in error messages. +.TP +.B \-annot +Deprecated since OCaml 4.11. Please use +.BR \-bin-annot +instead. +.TP +.B \-bin\-annot +Dump detailed information about the compilation (types, bindings, +tail-calls, etc) in binary format. The information for file +.IR src .ml +is put into file +.IR src .cmt. +In case of a type error, dump +all the information inferred by the type-checker before the error. +The annotation files produced by +.B \-bin\-annot +contain more information +and are much more compact than the files produced by +.BR \-annot . +.TP +.B \-c +Compile only. Suppress the linking phase of the +compilation. Source code files are turned into compiled files, but no +executable file is produced. This option is useful to +compile modules separately. +.TP +.BI \-cc \ ccomp +Use +.I ccomp +as the C linker called to build the final executable and as the C +compiler for compiling .c source files. +.TP +.BI \-cclib\ \-l libname +Pass the +.BI \-l libname +option to the linker. This causes the given C library to be linked +with the program. +.TP +.BI \-ccopt \ option +Pass the given option to the C compiler and linker. For instance, +.BI \-ccopt\ \-L dir +causes the C linker to search for C libraries in +directory +.IR dir . +.TP +.BI \-color \ mode +Enable or disable colors in compiler messages (especially warnings and errors). +The following modes are supported: + +.B auto +use heuristics to enable colors only if the output supports them (an +ANSI-compatible tty terminal); + +.B always +enable colors unconditionally; + +.B never +disable color output. + +The environment variable "OCAML_COLOR" is considered if \-color is not +provided. Its values are auto/always/never as above. + +If \-color is not provided, "OCAML_COLOR" is not set and the environment +variable "NO_COLOR" is set, then color output is disabled. Otherwise, +the default setting is +.B auto, +and the current heuristic +checks that the "TERM" environment variable exists and is +not empty or "dumb", and that isatty(stderr) holds. + +.TP +.BI \-error\-style \ mode +Control the way error messages and warnings are printed. +The following modes are supported: + +.B short +only print the error and its location; + +.B contextual +like "short", but also display the source code snippet corresponding +to the location of the error. + +The default setting is +.B contextual. + +The environment variable "OCAML_ERROR_STYLE" is considered if +\-error\-style is not provided. Its values are short/contextual as +above. + +.TP +.B \-compact +Optimize the produced code for space rather than for time. This +results in smaller but slightly slower programs. The default is to +optimize for speed. +.TP +.B \-config +Print the version number of +.BR ocamlopt (1) +and a detailed summary of its configuration, then exit. +.TP +.BI \-config-var +Print the value of a specific configuration variable +from the +.B \-config +output, then exit. If the variable does not exist, +the exit code is non-zero. +.TP +.BI \-depend\ ocamldep-args +Compute dependencies, as ocamldep would do. +.TP +.BI \-for\-pack \ module\-path +Generate an object file (.cmx and .o files) that can later be included +as a sub-module (with the given access path) of a compilation unit +constructed with +.BR \-pack . +For instance, +.B ocamlopt\ \-for\-pack\ P\ \-c\ A.ml +will generate a.cmx and a.o files that can later be used with +.BR "ocamlopt -pack -o P.cmx a.cmx" . +.TP +.B \-g +Add debugging information while compiling and linking. This option is +required in order to produce stack backtraces when +the program terminates on an uncaught exception (see +.BR ocamlrun (1)). +.TP +.B \-i +Cause the compiler to print all defined names (with their inferred +types or their definitions) when compiling an implementation (.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 interfaces, 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. +.TP +.BI \-I \ directory +Add the given directory to the list of directories searched for +compiled interface files (.cmi), compiled object code files (.cmx), +and libraries (.cmxa). 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. See also option +.BR \-nostdlib . + +If the given directory starts with +.BR + , +it is taken relative to the +standard library directory. For instance, +.B \-I\ +compiler-libs +adds the subdirectory +.B compiler-libs +of the standard library to the search path. +.TP +.BI \-impl \ filename +Compile the file +.I filename +as an implementation file, even if its extension is not .ml. +.TP +.BI \-inline \ n +Set aggressiveness of inlining to +.IR n , +where +.I n +is a positive +integer. Specifying +.B \-inline 0 +prevents all functions from being +inlined, except those whose body is smaller than the call site. Thus, +inlining causes no expansion in code size. The default aggressiveness, +.BR \-inline\ 1 , +allows slightly larger functions to be inlined, resulting +in a slight expansion in code size. Higher values for the +.B \-inline +option cause larger and larger functions to become candidate for +inlining, but can result in a serious increase in code size. +.TP +.B \-insn\-sched +Enables the instruction scheduling pass in the compiler backend. +.TP +.BI \-intf \ filename +Compile the file +.I filename +as an interface file, even if its extension is not .mli. +.TP +.BI \-intf\-suffix \ string +Recognize file names ending with +.I string +as interface files (instead of the default .mli). +.TP +.B \-keep-docs +Keep documentation strings in generated .cmi files. +.TP +.B \-keep-locs +Keep locations in generated .cmi files. +.TP +.B \-labels +Labels are not ignored in types, labels may be used in applications, +and labelled parameters can be given in any order. This is the default. +.TP +.B \-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 +.RB ( \-a +flag), setting the +.B \-linkall +flag forces all +subsequent links of programs involving that library to link all the +modules contained in the library. +When compiling a module (option +.BR \-c ), +setting the +.B \-linkall +option ensures that this module will +always be linked if it is put in a library and this library is linked. +.TP +.B \-linscan +Use linear scan register allocation. Compiling with this allocator is faster +than with the usual graph coloring allocator, sometimes quite drastically so for +long functions and modules. On the other hand, the generated code can be a bit +slower. +.TP +.B \-match\-context\-rows +Set number of rows of context used during pattern matching +compilation. Lower values cause faster compilation, but +less optimized code. The default value is 32. +.TP +.B \-no-alias-deps +Do not record dependencies for module aliases. +.TP +.B \-no\-app\-funct +Deactivates the applicative behaviour of functors. With this option, +each functor application generates new types in its result and +applying the same functor twice to the same argument yields two +incompatible structures. +.TP +.B \-noassert +Do not compile assertion checks. Note that the special form +.B assert\ false +is always compiled because it is typed specially. +This flag has no effect when linking already-compiled files. +.TP +.B \-noautolink +When linking .cmxa libraries, ignore +.BR \-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 +.B -noautolink +and pass the correct C libraries and options on the command line. +.TP +.B \-nodynlink +Allow the compiler to use some optimizations that are valid only for code +that is never dynlinked. +.TP +.B \-no\-insn\-sched +Disables the instruction scheduling pass in the compiler backend. +.TP +.B -nostdlib +Do not automatically add the standard library directory to the list of +directories searched for compiled interface files (.cmi), compiled +object code files (.cmx), and libraries (.cmxa). See also option +.BR \-I . +.TP +.B \-nolabels +Ignore non-optional labels in types. Labels cannot be used in +applications, and parameter order becomes strict. +.TP +.BI \-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 tradition. If the +.B \-a +option is given, specify the name of the library produced. If the +.B \-pack +option is given, specify the name of the packed object file produced. +If the +.B \-output\-obj +option is given, specify the name of the output file produced. If the +.B \-shared +option is given, specify the name of plugin file produced. +This can also be used when compiling an interface or implementation +file, without linking, in which case it sets the name of the cmi or +cmo file, and also sets the module name to the file name up to the +first dot. +.TP +.B \-opaque +When compiling a .mli interface file, this has the same effect as the +.B \-opaque +option of the bytecode compiler. When compiling a .ml implementation +file, this produces a .cmx file without cross-module optimization +information, which reduces recompilation on module change. +.TP +.BI \-open \ module +Opens the given module before processing the interface or +implementation files. If several +.B \-open +options are given, they are processed in order, just as if +the statements open! module1;; ... open! moduleN;; were added +at the top of each file. +.TP +.B \-output\-obj +Cause the linker to produce a C object file instead of an executable +file. This is useful to wrap OCaml code as a C library, +callable from any C program. The name of the output object file +must be set with the +.B \-o +option. +This option can also be used to produce a compiled shared/dynamic +library (.so extension). +.B \-output\-complete\-obj +Same as +.B \-output\-obj +except the object file produced includes the runtime and +autolink libraries. +.TP +.TP +.B \-pack +Build an object file (.cmx and .o files) and its associated compiled +interface (.cmi) that combines the .cmx object +files given on the command line, making them appear as sub-modules of +the output .cmx file. The name of the output .cmx file must be +given with the +.B \-o +option. For instance, +.B ocamlopt\ -pack\ -o\ P.cmx\ A.cmx\ B.cmx\ C.cmx +generates compiled files P.cmx, P.o and P.cmi describing a +compilation unit having three sub-modules A, B and C, +corresponding to the contents of the object files A.cmx, B.cmx and +C.cmx. These contents can be referenced as P.A, P.B and P.C +in the remainder of the program. + +The .cmx object files being combined must have been compiled with +the appropriate +.B \-for\-pack +option. In the example above, +A.cmx, B.cmx and C.cmx must have been compiled with +.BR ocamlopt\ \-for\-pack\ P . + +Multiple levels of packing can be achieved by combining +.B \-pack +with +.BR \-for\-pack . +See +.IR "The OCaml user's manual" , +chapter "Native-code compilation" for more details. +.TP +.BI \-pp \ command +Cause the compiler to call the given +.I command +as a preprocessor for each source file. The output of +.I command +is redirected to +an intermediate file, which is compiled. If there are no compilation +errors, the intermediate file is deleted afterwards. +.TP +.BI \-ppx \ command +After parsing, pipe the abstract syntax tree through the preprocessor +.IR command . +The module +.BR Ast_mapper (3) +implements the external interface of a preprocessor. +.TP +.B \-principal +Check information path during type-checking, to make sure that all +types are derived in a principal way. All programs accepted in +.B \-principal +mode are also accepted in default mode with equivalent +types, but different binary signatures. +.TP +.B \-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 dependencies. +.TP +.BI \-runtime\-variant \ suffix +Add +.I suffix +to the name of the runtime library that will be used by the program. +If OCaml was configured with option +.BR \-with\-debug\-runtime , +then the +.B d +suffix is supported and gives a debug version of the runtime. +.TP +.B \-S +Keep the assembly code produced during the compilation. The assembly +code for the source file +.IR x .ml +is saved in the file +.IR x .s. +.TP +.BI \-stop\-after \ pass +Stop compilation after the given compilation pass. The currently +supported passes are: +.BR parsing , +.BR typing , +.BR scheduling , +.BR emit . +.TP +.BI \-save\-ir\-after \ pass +Save intermediate representation after the given compilation pass. The currently +supported passes are: +.BR scheduling . +.TP +.B \-safe\-string +Enforce the separation between types +.BR string \ and\ bytes , +thereby making strings read-only. This is the default. +.TP +.B \-shared +Build a plugin (usually .cmxs) that can be dynamically loaded with +the +.B Dynlink +module. The name of the plugin must be +set with the +.B \-o +option. A plugin can include a number of OCaml +modules and libraries, and extra native objects (.o, .a files). +Building native plugins is only supported for some +operating system. Under some systems (currently, +only Linux AMD 64), all the OCaml code linked in a plugin must have +been compiled without the +.B \-nodynlink +flag. Some constraints might also +apply to the way the extra native objects have been compiled (under +Linux AMD 64, they must contain only position-independent code). +.TP +.B \-short\-paths +When a type is visible under several module-paths, use the shortest +one when printing the type's name in inferred interfaces and error and +warning messages. +.TP +.B \-strict\-sequence +The left-hand part of a sequence must have type unit. +.TP +.B \-unboxed\-types +When a type is unboxable (i.e. a record with a single argument or a +concrete datatype with a single constructor of one argument) it will +be unboxed unless annotated with +.BR [@@ocaml.boxed] . +.TP +.B \-no-unboxed\-types +When a type is unboxable it will be boxed unless annotated with +.BR [@@ocaml.unboxed] . +This is the default. +.TP +.B \-unsafe +Turn bound checking off for array and string accesses (the +.BR v.(i) and s.[i] +constructs). Programs compiled with +.B \-unsafe +are therefore +faster, but unsafe: anything can happen if the program accesses an +array or string outside of its bounds. Additionally, turn off the +check for zero divisor in integer division and modulus operations. +With +.BR \-unsafe , +an integer division (or modulus) by zero can halt the +program or continue with an unspecified result instead of raising a +.B Division_by_zero +exception. +.TP +.B \-unsafe\-string +Identify the types +.BR string \ and\ bytes , +thereby making strings writable. +This is intended for compatibility with old source code and should not +be used with new software. +.TP +.B \-v +Print the version number of the compiler and the location of the +standard library directory, then exit. +.TP +.B \-verbose +Print all external commands before they are executed, in particular +invocations of the assembler, C compiler, and linker. +.TP +.BR \-version \ or\ \-vnum +Print the version number of the compiler in short form (e.g. "3.11.0"), +then exit. +.TP +.BI \-w \ warning\-list +Enable, disable, or mark as fatal the warnings specified by the argument +.IR warning\-list . +See +.BR ocamlc (1) +for the syntax of +.IR warning-list . +.TP +.BI \-warn\-error \ warning\-list +Mark as fatal the warnings specified in the argument +.IR warning\-list . +The compiler will stop with an error when one of these +warnings is emitted. The +.I warning\-list +has the same meaning as for +the +.B \-w +option: a +.B + +sign (or an uppercase letter) marks the corresponding warnings as fatal, a +.B \- +sign (or a lowercase letter) turns them back into non-fatal warnings, and a +.B @ +sign both enables and marks as fatal the corresponding warnings. + +Note: it is not recommended to use the +.B \-warn\-error +option in production code, because it will almost certainly prevent +compiling your program with later versions of OCaml when they add new +warnings or modify existing warnings. + +The default setting is +.B \-warn\-error \-a+31 +(only warning 31 is fatal). +.TP +.B \-warn\-help +Show the description of all available warning numbers. +.TP +.B \-where +Print the location of the standard library, then exit. +.TP +.B \-with-runtime +Include the runtime system in the generated program. This is the default. +.TP +.B \-without-runtime +The compiler does not include the runtime system (nor a reference to it) in the +generated program; it must be supplied separately. +.TP +.BI \- \ file +Process +.I file +as a file name, even if it starts with a dash (-) character. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH OPTIONS FOR THE IA32 ARCHITECTURE + +The IA32 code generator (Intel Pentium, AMD Athlon) supports the +following additional option: +.TP +.B \-ffast\-math +Use the IA32 instructions to compute +trigonometric and exponential functions, instead of calling the +corresponding library routines. The functions affected are: +.BR atan , +.BR atan2 , +.BR cos , +.BR log , +.BR log10 , +.BR sin , +.B sqrt +and +.BR tan . +The resulting code runs faster, but the range of supported arguments +and the precision of the result can be reduced. In particular, +trigonometric operations +.BR cos , +.BR sin , +.B tan +have their range reduced to [\-2^64, 2^64]. + +.SH OPTIONS FOR THE AMD64 ARCHITECTURE + +The AMD64 code generator (64-bit versions of Intel Pentium and AMD +Athlon) supports the following additional options: +.TP +.B \-fPIC +Generate position-independent machine code. This is the default. +.TP +.B \-fno\-PIC +Generate position-dependent machine code. + +.SH OPTIONS FOR THE POWER ARCHITECTURE + +The PowerPC code generator supports the following additional options: +.TP +.B \-flarge\-toc +Enables the PowerPC large model allowing the TOC (table of contents) to be +arbitrarily large. This is the default since 4.11. +.TP +.B \-fsmall\-toc +Enables the PowerPC small model allowing the TOC to be up to 64 kbytes per +compilation unit. Prior to 4.11 this was the default behaviour. +\end{options} + +.SH OPTIONS FOR THE ARM ARCHITECTURE +The ARM code generator supports the following additional options: +.TP +.B \-farch=armv4|armv5|armv5te|armv6|armv6t2|armv7 +Select the ARM target architecture +.TP +.B \-ffpu=soft|vfpv2|vfpv3\-d16|vfpv3 +Select the floating-point hardware +.TP +.B \-fPIC +Generate position-independent machine code. +.TP +.B \-fno\-PIC +Generate position-dependent machine code. This is the default. +.TP +.B \-fthumb +Enable Thumb/Thumb-2 code generation +.TP +.B \-fno\-thumb +Disable Thumb/Thumb-2 code generation +.P +The default values for target architecture, floating-point hardware +and thumb usage were selected at configure-time when building +.B ocamlopt +itself. This configuration can be inspected using +.BR ocamlopt\ \-config . +Target architecture depends on the "model" setting, while +floating-point hardware and thumb support are determined from the ABI +setting in "system" ( +.BR linux_eabi or linux_eabihf ). + +.SH SEE ALSO +.BR ocamlc (1). +.br +.IR "The OCaml user's manual" , +chapter "Native-code compilation". diff --git a/man/ocamlopt.m b/man/ocamlopt.m deleted file mode 100644 index 8540a08c1e..0000000000 --- a/man/ocamlopt.m +++ /dev/null @@ -1,794 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLOPT 1 - -.SH NAME - -ocamlopt \- The OCaml native-code compiler - -.SH SYNOPSIS - -.B ocamlopt -[ -.I options -] -.IR filename \ ... - -.B ocamlopt.opt -(same options) - -.SH DESCRIPTION - -The OCaml high-performance -native-code compiler -.BR ocamlopt (1) -compiles OCaml source files to native code object files and link these -object files to produce standalone executables. - -The -.BR ocamlopt (1) -command has a command-line interface very close to that -of -.BR ocamlc (1). -It accepts the same types of arguments and processes them -sequentially, after all options have been processed: - -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 -.IR x .mli, -the -.BR ocamlopt (1) -compiler produces a compiled interface -in the file -.IR x .cmi. -The interface produced is identical to that -produced by the bytecode compiler -.BR ocamlc (1). - -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 -.IR x .ml, -the -.BR ocamlopt (1) -compiler produces two files: -.IR x .o, -containing native object code, and -.IR x .cmx, -containing extra information for linking and -optimization of the clients of the unit. The compiled implementation -should always be referred to under the name -.IR x .cmx -(when given a .o file, -.BR ocamlopt (1) -assumes that it contains code compiled from C, not from OCaml). - -The implementation is checked against the interface file -.IR x .mli -(if it exists) as described in the manual for -.BR ocamlc (1). - -Arguments ending in .cmx are taken to be compiled object code. These -files are linked together, along with the object files obtained -by compiling .ml arguments (if any), and the OCaml standard -library, to produce a native-code executable program. The order in -which .cmx 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 initialized it. Hence, a given -.IR x .cmx -file must come -before all .cmx files that refer to the unit -.IR x . - -Arguments ending in .cmxa are taken to be libraries of object code. -Such a library packs in two files -.IR lib .cmxa -and -.IR lib .a -a set of object files (.cmx/.o files). Libraries are build with -.B ocamlopt \-a -(see the description of the -.B \-a -option below). The object -files contained in the library are linked as regular .cmx files (see -above), in the order specified when the library 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. - -Arguments ending in .o or .a are assumed to be C object files and -libraries. They are linked with the program. - -The output of the linking phase is a regular Unix executable file. It -does not need -.BR ocamlrun (1) -to run. - -.B ocamlopt.opt -is the same compiler as -.BR ocamlopt , -but compiled with itself instead of with the bytecode compiler -.BR ocamlc (1). -Thus, it behaves exactly like -.BR ocamlopt , -but compiles faster. -.B ocamlopt.opt -is not available in all installations of OCaml. - -.SH OPTIONS - -The following command-line options are recognized by -.BR ocamlopt (1). -.TP -.B \-a -Build a library (.cmxa/.a file) with the object files (.cmx/.o -files) given on the command line, instead of linking them into an -executable file. The name of the library must be set with the -.B \-o -option. - -If -.BR \-cclib \ or \ \-ccopt -options are passed on the command -line, these options are stored in the resulting .cmxa library. Then, -linking with this library automatically adds back the -.BR \-cclib \ and \ \-ccopt -options as if they had been provided on the -command line, unless the -.B \-noautolink -option is given. Additionally, a substring -.B $CAMLORIGIN -inside a -.BR \ \-ccopt -options will be replaced by the full path to the .cma library, -excluding the filename. -.TP -.B \-absname -Show absolute filenames in error messages. -.TP -.B \-annot -Deprecated since OCaml 4.11. Please use -.BR \-bin-annot -instead. -.TP -.B \-bin\-annot -Dump detailed information about the compilation (types, bindings, -tail-calls, etc) in binary format. The information for file -.IR src .ml -is put into file -.IR src .cmt. -In case of a type error, dump -all the information inferred by the type-checker before the error. -The annotation files produced by -.B \-bin\-annot -contain more information -and are much more compact than the files produced by -.BR \-annot . -.TP -.B \-c -Compile only. Suppress the linking phase of the -compilation. Source code files are turned into compiled files, but no -executable file is produced. This option is useful to -compile modules separately. -.TP -.BI \-cc \ ccomp -Use -.I ccomp -as the C linker called to build the final executable and as the C -compiler for compiling .c source files. -.TP -.BI \-cclib\ \-l libname -Pass the -.BI \-l libname -option to the linker. This causes the given C library to be linked -with the program. -.TP -.BI \-ccopt \ option -Pass the given option to the C compiler and linker. For instance, -.BI \-ccopt\ \-L dir -causes the C linker to search for C libraries in -directory -.IR dir . -.TP -.BI \-color \ mode -Enable or disable colors in compiler messages (especially warnings and errors). -The following modes are supported: - -.B auto -use heuristics to enable colors only if the output supports them (an -ANSI-compatible tty terminal); - -.B always -enable colors unconditionally; - -.B never -disable color output. - -The environment variable "OCAML_COLOR" is considered if \-color is not -provided. Its values are auto/always/never as above. - -If \-color is not provided, "OCAML_COLOR" is not set and the environment -variable "NO_COLOR" is set, then color output is disabled. Otherwise, -the default setting is -.B auto, -and the current heuristic -checks that the "TERM" environment variable exists and is -not empty or "dumb", and that isatty(stderr) holds. - -.TP -.BI \-error\-style \ mode -Control the way error messages and warnings are printed. -The following modes are supported: - -.B short -only print the error and its location; - -.B contextual -like "short", but also display the source code snippet corresponding -to the location of the error. - -The default setting is -.B contextual. - -The environment variable "OCAML_ERROR_STYLE" is considered if -\-error\-style is not provided. Its values are short/contextual as -above. - -.TP -.B \-compact -Optimize the produced code for space rather than for time. This -results in smaller but slightly slower programs. The default is to -optimize for speed. -.TP -.B \-config -Print the version number of -.BR ocamlopt (1) -and a detailed summary of its configuration, then exit. -.TP -.BI \-config-var -Print the value of a specific configuration variable -from the -.B \-config -output, then exit. If the variable does not exist, -the exit code is non-zero. -.TP -.BI \-depend\ ocamldep-args -Compute dependencies, as ocamldep would do. -.TP -.BI \-for\-pack \ module\-path -Generate an object file (.cmx and .o files) that can later be included -as a sub-module (with the given access path) of a compilation unit -constructed with -.BR \-pack . -For instance, -.B ocamlopt\ \-for\-pack\ P\ \-c\ A.ml -will generate a.cmx and a.o files that can later be used with -.BR "ocamlopt -pack -o P.cmx a.cmx" . -.TP -.B \-g -Add debugging information while compiling and linking. This option is -required in order to produce stack backtraces when -the program terminates on an uncaught exception (see -.BR ocamlrun (1)). -.TP -.B \-i -Cause the compiler to print all defined names (with their inferred -types or their definitions) when compiling an implementation (.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 interfaces, 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. -.TP -.BI \-I \ directory -Add the given directory to the list of directories searched for -compiled interface files (.cmi), compiled object code files (.cmx), -and libraries (.cmxa). 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. See also option -.BR \-nostdlib . - -If the given directory starts with -.BR + , -it is taken relative to the -standard library directory. For instance, -.B \-I\ +compiler-libs -adds the subdirectory -.B compiler-libs -of the standard library to the search path. -.TP -.BI \-impl \ filename -Compile the file -.I filename -as an implementation file, even if its extension is not .ml. -.TP -.BI \-inline \ n -Set aggressiveness of inlining to -.IR n , -where -.I n -is a positive -integer. Specifying -.B \-inline 0 -prevents all functions from being -inlined, except those whose body is smaller than the call site. Thus, -inlining causes no expansion in code size. The default aggressiveness, -.BR \-inline\ 1 , -allows slightly larger functions to be inlined, resulting -in a slight expansion in code size. Higher values for the -.B \-inline -option cause larger and larger functions to become candidate for -inlining, but can result in a serious increase in code size. -.TP -.B \-insn\-sched -Enables the instruction scheduling pass in the compiler backend. -.TP -.BI \-intf \ filename -Compile the file -.I filename -as an interface file, even if its extension is not .mli. -.TP -.BI \-intf\-suffix \ string -Recognize file names ending with -.I string -as interface files (instead of the default .mli). -.TP -.B \-keep-docs -Keep documentation strings in generated .cmi files. -.TP -.B \-keep-locs -Keep locations in generated .cmi files. -.TP -.B \-labels -Labels are not ignored in types, labels may be used in applications, -and labelled parameters can be given in any order. This is the default. -.TP -.B \-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 -.RB ( \-a -flag), setting the -.B \-linkall -flag forces all -subsequent links of programs involving that library to link all the -modules contained in the library. -When compiling a module (option -.BR \-c ), -setting the -.B \-linkall -option ensures that this module will -always be linked if it is put in a library and this library is linked. -.TP -.B \-linscan -Use linear scan register allocation. Compiling with this allocator is faster -than with the usual graph coloring allocator, sometimes quite drastically so for -long functions and modules. On the other hand, the generated code can be a bit -slower. -.TP -.B \-match\-context\-rows -Set number of rows of context used during pattern matching -compilation. Lower values cause faster compilation, but -less optimized code. The default value is 32. -.TP -.B \-no-alias-deps -Do not record dependencies for module aliases. -.TP -.B \-no\-app\-funct -Deactivates the applicative behaviour of functors. With this option, -each functor application generates new types in its result and -applying the same functor twice to the same argument yields two -incompatible structures. -.TP -.B \-noassert -Do not compile assertion checks. Note that the special form -.B assert\ false -is always compiled because it is typed specially. -This flag has no effect when linking already-compiled files. -.TP -.B \-noautolink -When linking .cmxa libraries, ignore -.BR \-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 -.B -noautolink -and pass the correct C libraries and options on the command line. -.TP -.B \-nodynlink -Allow the compiler to use some optimizations that are valid only for code -that is never dynlinked. -.TP -.B \-no\-insn\-sched -Disables the instruction scheduling pass in the compiler backend. -.TP -.B -nostdlib -Do not automatically add the standard library directory to the list of -directories searched for compiled interface files (.cmi), compiled -object code files (.cmx), and libraries (.cmxa). See also option -.BR \-I . -.TP -.B \-nolabels -Ignore non-optional labels in types. Labels cannot be used in -applications, and parameter order becomes strict. -.TP -.BI \-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 tradition. If the -.B \-a -option is given, specify the name of the library produced. If the -.B \-pack -option is given, specify the name of the packed object file produced. -If the -.B \-output\-obj -option is given, specify the name of the output file produced. If the -.B \-shared -option is given, specify the name of plugin file produced. -This can also be used when compiling an interface or implementation -file, without linking, in which case it sets the name of the cmi or -cmo file, and also sets the module name to the file name up to the -first dot. -.TP -.B \-opaque -When compiling a .mli interface file, this has the same effect as the -.B \-opaque -option of the bytecode compiler. When compiling a .ml implementation -file, this produces a .cmx file without cross-module optimization -information, which reduces recompilation on module change. -.TP -.BI \-open \ module -Opens the given module before processing the interface or -implementation files. If several -.B \-open -options are given, they are processed in order, just as if -the statements open! module1;; ... open! moduleN;; were added -at the top of each file. -.TP -.B \-output\-obj -Cause the linker to produce a C object file instead of an executable -file. This is useful to wrap OCaml code as a C library, -callable from any C program. The name of the output object file -must be set with the -.B \-o -option. -This option can also be used to produce a compiled shared/dynamic -library (.so extension). -.B \-output\-complete\-obj -Same as -.B \-output\-obj -except the object file produced includes the runtime and -autolink libraries. -.TP -.TP -.B \-pack -Build an object file (.cmx and .o files) and its associated compiled -interface (.cmi) that combines the .cmx object -files given on the command line, making them appear as sub-modules of -the output .cmx file. The name of the output .cmx file must be -given with the -.B \-o -option. For instance, -.B ocamlopt\ -pack\ -o\ P.cmx\ A.cmx\ B.cmx\ C.cmx -generates compiled files P.cmx, P.o and P.cmi describing a -compilation unit having three sub-modules A, B and C, -corresponding to the contents of the object files A.cmx, B.cmx and -C.cmx. These contents can be referenced as P.A, P.B and P.C -in the remainder of the program. - -The .cmx object files being combined must have been compiled with -the appropriate -.B \-for\-pack -option. In the example above, -A.cmx, B.cmx and C.cmx must have been compiled with -.BR ocamlopt\ \-for\-pack\ P . - -Multiple levels of packing can be achieved by combining -.B \-pack -with -.BR \-for\-pack . -See -.IR "The OCaml user's manual" , -chapter "Native-code compilation" for more details. -.TP -.BI \-pp \ command -Cause the compiler to call the given -.I command -as a preprocessor for each source file. The output of -.I command -is redirected to -an intermediate file, which is compiled. If there are no compilation -errors, the intermediate file is deleted afterwards. -.TP -.BI \-ppx \ command -After parsing, pipe the abstract syntax tree through the preprocessor -.IR command . -The module -.BR Ast_mapper (3) -implements the external interface of a preprocessor. -.TP -.B \-principal -Check information path during type-checking, to make sure that all -types are derived in a principal way. All programs accepted in -.B \-principal -mode are also accepted in default mode with equivalent -types, but different binary signatures. -.TP -.B \-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 dependencies. -.TP -.BI \-runtime\-variant \ suffix -Add -.I suffix -to the name of the runtime library that will be used by the program. -If OCaml was configured with option -.BR \-with\-debug\-runtime , -then the -.B d -suffix is supported and gives a debug version of the runtime. -.TP -.B \-S -Keep the assembly code produced during the compilation. The assembly -code for the source file -.IR x .ml -is saved in the file -.IR x .s. -.TP -.BI \-stop\-after \ pass -Stop compilation after the given compilation pass. The currently -supported passes are: -.BR parsing , -.BR typing , -.BR scheduling , -.BR emit . -.TP -.BI \-save\-ir\-after \ pass -Save intermediate representation after the given compilation pass. The currently -supported passes are: -.BR scheduling . -.TP -.B \-safe\-string -Enforce the separation between types -.BR string \ and\ bytes , -thereby making strings read-only. This is the default. -.TP -.B \-shared -Build a plugin (usually .cmxs) that can be dynamically loaded with -the -.B Dynlink -module. The name of the plugin must be -set with the -.B \-o -option. A plugin can include a number of OCaml -modules and libraries, and extra native objects (.o, .a files). -Building native plugins is only supported for some -operating system. Under some systems (currently, -only Linux AMD 64), all the OCaml code linked in a plugin must have -been compiled without the -.B \-nodynlink -flag. Some constraints might also -apply to the way the extra native objects have been compiled (under -Linux AMD 64, they must contain only position-independent code). -.TP -.B \-short\-paths -When a type is visible under several module-paths, use the shortest -one when printing the type's name in inferred interfaces and error and -warning messages. -.TP -.B \-strict\-sequence -The left-hand part of a sequence must have type unit. -.TP -.B \-unboxed\-types -When a type is unboxable (i.e. a record with a single argument or a -concrete datatype with a single constructor of one argument) it will -be unboxed unless annotated with -.BR [@@ocaml.boxed] . -.TP -.B \-no-unboxed\-types -When a type is unboxable it will be boxed unless annotated with -.BR [@@ocaml.unboxed] . -This is the default. -.TP -.B \-unsafe -Turn bound checking off for array and string accesses (the -.BR v.(i) and s.[i] -constructs). Programs compiled with -.B \-unsafe -are therefore -faster, but unsafe: anything can happen if the program accesses an -array or string outside of its bounds. Additionally, turn off the -check for zero divisor in integer division and modulus operations. -With -.BR \-unsafe , -an integer division (or modulus) by zero can halt the -program or continue with an unspecified result instead of raising a -.B Division_by_zero -exception. -.TP -.B \-unsafe\-string -Identify the types -.BR string \ and\ bytes , -thereby making strings writable. -This is intended for compatibility with old source code and should not -be used with new software. -.TP -.B \-v -Print the version number of the compiler and the location of the -standard library directory, then exit. -.TP -.B \-verbose -Print all external commands before they are executed, in particular -invocations of the assembler, C compiler, and linker. -.TP -.BR \-version \ or\ \-vnum -Print the version number of the compiler in short form (e.g. "3.11.0"), -then exit. -.TP -.BI \-w \ warning\-list -Enable, disable, or mark as fatal the warnings specified by the argument -.IR warning\-list . -See -.BR ocamlc (1) -for the syntax of -.IR warning-list . -.TP -.BI \-warn\-error \ warning\-list -Mark as fatal the warnings specified in the argument -.IR warning\-list . -The compiler will stop with an error when one of these -warnings is emitted. The -.I warning\-list -has the same meaning as for -the -.B \-w -option: a -.B + -sign (or an uppercase letter) marks the corresponding warnings as fatal, a -.B \- -sign (or a lowercase letter) turns them back into non-fatal warnings, and a -.B @ -sign both enables and marks as fatal the corresponding warnings. - -Note: it is not recommended to use the -.B \-warn\-error -option in production code, because it will almost certainly prevent -compiling your program with later versions of OCaml when they add new -warnings or modify existing warnings. - -The default setting is -.B \-warn\-error \-a+31 -(only warning 31 is fatal). -.TP -.B \-warn\-help -Show the description of all available warning numbers. -.TP -.B \-where -Print the location of the standard library, then exit. -.TP -.B \-with-runtime -Include the runtime system in the generated program. This is the default. -.TP -.B \-without-runtime -The compiler does not include the runtime system (nor a reference to it) in the -generated program; it must be supplied separately. -.TP -.BI \- \ file -Process -.I file -as a file name, even if it starts with a dash (-) character. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH OPTIONS FOR THE IA32 ARCHITECTURE - -The IA32 code generator (Intel Pentium, AMD Athlon) supports the -following additional option: -.TP -.B \-ffast\-math -Use the IA32 instructions to compute -trigonometric and exponential functions, instead of calling the -corresponding library routines. The functions affected are: -.BR atan , -.BR atan2 , -.BR cos , -.BR log , -.BR log10 , -.BR sin , -.B sqrt -and -.BR tan . -The resulting code runs faster, but the range of supported arguments -and the precision of the result can be reduced. In particular, -trigonometric operations -.BR cos , -.BR sin , -.B tan -have their range reduced to [\-2^64, 2^64]. - -.SH OPTIONS FOR THE AMD64 ARCHITECTURE - -The AMD64 code generator (64-bit versions of Intel Pentium and AMD -Athlon) supports the following additional options: -.TP -.B \-fPIC -Generate position-independent machine code. This is the default. -.TP -.B \-fno\-PIC -Generate position-dependent machine code. - -.SH OPTIONS FOR THE POWER ARCHITECTURE - -The PowerPC code generator supports the following additional options: -.TP -.B \-flarge\-toc -Enables the PowerPC large model allowing the TOC (table of contents) to be -arbitrarily large. This is the default since 4.11. -.TP -.B \-fsmall\-toc -Enables the PowerPC small model allowing the TOC to be up to 64 kbytes per -compilation unit. Prior to 4.11 this was the default behaviour. -\end{options} - -.SH OPTIONS FOR THE ARM ARCHITECTURE -The ARM code generator supports the following additional options: -.TP -.B \-farch=armv4|armv5|armv5te|armv6|armv6t2|armv7 -Select the ARM target architecture -.TP -.B \-ffpu=soft|vfpv2|vfpv3\-d16|vfpv3 -Select the floating-point hardware -.TP -.B \-fPIC -Generate position-independent machine code. -.TP -.B \-fno\-PIC -Generate position-dependent machine code. This is the default. -.TP -.B \-fthumb -Enable Thumb/Thumb-2 code generation -.TP -.B \-fno\-thumb -Disable Thumb/Thumb-2 code generation -.P -The default values for target architecture, floating-point hardware -and thumb usage were selected at configure-time when building -.B ocamlopt -itself. This configuration can be inspected using -.BR ocamlopt\ \-config . -Target architecture depends on the "model" setting, while -floating-point hardware and thumb support are determined from the ABI -setting in "system" ( -.BR linux_eabi or linux_eabihf ). - -.SH SEE ALSO -.BR ocamlc (1). -.br -.IR "The OCaml user's manual" , -chapter "Native-code compilation". diff --git a/man/ocamlopt.opt.1 b/man/ocamlopt.opt.1 new file mode 100644 index 0000000000..f548264fa1 --- /dev/null +++ b/man/ocamlopt.opt.1 @@ -0,0 +1 @@ +.so man1/ocamlopt.1 diff --git a/man/ocamloptp.1 b/man/ocamloptp.1 new file mode 100644 index 0000000000..bfd9d3e31a --- /dev/null +++ b/man/ocamloptp.1 @@ -0,0 +1 @@ +.so man1/ocamlcp.1 diff --git a/man/ocamlprof.1 b/man/ocamlprof.1 new file mode 100644 index 0000000000..97d5671441 --- /dev/null +++ b/man/ocamlprof.1 @@ -0,0 +1,87 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLPROF 1 + +.SH NAME +ocamlprof \- The OCaml profiler + +.SH SYNOPSIS +.B ocamlprof +[ +.I options +] +.I filename ... + +.SH DESCRIPTION +The +.B ocamlprof +command prints execution counts gathered during the execution of a +OCaml program instrumented with +.BR ocamlcp (1). + +It produces a source listing of the program modules given as arguments +where execution counts have been inserted as comments. For instance, + +.B ocamlprof foo.ml + +prints the source code for the foo module, with comments indicating +how many times the functions in this module have been called. Naturally, +this information is accurate only if the source file has not been modified +since the profiling execution took place. + +.SH OPTIONS + +.TP +.BI \-f \ dumpfile +Specifies an alternate dump file of profiling information. +.TP +.BI \-F \ string +Specifies an additional string to be output with profiling information. +By default, +.BR ocamlprof (1) +will annotate programs with comments of the form +.BI (* \ n \ *) +where +.I n +is the counter value for a profiling point. With option +.BI \-F \ s +the annotation will be +.BI (* \ sn \ *) +.TP +.BI \-impl \ filename +Compile the file +.I filename +as an implementation file, even if its extension is not .ml. +.TP +.BI \-intf \ filename +Compile the file +.I filename +as an interface file, even if its extension is not .mli. +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.BR \-help \ or \ \-\-help +Display a short usage summary and exit. + +.SH SEE ALSO +.BR ocamlcp (1). +.br +.IR "The OCaml user's manual" , +chapter "Profiling". diff --git a/man/ocamlprof.m b/man/ocamlprof.m deleted file mode 100644 index 97d5671441..0000000000 --- a/man/ocamlprof.m +++ /dev/null @@ -1,87 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLPROF 1 - -.SH NAME -ocamlprof \- The OCaml profiler - -.SH SYNOPSIS -.B ocamlprof -[ -.I options -] -.I filename ... - -.SH DESCRIPTION -The -.B ocamlprof -command prints execution counts gathered during the execution of a -OCaml program instrumented with -.BR ocamlcp (1). - -It produces a source listing of the program modules given as arguments -where execution counts have been inserted as comments. For instance, - -.B ocamlprof foo.ml - -prints the source code for the foo module, with comments indicating -how many times the functions in this module have been called. Naturally, -this information is accurate only if the source file has not been modified -since the profiling execution took place. - -.SH OPTIONS - -.TP -.BI \-f \ dumpfile -Specifies an alternate dump file of profiling information. -.TP -.BI \-F \ string -Specifies an additional string to be output with profiling information. -By default, -.BR ocamlprof (1) -will annotate programs with comments of the form -.BI (* \ n \ *) -where -.I n -is the counter value for a profiling point. With option -.BI \-F \ s -the annotation will be -.BI (* \ sn \ *) -.TP -.BI \-impl \ filename -Compile the file -.I filename -as an implementation file, even if its extension is not .ml. -.TP -.BI \-intf \ filename -Compile the file -.I filename -as an interface file, even if its extension is not .mli. -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.BR \-help \ or \ \-\-help -Display a short usage summary and exit. - -.SH SEE ALSO -.BR ocamlcp (1). -.br -.IR "The OCaml user's manual" , -chapter "Profiling". diff --git a/man/ocamlrun.1 b/man/ocamlrun.1 new file mode 100644 index 0000000000..78216f2eb5 --- /dev/null +++ b/man/ocamlrun.1 @@ -0,0 +1,313 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLRUN 1 + +.SH NAME +ocamlrun \- The OCaml bytecode interpreter + +.SH SYNOPSIS +.B ocamlrun +[ +.I options +] +.I filename argument ... + +.SH DESCRIPTION +The +.BR ocamlrun (1) +command executes bytecode files produced by the +linking phase of the +.BR ocamlc (1) +command. + +The first non-option argument is taken to be the name of the file +containing the executable bytecode. (That file is searched in the +executable path as well as in the current directory.) The remaining +arguments are passed to the OCaml program, in the string array +.BR Sys.argv . +Element 0 of this array is the name of the +bytecode executable file; elements 1 to +.I n +are the remaining arguments. + +In most cases, the bytecode +executable files produced by the +.BR ocamlc (1) +command are self-executable, +and manage to launch the +.BR ocamlrun (1) +command on themselves automatically. + +.SH OPTIONS + +The following command-line options are recognized by +.BR ocamlrun (1). +.TP +.B \-b +When the program aborts due to an uncaught exception, print a detailed +"back trace" of the execution, showing where the exception was +raised and which function calls were outstanding at this point. The +back trace is printed only if the bytecode executable contains +debugging information, i.e. was compiled and linked with the +.B \-g +option to +.BR ocamlc (1) +set. This option is equivalent to setting the +.B b +flag in the OCAMLRUNPARAM environment variable (see below). +.TP +.BI \-I \ dir +Search the directory +.I dir +for dynamically-loaded libraries, in addition to the standard search path. +.TP +.BI \-m \ file +Print the magic number of the bytecode executable +.I file +and exit. +.TP +.B \-M +Print the magic number expected for bytecode executables by this version +of the runtime and exit. +.TP +.B \-p +Print the names of the primitives known to this version of +.BR ocamlrun (1) +and exit. +.TP +.B \-t +Increment the trace level for the debug runtime (ignored by the standard +runtime). +.TP +.B \-v +Direct the memory manager to print verbose messages on standard error. +This is equivalent to setting +.B v=63 +in the OCAMLRUNPARAM environment variable (see below). +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. + +.SH ENVIRONMENT VARIABLES + +The following environment variable are also consulted: +.TP +.B CAML_LD_LIBRARY_PATH +Additional directories to search for dynamically-loaded libraries. +.TP +.B OCAMLLIB +The directory containing the OCaml standard +library. (If +.B OCAMLLIB +is not set, +.B CAMLLIB +will be used instead.) Used to locate the ld.conf configuration file for +dynamic loading. If not set, +default to the library directory specified when compiling OCaml. +.TP +.B OCAMLRUNPARAM +Set the runtime system options and garbage collection parameters. +(If OCAMLRUNPARAM is not set, CAMLRUNPARAM will be used instead.) +This variable must be a sequence of parameter specifications separated +by commas. +A parameter specification is a letter, optionally followed by an = +sign, a decimal number (or a hexadecimal number prefixed by +.BR 0x ), +and an optional multiplier. If the letter is followed by anything +else, the corresponding option is set to 1. Unknown letters +are ignored. +The options are documented below; the options +.B a, i, l, m, M, n, o, O, s, v, w +correspond to the fields of the +.B control +record documented in +.IR "The OCaml user's manual", +chapter "Standard Library", section "Gc". + +.RS 7 +.TP +.BR a \ (allocation_policy) +The policy used for allocating in the OCaml heap. Possible values +are 0 for the next-fit policy, 1 for the first-fit +policy, and 2 for the best-fit policy. The default is 2. +See the Gc module documentation for details. +.TP +.B b +Trigger the printing of a stack backtrace +when an uncaught exception aborts the program. +This option takes no argument. +.TP +.B c +(cleanup_on_exit) Shut the runtime down gracefully on exit. The option +also enables pooling (as in caml_startup_pooled). This mode can be used +to detect leaks with a third-party memory debugger. +.TP +.BR h +The initial size of the major heap (in words). +.TP +.BR H +Allocate heap chunks by mmapping huge pages. Huge pages are locked into +memory, and are not swapped. +.TP +.BR i \ (major_heap_increment) +The default size increment for the major heap (in words if greater than 1000, +else in percents of the heap size). +.TP +.BR l \ (stack_limit) +The limit (in words) of the stack size. +.TP +.BR m \ (custom_minor_ratio) +Bound on floating garbage for out-of-heap memory +held by custom values in the minor heap. A minor GC is triggered +when this much memory is held by custom values located in the minor +heap. Expressed as a percentage of minor heap size. +Note: this only applies to values allocated with +.B caml_alloc_custom_mem +(e.g. bigarrays). + Default: 100. +.TP +.BR M \ (custom_major_ratio) +Target ratio of floating garbage to +major heap size for out-of-heap memory held by custom values +located in the major heap. The GC speed is adjusted +to try to use this much memory for dead values that are not yet +collected. Expressed as a percentage of major heap size. +The default value keeps the out-of-heap floating garbage about the +same size as the in-heap overhead. +Note: this only applies to values allocated with +.B caml_alloc_custom_mem +(e.g. bigarrays). +Default: 44. +.TP +.BR n \ (custom_minor_max_size) +Maximum amount of out-of-heap +memory for each custom value allocated in the minor heap. When a custom +value is allocated on the minor heap and holds more than this many +bytes, only this value is counted against +.B custom_minor_ratio +and the rest is directly counted against +.BR custom_major_ratio . +Note: this only applies to values allocated with +.B caml_alloc_custom_mem +(e.g. bigarrays). +Default: 8192 bytes. +.TP +.BR o \ (space_overhead) +The major GC speed setting. +.TP +.BR O \ (max_overhead) +The heap compaction trigger setting. +.TP +.B p +Turn on debugging support for +.BR ocamlyacc -generated +parsers. When this option is on, +the pushdown automaton that executes the parsers prints a +trace of its actions. This option takes no argument. +.TP +.BR R +Turn on randomization of all hash tables by default (see the +.B Hashtbl +module of the standard library). This option takes no +argument. +.TP +.BR s \ (minor_heap_size) +The size of the minor heap (in words). +.TP +.B t +Set the trace level for the debug runtime (ignored by the standard +runtime). +.TP +.BR v \ (verbose) +What GC messages to print to stderr. This is a sum of values selected +from the following: + +.B 0x001 +Start and end of major GC cycle. + +.B 0x002 +Minor collection and major GC slice. + +.B 0x004 +Growing and shrinking of the heap. + +.B 0x008 +Resizing of stacks and memory manager tables. + +.B 0x010 +Heap compaction. + +.BR 0x020 +Change of GC parameters. + +.BR 0x040 +Computation of major GC slice size. + +.BR 0x080 +Calling of finalisation functions. + +.BR 0x100 +Startup messages (loading the bytecode executable file, resolving +shared libraries). + +.BR 0x200 +Computation of compaction-triggering condition. + +.BR 0x400 +Output GC statistics at program exit, in the same format as Gc.print_stat. +.TP +.BR w \ (window_size) +Set size of the window used by major GC for smoothing out variations in +its workload. This is an integer between 1 and 50. (Default: 1) +.TP +.BR W +Print runtime warnings to stderr (such as Channel opened on file dies without +being closed, unflushed data, etc.) + +.RS 0 +The multiplier is +.BR k , +.BR M ,\ or +.BR G , +for multiplication by 2^10, 2^20, and 2^30 respectively. + +If the option letter is not recognized, the whole parameter is ignored; +if the equal sign or the number is missing, the value is taken as 1; +if the multiplier is not recognized, it is ignored. + +For example, on a 32-bit machine under bash, the command +.B export OCAMLRUNPARAM='s=256k,v=1' +tells a subsequent +.B ocamlrun +to set its initial minor heap size to 1 megabyte and to print +a message at the start of each major GC cycle. +.TP +.B CAMLRUNPARAM +If OCAMLRUNPARAM is not found in the environment, then CAMLRUNPARAM +will be used instead. If CAMLRUNPARAM is also not found, then the default +values will be used. +.TP +.B PATH +List of directories searched to find the bytecode executable file. + +.SH SEE ALSO +.BR ocamlc (1). +.br +.IR "The OCaml user's manual" , +chapter "Runtime system". diff --git a/man/ocamlrun.m b/man/ocamlrun.m deleted file mode 100644 index 78216f2eb5..0000000000 --- a/man/ocamlrun.m +++ /dev/null @@ -1,313 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLRUN 1 - -.SH NAME -ocamlrun \- The OCaml bytecode interpreter - -.SH SYNOPSIS -.B ocamlrun -[ -.I options -] -.I filename argument ... - -.SH DESCRIPTION -The -.BR ocamlrun (1) -command executes bytecode files produced by the -linking phase of the -.BR ocamlc (1) -command. - -The first non-option argument is taken to be the name of the file -containing the executable bytecode. (That file is searched in the -executable path as well as in the current directory.) The remaining -arguments are passed to the OCaml program, in the string array -.BR Sys.argv . -Element 0 of this array is the name of the -bytecode executable file; elements 1 to -.I n -are the remaining arguments. - -In most cases, the bytecode -executable files produced by the -.BR ocamlc (1) -command are self-executable, -and manage to launch the -.BR ocamlrun (1) -command on themselves automatically. - -.SH OPTIONS - -The following command-line options are recognized by -.BR ocamlrun (1). -.TP -.B \-b -When the program aborts due to an uncaught exception, print a detailed -"back trace" of the execution, showing where the exception was -raised and which function calls were outstanding at this point. The -back trace is printed only if the bytecode executable contains -debugging information, i.e. was compiled and linked with the -.B \-g -option to -.BR ocamlc (1) -set. This option is equivalent to setting the -.B b -flag in the OCAMLRUNPARAM environment variable (see below). -.TP -.BI \-I \ dir -Search the directory -.I dir -for dynamically-loaded libraries, in addition to the standard search path. -.TP -.BI \-m \ file -Print the magic number of the bytecode executable -.I file -and exit. -.TP -.B \-M -Print the magic number expected for bytecode executables by this version -of the runtime and exit. -.TP -.B \-p -Print the names of the primitives known to this version of -.BR ocamlrun (1) -and exit. -.TP -.B \-t -Increment the trace level for the debug runtime (ignored by the standard -runtime). -.TP -.B \-v -Direct the memory manager to print verbose messages on standard error. -This is equivalent to setting -.B v=63 -in the OCAMLRUNPARAM environment variable (see below). -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. - -.SH ENVIRONMENT VARIABLES - -The following environment variable are also consulted: -.TP -.B CAML_LD_LIBRARY_PATH -Additional directories to search for dynamically-loaded libraries. -.TP -.B OCAMLLIB -The directory containing the OCaml standard -library. (If -.B OCAMLLIB -is not set, -.B CAMLLIB -will be used instead.) Used to locate the ld.conf configuration file for -dynamic loading. If not set, -default to the library directory specified when compiling OCaml. -.TP -.B OCAMLRUNPARAM -Set the runtime system options and garbage collection parameters. -(If OCAMLRUNPARAM is not set, CAMLRUNPARAM will be used instead.) -This variable must be a sequence of parameter specifications separated -by commas. -A parameter specification is a letter, optionally followed by an = -sign, a decimal number (or a hexadecimal number prefixed by -.BR 0x ), -and an optional multiplier. If the letter is followed by anything -else, the corresponding option is set to 1. Unknown letters -are ignored. -The options are documented below; the options -.B a, i, l, m, M, n, o, O, s, v, w -correspond to the fields of the -.B control -record documented in -.IR "The OCaml user's manual", -chapter "Standard Library", section "Gc". - -.RS 7 -.TP -.BR a \ (allocation_policy) -The policy used for allocating in the OCaml heap. Possible values -are 0 for the next-fit policy, 1 for the first-fit -policy, and 2 for the best-fit policy. The default is 2. -See the Gc module documentation for details. -.TP -.B b -Trigger the printing of a stack backtrace -when an uncaught exception aborts the program. -This option takes no argument. -.TP -.B c -(cleanup_on_exit) Shut the runtime down gracefully on exit. The option -also enables pooling (as in caml_startup_pooled). This mode can be used -to detect leaks with a third-party memory debugger. -.TP -.BR h -The initial size of the major heap (in words). -.TP -.BR H -Allocate heap chunks by mmapping huge pages. Huge pages are locked into -memory, and are not swapped. -.TP -.BR i \ (major_heap_increment) -The default size increment for the major heap (in words if greater than 1000, -else in percents of the heap size). -.TP -.BR l \ (stack_limit) -The limit (in words) of the stack size. -.TP -.BR m \ (custom_minor_ratio) -Bound on floating garbage for out-of-heap memory -held by custom values in the minor heap. A minor GC is triggered -when this much memory is held by custom values located in the minor -heap. Expressed as a percentage of minor heap size. -Note: this only applies to values allocated with -.B caml_alloc_custom_mem -(e.g. bigarrays). - Default: 100. -.TP -.BR M \ (custom_major_ratio) -Target ratio of floating garbage to -major heap size for out-of-heap memory held by custom values -located in the major heap. The GC speed is adjusted -to try to use this much memory for dead values that are not yet -collected. Expressed as a percentage of major heap size. -The default value keeps the out-of-heap floating garbage about the -same size as the in-heap overhead. -Note: this only applies to values allocated with -.B caml_alloc_custom_mem -(e.g. bigarrays). -Default: 44. -.TP -.BR n \ (custom_minor_max_size) -Maximum amount of out-of-heap -memory for each custom value allocated in the minor heap. When a custom -value is allocated on the minor heap and holds more than this many -bytes, only this value is counted against -.B custom_minor_ratio -and the rest is directly counted against -.BR custom_major_ratio . -Note: this only applies to values allocated with -.B caml_alloc_custom_mem -(e.g. bigarrays). -Default: 8192 bytes. -.TP -.BR o \ (space_overhead) -The major GC speed setting. -.TP -.BR O \ (max_overhead) -The heap compaction trigger setting. -.TP -.B p -Turn on debugging support for -.BR ocamlyacc -generated -parsers. When this option is on, -the pushdown automaton that executes the parsers prints a -trace of its actions. This option takes no argument. -.TP -.BR R -Turn on randomization of all hash tables by default (see the -.B Hashtbl -module of the standard library). This option takes no -argument. -.TP -.BR s \ (minor_heap_size) -The size of the minor heap (in words). -.TP -.B t -Set the trace level for the debug runtime (ignored by the standard -runtime). -.TP -.BR v \ (verbose) -What GC messages to print to stderr. This is a sum of values selected -from the following: - -.B 0x001 -Start and end of major GC cycle. - -.B 0x002 -Minor collection and major GC slice. - -.B 0x004 -Growing and shrinking of the heap. - -.B 0x008 -Resizing of stacks and memory manager tables. - -.B 0x010 -Heap compaction. - -.BR 0x020 -Change of GC parameters. - -.BR 0x040 -Computation of major GC slice size. - -.BR 0x080 -Calling of finalisation functions. - -.BR 0x100 -Startup messages (loading the bytecode executable file, resolving -shared libraries). - -.BR 0x200 -Computation of compaction-triggering condition. - -.BR 0x400 -Output GC statistics at program exit, in the same format as Gc.print_stat. -.TP -.BR w \ (window_size) -Set size of the window used by major GC for smoothing out variations in -its workload. This is an integer between 1 and 50. (Default: 1) -.TP -.BR W -Print runtime warnings to stderr (such as Channel opened on file dies without -being closed, unflushed data, etc.) - -.RS 0 -The multiplier is -.BR k , -.BR M ,\ or -.BR G , -for multiplication by 2^10, 2^20, and 2^30 respectively. - -If the option letter is not recognized, the whole parameter is ignored; -if the equal sign or the number is missing, the value is taken as 1; -if the multiplier is not recognized, it is ignored. - -For example, on a 32-bit machine under bash, the command -.B export OCAMLRUNPARAM='s=256k,v=1' -tells a subsequent -.B ocamlrun -to set its initial minor heap size to 1 megabyte and to print -a message at the start of each major GC cycle. -.TP -.B CAMLRUNPARAM -If OCAMLRUNPARAM is not found in the environment, then CAMLRUNPARAM -will be used instead. If CAMLRUNPARAM is also not found, then the default -values will be used. -.TP -.B PATH -List of directories searched to find the bytecode executable file. - -.SH SEE ALSO -.BR ocamlc (1). -.br -.IR "The OCaml user's manual" , -chapter "Runtime system". diff --git a/man/ocamlyacc.1 b/man/ocamlyacc.1 new file mode 100644 index 0000000000..f522d5cc26 --- /dev/null +++ b/man/ocamlyacc.1 @@ -0,0 +1,112 @@ +.\"************************************************************************** +.\"* * +.\"* OCaml * +.\"* * +.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * +.\"* * +.\"* Copyright 1996 Institut National de Recherche en Informatique et * +.\"* en Automatique. * +.\"* * +.\"* All rights reserved. This file is distributed under the terms of * +.\"* the GNU Lesser General Public License version 2.1, with the * +.\"* special exception on linking described in the file LICENSE. * +.\"* * +.\"************************************************************************** +.\" +.TH OCAMLYACC 1 + +.SH NAME +ocamlyacc \- The OCaml parser generator + +.SH SYNOPSIS +.B ocamlyacc +[ +.BI \-b prefix +] [ +.B \-q +] [ +.B \-v +] [ +.B \-version +] [ +.B \-vnum +] +.I filename.mly + +.SH DESCRIPTION + +The +.BR ocamlyacc (1) +command produces a parser from a LALR(1) context-free grammar +specification with attached semantic actions, in the style of +.BR yacc (1). +Assuming the input file is +.IR grammar \&.mly, +running +.B ocamlyacc +produces OCaml code for a parser in the file +.IR grammar \&.ml, +and its interface in file +.IR grammar \&.mli. + +The generated module defines one parsing function per entry point in +the grammar. These functions have the same names as the entry points. +Parsing functions take as arguments a lexical analyzer (a function +from lexer buffers to tokens) and a lexer buffer, and return the +semantic attribute of the corresponding entry point. Lexical analyzer +functions are usually generated from a lexer specification by the +.BR ocamllex (1) +program. Lexer buffers are an abstract data type +implemented in the standard library module Lexing. Tokens are values from +the concrete type token, defined in the interface file +.IR grammar \&.mli +produced by +.BR ocamlyacc (1). + +.SH OPTIONS + +The +.BR ocamlyacc (1) +command recognizes the following options: +.TP +.BI \-b prefix +Name the output files +.IR prefix \&.ml, +.IR prefix \&.mli, +.IR prefix \&.output, +instead of the default naming convention. +.TP +.B \-q +This option has no effect. +.TP +.B \--strict +Reject grammars with conflicts. +.TP +.B \-v +Generate a description of the parsing tables and a report on conflicts +resulting from ambiguities in the grammar. The description is put in +file +.IR grammar .output. +.TP +.B \-version +Print version string and exit. +.TP +.B \-vnum +Print short version number and exit. +.TP +.B \- +Read the grammar specification from standard input. The default +output file names are stdin.ml and stdin.mli. +.TP +.BI \-\- \ file +Process +.I file +as the grammar specification, even if its name +starts with a dash (-) character. This option must be the last on the +command line. + +.SH SEE ALSO +.BR ocamllex (1). +.br +.IR "The OCaml user's manual" , +chapter "Lexer and parser generators". diff --git a/man/ocamlyacc.m b/man/ocamlyacc.m deleted file mode 100644 index f522d5cc26..0000000000 --- a/man/ocamlyacc.m +++ /dev/null @@ -1,112 +0,0 @@ -.\"************************************************************************** -.\"* * -.\"* OCaml * -.\"* * -.\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt * -.\"* * -.\"* Copyright 1996 Institut National de Recherche en Informatique et * -.\"* en Automatique. * -.\"* * -.\"* All rights reserved. This file is distributed under the terms of * -.\"* the GNU Lesser General Public License version 2.1, with the * -.\"* special exception on linking described in the file LICENSE. * -.\"* * -.\"************************************************************************** -.\" -.TH OCAMLYACC 1 - -.SH NAME -ocamlyacc \- The OCaml parser generator - -.SH SYNOPSIS -.B ocamlyacc -[ -.BI \-b prefix -] [ -.B \-q -] [ -.B \-v -] [ -.B \-version -] [ -.B \-vnum -] -.I filename.mly - -.SH DESCRIPTION - -The -.BR ocamlyacc (1) -command produces a parser from a LALR(1) context-free grammar -specification with attached semantic actions, in the style of -.BR yacc (1). -Assuming the input file is -.IR grammar \&.mly, -running -.B ocamlyacc -produces OCaml code for a parser in the file -.IR grammar \&.ml, -and its interface in file -.IR grammar \&.mli. - -The generated module defines one parsing function per entry point in -the grammar. These functions have the same names as the entry points. -Parsing functions take as arguments a lexical analyzer (a function -from lexer buffers to tokens) and a lexer buffer, and return the -semantic attribute of the corresponding entry point. Lexical analyzer -functions are usually generated from a lexer specification by the -.BR ocamllex (1) -program. Lexer buffers are an abstract data type -implemented in the standard library module Lexing. Tokens are values from -the concrete type token, defined in the interface file -.IR grammar \&.mli -produced by -.BR ocamlyacc (1). - -.SH OPTIONS - -The -.BR ocamlyacc (1) -command recognizes the following options: -.TP -.BI \-b prefix -Name the output files -.IR prefix \&.ml, -.IR prefix \&.mli, -.IR prefix \&.output, -instead of the default naming convention. -.TP -.B \-q -This option has no effect. -.TP -.B \--strict -Reject grammars with conflicts. -.TP -.B \-v -Generate a description of the parsing tables and a report on conflicts -resulting from ambiguities in the grammar. The description is put in -file -.IR grammar .output. -.TP -.B \-version -Print version string and exit. -.TP -.B \-vnum -Print short version number and exit. -.TP -.B \- -Read the grammar specification from standard input. The default -output file names are stdin.ml and stdin.mli. -.TP -.BI \-\- \ file -Process -.I file -as the grammar specification, even if its name -starts with a dash (-) character. This option must be the last on the -command line. - -.SH SEE ALSO -.BR ocamllex (1). -.br -.IR "The OCaml user's manual" , -chapter "Lexer and parser generators". -- cgit v1.2.1