Your First OCaml Program

To complete this tutorial, you need to have installed OCaml. Optionally, we recommend configuring your editor.

We will work with files containing OCaml source code and compile them to produce executable binaries. However, this is not a detailed tutorial on OCaml compilation, project modularisation, or dependencies management; it only gives a glimpse at those topics. The goal is to sketch the bigger picture in order to avoid getting lost in the details. In other words, we do breadth-first learning instead of depth-first learning.

In the previous tutorial most commands were entered in UTop. In this tutorial, the majority of commands should be entered into a terminal. Code examples starting with a dollar sign $ are intended to be entered in the terminal, while lines starting with a hash sign # are intended to be entered in UTop.

Once you've completed this tutorial, you should be able to create, compile, and execute an OCaml project using Dune, OCaml's build system. You will be able to work with files, make private definitions within modules, and know how to install and use opam packages.

Note: The files illustrating this tutorial are available as a Git repo.

Working Within an opam Switch

When you installed OCaml, a global opam switch was created automatically. This tutorial can be completed while working inside this global opam switch.

When you work on several OCaml projects simultaneously, you should create more opam switches. For instructions on how to do that, see Introduction to opam Switches.

Compiling OCaml Programs

By default, OCaml comes with two compilers: one translating sources into native binaries and another turning sources into a bytecode format. OCaml also comes with an interpreter for that bytecode format. This tutorial demonstrates how to use the native compiler to write OCaml programs.

We start by setting up a traditional “Hello, World!” project using Dune. Make sure to have installed version 3.12 or later. The following creates a project named hello:

$ opam exec -- dune init proj hello
Success: initialized project component named hello

Note 1: If you have run eval $(opam env) at the start of your current terminal session, or if you answered yes to the question that was asked when you ran opam init, you can omit opam exec -- from the start of dune commands.

Note 2: Throughout this tutorial, outputs generated by Dune might vary slightly because of the Dune version installed. This tutorial shows the output for Dune 3.12. If you'd like to get the most recent version of Dune, run opam update; opam upgrade dune in a terminal.

The project is stored in a directory named hello. The tree command lists the files and directories created. It might be necessary to install tree if you don't see the following. Through Homebrew, for example, run brew install tree.

Note 3: If you get an error in Homebrew from this in an Apple silicon macOS, it's likely an issue with the architecture switch from Intel to ARM. Please refer to the ARM64 Fix to remedy the ARM64 error.

Note 4: Unlike in Unix where they contain compiled binaries, directories lib and bin contain source code files, for libraries and programs, respectively. This is the a convention used in many OCaml projects, and the canned project created by Dune. All the built artifacts, and a copy of the sources, are stored in the _build directory. You shall not edit anything in the _build directory.

$ cd hello
$ tree
.
├── bin
│   ├── dune
│   └── main.ml
├── _build
│   └── log
├── dune-project
├── hello.opam
├── lib
│   └── dune
└── test
    ├── dune
    └── hello.ml

4 directories, 8 files

OCaml source files have the .ml extension, which stands for “Meta Language.” Meta Language (ML) is an ancestor of OCaml. This is also what the “ml” stands for in “OCaml.” Here is the content of the bin/main.ml file:

let () = print_endline "Hello, World!"

The project-wide metadata is available in the dune-project file. It contains information about the project name, dependencies, and global setup.

Each directory containing source files that need to be built must contain a dune file describing how.

This builds the project:

$ opam exec -- dune build

This launches the executable it creates:

$ opam exec -- dune exec hello
Hello, World!

Let's see what happens when we edit the bin/main.ml file directly. Open it in your editor and replace the word World with your first name. Recompile the project with dune build as before, and then launch it again with dune exec hello.

Voilà! You've just written your first OCaml program.

In the rest of this tutorial, we will make more changes to this project in order to illustrate OCaml's tooling.

Watch Mode

Before we dive in, note that you will typically want to use Dune's watch mode to continually compile and optionally restart your program. This ensures that the language server has the freshest possible data about your project, so your editor support will be top-notch. To use watch mode, just add the -w flag:

$ opam exec -- dune build -w
$ opam exec -- dune exec hello -w

Why Isn't There a Main Function?

Although bin/main.ml's name suggests it contains the application entry point into the project, it does not contain a dedicated main function, and there is no requirement that a project must contain a file with that name in order to produce an executable. A compiled OCaml file behaves as though that file were entered line by line into the toplevel. In other words, an executable OCaml file's entry point is its first line.

Double semicolons aren't needed in source files like they are in the toplevel. Statements are just processed in order from top to bottom, each triggering the side effects it may have. Definitions are added to the environment. Values resulting from nameless expressions are ignored. Side effects from all those will take place in the same order. That's OCaml main.

However, it is common practice to single out a value that triggers all the side effects and mark it as the intended main entry point. In OCaml, that's the role of let () =, which evaluates the expression on the right, including all the side effects, without creating a name.

Modules and the Standard Library, Cont'd

Let's summarise what was said about modules in the Tour of OCaml:

• A module is a collection of named values.
• Identical names from distinct modules don't clash.
• The standard library is collection of several modules.

Modules aid in organising projects; concerns can be separated into isolated modules. This is outlined in the next section. Before creating a module ourselves, we'll demonstrate using a definition from a module of the standard library. Change the content of the file bin/main.ml to this:

let () = Printf.printf "%s\n" "Hello, World!"

This replaces the function print_endline with the function printf from the Printf module in the standard library. Building and executing this modified version should produce the same output as before. Use dune exec hello to try it for yourself.

Every File Defines a Module

Each OCaml file defines a module, once compiled. This is how separate compilation works in OCaml. Each sufficiently standalone concern should be isolated into a module. References to external modules create dependencies. Circular dependencies between modules are not allowed.

To create a module, let's create a new file named lib/en.ml containing this:

let v = "Hello, world!"

Here is a new version of the bin/main.ml file:

let () = Printf.printf "%s\n" Hello.En.v

Now execute the resulting project:

$ opam exec -- dune exec hello
Hello, world!

The file lib/en.ml creates the module named En, which in turn defines a string value named v. Dune wraps En into another module called Hello; this name is defined by the stanza name hello in the file lib/dune. The string definition is Hello.En.v from the bin/main.ml file.

Dune can launch UTop to access the modules exposed by a project interactively. Here's how:

$ opam exec -- dune utop

Then, inside the utop toplevel, it is possible to inspect our Hello.En module:

# #show Hello.En;;
module Hello : sig val v : string end

Now exit utop with Ctrl-D or enter #quit;; before going to the next section.

Note: If you add a file named hello.ml in the lib directory, Dune will consider this the whole Hello module and it will make En unreachable. If you want your module En to be visible, you need to add this in your hello.ml file:

module En = En

Defining Module Interfaces

UTop's #show command displays an API (in the software library sense): the list of definitions provided by a module. In OCaml, this is called a module interface. An .ml file defines a module. In a similar way, an .mli file defines a module interface. The module interface file corresponding to a module file must have the same base name, e.g., en.mli is the module interface for module en.ml. Create a lib/en.mli file with this content:

val v : string

Observe that only the list of the module signature's declarations (which is between sig and end in the #show output) has been written in the interface file lib/en.mli. This is explained in more detail in the tutorial dedicated to modules.

Module interfaces are also used to create private definitions. A module definition is private if it is not listed in its corresponding module interface. If no module interface file exists, everything is public.

Amend the lib/en.ml file in your preferred editor; replace what's there with the following:

let hello = "Hello"
let v = hello ^ ", world!"

Also edit the bin/main.ml file like this:

let () = Printf.printf "%s\n" Hello.En.hello

Trying to compile this fails.

$ opam exec -- dune build
File "hello/bin/main.ml", line 1, characters 30-43:
1 | let () = Printf.printf "%s\n" Hello.En.hello
                                  ^^^^^^^^^^^^^^
Error: Unbound value Hello.En.hello

This is because we haven't changed lib/en.mli. Since it does not list hello, it is therefore private.

Defining Multiple Modules in a Library

Multiple modules can be defined in a single library. To demonstrate this, create a new file named lib/es.ml with the following content:

let v = "¡Hola, mundo!"

And use the new module in bin/main.ml:

let () = Printf.printf "%s\n" Hello.Es.v
let () = Printf.printf "%s\n" Hello.En.v

Finally, run dune build and dune exec hello to see the new output, using the modules you just created in the hello library.

$ opam exec -- dune exec hello
¡Hola, mundo!
Hello, world!

A more detailed introduction to modules can be found at Modules.

Installing and Using Modules From a Package

OCaml has an active community of open-source contributors. Most projects are available using the opam package manager, which you installed in the Install OCaml tutorial. The following section shows you how to install and use a package from opam's open-source repository.

To illustrate this, let's update our hello project to parse a string containing an S-expression and print back to a string, both using Sexplib. First, update the package list for opam by running opam update. Then, install the Sexplib package with this command:

$ opam install sexplib

Next, define a string containing a valid S-expression in bin/main.ml. Parse it into a S-expression with the Sexplib.Sexp.of_string function, and then convert it back into a string with Sexplib.Sexp.to_string and print it.

(* Read in Sexp from string *)
let exp1 = Sexplib.Sexp.of_string "(This (is an) (s expression))"

(* Do something with the Sexp ... *)

(* Convert back to a string to print *)
let () = Printf.printf "%s\n" (Sexplib.Sexp.to_string exp1)

The string you entered representing a valid S-expression is parsed into an S-expression type, which is defined as either an Atom (string) or a List of S-expressions (it's a recursive type). Refer to the Sexplib documentation for more information.

Before the example will build and run, you need to tell Dune that it needs Sexplib to compile the project. Do this by adding Sexplib to the library stanza of the bin/dune file. The full bin/dune file should then match the following.

(executable
 (public_name hello)
 (name main)
 (libraries hello sexplib))

Fun fact: Dune configuration files are S-expressions.

Finally, execute as before:

$ opam exec -- dune exec hello
(This(is an)(s expression))

Using the Preprocessor to Generate Code

Note: This example was successfully tested on Windows using DkML 2.1.0. Run dkml version to see the version.

Let's assume we'd like hello to display its output as if it was a list of strings in UTop: ["hello"; "using"; "an"; "opam"; "library"]. To do that, we need a function turning a string list into a string, adding brackets, spaces, and commas. Instead of defining it ourselves, let's generate it automatically with a package. We'll use ppx_deriving. Here is how to install it:

$ opam install ppx_deriving

Dune needs to be told how to use it, which is done in the lib/dune file. Note that this is different from the bin/dune file that you edited earlier! Open up the lib/dune file, and edit it to look like this:

(library
 (name hello)
 (preprocess (pps ppx_deriving.show)))

The line (preprocess (pps ppx_deriving.show)) means that before compilation the source needs to be transformed using the preprocessor show provided by the package ppx_deriving. It is not required to write (libraries ppx_deriving), Dune infers that from the preprocess stanza.

The files lib/en.ml and lib/en.mli need to be edited, too:

lib/en.mli

val string_of_string_list : string list -> string
val v : string list

lib/en.ml

let string_of_string_list = [%show: string list]

let v = String.split_on_char ' ' "Hello using an opam library"

Let's read this from the bottom up:

• v has the type string list. We're using String.split_on_char to turn a string into a string list by splitting the string on space characters.
• string_of_string_list has type string list -> string. This converts a list of strings into a string, applying the expected formatting.

Finally, you'll also need to edit bin/main.ml

let () = print_endline Hello.En.(string_of_string_list v)

Here is the result:

$ opam exec -- dune exec hello
["Hello"; "using"; "an"; "opam"; "library"]

A Sneak-Peek at Dune as a One-Stop Shop

This section explains the purpose of the files and directories created by dune init proj which haven't been mentioned earlier.

Along the history of OCaml, several build systems have been used. As of writing this tutorial (Summer 2023), Dune is the mainstream one, which is why it is used in the tutorial. Dune automatically extracts the dependencies between the modules from the files and compiles them in a compatible order. It only needs one dune file per directory where there is something to build. The three directories created by dune init proj have the following purposes:

• bin: executable programs
• lib: libraries
• test: tests

There will be a tutorial dedicated to Dune. This tutorial will present the many features of Dune, a few of which are listed here:

• Running tests
• Generating documentation
• Producing packaging metadata (here in hello.opam)
• Creating arbitrary files using all-purpose rules

The _build directory is where Dune stores all the files it generates. It can be deleted at any time, but subsequent builds will recreate it.

Minimum Setup

In this last section, let's create a bare minimum project, highlighting what's really needed for Dune to work. We begin by creating a fresh project directory:

$ cd ..
$ mkdir minimo
$ cd minimo

At the very least, Dune only needs two files: dune-project and one dune file. Here is how to write them with as little text as possible:

dune-project

(lang dune 3.6)

dune

(executable (name minimo))

minimo.ml

let () = print_endline "My name is Minimo"

That's all! This is sufficient for Dune to build and execute the minimo.ml file.

$ opam exec -- dune exec ./minimo.exe
My name is Minimo

Note: minimo.exe is not a file name. This is how Dune is told to compile the minimo.ml file using OCaml's native compiler instead of the bytecode compiler. As a fun fact, note that an empty file is valid OCaml syntax. You can use that to reduce minimo even more; of course, it will not display anything, but it will be a valid project!

Conclusion

This tutorial is the last of the "Getting Started" series. Moving forward, you have enough to pick and choose among the other tutorials to follow your own learning path.