DUNE-INSTALL(1)

📦
version 3.24.1 · 15 versions
, in ubuntu stonking

💖 DUNE-INSTALL(1) 💖

okay bestie, sit down, we're installing stuff ✨ this is the Dune manual page for dune-install, and it's lowkey a banger.

🌸 NAME 🌸

dune-install — install packages defined in the workspace 🫶

🎀 SYNOPSIS 🎀

So the way installation directories work is by priority, queen. Here's the order, top to bottom:

  • directories set on the command line of dune install, or the corresponding environment variables 👑
  • directories set in the dune binary. These get set up before the compilation of dune with ./configure
  • inferred from the environment variable OPAM_SWITCH_PREFIX if it's present

✨ OPTIONS ✨

okay this is the main character section, let's go 💅

  • --action-stderr-on-success=VAL — literally the same thing as --action-stdout-on-success but for standard error instead of standard output. And ngl, a really good default for big mono-repositories is:
--action-stdout-on-success=swallow
--action-stderr-on-success=must-be-empty

which makes sure a successful build has a "clean" empty output. ate. ✨

  • --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, Dune will consider that the action failed if it printed something to its standard output 😭. The default is print.
  • --bindir=PATH — manually override the directory where public binaries get installed. Only absolute path accepted, periodt. 💅
  • --build-info — show build information 👑
  • --context=CONTEXT — pick which context to install from. By default it installs files from all defined contexts.
  • --create-install-files — don't install directly, bestie, instead create install files in the root directory and create substituted files if needed in destdir (_destdir by default). 🦋
  • --datadir=PATH — manually override the directory where files from the share section get installed. Only absolute path accepted. ✨
  • --destdir=PATH (absent DESTDIR env) — this directory gets prepended to all installed paths.
  • --display-separate-messages — separate error messages with a blank line.
  • --docdir=PATH — manually override the directory where documentation files get installed. Only absolute path accepted. 🎀
  • --dry-run — only display the file operations that would be performed. like a little window shopping moment 🛍️
  • --error-reporting=VAL (absent=deterministic) — controls when the build errors get reported, girl.
    • 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 the error is discovered, and then again at the end of the build, in a deterministic order
  • --etcdir=PATH — manually override the directory where configuration files get installed. Only absolute path accepted. 💜
  • -f, --force — force actions associated to aliases to be re-executed even if their dependencies haven't changed. no cap.
  • --file-watcher=VAL (absent=automatic) — the mechanism for detecting changes in the source. automatic makes dune run an external program to detect changes. manual means you notify dune that files have changed manually. 🙈
  • --libdir=PATH — directory where library files are copied, relative to prefix or absolute. If --prefix is specified, the default is $prefix/lib. Only absolute path accepted.
  • --libexecdir=PATH — manually override the directory where executable library files get installed. Only absolute path accepted.
  • --mandir=PATH — manually override the directory where man pages get installed. Only absolute path accepted. (yes, this exact page you're reading right now, being a baddie 💅)
  • --passive-watch-mode — similar to [--watch], but it only starts a build when instructed externally by an RPC. it's giving "I'll build when I'm asked to build" 💀
  • --prefix=PREFIX (absent DUNE_INSTALL_PREFIX env) — the directory where files get copied. For instance, binaries get copied into $prefix/bin, library files into $prefix/lib, etc...
  • --relocatable — makes the binaries relocatable, meaning the installation directory can be moved 🦋. The installation directory must be specified with --prefix.
  • --sandbox=VAL (absent DUNE_SANDBOX env) — set the sandboxing mode. Some actions require a certain sandboxing mode, so they will ignore this setting 👀. The allowed values are: none, symlink, copy, hardlink.
  • --sbindir=PATH — manually override the directory where files from the sbin section get installed. Only absolute path accepted. ✨
  • --sections=VAL — sections that should be installed.
  • --stop-on-first-error — stop the build as soon as an error is encountered. no patience, only urgency 💅
  • -w, --watch — instead of terminating the build after completion, wait continuously for file changes. main character energy fr fr 👑
  • --wait-for-filesystem-clock — Dune digests file contents for better incrementality, and 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 it doesn't need to drop anything. 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. 🌈

and that's part one, bestie — more is coming so don't you dare close the tab 💖

🌸 COMMON OPTIONS 🌸

Okay bestie, these ones are the shared options — like the communal snacks of the dune world. Every command gets them, no gatekeeping. 💖

  • --always-show-command-line — literally always show the full command lines of programs that dune runs. Every single one. No hiding. 👀
  • --auto-promote — promote files automatically, which is basically the same thing as running dune promote after the build. Iconic laziness, honestly. ✨
  • --build-dir=FILE (absent DUNE_BUILD_DIR env) — says which build directory to use. If you don't say anything, it's _build. Default behaviour, no thoughts. 🌸
  • --cache=VAL (absent DUNE_CACHE env) — turns the Dune cache on or off. VAL must be 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) — checks whether builds are reproducible by re-running randomly chosen rules and comparing the results against what's in the Dune cache. ⚠️ Heads up: raising this probability makes your build slower, bestie. The default probability is zero, which means literally no rules get checked. Chill by default.
  • --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env) — picks the Dune cache storage mode, one of auto, hardlink or copy. Default is hardlink. 🫶
  • --config-file=FILE — loads this configuration file instead of the default one. Main character config. 👑
  • --debug-backtraces — always print exception backtraces. All of them. We love a paper trail. 📜
  • --debug-dependency-path — when there's an error, it prints the dependency path all the way from the targets on the command line to the rule that failed. Detective mode activated. 🔍
  • --debug-package-logs (absent DUNE_DEBUG_PACKAGE_LOGS env) — always print the standard logs while building packages. 👑
  • --default-target=TARGET (absent=@@default) — sets the default target used when you don't specify one to dune build. If you don't set it, it's @@default. 🎯
  • --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) — disables all promotion rules. Zero promotion. None. Nada. 💀
  • --display=MODE — controls dune's display mode. Peep dune-config(5) for the full tea ☕. Valid values for this option are progress, verbose, short, quiet or tui.
  • --dump-gc-stats=FILE — dumps the garbage collector stats into a file once the build finishes. 📊
  • --help[=FMT] (default=auto) — shows this help in the format FMT. FMT has to be one of auto, pager, groff or plain. With auto, the format becomes pager or plain whenever the TERM env var is dumb or not set at all. ✨
  • --ignore-promoted-rules — ignores rules with (mode promote), except the ones that have (only ...). The variable %{ignoring_promoted_rules} inside dune files shows whether you passed this option or not. 🦋
  • --instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env) — turns on instrumentation via BACKENDS. BACKENDS is a comma-separated list of library names, and every single one of them has to declare an instrumentation backend. No exceptions, bestie. 🎀
  • -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). 💅
  • --no-buffer — don't buffer the output of commands that dune executes. By default dune does buffer subcommand output to stop things from interleaving when multiple commands run in parallel. But ngl, that can be a real problem when you're debugging long running tests. With --no-buffer, commands get direct access to the terminal. ⚠️ Because of that, their output won't be captured in the log file. You should use this option together with -j 1 to avoid interleaving, and also use --verbose so you can be sure commands get printed before they're executed.
  • --no-config — do not load the configuration file. Periodt. 🚫
  • --no-print-directory — suppresses the "Entering directory" messages. Quiet-ish queen. 🤫
  • --only-packages=PACKAGES — ignores stanzas that refer to a package not in PACKAGES. PACKAGES is a comma-separated list of package names. Heads up: this does the exact same thing as deleting those stanzas from your dune files, and 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. Required is required, bestie.
  • --pkg=VAL — enables or disables package management. The default behaviour depends on whether a lock directory exists. 🔒
  • --profile=VAL (absent DUNE_PROFILE env) — selects the build profile, for instance dev or release. The default is dev. 💜
  • --promote-install-files[=VAL] (default=true) — promotes any generated <package>.install files into the source tree. 📦
  • --release — puts dune into a 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 option for release builds — for instance, you must use it in your <package>.opam files. Except if you already use -p, because -p implies this option. 🔥
  • --require-dune-project-file[=VAL] (default=true) — fails if a dune-project file is missing. No file, no build. 💀
  • --root=DIR (absent DUNE_ROOT env) — uses 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 while cross-compiling. Format: TOOLCHAIN=CMD (e.g., 'windows=wine'). 🍷
  • --terminal-persistence=MODE — changes how the log of build results shows up 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 — outputs trace data in catapult format (compatible with chrome://tracing). 📊
  • --verbose — same as --display verbose. That's it, that's the whole thing. 🗣️
  • --version — shows version information. 🏷️
  • --watch-exclusions=REGEX — adds a POSIX regular expression that excludes matching directories from dune build --watch. You can repeat --watch-exclusions to add multiple exclusions, and semicolons can also be used as a separator. If you provide no exclusions, then a standard set of exclusions gets used. However, if you use one or more --watch-exclusions, then 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) — uses this specific workspace file instead of looking one up. 🔎
  • -x VAL (absent DUNE_CROSS_TARGET env) — cross-compiles using this toolchain. 🌍

🫶 MORE HELP 🫶

Wanna know about just one command? Use dune COMMAND --help for help on a single command. One command, one help page, no scrolling through the whole novel. 💅

💀 EXIT STATUS 💀

dune install exits with:

  • 0 — on success. We ate. 🎉
  • 1 — if an error happened. Sad girl hours. 😭
  • 130 — if it was interrupted by a signal. Rude. 🛑

🌈 ENVIRONMENT 🌈

These environment variables affect the execution of install. Bestie, they're like the options' little siblings — same energy, different doorway. 🚪✨

  • DESTDIR — see option --destdir.
  • 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_INSTALL_PREFIX — see option --prefix.
  • 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 🐛

Found something cursed? Check bug reports at https://github.com/ocaml/dune/issues. Go snitch, bestie, it's how things get fixed. 💖

👀 SEE ALSO 👀

dune(1)

That's the whole page, babes. You read all of it and you understood it — main character energy, no cap. 🦋

This whole thing is from Dune 3.24.1, and yeah, it's the DUNE-INSTALL(1) page, sliced fresh for you. Now go build something iconic. 💅✨🎀

📦 where this page comes from