DUNE-BUILD(1)

📦
version 3.24.1 · 15 versions
, in ubuntu stonking

💖 dune-build — the manual, but make it make sense 💖

okay bestie, gather round, because this is the DUNE-BUILD(1) page from the Dune Manual and we're gonna get through it together. it's long. it's giving "reference documentation." but we're built different and we're gonna slay it. 🦋

✨ NAME ✨

dune-build — build the targets you asked for, or the default ones if you didn't ask for any. that's it. that's the whole vibe. 🎀

🌸 SYNOPSIS 🌸

dune build [OPTION]… [TARGET]…

💅 DESCRIPTION 💅

so here's the one thing to internalize: targets that start with a @ get interpreted as aliases. that's the whole description. no cap. 🫶

👑 OPTIONS 👑

  • --action-stderr-on-success=VAL — same as --action-stdout-on-success but for standard error instead of standard output. for big ol' mono-repos, a genuinely good default combo is --action-stdout-on-success=swallow plus --action-stderr-on-success=must-be-empty. why? because it guarantees a successful build has a "clean," empty output. iconic behavior honestly. ✨
  • --action-stdout-on-success=VAL — tells Dune how to deal with the standard output of actions when they succeed. the possible values are:
    • print — just print it to Dune's output.
    • swallow — completely ignore it.
    • must-be-empty — enforce that the action printed nothing. with this one, if the action printed anything to standard output, Dune will consider the action failed. 💀

the default is print.

  • --alias=ALIAS — build ALIAS in its parent directory only. equivalent to the build target @@ALIAS. example: --alias dir/foo builds the foo alias in dir/ only. repeatable, so you can stack 'em. 🍓
  • --alias-rec=ALIAS — build the alias ALIAS in its parent directory and all subdirectories. equivalent to the build target @ALIAS. example: --alias-rec dir/foo builds the foo alias in dir/ and all its subdirectories. also repeatable. 🌈
  • --build-info — show build information.
  • --display-separate-messages — separate error messages with a blank line. a lil breathing room, bestie. 💜
  • --error-reporting=VAL (absent=deterministic) — controls when build errors get reported:
    • early — reports errors as soon as they're discovered.
    • deterministic — reports errors at the end of the build, in a deterministic order.
    • twice — reports each error twice: once as soon as it's discovered, and then again at the end of the build, in a deterministic order.
  • -f, --force — force actions associated with aliases to be re-executed even if their dependencies haven't changed. sometimes you just need a redo. 🙈
  • --file-watcher=VAL (absent=automatic) — the mechanism used to detect changes in the source. Automatic means dune runs an external program to detect changes. Manual means you notify dune that files have changed, yourself, manually, with your own two hands. 💅
  • --passive-watch-mode — similar to [--watch], but it only starts a build when instructed externally by an RPC.
  • --sandbox=VAL (absent DUNE_SANDBOX env) — set the sandboxing mode. heads up: some actions require a certain sandboxing mode, so they will ignore this setting. the allowed values are: none, symlink, copy, hardlink. 🧚
  • --stop-on-first-error — stop the build as soon as an error is encountered. no finishing the race, we're pulling over. 😭
  • -w, --watch — instead of terminating the build after completion, wait continuously for file changes. it just keeps watching. like that one friend who never leaves the group chat. 🔥
  • --wait-for-filesystem-clock — okay so Dune digests file contents for better incrementality, and those digests are themselves cached. in some cases, Dune needs to drop some digest cache entries in order for things to be reliable. this option makes Dune wait for the file system clock to advance, so that it doesn't need to drop anything. you should probably not care about this option; it's mostly useful for Dune developers to make Dune tests of the digest cache more reproducible. iykyk. 🤓

⭐ COMMON OPTIONS ⭐

these options are common to all commands, so they're basically the shared playlist. 🎧

  • --always-show-command-line — always show the full command lines of programs executed by dune.
  • --auto-promote — automatically promote files. this is similar to running dune promote after the build. ✨
  • --build-dir=FILE (absent DUNE_BUILD_DIR env) — specify the build directory. it's _build if unspecified.
  • --cache=VAL (absent DUNE_CACHE env) — enable or disable Dune cache. one of disabled, enabled-except-user-rules, or enabled. default is `enabled-except-user-rules'.
  • --cache-check-probability=VAL (absent DUNE_CACHE_CHECK_PROBABILITY env) — check build reproducibility by re-executing randomly chosen rules and comparing their results with those stored in Dune cache. ⚠️ note: by increasing the probability of such checks you slow down the build. the default probability is zero, i.e. no rules are checked.
  • --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env) — Dune cache storage mode, one of auto, hardlink, or copy. default is `hardlink'.
  • --config-file=FILE — load this configuration file instead of the default one.
  • --debug-backtraces — always print exception backtraces.
  • --debug-dependency-path — in case of error, print the dependency path from the targets on the command line to the rule that failed. detective mode. 🔍
  • --debug-package-logs (absent DUNE_DEBUG_PACKAGE_LOGS env) — always print the standard logs when building packages.
  • --default-target=TARGET (absent=@@default) — set the default target that's used when none is specified to dune build.
  • --diff-command=VAL (absent DUNE_DIFF_COMMAND env) — shell command to use to diff files. use - to disable printing the diff.
  • --disable-promotion (absent DUNE_DISABLE_PROMOTION env) — disable all promotion rules.
  • --display=MODE — control the display mode of Dune. see dune-config(5) for more details. valid values for this option are progress, verbose, short, quiet or tui.
  • --dump-gc-stats=FILE — dump the garbage collector stats to a file after the build is complete.
  • --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.
  • --ignore-promoted-rules — ignore rules with (mode promote), except ones with (only ...). the variable %{ignoring_promoted_rules} in dune files reflects whether this option was passed or not.
  • --instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env) — enable instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, each one of which must declare an instrumentation backend.
  • -j JOBS (absent DUNE_JOBS env) — run no more than JOBS commands simultaneously. JOBS must be a positive integer or auto to auto-detect the number of cores (which is the default). 💪
  • --no-buffer — do not buffer the output of commands executed by dune. by default dune buffers the output of subcommands, in order to prevent interleaving when multiple commands are executed in parallel. however, this can be an issue when debugging long running tests. with --no-buffer, commands have direct access to the terminal. ⚠️ note that as a result their output won't be captured in the log file. you should use this option in conjunction with -j 1, to avoid interleaving. additionally you should use --verbose as well, to make sure that commands are printed before they're being executed.
  • --no-config — do not load the configuration file.
  • --no-print-directory — suppress "Entering directory" messages.
  • --only-packages=PACKAGES — ignore stanzas referring to a package that isn't in PACKAGES. PACKAGES is a comma-separated list of package names. note that this has the same effect as deleting the relevant stanzas from dune files. it's mostly meant for releases. during development, it's likely that what you want instead is to build a particular <package>.install target. 💡
  • -p PACKAGES, --for-release-of-packages=PACKAGES (required) — shorthand for --release --pkg=disabled --only-packages PACKAGE. 🚨 you must use this option in your <package>.opam files, in order to build only what's necessary when your project contains multiple packages, as well as getting reproducible builds.
  • --pkg=VAL — enable or disable package management. the default behaviour depends on whether a lock directory exists.
  • --profile=VAL (absent DUNE_PROFILE env) — select the build profile, for instance dev or release. the default is dev.
  • --promote-install-files[=VAL] (default=true) — promote any generated <package>.install files to the source tree.
  • --release — put dune into a reproducible release mode. shorthand for --root . --ignore-promoted-rules --no-config --profile release --always-show-command-line --promote-install-files --require-dune-project-file --default-target @install. you should use this option for release builds. for instance, you must use this option in your <package>.opam files. except if you already use -p, as -p implies this option. 👑
  • --require-dune-project-file[=VAL] (default=true) — fail if a dune-project file is missing.
  • --root=DIR (absent DUNE_ROOT env) — use this directory as workspace root instead of guessing it. note that this option doesn't change the interpretation of targets given on the command line. it's only intended for scripts. 🤖
  • --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env) — store original source location in dune-package metadata.
  • --target-exec=TOOLCHAIN=CMD (absent DUNE_TARGET_EXEC env) — wrapper command for running target binaries when cross-compiling. format: TOOLCHAIN=CMD (e.g., 'windows=wine').
  • --terminal-persistence=MODE — change how the log of build results is displayed to the console between rebuilds while in --watch mode. supported modes: preserve, clear-on-rebuild, clear-on-rebuild-and-flush-history.
  • --trace-file=FILE — output trace data in catapult format (compatible with chrome://tracing). 🌈
  • --verbose — same as --display verbose.
  • --version — show version information.
  • --watch-exclusions=REGEX — adds a POSIX regular expression that will exclude matching directories from dune build --watch. the option --watch-exclusions can be repeated to add multiple exclusions. semicolons can also be used as a separator. if no exclusions are provided, then a standard set of exclusions is used; however, if one or more --watch-exclusions are used, none of the standard exclusions are used. the standard exclusions are: ^_opam /_opam ^_esy /_esy ^\.#.* /\.#.* ~$ ^#[^#]*#$ /#[^#]*#$ ^4913$ /4913$ /.git /.hg :/windows. 🚫
  • --workspace=FILE (absent DUNE_WORKSPACE env) — use this specific workspace file instead of looking it up.
  • -x VAL (absent DUNE_CROSS_TARGET env) — cross-compile using this toolchain.

🫶 MORE HELP 🫶

use `dune COMMAND --help' for help on a single command. one command at a time, bestie, we got this. 💖

💀 EXIT STATUS 💀

dune build exits with:

  • 0 — on success. slay. 🎉
  • 1 — if an error happened. 😭
  • 130 — if it was interrupted by a signal. 😵

and that's where part 1 wraps… but we're not done, keep scrolling because there's more coming. 💅✨

🌍 ENVIRONMENT 🌍

okay so these little environment variables? they're like the mood ring of build 💅 set them and they change how the whole thing behaves:

  • CLICOLOR — if it's anything other than 0, ANSI colors are supported and should be used (as long as the program isn't piped, obviously 🎀). If it's exactly 0, bestie, no ANSI color escape codes for you.
  • CLICOLOR_FORCE — if this one is anything other than 0, ANSI colors get enabled no matter what. zero chill, zero exceptions ✨
  • DUNE_BUILD_DIR — the build directory you're specifying. If you don't set it at all, it's just _build. lowkey the default everyone forgets exists 💖
  • DUNE_CACHE — turns the Dune cache on or off. pick one of disabled, enabled-except-user-rules or enabled. The default? enabled-except-user-rules. she's the default girlie 👑
  • DUNE_CACHE_CHECK_PROBABILITY — checks build reproducibility by re-executing randomly chosen rules and comparing their results against what's stored in the Dune cache. ⚠️ note bestie: cranking up this probability slows your build down, so it's not a free snack. Default probability is zero, aka no rules get checked, periodt.
  • DUNE_CACHE_ROOT — if you set it, it decides where all the different caches used by dune live. one root to rule them all 🧚
  • DUNE_CACHE_STORAGE_MODE — the Dune cache storage mode, one of auto, hardlink or copy. Default is hardlink 🍓
  • DUNE_CROSS_TARGET — cross-compile using this toolchain. it's giving very much platform-hopping energy 🦋
  • DUNE_DEBUG_PACKAGE_LOGS — always print the standard logs when building packages. no more "where did the logs go" moments 😭
  • DUNE_DIFF_COMMAND — the shell command used to diff files. want the diff to just not? use - to disable printing the diff entirely 💀
  • DUNE_DISABLE_PROMOTION — disables all promotion rules. all of them. not one survivor 🙈
  • DUNE_INSTRUMENT_WITH — enables instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and every single one of them has to declare an instrumentation backend. no freeloaders allowed 🌸
  • DUNE_JOBS — run no more than JOBS commands simultaneously. JOBS has to be a positive integer, or auto to auto-detect the number of cores. and yes, auto is the default, because duh ✨
  • DUNE_PROFILE — the build profile. dev if you don't specify anything, or release if -p is set. your vibe, your choice 💅
  • DUNE_ROOT — use this directory as the workspace root instead of letting dune guess it. 🫶 heads up tho: this option does not change how targets given on the command line are interpreted. it's only intended for scripts, iykyk.
  • DUNE_SANDBOX — the sandboxing mode to use by default. (peep --sandbox for the details 🎀)
  • DUNE_STORE_ORIG_SOURCE_DIR — stores the original source location in the dune-package metadata. archival queen behavior 📦
  • DUNE_TARGET_EXEC — wrapper command for running target binaries when cross-compiling. Format is TOOLCHAIN=CMD (e.g., 'windows=wine'). so fancy 🍷
  • DUNE_WORKSPACE — use this specific workspace file instead of going looking for one. no detective work needed 🔍

🐛 BUGS 🐛

Spotted a bug? don't suffer in silence bestie, check the bug reports at:

https://github.com/ocaml/dune/issues

👀 SEE ALSO 👀

  • dune(1) — the main character, obviously 💖

🌈 EXAMPLES 🌈

  1. Build every target in the current source tree:
dune build
  1. Build targets inside the ./foo/bar directory:
dune build ./foo/bar
  1. Build the minimal set of targets that tooling like Merlin needs (so useful for spotting errors fast, no cap):
dune build @check
  1. Run all the code formatting tools in-place:
dune build --auto-promote @fmt

aaaand that's the whole page bestie, you made it 🎉 this was Dune 3.24.1, DUNE-BUILD(1), go build something iconic 💖✨👑

📦 where this page comes from