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 in‐
14       teractive 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 be‐
18       fore 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, er‐
31       rors  printed on standard error.  ocaml(1) exits after the execution of
32       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 op‐
68              tion, each functor application generates new types in its result
69              and applying the same functor twice to the same argument  yields
70              two incompatible structures.
71
72       -noassert
73              Do not compile assertion checks.  Note that the special form as‐
74              sert 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 di‐
94              rectories 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  ex‐
104              ternal 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  de‐
113              fault  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 de‐
119              fault, only recursive types where the recursion goes through  an
120              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 environment variable "OCAML_COLOR" is considered  if  -color
188              is not provided. Its values are auto/always/never as above.
189
190              If  -color is not provided, "OCAML_COLOR" is not set and the en‐
191              vironment variable "NO_COLOR" is set, then color output is  dis‐
192              abled.  Otherwise,  the default setting is auto, and the current
193              heuristic checks that the "TERM" environment variable exists and
194              is not empty or "dumb", and that isatty(stderr) holds.
195
196
197       -error-style mode
198              Control  the  way  error messages and warnings are printed.  The
199              following modes are supported:
200
201              short only print the error and its location;
202
203              contextual like "short", but also display the source code  snip‐
204              pet corresponding to the location of the error.
205
206              The default setting is contextual.
207
208              The  environment  variable  "OCAML_ERROR_STYLE" is considered if
209              -error-style is not provided. Its values are short/contextual as
210              above.
211
212
213       -warn-help
214              Show the description of all available warning numbers.
215
216       - file Use  file  as a script file name, even when it starts with a hy‐
217              phen (-).
218
219       -help or --help
220              Display a short usage summary and exit.
221
222

INITIALIZATION FILE

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

ENVIRONMENT VARIABLES

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

SEE ALSO

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