Many OCaml guides and tutorials refer to the OCaml toplevel, but what exactly is this thing? In short, the toplevel is OCaml’s Read-Eval-Print-Loop (repl) allowing interative use of the OCaml system. You can consider the toplevel an alternative to compiling OCaml into an executable. In this mode, the OCaml system is configured to repeatedly read phrases from input, typecheck, compile, and evaluate them, then print the inferred type and result value.
Any input into the toplevel can span several lines and we terminate toplevel statements with a double-semicolon (;;).
Starting the toplevel
If you have an OCaml system
installed you can
start a toplevel environment by typing
ocaml at a command prompt. You can
check that it is working by doing some basic math. The toplevel system prints a
# prompt before reading your input.
utop provides an improved interactive to the OCaml toplevel. It supports
command history, macro expansion, module completion, and other additions that
make OCaml programming easier. After installing
UTop you can
start it with the
utop command to start the interactive environment. When you
start typing a command from the utop prompt, you will see automatic completions
being presented. Press tab at any time to select a completion.
Using the toplevel
When you start a new toplevel session, no code is loaded — you begin with
a complete blank slate which isn’t very interesting. Where this becomes useful
is testing code you’ve written and exploring code written by others. To load an
OCaml module installed through opam in the toplevel, use the
By opening Base, we make the definitions it contains available without having to
reference Base explicitly. You can do the same for any modules you’ve written in
two different ways. First, you can use the
#use command to directly include
the file into the toplevel. For example, if I have the file
that simply encodes a message:
I can directly include that in the toplevel with
declared in the file becomes available to the toplevel.
To include the file as a module, rather than directly, use the
command. In this case, the
message variable is available to us prefixed by the
module name we loaded (which is the file name with a uppercase first letter).
Lastly, you can compile your file into bytecode, and load the associated
bytecode into the toplevel through the
This should get you started using the Ocaml toplevel to interact with your code.