DUNE-EXTERNAL-LIB-DEPS(1)

📦
version 3.24.1 · 15 versions
, in ubuntu stonking

💖 DUNE-EXTERNAL-LIB-DEPS 💖

okay so bestie, this is a page from the Dune Manual — it's DUNE-EXTERNAL-LIB-DEPS(1) and honestly? she's a ghost. a legend. a memory. let's get into it 🫶

✨ NAME ✨

dune-external-lib-deps — literally just got moved to dune describe external-lib-deps. that's it. that's the name. moving on 💅

🌸 SYNOPSIS 🌸

dune external-lib-deps [OPTION]… [TARGET]…

🦋 DESCRIPTION 🦋

so back in the day, this subcommand would print out an approximate set of external libraries you'd need to build a given set of targets — and it did that without actually running the build. iconic behavior, honestly. no cap.

but like… the approximation got worse over time 😭 and the maintenance cost went up 📈, so the Dune girlies decided to remove it entirely. she's gone. periodt.

👑 OPTIONS 👑

  • --action-stderr-on-success=VAL — same vibe as --action-stdout-on-success, except it's about standard error instead of standard output. a good default for big ol' mono-repositories is --action-stdout-on-success=swallow plus --action-stderr-on-success=must-be-empty. that combo guarantees a successful build has a "clean", empty output. chef's kiss ✨
  • --action-stdout-on-success=VAL — tells Dune how to handle an action's standard output when the action succeeds. the possible values are: print (just print it to Dune's output), swallow (completely ignore it), and must-be-empty (enforce that the action printed nothing). with must-be-empty, if the action printed anything to standard output, Dune counts it as a failure. the default is print.
  • --build-info — show build information. that's the whole thing 🎀
  • --display-separate-messages — separate error messages with a blank line. breathing room, we love to see it.
  • **--error-reporting=VAL (absent=deterministic)** — controls *when* build errors get reported. earlyreports errors as soon as they're discovered.deterministicreports errors at the end of the build, in a deterministic order.twice` reports each error twice: once the moment it's discovered, and then again at the end of the build, in a deterministic order. (yelling at you, then yelling at you again, respectfully.)
  • -f, --force — force actions associated with aliases to be re-executed, even if their dependencies haven't changed at all. no changes? don't care. running anyway 💅
  • *--file-watcher=VAL (absent=automatic)** — the mechanism used to detect changes in the source. automaticmakes Dune run an external program to detect changes.manual` means *you notify Dune that files have changed, manually.
  • --missing — unused. yeah. nothing. she's just sitting there 🙈
  • --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. some actions require a certain sandboxing mode, so they'll straight up ignore this setting. the allowed values are: none, symlink, copy, hardlink`.
  • --sexp — unused. also just vibing. no thoughts, head empty 💀
  • --stop-on-first-error — stop the build the second an error is encountered. no chill, no second chances.
  • --unstable-by-dir — unused. third one. she's also just here 🍓
  • -w, --watch — instead of terminating the build after completion, wait around continuously for file changes. main character who refuses to leave the party.
  • --wait-for-filesystem-clock — Dune digests file contents for better incrementality, and those digests are themselves cached. in some cases Dune needs to drop some digest cache entries so things stay reliable. this option makes Dune wait for the file system clock to advance, so it doesn't need to drop anything. you should probably not care about this option; it's mostly useful for Dune developers who want Dune's digest-cache tests to be more reproducible. (iykyk 🧚)

🌈 COMMON OPTIONS 🌈

these options are common to all commands, bestie. every single one.

  • --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 the Dune cache. one of disabled, enabled-except-user-rulesorenabled. 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 the Dune cache. note: the higher the probability of these checks, the slower your build gets. the default probability is zero, meaning no rules are checked.
  • **--cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env)** — Dune cache storage mode, one of auto, hardlinkorcopy. default is hardlink`.
  • --config-file=FILE — load this configuration file instead of the default one.
  • --debug-backtraces — always print exception backtraces. every last one.
  • --debug-dependency-path — if there's an error, print the dependency path all the way from the targets on the command line to the rule that failed. receipts, fully traced.
  • --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 none is specified 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.
  • --disable-promotion (absent DUNE_DISABLE_PROMOTION env)` — disable all promotion rules.
  • --display=MODE — control Dune's display mode. 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 once the build is complete.
  • **--help[=FMT] (default=auto)** — show this help in format FMT. the value FMTmust be one ofauto, pager, grofforplain. with auto, the format is pagerorplainwhenever theTERMenv var isdumb` 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 each one of them must declare an instrumentation backend.
  • **-j JOBS (absent DUNE_JOBS env)** — run no more than JOBScommands simultaneously.JOBSmust be a positive integer, orauto` 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 subcommand output, to prevent 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. 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 too, so commands get printed before they're executed. stack the flags, bestie.
  • --no-config — do not load the configuration file.
  • --no-print-directory — suppress "Entering directory" messages. bye 👋
  • --only-packages=PACKAGES — ignore stanzas that refer to a package that isn't in PACKAGES. PACKAGES is a comma-separated list of package names. note that this has the exact 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 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)** — select the build profile, for instance devorrelease. 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 it in your <package>.opam files — except if you already use -p, since -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 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)** — store the 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 excludes matching directories from dune build --watch. the option --watch-exclusions can be repeated to add multiple exclusions, and semicolons can also be used as a separator. if no exclusions are provided, a standard set of exclusions is used — but 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 🎀

for help on a single command, hit:

dune COMMAND --help

⭐ EXIT STATUS ⭐

dune external-lib-deps exits with:

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

🌸 ENVIRONMENT 🌸

These little env vars are the vibe-setters for external-lib-deps, bestie. Set them and the command does its thing your way 💖

  • DUNE_BUILD_DIR — tells Dune where the build directory should live. If you don't say anything, it's _build, no thoughts head empty 🎀
  • 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 checks build reproducibility by re-running randomly chosen rules and comparing the results with what's sitting in the Dune cache 🧚 Heads up though: cranking up the probability of these checks slows your build down. The default probability is zero, meaning literally no rules get checked, periodt.
  • DUNE_CACHE_STORAGE_MODE — how the Dune cache stores stuff. Pick 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. No hiding, we're being transparent 🫶
  • DUNE_DIFF_COMMAND — the shell command used to diff files. Use - to disable printing the diff entirely 🙈
  • DUNE_DISABLE_PROMOTION — disables all the promotion rules. All of them. Every single one 💀
  • DUNE_INSTRUMENT_WITH — enables instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and each one of those libraries has to declare an instrumentation backend 🔥
  • DUNE_JOBS — 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, iconic behaviour honestly) 👑
  • DUNE_PROFILE — the build profile. It's dev if you don't specify anything, or release if -p is set 🎀
  • DUNE_ROOT — use this directory as the workspace root instead of letting Dune guess it. Quick note though: this option doesn't 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) 🦋
  • 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 you're cross-compiling. Format is TOOLCHAIN=CMD (like, for example, 'windows=wine') 🍓
  • DUNE_WORKSPACE — use this specific workspace file instead of making Dune go looking for one 🔍

🐛 BUGS 🐛

Found something cursed? Check the bug reports at https://github.com/ocaml/dune/issues and tell the maintainers, they wanna know fr fr 😭

👀 SEE ALSO 👀

And that's the whole page, bestie, you ate it up 💅✨ This was Dune 3.24.1's write-up of DUNE-EXTERNAL-LIB-DEPS(1) — go forth, check those external lib deps, and slay 💖🦋🌸

📦 where this page comes from