DUNE-RULES(1)

📦
version 3.24.1 · 16 versions
, in ubuntu stonking

💖 dune-rules(1) — Dune Manual 💖

okay bestie, pull up a chair, because this is the dune-rules page from the Dune Manual and we are going to vibe our way through every single flag together. no skipping, no skimming, we're doing this properly. 💅

✨ NAME ✨

dune-rules — Dump rules. that's it. that's the whole name. short, iconic, does exactly what it says on the tin. 🎀

🌸 SYNOPSIS 🌸

dune rules [OPTION]… [TARGET]…

literally just dune rules, some options if you want, some targets if you want. she's flexible like that. 🦋

💜 DESCRIPTION 💜

so what this does is dump Dune rules for whatever targets you hand her. and if you hand her no targets? she dumps all the rules. all of them. every last one. she's an overachiever, we love her for it. 👑

With --deps, she only prints the dependencies of the matching rules. just the receipts of what each rule depends on, nothing else. no extra baggage. minimalism queen. ✨

By default the output is a list of S-expressions, one S-expression per rule. and each S-expression is giving exactly this shape:

((deps    (<dependencies>))
 (targets (<targets>))
 (context <context-name>)
 (action  <action>))

now let's break that down because it matters:

  • <context-name> is the context in which the action is executed. it gets omitted if the action is independent from the context — she's not gonna include a field that doesn't apply, that's just clutter. 🙈
  • <action> is the action, following the same syntax as user actions, as described in the manual. same syntax, same rules, iykyk.

and if S-expressions aren't your thing? use --format=json to dump the same data as JSON. same tea, different cup. 🍓

🎀 OPTIONS 🎀

here we go bestie, the big list. every single one. no cap. 💖

  • --action-stderr-on-success=VAL — same as --action-stdout-on-success but for standard error instead of standard output. and ngl, the pros recommend this combo for large mono-repositories: --action-stdout-on-success=swallow together with --action-stderr-on-success=must-be-empty. why? because it ensures that a successful build has a "clean", empty output. tidy. immaculate. ✨
  • --action-stdout-on-success=VAL — tells Dune how to deal with the standard output of actions when they succeed. the possible values are: print to just print it to Dune's output, swallow to completely ignore it, and must-be-empty to enforce that the action printed nothing. with must-be-empty, Dune will consider that the action failed if it printed something to its standard output. so like… dramatic much, but effective. 😭 the default is print.
  • --build-info — show build information. that's it. she's showing off her build lore. 🫶
  • --deps — only print the dependencies of matching rules. just the deps, bestie, nothing more. 💜
  • --display-separate-messages — separate error messages with a blank line. breathing room for your errors. she's considerate like that. 🌸
  • --error-reporting=VAL (absent=deterministic) — controls when the build errors get reported. here's the tea:
    • early reports errors as soon as they are discovered. instant. no waiting.
    • deterministic reports errors at the end of the build, in a deterministic order. this is the default, she likes a tidy queue.
    • 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. double the drama, double the info. 💀
  • -f, --force — force actions associated to aliases to be re-executed even if their dependencies haven't changed. she said run it again and she means it. 🔥
  • --file-watcher=VAL (absent=automatic) — the mechanism to detect changes in the source. automatic makes dune run an external program to detect changes. manual means you notify dune that files have changed, manually, by hand, yourself. main character energy, you're in charge. 👑
  • --format=FORMAT (absent=sexp) — FORMAT must be either sexp or json. pick your aesthetic. 🌈
  • -o FILE — output to a file instead of stdout. take it to go. 🎀
  • --passive-watch-mode — similar to [--watch], but she only starts a build when instructed externally by an RPC. so she's waiting. patiently. on you. 🦋
  • -r, --recursive — print all rules needed to build the transitive dependencies of the given targets. go deeper. go recursive. 😭
  • --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. pick your containment strategy bestie. 💅
  • --stop-on-first-error — stop the build as soon as an error is encountered. no need to see the rest, we're done here, thank u next. ✋
  • -w, --watch — instead of terminating the build after completion, wait continuously for file changes. she lives here now. she's not leaving. 🫶
  • --wait-for-filesystem-clock — okay this one needs setup. Dune digests file contents for better incrementality (yes, it's a word, moving on). these 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. and, direct quote from the page: 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. so if that's not you… it's not you. 💀
💖 okay that's part 1! more parts are coming, so don't go anywhere bestie — we're not done. ✨

💖 COMMON OPTIONS 💖

okay bestie these ones are the ✨universal✨ options, the ones that every single command shares. same energy, every time. 💅

  • --always-show-command-line — literally always show the full command lines of the programs dune runs. no hiding, we see everything. 👀
  • --auto-promote — auto-promotes files for you, kind of like running dune promote right after the build. self-care honestly. ✨
  • --build-dir=FILE (absent → DUNE_BUILD_DIR env) — the build directory you want. if you don't say anything it's _build, the classic.
  • --cache=VAL (absent → DUNE_CACHE env) — turn the Dune cache on or off. valid values are disabled, enabled-except-user-rules or enabled. the default is enabled-except-user-rules. 💖
  • --cache-check-probability=VAL (absent → DUNE_CACHE_CHECK_PROBABILITY env) — checks build reproducibility by re-executing randomly chosen rules and comparing what they produce with what's stored in the Dune cache. ⚠️ heads up: cranking up the probability of these checks slows your build down. default probability is zero, meaning literally no rules get checked.
  • --cache-storage-mode=VAL (absent → DUNE_CACHE_STORAGE_MODE env) — the Dune cache storage mode, one of auto, hardlink or copy. default is hardlink.
  • --config-file=FILE — load this config file instead of the default one. main character config file energy. 👑
  • --debug-backtraces — always print exception backtraces. no mystery crashes, we get receipts. 🧾
  • --debug-dependency-path — when something errors, print the dependency path from the targets on the command line all the way to the rule that failed. it's giving detective work 🔍
  • --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, the one that gets used when you don't give dune build any target at all.
  • --diff-command=VAL (absent → DUNE_DIFF_COMMAND env) — the shell command used to diff files. use - to disable printing the diff entirely, no diff no drama.
  • --disable-promotion (absent → DUNE_DISABLE_PROMOTION env) — disables all promotion rules. periodt. 🚫
  • --display=MODE — controls what dune shows you. see dune-config(5) for the deets. valid values are progress, verbose, short, quiet or tui.
  • --dump-gc-stats=FILE — dumps the garbage collector stats into a file once the build is done. gc tea ☕
  • --help[=FMT] (default=auto) — shows 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 — ignores rules with (mode promote), except the ones with (only ...). the variable %{ignoring_promoted_rules} in dune files reflects whether you passed this option or not. iykyk 💅
  • --instrument-with=BACKENDS (absent → DUNE_INSTRUMENT_WITH env) — enables instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and each 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 (that's the default, bestie 🌈).
  • --no-buffer — do not buffer the output of commands that dune executes. by default dune buffers subcommand output so nothing interleaves while multiple commands run in parallel. but deadass 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 together with -j 1, to avoid interleaving. and additionally you should use --verbose too, to make sure commands are printed before they're executed.
  • --no-config — do not load the configuration file. simple as that. 🙈
  • --no-print-directory — suppresses those "Entering directory" messages. shhh, we're sneaky 🤫
  • --only-packages=PACKAGES — ignores 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, what you probably 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, so that only what's necessary gets built when your project has multiple packages — and so you also get reproducible builds. crucial 💯
  • --pkg=VAL — enable or disable package management. the default behaviour depends on whether a lock directory exists.
  • --profile=VAL (absent → DUNE_PROFILE env) — pick your build profile, for instance dev or release. default is dev.
  • --promote-install-files[=VAL] (default=true) — promotes any generated <package>.install files to the source tree. ✨
  • --release — puts 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 for release builds. for instance, you must use it in your <package>.opam files — except if you already use -p, since -p implies this option. slay but responsibly 👑
  • --require-dune-project-file[=VAL] (default=true) — fail if a dune-project file is missing. no file, no vibes. 💀
  • --root=DIR (absent → DUNE_ROOT env) — use this directory as the workspace root instead of guessing it. note that this option does not 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) — stores 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 — changes 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 — outputs trace data in catapult format (compatible with chrome://tracing). pretty graphs bestie 📊
  • --verbose — same as --display verbose.
  • --version — shows version information. 💅
  • --watch-exclusions=REGEX — adds a POSIX regular expression that will exclude matching directories from dune build --watch. you can repeat --watch-exclusions to add multiple exclusions, and semicolons work as a separator too. if you don't provide any exclusions, a standard set of exclusions is used; however, if 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. 🔥

🦋 MORE HELP 🦋

want help on just one command? so valid of you. use dune COMMAND --help. that's it, that's the whole section. 💖

✨ EXIT STATUS ✨

dune rules exits with:

  • 0 — on success. we ate. 🎀
  • 1 — if an error happened. 😭
  • 130 — if it was interrupted by a signal.

🌸 ENVIRONMENT 🌸

these environment variables affect the execution of rules, bestie:

  • DUNE_BUILD_DIR — specified build directory. _build if unspecified.
  • DUNE_CACHE — enable or disable Dune cache (one of disabled, enabled-except-user-rules or enabled). default is enabled-except-user-rules.
  • DUNE_CACHE_CHECK_PROBABILITY — 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.
  • DUNE_CACHE_STORAGE_MODE — Dune cache storage mode (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.
  • DUNE_DIFF_COMMAND — shell command to use to diff files. use - to disable printing the diff.
  • DUNE_DISABLE_PROMOTION — disable all promotion rules.
  • DUNE_INSTRUMENT_WITH — enable instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, each one of which must declare an instrumentation backend.
  • DUNE_JOBS — run no more than JOBS commands simultaneously. JOBS must be a positive integer or auto to auto-detect the number of cores (the default).
  • DUNE_PROFILE — build profile. dev if unspecified or release if -p is set.
  • DUNE_ROOT — 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 is only intended for scripts.
  • DUNE_SANDBOX — sandboxing mode to use by default. (see --sandbox)
  • DUNE_STORE_ORIG_SOURCE_DIR — store original source location in dune-package metadata.
  • DUNE_TARGET_EXEC — 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 looking it up.

💀 BUGS 💀

spotted a bug? not the vibe, but okay. check bug reports at https://github.com/ocaml/dune/issues and we'll figure it out together. 🫶

🌈 SEE ALSO 🌈

okay that's the whole page bestie, you're officially a dune-rules girly now 💅 this was Dune 3.24.1, page DUNE-RULES(1) — go forth and build, you absolute icon. 👑✨🎀

📦 where this page comes from