DUNE-DESCRIBE(1)

📦
version 3.24.1 · 15 versions
, in ubuntu stonking

💫 dune-describe — the Dune Manual page, bestie edition 💫

okay so. DUNE-DESCRIBE(1)? It lives in the Dune Manual. And basically it's your group chat with the workspace itself. Let's get into it 🫶

✨ NAME ✨

dune-describe — Describe the workspace. that's it. that's the whole job. and honestly? iconic.

🎀 SYNOPSIS 🎀

dune describe [COMMAND] …

🦋 DESCRIPTION 🦋

So here's the vibe: this command tells you what's up in your current workspace, and it can do it in human form or machine form. Choose your fighter 💅

By default, it spits out a human readable description of the current workspace. Key word: human. This output is aimed at humans and it is NOT suitable for machine processing. Specifically, it is not versioned — so if you're out here trying to parse it from a program, hard no bestie 😭

If you want to interpret the output of this command from a program, you must use the --format option to specify a machine readable format, plus the --lang option to get a stable output. Both. Not one. Both. periodt 💖

👑 COMMANDS 👑

  • aliases [OPTION]… [DIR]… — Print aliases in a given directory. It works similarly to ls. lowkey serving the same energy 👑
  • contexts [OPTION]… — List the build contexts available in the workspace. all of them. every single one 🫶
  • depexts [OPTION]… — Print the list of all the available depexts. yes, all of them, no cap ✨
  • env [OPTION]… [PATH] — Print the environment of a directory. give it a PATH and it'll tell you the env, bestie 🌸
  • external-lib-deps [OPTION]… — Print out external libraries needed to build the project. heads up though: it's an approximated set of libraries. approx. not exact. don't come for me 💀
  • installed-libraries [OPTION]… — Print out libraries installed on the system. the ones already on your machine, living their best life 🧚
  • location [OPTION]… PROG — Print the path to the executable using the same resolution logic as [dune exec]. same brain, same logic, same answer 💅
  • opam-files [OPTION]… — Print information about the opam files that have been discovered. the ones Dune found. like a little scavenger hunt 🔥
  • package-entries [OPTION]… — prints information about the entries per package. per package!! 📦
  • pkg COMMAND … — Subcommands related to package management. it's the package management corner of the house 🏠
  • pp [OPTION]… FILE — Build a given FILE and print the preprocessed output. build it, then show you the preprocessed glow-up ⭐
  • rules [OPTION]… [TARGET]… — Dump rules. all the rules. dumped. 💖
  • targets [OPTION]… [DIR]… — Print targets in a given directory. Works similarly to ls. same energy as aliases, real ones know 🙈
  • tests [OPTION]… — Print out the tests defined in the project. ⚠️ but the output format of this command is experimental and is subject to change without warning. like. don't build your whole pipeline on it. it's giving chaos 🍓
  • workspace [OPTION]… [DIRS]… — Print a description of the workspace's structure. And if some directories DIRS are provided, then only those directories of the workspace are considered. narrowing the scope, we love to see it ✨

🌸 ARGUMENTS 🌸

  • DIRS — prints a description of the workspace's structure. If some directories DIRS are provided, then only those directories of the workspace are considered. yes it says the same thing as workspace up there. that's just how it is bestie 🤷♀️

💅 OPTIONS 💅

  • --action-stderr-on-success=VAL — Same as --action-stdout-on-success but for standard error instead of standard output. And listen: a good default for large mono-repositories is --action-stdout-on-success=swallow --action-stderr-on-success=must-be-empty. This ensures that a successful build has a "clean" empty output. clean girl aesthetic, but for builds ✨
  • --action-stdout-on-success=VAL — Specify how to deal with the standard output of actions when they succeed. 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. The default is print. those are the three (3) options, no more no less 🎀
  • --build-info — Show build information. the receipts 🧾
  • --context=CONTEXT (absent=default) — Build context to use. if you don't say anything, it assumes default 💜
  • --display-separate-messages — Separate error messages with a blank line. breathing room for your errors, honestly a mental health win 🌈
  • --error-reporting=VAL (absent=deterministic) — Controls when the build errors are reported. early reports errors as soon as they are discovered. deterministic reports errors at the end of the build in a deterministic order. twice reports each error twice: once as soon as the error is discovered and then again at the end of the build, in a deterministic order. pick your trauma timing bestie 💀
  • -f, --force — Force actions associated to aliases to be re-executed even if their dependencies haven't changed. yes even then. forceful. we respect it 🔥
  • --file-watcher=VAL (absent=automatic) — Mechanism to detect changes in the source. Automatic to make dune run an external program to detect changes. Manual to notify dune that files have changed manually. you either let the machine watch, or you tell it yourself 👀
  • --format=FORMAT (absent=sexp) — FORMAT must be either sexp or csexp. those are the only two. don't try anything else 🚫
  • --lang=VERSION (absent=0.1) — Behave the same as this version of Dune. it's a whole time machine vibe 🕰️
  • --no-recursive — Do not traverse subdirectories. Only consider the provided directories, or the workspace root when none are given. stay in your lane, literally 🌸
  • --passive-watch-mode — Similar to [--watch], but only start a build when instructed externally by an RPC. passive. waiting. main character energy that only moves when summoned 👑
  • --sandbox=VAL (absent DUNE_SANDBOX env) — Set sandboxing mode. Some actions require a certain sandboxing mode, so they will ignore this setting. The allowed values are: none, symlink, copy, hardlink. four (4) values, and also heyyyy it reads the DUNE_SANDBOX env var if you don't pass it 💖
  • --sanitize-for-tests — Sanitize the absolute paths in workspace items, and the associated UIDs, so that the output is reproducible. for reproducible output, as a treat 🧚
  • --stop-on-first-error — Stop the build as soon as an error is encountered. no mercy. first error, we're out 😤
  • -w, --watch — Instead of terminating build after completion, wait continuously for file changes. it just. keeps going. forever. watching. 🌙
  • --wait-for-filesystem-clock — okay so: Dune digest file contents for better incrementally. 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 like — you should probably not care about this option; it is mostly useful for Dune developers to make Dune tests of the digest cache more reproducible. it's an iykyk situation fr fr 🙈
  • --with-deps — Whether the dependencies between modules should be printed. the module tea ☕
  • --with-pps — Whether the dependencies towards ppx-rewriters (that are called at compile time) should be taken into account. ppx-rewriters, compile time, all of it, accounted for 🦋
🫶 okay that's part one bestie, but there's more coming — don't go anywhere 💖

💖 COMMON OPTIONS 💖

Okay bestie, these are the universal ones. Like, these work on every command, not just describe. Slay. 🎀

  • --always-show-command-line — literally always show the full command lines of the programs dune runs. no hiding. 🫶
  • --auto-promote — auto-promote your files. it's basically the same as running dune promote right after the build. lowkey magic.
  • --build-dir=FILE (absent → falls back to the DUNE_BUILD_DIR env var) — the build directory you want. if you don't say anything it's _build. classic. ✨
  • --cache=VAL (absent → DUNE_CACHE env) — turn the Dune cache on or off. options are disabled, enabled-except-user-rules or enabled. the default? enabled-except-user-rules. she's the main character fr.
  • --cache-check-probability=VAL (absent → DUNE_CACHE_CHECK_PROBABILITY env) — check whether builds are reproducible by re-running randomly chosen rules and comparing their results to what's stored in the Dune cache. ⚠️ note: the more you crank up this probability, the slower your build gets. default probability is zero, meaning nobody gets checked. zero thoughts, head empty.
  • --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. not like other configs.
  • --debug-backtraces — always print exception backtraces. for when you simply must know. 😭
  • --debug-dependency-path — if something errors, print the dependency path all the way from the targets on the command line to the rule that failed. it's giving detective energy 🔍
  • --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 used when you don't specify one to dune build.
  • --diff-command=VAL (absent → DUNE_DIFF_COMMAND env) — the shell command used to diff files. pass - to disable printing the diff entirely. 🙈
  • --disable-promotion (absent → DUNE_DISABLE_PROMOTION env) — disable all promotion rules. nobody's promoting anything today, bestie.
  • --display=MODE — control how Dune displays stuff. check dune-config(5) for the details. valid values are progress, verbose, short, quiet or tui. pick your vibe 🌈
  • --dump-gc-stats=FILE — dump the garbage collector stats to a file once the build is done. numbers, but make it fashion. ✨
  • --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 is pager or plain whenever the TERM env var is dumb or not set at all. she adapts. 💅
  • --ignore-promoted-rules — ignore rules that have (mode promote), except the ones with (only ...). the variable %{ignoring_promoted_rules} in dune files reflects whether you passed this option or not. yep, she's watching. 👑
  • --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. no backend, no entry. 🚫
  • -j JOBS (absent → DUNE_JOBS env) — run no 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 is the default). auto-detect is so her. 🧚
  • --no-buffer — do not buffer the output of commands executed by dune. by default dune buffers subcommand output so nothing interleaves when multiple commands run in parallel. but that can be a whole issue when you're debugging long-running tests. with --no-buffer, the commands get direct access to the terminal. ⚠️ heads up though: 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 you should also use --verbose as well, to make sure commands are printed before they get executed. team work makes the dream work 🫶
  • --no-config — don't load the configuration file. periodt.
  • --no-print-directory — suppress the Entering directory messages. quiet queen. 🤫
  • --only-packages=PACKAGES — ignore any stanzas that refer to a package that's not in PACKAGES. PACKAGES is a comma-separated list of package names. note this does the exact same thing as deleting the relevant stanzas out of your dune files. it's mostly meant for releases. during development, what you probably actually 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 you only build what's necessary when your project has multiple packages, and so you get reproducible builds. yes, must. we don't make the rules (we do, actually, but still). 💅
  • --pkg=VAL — enable or disable package management. the default behaviour depends on whether a lock directory exists. suspenseful.
  • --profile=VAL (absent → DUNE_PROFILE env) — pick the build profile, like dev or release. default is dev. 🌸
  • --promote-install-files[=VAL] (default=true) — promote any generated <package>.install files into the source tree.
  • --release — put dune into reproducible release mode. it's 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 anyway. don't double up, bestie. 🔥
  • --require-dune-project-file[=VAL] (default=true) — fail if a dune-project file is missing. no file, no build. sorry. 😭
  • --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 meant for scripts. iykyk.
  • --store-orig-source-dir (absent → DUNE_STORE_ORIG_SOURCE_DIR env) — store the original source location in the dune-package metadata. receipts, kept. 🧾
  • --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 gets displayed on 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). fancy. ✨
  • --verbose — same as --display verbose. two ways, one vibe.
  • --version — show version information.
  • --watch-exclusions=REGEX — adds a POSIX regular expression that excludes matching directories from dune build --watch. you can repeat the --watch-exclusions option to add multiple exclusions, and semicolons work as a separator too. ⚠️ here's the tea: if you provide no exclusions, a standard set gets used. but if you use one or more --watch-exclusions, none of the standard exclusions are used anymore. it's all or nothing, bestie. 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 💜

Need help with just one command? girly just run:

dune COMMAND --help

that's it. that's the whole tip. 🎀

⭐ EXIT STATUS ⭐

dune describe exits with:

  1. 0 — on success. we love a happy ending. 🥳
  2. 1 — if an error happened. 😭
  3. 130 — if it was interrupted by a signal. rip, she got interrupted mid-sentence. 💀

🦋 ENVIRONMENT 🦋

these environment variables affect how describe runs, bestie. memorize them, or at least bookmark this. 📌

  • DUNE_BUILD_DIR — specified build directory. _build if unspecified.
  • DUNE_CACHE — enable or disable the 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 the ones stored in the Dune cache. ⚠️ note: cranking this up slows your build down. the default probability is zero, i.e., no rules get 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 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's 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 🫶

found a bug? not cute. check bug reports at https://github.com/ocaml/dune/issues — the devs are literally so on it, fr fr. 🐛✨

👑 SEE ALSO 👑

  • dune(1) — the main character herself.

<div align="center">

💖✨ aaaand that's the whole page ✨💖

sending you off with love from Dune 3.24.1, page DUNE-DESCRIBE(1) — go build something iconic, bestie. you got this. periodt. 💅🦋🌸

</div>

📦 where this page comes from