DUNE-DIAGNOSTICS(1)

📦
version 3.24.1 · 12 versions
, in ubuntu stonking

💖 DUNE-DIAGNOSTICS(1) 💖

okay so this is part 1 of the Dune Manual, section 1, and we're talking about dune-diagnostics today bestie, get comfy 🌸

🎀 NAME 🎀

dune-diagnostics — fetch and return errors from the current build. it is literally the error-gossip channel of your build. she's giving "tell me everything that went wrong, no filter" ✨

🌈 SYNOPSIS 🌈

dune diagnostics [OPTION]…

💅 OPTIONS 💅

okay this is the big one, stay with me 🫶

  • --action-stderr-on-success=VAL — same vibe as --action-stdout-on-success, but for standard error instead of standard output. and ngl, if you're in a big mono-repo, the truly iconic combo is --action-stdout-on-success=swallow plus --action-stderr-on-success=must-be-empty, because that way a successful build gets a totally clean, empty output. chef's kiss 👑
  • --action-stdout-on-success=VAL — tells Dune how to treat an action's standard output when the action succeeds. the possible values are: print, which just, y'know, prints it to Dune's output; swallow, which ignores it entirely; and must-be-empty, which literally enforces that the action printed nothing. with must-be-empty, if the action printed anything to stdout, Dune is gonna treat that action as failed, periodt. the default is print.
  • --build-info — show build information. slay ✨
  • --display-separate-messages — put a blank line between error messages so they stop holding hands. separation era 💅
  • --error-reporting=VAL (absent=deterministic) — controls when build errors get reported:
    • early reports them the second they're discovered,
    • deterministic waits until the end of the build and reports them in a deterministic order,
    • twice does both: reports each error once immediately when it's discovered, and then again at the end of the build in a deterministic order. main character behavior, honestly 😭
  • -f, --force — force actions tied to aliases to be re-executed even when their dependencies haven't changed. she does not care about your caching today 🔥
  • --file-watcher=VAL (absent=automatic) — the mechanism for spotting changes in the source. automatic makes Dune run an external program to detect changes. manual means you notify Dune that files changed, by hand, yourself. 💀
  • --passive-watch-mode — like --watch but chiller: it only starts a build when something externally tells it to via an RPC. she's waiting for a text back 🫶
  • --sandbox=VAL (absent DUNE_SANDBOX env) — set the sandboxing mode. heads up: some actions require a certain sandboxing mode and will straight-up ignore this setting. the allowed values are none, symlink, copy and hardlink.
  • --stop-on-first-error — stop the whole build the moment an error shows up. no mercy, no cap 🛑
  • -w, --watch — instead of dipping after the build finishes, just keep waiting forever for file changes. girl is committed 💜
  • --wait-for-filesystem-clock — Dune digests file contents for better incrementality, and those digests get cached. sometimes Dune has to drop some digest cache entries to keep things reliable, and this option makes Dune wait for the file system clock to move forward so it doesn't have to drop anything. honestly? you probably shouldn't care about this option. it's mostly for Dune developers trying to make Dune's digest-cache tests more reproducible. iykyk 🧚

🌸 COMMON OPTIONS 🌸

the classics, the staples, the ones that show up everywhere 🎀

  • --always-show-command-line — always show the full command lines of the programs Dune executes.
  • --auto-promote — automatically promote files. basically like running dune promote right after the build. she promotes herself 💅
  • --build-dir=FILE (absent DUNE_BUILD_DIR env) — specify the build directory. it's _build if you don't say anything.
  • --cache=VAL (absent DUNE_CACHE env) — turn the Dune cache on or off. one of disabled, enabled-except-user-rules or enabled. the 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 what's stored in the Dune cache. note: raising the probability of these checks slows your build down, so be mindful. the default probability is zero, meaning no rules get checked at all.
  • --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env) — the Dune cache storage mode, one of auto, hardlink or copy. the default is hardlink.
  • --config-file=FILE — load this config file instead of the default one.
  • --debug-backtraces — always print exception backtraces. for when you need the full lore 😭
  • --debug-dependency-path — when there's an error, print the dependency path from the targets on the command line all the way to the rule that failed.
  • --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 gets used when you don't specify one to dune build.
  • --diff-command=VAL (absent DUNE_DIFF_COMMAND env) — the shell command to use for diffing files. use - to disable printing the diff entirely.
  • --disable-promotion (absent DUNE_DISABLE_PROMOTION env) — disable all promotion rules. none of that here 🚫
  • --display=MODE — control Dune's display mode. see dune-config(5) for the details. the valid values for this option are progress, verbose, short, quiet or tui.
  • --dump-gc-stats=FILE — dump the garbage collector stats into a file once the build is complete.
  • --help[=FMT] (default=auto) — show this help in format FMT. FMT has to be one of auto, pager, groff or plain. with auto, the format ends up being pager or plain whenever the TERM env var is dumb or undefined.
  • --ignore-promoted-rules — ignore rules with (mode promote), except the 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, and every single one of them has to declare an instrumentation backend.
  • -j JOBS (absent DUNE_JOBS env) — run no more than JOBS commands at the same time. 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 Dune executes. by default Dune buffers subcommand output to stop things interleaving when multiple commands run in parallel — but that can be a whole problem when you're debugging long-running tests. with --no-buffer, commands get 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 alongside -j 1 to avoid interleaving, and also use --verbose as well, so you're sure commands get printed before they run.
  • --no-config — do not load the configuration file.
  • --no-print-directory — suppress those "Entering directory" messages. shush 💜
  • --only-packages=PACKAGES — ignore stanzas that refer to a package not in PACKAGES. PACKAGES is a comma-separated list of package names. note that this has the same effect as deleting the relevant stanzas from your dune files, and it's mostly meant for releases. during development you probably want to build a particular <package>.install target instead.
  • -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, so you only build what's necessary when your project has multiple packages, and so you get 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) — pick the build profile, for instance dev or release. the default is dev.
  • --promote-install-files[=VAL] (default=true) — promote any generated <package>.install files into the source tree.
  • --release — put Dune into a reproducible release mode. it's a 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, and for instance you must use it in your <package>.opam files — unless you already use -p, because -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 the workspace root instead of guessing it. note that this option doesn't change how targets given on the command line are interpreted — it's only intended for scripts.
  • --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env) — store the original source location in dune-package metadata.
  • --target-exec=TOOLCHAIN=CMD (absent DUNE_TARGET_EXEC env) — a 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 you're 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 — add a POSIX regular expression that excludes matching directories from dune build --watch. you can repeat --watch-exclusions to add multiple exclusions, and semicolons work as a separator too. if you provide no exclusions at all, then a standard set is used — but heads up: the moment you use one or more --watch-exclusions, none of the standard exclusions apply. 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 one up.
  • -x VAL (absent DUNE_CROSS_TARGET env) — cross-compile using this toolchain.

⭐ EXIT STATUS ⭐

dune diagnostics exits with:

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

🌸 ENVIRONMENT 🌸

ok so these are the vibes the environment can hand to diagnostics before it even wakes up. Every single one of these lil guys changes how dune/diagnostics behaves, so set them in your shell, in a script, in CI, wherever — just know they're there. 💖

  • DUNE_BUILD_DIR — the build directory you want to use. If you don't say anything, it's lowkey just _build. 🏠
  • DUNE_CACHE — turn the Dune cache on or off. Pick one of disabled, enabled-except-user-rules, or enabled. The default is enabled-except-user-rules. ✨
  • DUNE_CACHE_CHECK_PROBABILITY — this one makes Dune check whether your builds are reproducible by re-running randomly chosen rules and comparing the results against what's sitting in the Dune cache. ⚠️ Heads up bestie: bumping this probability up slows your build down. The default probability is zero, meaning no rules get checked at all. 🐢
  • DUNE_CACHE_STORAGE_MODE — how the Dune cache stores stuff: one of auto, hardlink, or copy. Default is hardlink. 💾
  • DUNE_CROSS_TARGET — cross-compile using this toolchain. 🔀
  • DUNE_DEBUG_PACKAGE_LOGS — always print the standard logs when building packages. Loud and proud, no silence era. 📢
  • DUNE_DIFF_COMMAND — the shell command used to diff files. Pass - if you want to disable printing the diff entirely. 🔍
  • DUNE_DISABLE_PROMOTION — disables all promotion rules. 🙅
  • DUNE_INSTRUMENT_WITH — enables instrumentation with BACKENDS. BACKENDS is a comma-separated list of library names, and each one of those libraries has to declare an instrumentation backend. 🎛️
  • DUNE_JOBS — never run more than JOBS commands at the same time. JOBS has to be a positive integer, or auto to auto-detect the number of cores — which, btw, is the default. 🧵
  • DUNE_PROFILE — the build profile. Unspecified means dev, and it's release if -p is set. 🎀
  • DUNE_ROOT — use this directory as the workspace root instead of letting Dune guess it. 📌 Note that 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. (see --sandbox) 🏖️
  • DUNE_STORE_ORIG_SOURCE_DIR — store the original source location in dune-package metadata. 🗂️
  • DUNE_TARGET_EXEC — a wrapper command for running target binaries when cross-compiling. Format: TOOLCHAIN=CMD (e.g., 'windows=wine'). 🍷
  • DUNE_WORKSPACE — use this specific workspace file instead of going off and looking one up. 📄

💜 SEE ALSO 💜

obviously. go read it, it's the main character of this whole franchise. 👑

and that's a wrap on DUNE-DIAGNOSTICS(1), bestie!! 🫶 this page ships with Dune 3.24.1 — that's the version in the footer, along with the date it was last touched, right there in the bottom corner. go forth and diagnose, you absolute legend. 🦋✨💅

📦 where this page comes from