1OCAML(1)                    General Commands Manual                   OCAML(1)
2
3
4

NAME

6       ocaml - The OCaml interactive toplevel
7
8

SYNOPSIS

10       ocaml [ options ] [ object-files ] [ script-file ]
11

DESCRIPTION

13       The  ocaml(1)  command  is  the toplevel system for OCaml, that permits
14       interactive use of the OCaml system through a read-eval-print loop.  In
15       this  mode,  the  system repeatedly reads OCaml phrases from the input,
16       then typechecks, compiles and evaluates them, then prints the  inferred
17       type  and  result  value,  if  any. The system prints a # (hash) prompt
18       before reading each phrase.
19
20       A toplevel phrase can span several lines. It is  terminated  by  ;;  (a
21       double-semicolon). The syntax of toplevel phrases is as follows.
22
23       The  toplevel  system  is started by the command ocaml(1).  Phrases are
24       read on standard input, results are printed on standard output,  errors
25       on standard error. End-of-file on standard input terminates ocaml(1).
26
27       If  one  or  more object-files (ending in .cmo or .cma) are given, they
28       are loaded silently before starting the toplevel.
29
30       If a script-file is given, phrases are read  silently  from  the  file,
31       errors  printed  on standard error.  ocaml(1) exits after the execution
32       of the last phrase.
33
34

OPTIONS

36       The following command-line options are recognized by ocaml(1).
37
38       -absname
39              Show absolute filenames in error messages.
40
41       -I directory
42              Add the given directory to the list of directories searched  for
43              source  and compiled files. By default, the current directory is
44              searched first, then the standard library directory. Directories
45              added  with  -I are searched after the current directory, in the
46              order in which they were given on the command line,  but  before
47              the standard library directory.
48
49              If  the  given  directory starts with +, it is taken relative to
50              the standard library directory. For instance,  -I +compiler-libs
51              adds  the  subdirectory compiler-libs of the standard library to
52              the search path.
53
54              Directories can also be  added  to  the  search  path  once  the
55              toplevel is running with the #directory directive.
56
57       -init file
58              Load  the given file instead of the default initialization file.
59              See the "Initialization file" section below.
60
61       -labels
62              Labels are not ignored in types, labels may be used in  applica‐
63              tions,  and labelled parameters can be given in any order.  This
64              is the default.
65
66       -no-app-funct
67              Deactivates the applicative behaviour  of  functors.  With  this
68              option,  each  functor  application  generates  new types in its
69              result and applying the same functor twice to the same  argument
70              yields two incompatible structures.
71
72       -noassert
73              Do  not  compile  assertion  checks.  Note that the special form
74              assert false is always compiled because it is typed specially.
75
76       -noinit
77              Do not load any initialization file.   See  the  "Initialization
78              file" section below.
79
80       -nolabels
81              Ignore  non-optional  labels  in types. Labels cannot be used in
82              applications, and parameter order becomes strict.
83
84       -noprompt
85              Do not display any prompt when waiting for input.
86
87       -nopromptcont
88              Do not display the secondary prompt when waiting  for  continua‐
89              tion  lines in multi-line inputs.  This should be used e.g. when
90              running ocaml(1) in an emacs(1) window.
91
92       -nostdlib
93              Do not include the standard library directory  in  the  list  of
94              directories searched for source and compiled files.
95
96       -open module
97              Opens  the given module before starting the toplevel. If several
98              -open options are given, they are processed in order, just as if
99              the statements open! module1;; ... open! moduleN;; were input.
100
101       -ppx command
102              After  parsing,  pipe  the abstract syntax tree through the pre‐
103              processor command.   The  module  Ast_mapper(3)  implements  the
104              external interface of a preprocessor.
105
106       -principal
107              Check  information  path during type-checking, to make sure that
108              all types are derived in a principal way.  When  using  labelled
109              arguments  and/or  polymorphic methods, this flag is required to
110              ensure future versions of the compiler will  be  able  to  infer
111              types  correctly,  even if internal algorithms change.  All pro‐
112              grams accepted in -principal  mode  are  also  accepted  in  the
113              default  mode with equivalent types, but different binary signa‐
114              tures, and this may slow down type checking; yet it  is  a  good
115              idea to use it once before publishing source code.
116
117       -rectypes
118              Allow   arbitrary  recursive  types  during  type-checking.   By
119              default, only recursive types where the recursion  goes  through
120              an object type are supported.
121
122       -safe-string
123              Enforce  the  separation between types string and bytes, thereby
124              making strings read-only. This is the default.
125
126       -short-paths
127              When a type is  visible  under  several  module-paths,  use  the
128              shortest  one  when  printing the type's name in inferred inter‐
129              faces and error and warning messages.
130
131       -stdin Read the standard input as a script file rather than starting an
132              interactive session.
133
134       -strict-sequence
135              Force the left-hand part of each sequence to have type unit.
136
137       -unboxed-types
138              When  a  type is unboxable (i.e. a record with a single argument
139              or a concrete datatype with a single constructor  of  one  argu‐
140              ment) it will be unboxed unless annotated with [@@ocaml.boxed].
141
142       -no-unboxed-types
143              When a type is unboxable  it will be boxed unless annotated with
144              [@@ocaml.unboxed].  This is the default.
145
146       -unsafe
147              Turn bound checking  off  on  array  and  string  accesses  (the
148              v.(i)ands.[i]  constructs).  Programs  compiled with -unsafe are
149              therefore slightly faster, but unsafe: anything  can  happen  if
150              the program accesses an array or string outside of its bounds.
151
152       -unsafe-string
153              Identify  the  types  string and bytes,  thereby  making strings
154              writable.  This is intended for compatibility  with  old  source
155              code and should not be used with new software.
156
157       -version
158              Print version string and exit.
159
160       -vnum  Print short version number and exit.
161
162       -no-version
163              Do not print the version banner at startup.
164
165       -w warning-list
166              Enable  or  disable  warnings according to the argument warning-
167              list.  See ocamlc(1) for the syntax of  the  warning-list  argu‐
168              ment.
169
170       -warn-error warning-list
171              Mark  as  fatal  the  warnings  described  by the argument warn‐
172              ing-list.  Note that a warning is not triggered  (and  does  not
173              trigger  an  error)  if  it  is  disabled by the -w option.  See
174              ocamlc(1) for the syntax of the warning-list argument.
175
176       -color mode
177              Enable or disable colors in compiler messages (especially  warn‐
178              ings and errors).  The following modes are supported:
179
180              auto use heuristics to enable colors only if the output supports
181              them (an ANSI-compatible tty terminal);
182
183              always enable colors unconditionally;
184
185              never disable color output.
186
187              The default setting is auto, and the  current  heuristic  checks
188              that  the "TERM" environment variable exists and is not empty or
189              "dumb", and that isatty(stderr) holds.
190
191              The environment variable "OCAML_COLOR" is considered  if  -color
192              is not provided. Its values are auto/always/never as above.
193
194
195       -error-style mode
196              Control  the  way  error messages and warnings are printed.  The
197              following modes are supported:
198
199              short only print the error and its location;
200
201              contextual like "short", but also display the source code  snip‐
202              pet corresponding to the location of the error.
203
204              The default setting is contextual.
205
206              The  environment  variable  "OCAML_ERROR_STYLE" is considered if
207              -error-style is not provided. Its values are short/contextual as
208              above.
209
210
211       -warn-help
212              Show the description of all available warning numbers.
213
214       - file Use  file  as  a  script  file  name, even when it starts with a
215              hyphen (-).
216
217       -help or --help
218              Display a short usage summary and exit.
219
220

INITIALIZATION FILE

222       When ocaml(1) is invoked, it will read phrases from  an  initialization
223       file  before giving control to the user. The default file is .ocamlinit
224       in  the  current   directory   if   it   exists,   otherwise   XDG_CON‐
225       FIG_HOME/ocaml/init.ml  according  to the XDG base directory specifica‐
226       tion lookup if it exists (on Windows this is skipped), otherwise .ocam‐
227       linit in the user's home directory ( HOME variable).  You can specify a
228       different initialization file by using the -init file option, and  dis‐
229       able initialization files by using the -noinit option.
230
231       Note  that  you  can also use the #use directive to read phrases from a
232       file.
233
234

ENVIRONMENT VARIABLES

236       OCAMLTOP_UTF_8
237              When printing string values, non-ascii bytes (>0x7E) are printed
238              as  decimal  escape  sequence if OCAMLTOP_UTF_8 is set to false.
239              Otherwise they are printed unescaped.
240
241       TERM   When printing error messages, the toplevel  system  attempts  to
242              underline  visually  the  location of the error. It consults the
243              TERM variable to determines the type of output terminal and look
244              up its capabilities in the terminal database.
245
246       XDG_CONFIG_HOME HOME
247              .ocamlinit lookup procedure (see above).
248

SEE ALSO

250       ocamlc(1), ocamlopt(1), ocamlrun(1).
251       The OCaml user's manual, chapter "The toplevel system".
252
253
254
255                                                                      OCAML(1)
Impressum