1 .\"**************************************************************************
2 .\"* *
3 .\"* OCaml *
4 .\"* *
5 .\"* Xavier Leroy, projet Cristal, INRIA Rocquencourt *
6 .\"* *
7 .\"* Copyright 1996 Institut National de Recherche en Informatique et *
8 .\"* en Automatique. *
9 .\"* *
10 .\"* All rights reserved. This file is distributed under the terms of *
11 .\"* the GNU Lesser General Public License version 2.1, with the *
12 .\"* special exception on linking described in the file LICENSE. *
13 .\"* *
14 .\"**************************************************************************
15 .\"
16 .TH OCAML 1
17
18 .SH NAME
19 ocaml \- The OCaml interactive toplevel
20
21 .SH SYNOPSIS
22 .B ocaml
23 [
24 .I options
25 ]
26 [
27 .I object-files
28 ]
29 [
30 .I script-file
31 ]
32 .SH DESCRIPTION
33
34 The
35 .BR ocaml (1)
36 command is the toplevel system for OCaml,
37 that permits interactive use of the OCaml system through a
38 read-eval-print loop. In this mode, the system repeatedly reads OCaml
39 phrases from the input, then typechecks, compiles and evaluates
40 them, then prints the inferred type and result value, if any. The
41 system prints a # (hash) prompt before reading each phrase.
42
43 A toplevel phrase can span several lines. It is terminated by ;; (a
44 double-semicolon). The syntax of toplevel phrases is as follows.
45
46 The toplevel system is started by the command
47 .BR ocaml (1).
48 Phrases are read on standard input, results are printed on standard
49 output, errors on standard error. End-of-file on standard input
50 terminates
51 .BR ocaml (1).
52
53 If one or more
54 .I object-files
55 (ending in .cmo or .cma) are given, they are loaded silently before
56 starting the toplevel.
57
58 If a
59 .I script-file
60 is given, phrases are read silently from the file, errors printed on
61 standard error.
62 .BR ocaml (1)
63 exits after the execution of the last phrase.
64
65 .SH OPTIONS
66
67 The following command-line options are recognized by
68 .BR ocaml (1).
69 .TP
70 .B \-absname
71 Show absolute filenames in error messages.
72 .TP
73 .BI \-I \ directory
74 Add the given directory to the list of directories searched for
75 source and compiled files. By default, the current directory is
76 searched first, then the standard library directory. Directories added
77 with
78 .B \-I
79 are searched after the current directory, in the order in which they
80 were given on the command line, but before the standard library
81 directory.
82 .IP
83 If the given directory starts with
84 .BR + ,
85 it is taken relative to the
86 standard library directory. For instance,
87 .B \-I\ +compiler-libs
88 adds the subdirectory
89 .B compiler-libs
90 of the standard library to the search path.
91 .IP
92 Directories can also be added to the search path once the toplevel
93 is running with the
94 .B #directory
95 directive.
96 .TP
97 .BI \-init \ file
98 Load the given file instead of the default initialization file.
99 See the "Initialization file" section below.
100 .TP
101 .B \-labels
102 Labels are not ignored in types, labels may be used in applications,
103 and labelled parameters can be given in any order. This is the default.
104 .TP
105 .B \-no\-app\-funct
106 Deactivates the applicative behaviour of functors. With this option,
107 each functor application generates new types in its result and
108 applying the same functor twice to the same argument yields two
109 incompatible structures.
110 .TP
111 .B \-noassert
112 Do not compile assertion checks. Note that the special form
113 .B assert\ false
114 is always compiled because it is typed specially.
115 .TP
116 .B \-noinit
117 Do not load any initialization file.
118 See the "Initialization file" section below.
119 .TP
120 .B \-nolabels
121 Ignore non-optional labels in types. Labels cannot be used in
122 applications, and parameter order becomes strict.
123 .TP
124 .B \-noprompt
125 Do not display any prompt when waiting for input.
126 .TP
127 .B \-nopromptcont
128 Do not display the secondary prompt when waiting for continuation lines in
129 multi-line inputs. This should be used e.g. when running
130 .BR ocaml (1)
131 in an
132 .BR emacs (1)
133 window.
134 .TP
135 .B \-nostdlib
136 Do not include the standard library directory in the list of
137 directories searched for source and compiled files.
138 .TP
139 .BI \-open \ module
140 Opens the given module before starting the toplevel. If several
141 .B \-open
142 options are given, they are processed in order, just as if
143 the statements open! module1;; ... open! moduleN;; were input.
144 .TP
145 .BI \-ppx \ command
146 After parsing, pipe the abstract syntax tree through the preprocessor
147 .IR command .
148 The module
149 .BR Ast_mapper (3)
150 implements the external interface of a preprocessor.
151 .TP
152 .B \-principal
153 Check information path during type-checking, to make sure that all
154 types are derived in a principal way. When using labelled arguments
155 and/or polymorphic methods, this flag is required to ensure future
156 versions of the compiler will be able to infer types correctly, even
157 if internal algorithms change.
158 All programs accepted in
159 .B \-principal
160 mode are also accepted in the
161 default mode with equivalent types, but different binary signatures,
162 and this may slow down type checking; yet it is a good idea to
163 use it once before publishing source code.
164 .TP
165 .B \-rectypes
166 Allow arbitrary recursive types during type-checking. By default,
167 only recursive types where the recursion goes through an object type
168 are supported.
169 .TP
170 .B \-safe\-string
171 Enforce the separation between types
172 .BR string \ and\ bytes ,
173 thereby making strings read-only. This is the default.
174 .TP
175 .B \-short\-paths
176 When a type is visible under several module-paths, use the shortest
177 one when printing the type's name in inferred interfaces and error and
178 warning messages.
179 .TP
180 .B \-stdin
181 Read the standard input as a script file rather than starting an
182 interactive session.
183 .TP
184 .B \-strict\-sequence
185 Force the left-hand part of each sequence to have type unit.
186 .TP
187 .B \-unboxed\-types
188 When a type is unboxable (i.e. a record with a single argument or a
189 concrete datatype with a single constructor of one argument) it will
190 be unboxed unless annotated with
191 .BR [@@ocaml.boxed] .
192 .TP
193 .B \-no-unboxed\-types
194 When a type is unboxable it will be boxed unless annotated with
195 .BR [@@ocaml.unboxed] .
196 This is the default.
197 .TP
198 .B \-unsafe
199 Turn bound checking off on array and string accesses (the
200 .BR v.(i) and s.[i]
201 constructs). Programs compiled with
202 .B \-unsafe
203 are therefore slightly faster, but unsafe: anything can happen if the program
204 accesses an array or string outside of its bounds.
205 .TP
206 .B \-unsafe\-string
207 Identify the types
208 .BR string \ and\ bytes ,
209 thereby making strings writable.
210 This is intended for compatibility with old source code and should not
211 be used with new software.
212 .TP
213 .B \-version
214 Print version string and exit.
215 .TP
216 .B \-vnum
217 Print short version number and exit.
218 .TP
219 .B \-no\-version
220 Do not print the version banner at startup.
221 .TP
222 .BI \-w \ warning\-list
223 Enable or disable warnings according to the argument
224 .IR warning-list .
225 See
226 .BR ocamlc (1)
227 for the syntax of the
228 .I warning\-list
229 argument.
230 .TP
231 .BI \-warn\-error \ warning\-list
232 Mark as fatal the warnings described by the argument
233 .IR warning\-list .
234 Note that a warning is not triggered (and does not trigger an error) if
235 it is disabled by the
236 .B \-w
237 option. See
238 .BR ocamlc (1)
239 for the syntax of the
240 .I warning\-list
241 argument.
242 .TP
243 .BI \-color \ mode
244 Enable or disable colors in compiler messages (especially warnings and errors).
245 The following modes are supported:
246
247 .B auto
248 use heuristics to enable colors only if the output supports them (an
249 ANSI-compatible tty terminal);
250
251 .B always
252 enable colors unconditionally;
253
254 .B never
255 disable color output.
256
257 The default setting is
258 .B auto,
259 and the current heuristic
260 checks that the "TERM" environment variable exists and is
261 not empty or "dumb", and that isatty(stderr) holds.
262
263 The environment variable "OCAML_COLOR" is considered if \-color is not
264 provided. Its values are auto/always/never as above.
265
266 .TP
267 .BI \-error\-style \ mode
268 Control the way error messages and warnings are printed.
269 The following modes are supported:
270
271 .B short
272 only print the error and its location;
273
274 .B contextual
275 like "short", but also display the source code snippet corresponding
276 to the location of the error.
277
278 The default setting is
279 .B contextual.
280
281 The environment variable "OCAML_ERROR_STYLE" is considered if
282 \-error\-style is not provided. Its values are short/contextual as
283 above.
284
285 .TP
286 .B \-warn\-help
287 Show the description of all available warning numbers.
288 .TP
289 .BI \- \ file
290 Use
291 .I file
292 as a script file name, even when it starts with a hyphen (-).
293 .TP
294 .BR \-help \ or \ \-\-help
295 Display a short usage summary and exit.
296
297 .SH INITIALIZATION FILE
298
299 When
300 .BR ocaml (1)
301 is invoked, it will read phrases from an initialization file before
302 giving control to the user. The default file is
303 .B .ocamlinit
304 in the current directory if it exists, otherwise
305 .B XDG_CONFIG_HOME/ocaml/init.ml
306 according to the XDG base directory specification lookup if it exists (on
307 Windows this is skipped), otherwise
308 .B .ocamlinit
309 in the user's home directory (
310 .B HOME
311 variable).
312 You can specify a different initialization file
313 by using the
314 .BI \-init \ file
315 option, and disable initialization files by using the
316 .B \-noinit
317 option.
318
319 Note that you can also use the
320 .B #use
321 directive to read phrases from a file.
322
323 .SH ENVIRONMENT VARIABLES
324 .TP
325 .B OCAMLTOP_UTF_8
326 When printing string values, non-ascii bytes (>0x7E) are printed as
327 decimal escape sequence if
328 .B OCAMLTOP_UTF_8
329 is set to false. Otherwise they are printed unescaped.
330 .TP
331 .B TERM
332 When printing error messages, the toplevel system
333 attempts to underline visually the location of the error. It
334 consults the TERM variable to determines the type of output terminal
335 and look up its capabilities in the terminal database.
336 .TP
337 .B XDG_CONFIG_HOME HOME
338 .B .ocamlinit
339 lookup procedure (see above).
340 .SH SEE ALSO
341 .BR ocamlc (1), \ ocamlopt (1), \ ocamlrun (1).
342 .br
343 .IR The\ OCaml\ user's\ manual ,
344 chapter "The toplevel system".
345