Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 40 ยท Getting Started

Your First OCaml Program with dune

Create, build and run your first OCaml project with dune: project layout, the dune-project and dune files, dune build, dune exec and a tour of a small program.

A single .ml file is fine for a quick test, but real programs live in projects. OCaml projects are built with dune. In this lesson you will create a project, look at every file dune generates, build it, run it and read the code of a small program line by line.

These commands run on your own computer. The code blocks here are read-only; the output is what you will see in your terminal.

Create a project

Terminal
dune init project hello
cd hello

Dune creates this layout:

TEXT
hello/
  dune-project
  hello.opam
  bin/
    dune
    main.ml
  lib/
    dune
  test/
    dune
    hello.ml

(Exact files vary a little between dune versions.) The three that matter now are dune-project, bin/dune and bin/main.ml.

dune-project

LISP
(lang dune 3.16)
(name hello)

This marks the root of the project and says which dune language version the build files use. Dune files are written in a Lisp-like syntax of parentheses, which is easy to read once you have seen a few.

bin/dune

LISP
(executable
 (public_name hello)
 (name main))

This declares that the folder builds an executable. name main means the entry point is main.ml. public_name is the name under which the program can be installed.

bin/main.ml

OCAML
let () = print_endline "Hello, World!"

Build and run

Terminal
dune build
dune exec hello
TEXT
Hello, World!

dune build compiles everything into a _build folder, which you never edit and normally ignore in version control. dune exec hello builds first if needed and then runs the program. You can also run dune exec ./bin/main.exe, because dune names the executable file after the module.

Add --watch to rebuild on every save:

Terminal
dune build --watch

Reading the program

Let us replace main.ml with something slightly bigger:

OCAML
let greeting name = "Hello, " ^ name ^ "!"

let () =
  let who = "world" in
  print_endline (greeting who);
  print_endline "Welcome to OCaml"

Go through it piece by piece:

  1. let greeting name = ... defines a function. There are no parentheses around the parameter and no return; the body is just an expression, and its value is the result.
  2. ^ concatenates strings.
  3. let () = ... is a definition whose pattern is (), the unit value. It is how a program says "run this when the module is loaded". Without it, the file would only define things and print nothing.
  4. let who = "world" in ... creates a local name used in the expressions after in.
  5. ; sequences two expressions: run the first (its value is thrown away; it must be unit) and then the second.
  6. print_endline writes a string and a newline to standard output.

Notice that there is no main function. A module's top-level let () = ... runs, in order, when the program starts.

Splitting code into modules

Every .ml file is automatically a module whose name is the file name with a capital letter. Create bin/greet.ml:

OCAML
let hello name = "Hello, " ^ name ^ "!"

Now in bin/main.ml call it as Greet.hello:

OCAML
let () = print_endline (Greet.hello "dune")

Dune finds greet.ml in the same folder without any extra configuration. If you prefer not to write Greet. each time, write open Greet at the top of the file. You will meet modules properly later in this tutorial.

Common mistakes

  • "Unbound module Greet" usually means the file is in another directory that has no dune file, or has a typo in the file name (Greet needs greet.ml).
  • Forgetting ; between statements, or adding one after the last statement, produces a syntax error or a warning about an unused value.
  • Warnings are errors in dev builds. Dune's default development profile turns many warnings, such as "unused variable", into build errors. This is deliberate: it keeps code clean. While learning, you can silence it per executable with (flags (:standard -w +a-4-9-26-27)) but fixing the code is usually better.

A stand-in: the order a module runs

Top-level definitions in a module run from top to bottom. The stand-in below shows the effect: the function is defined first, the printing happens in the final "unit" step.

JS Stand-in: top-level items run in order

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command creates a new executable project?

    dune init project NAME generates a project skeleton with a bin folder and dune files.
  2. 2. What does let () = ... do at the top level of main.ml?

    The pattern () matches the unit value, so the definition evaluates its expression for its effect.
  3. 3. What is the module name for the file greet.ml?

    The file name with its first letter capitalized becomes the module name.
  4. 4. What does dune exec hello do?

    exec rebuilds what is out of date and then runs the program.

Summary

  • dune init project creates a project; dune build compiles it and dune exec runs it.
  • dune-project marks the project root and dune files describe what to build.
  • let () = ... is the entry point idiom; there is no required main.
  • Each .ml file is a module named after the file, usable as Module.value.

Next: The utop toplevel