DUNE(1)

📦
version 3.24.1 · 16 versions
, in ubuntu stonking

💖 DUNE(1) — the Dune Manual, but make it a group chat 💖

okay bestie, sit down, hydrate, because we're about to talk about the single most iconic build system in the OCaml cinematic universe. it's dune, it's giving composable build system for OCaml, and it's literally about to carry your whole project on its back. 🎀

✨ NAME ✨

dune — a composable build system for OCaml 💅

🌸 SYNOPSIS 🌸

dune build [--watch]
dune runtest [--watch]
dune exec NAME
dune utop [DIR]
dune install
dune init project NAME [PATH] [--libs=l1,l2 --ppx=p1,p2 --inline-tests]

🦋 DESCRIPTION 🦋

so. Dune is a build system designed for OCaml projects only. it's not trying to be everything to everyone, it's just trying to be your everything. it focuses on giving you a consistent experience and it handles basically all the low-level details of OCaml compilation that you do NOT want to be thinking about at 2am. all you have to do is describe your project, and Dune does the rest. that's it. that's the deal. no cap. 🔥

the scheme it implements is inspired by the one used inside Jane Street, adapted for the open source world. it has matured over a long time and is used daily by hundreds of developers, which means it is highly tested and productive. it ate, honestly. 👑

💫 COMMAND ALIASES 💫

these are the little shortcut besties. same energy, shorter name.

  • printenv [OPTION]… [PATH] — an alias for env.
  • promote [--build-info] [--file] [OPTION]… [FILE]… — an alias for promotion apply.
  • test [OPTION]… [TEST]… — an alias for runtest.

👑 COMMANDS 👑

the whole squad, in order, no one left behind:

  • build [OPTION]… [TARGET]… — build the given targets, or the default ones if none are given.
  • cache COMMAND … — manage Dune's shared cache of build artifacts.
  • clean [OPTION]… [PATH]… — clean the project.
  • describe [COMMAND] … — describe the workspace.
  • diagnostics [OPTION]… — fetch and return errors from the current build.
  • exec [OPTION]… PROG [ARGS]… — execute a command in a similar environment as if installation was performed.
  • external-lib-deps [OPTION]… [TARGET]… — moved to dune describe external-lib-deps. (it moved, we don't gatekeep, but also we're telling you where it went 💀)
  • fmt [OPTION]… — format source code.
  • format-dune-file [OPTION]… [FILE] — format dune files.
  • help [--build-info] [--man-format=FMT] [OPTION]… [TOPIC] — additional Dune help.
  • init COMMAND … — command group for initializing Dune components.
  • install [OPTION]… [PACKAGE]… — install packages defined in the workspace.
  • installed-libraries [OPTION]… — print out libraries installed on the system.
  • internal COMMAND … — (yes it's just there, being mysterious, minding its business 🫶)
  • monitor [OPTION]… — connect to a Dune RPC server and monitor it.
  • ocaml COMMAND … — command group related to OCaml.
  • ocaml-merlin [OPTION]… — start a merlin configuration server.
  • package COMMAND … — experimental package management
  • pkg COMMAND … — experimental package management
  • promotion COMMAND … — control how changes are propagated back to source code.
  • rocq COMMAND … — command group related to Rocq.
  • rpc COMMAND … — Dune's RPC mechanism. Experimental.
  • rules [OPTION]… [TARGET]… — dump rules.
  • runtest [OPTION]… [TEST]… — run tests.
  • show COMMAND … — command group for showing information about the workspace
  • shutdown [OPTION]… — cancel and shutdown any builds in the current workspace.
  • subst [--build-info] [OPTION]… — substitute watermarks in source files.
  • tools COMMAND … — command group for wrapped tools.
  • top [OPTION]… [DIR] — print a list of toplevel directives for including directories and loading cma files.
  • trace COMMAND … — commands to view dune's event trace
  • uninstall [OPTION]… [PACKAGE]… — uninstall packages defined in the workspace.
  • upgrade [OPTION]… — upgrade projects across major Dune versions.
  • utop [OPTION]… [DIR] [ARGS]… — load library in utop.

🌈 COMMON OPTIONS 🌈

these ones are common to all commands. every single one. they're the universal besties. ✨

  • --help[=FMT] (default=auto) — show this help in format FMT. the value FMT must be one of auto, pager, groff or plain. with auto, the format is pager or plain whenever the TERM env var is dumb or undefined.
  • --version — show version information.

⭐ MORE HELP ⭐

use dune COMMAND --help for help on a single command. iykyk. 🙈

💀 EXIT STATUS 💀

dune exits with:

  • 0 — on success. we love a win. 🎀
  • 1 — if an error happened. it's giving not our day. 😭
  • 130 — if it was interrupted by a signal.

🧚 ENVIRONMENT 🧚

these environment variables affect the execution of dune:

  • CLICOLOR — if different than 0, ANSI colors are supported and should be used when the program isn't piped. if equal to 0, don't output ANSI color escape codes
  • CLICOLOR_FORCE — if different than 0, ANSI colors should be enabled no matter what.
  • DUNE_CACHE_ROOT — if set, determines the location of all the different caches used by dune.

🙈 BUGS 🙈

check bug reports at https://github.com/ocaml/dune/issues — the devs are literally right there, go tell them, they're nice about it fr fr.

🌸 EXAMPLES 🌸

some little situations to manifest ✨

  1. Initialise a new project named foo:
dune init project foo
  1. Build all targets in the current source tree:
dune build
  1. Run the executable named bar:
dune exec bar
  1. Run all tests in the current source tree:
dune runtest
  1. Install all components defined in the project:
dune install
  1. Remove all build artefacts:
dune clean
💖 that's the whole page bestie. every flag, every command, every env var, nothing skipped, nothing guessed. go build something iconic. periodt. 💅

okay and lastly, the little signature at the bottom of the original: this is from Dune 3.24.1, and yes, this whole thing is the DUNE(1) page. take care of her, she's doing her best. 🫶✨

📦 where this page comes from