DUNE-UTOP(1)

📦
version 3.24.1 · 15 versions
, in ubuntu stonking

🌈 dune-utop(1) 🌈 — Dune Manual vibes only ✨

okay so. bestie. you found the manual page. it's giving✨documentation✨ and honestly? it's a lot. but we're gonna get through it together because you deserve to know what dune utop is doing. no cap. 💅

🎀 NAME 🎀

dune-utop — load your library up in utop, fr fr. 🦋

🍓 SYNOPSIS 🍓

dune utop [OPTION]… [DIR] [ARGS]…

💖 DESCRIPTION 💖

dune utop DIR does the whole thing: it builds and then runs the utop toplevel with all the libraries that are defined in DIR. like, it hands you a toplevel pre-loaded with your own code. iconic behaviour honestly. 👑

✨ OPTIONS ✨

  • --action-stderr-on-success=VAL — literally the same as --action-stdout-on-success except it's for standard error instead of standard output. for big mono-repos the glow-up default is --action-stdout-on-success=swallow --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 — controls how Dune treats the standard output of actions when they succeed. 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 decides the action failed if it printed anything to its standard output 😭). default is print.
  • --build-info — show build information. that's it, that's the option. 📋
  • --context=CONTEXT (absent=default) — pick which context to build/run utop in. 🏠
  • --display-separate-messages — separate error messages with a blank line. breathing room between the chaos. 😮‍💨
  • --error-reporting=VAL (absent=deterministic) — controls when build errors get reported. early reports errors the second they're discovered. deterministic reports errors at the end of the build, in a deterministic order. twice reports each error twice: once the moment it's discovered, and again at the end of the build in deterministic order. yes, twice. it said what it said. 💀
  • -f, --force — forces actions tied to aliases to be re-executed even if their dependencies haven't changed. no take-backs. 🔥
  • --file-watcher=VAL (absent=automatic) — the mechanism for detecting changes in the source. automatic makes dune run an external program to spot changes. manual means you notify dune yourself that files changed. 👀
  • --passive-watch-mode — basically --watch but chill: it only starts a build when something instructs it externally via an RPC. 😌
  • --sandbox=VAL (absent DUNE_SANDBOX env) — sets the sandboxing mode. heads up: some actions require a certain sandboxing mode, so they'll just ignore this setting entirely (main character energy, honestly). allowed values are: none, symlink, copy, hardlink. 📦
  • --stop-on-first-error — stop the build the absolute second an error shows up. no waiting, no collecting. 💅
  • -w, --watch — instead of dipping out after the build completes, it just waits around continuously for file changes. 🕰️
  • --wait-for-filesystem-clock — okay so Dune digests file contents for better incrementality, and those digests get cached. sometimes Dune has to drop some digest cache entries so everything stays 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 at all — it's mostly for Dune developers, to make Dune's tests of the digest cache more reproducible. 🧪

🌸 COMMON OPTIONS 🌸

these ones are common to all commands, not just this one. ✨

  • --always-show-command-line — always show the full command lines of the programs Dune executes. full transparency, no secrets. 🔍
  • --auto-promote — automatically promote files. it's basically the same as running dune promote after the build. glow-up on autopilot. 💖
  • --build-dir=FILE (absent DUNE_BUILD_DIR env) — specifies the build directory. if you don't specify it? _build. 📁
  • --cache=VAL (absent DUNE_CACHE env) — turn the Dune cache on or off. one of disabled, enabled-except-user-rules or enabled. 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 their results against what's stored in the Dune cache. ⚠️ heads up though: raising this probability slows your build down. default probability is zero, meaning no rules get checked at all. 🐌
  • --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env) — Dune cache storage mode, one of auto, hardlink or copy. default is hardlink. 💾
  • --config-file=FILE — load this configuration file instead of the default one. picky, and valid for it. 📄
  • --debug-backtraces — always print exception backtraces. 🐛
  • --debug-dependency-path — if there's an error, print the dependency path from the targets on the command line all the way to the rule that failed. follow the breadcrumbs. 🍞
  • --debug-package-logs (absent DUNE_DEBUG_PACKAGE_LOGS env) — always print the standard logs when building packages. 📜
  • --default-target=TARGET (absent=@@default) — sets the default target used when none is specified to dune build. 🎯
  • --diff-command=VAL (absent DUNE_DIFF_COMMAND env) — the shell command used to diff files. use - to disable printing the diff. 🔀
  • --disable-promotion (absent DUNE_DISABLE_PROMOTION env) — disables all promotion rules. 🚫
  • --display=MODE — controls 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. FMT must be one of auto, pager, groff or plain. with auto, the format is pager or plain whenever the TERM env var is dumb or undefined. 🆘
  • --ignore-promoted-rules — ignore rules with (mode promote), except 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 JOBS commands simultaneously. 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 executed by dune. by default dune does buffer subcommand output, so that parallel commands don't interleave into a mess. but that can be a real problem when you're debugging long running tests. with --no-buffer, commands get direct access to the terminal. ⚠️ but note: as a result their output won't be captured in the log file. you should use this together with -j 1 to avoid interleaving, and you should also use --verbose so commands get printed before they're executed. 🖨️
  • --no-config — don't load the configuration file. 🙅
  • --no-print-directory — suppress "Entering directory" messages. shhh. 🤫
  • --only-packages=PACKAGES — ignore stanzas that refer to a package not in PACKAGES. PACKAGES is a comma-separated list of package names. heads up: this has the same effect as deleting the relevant stanzas from dune files, and it's mostly meant for releases. during development, what you probably actually want is 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 that only what's necessary gets built when your project contains multiple packages, and so you get reproducible builds. non-negotiable. 📌
  • --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 dev or release. default is dev. 🎚️
  • --promote-install-files[=VAL] (default=true) — promote 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, 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 the interpretation of targets given on the command line. 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 — changes 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 will exclude matching directories from dune build --watch. this option can be repeated to add multiple exclusions. semicolons can also be used as a separator. if no exclusions are provided, then a standard set of exclusions is used — however, if one or more --watch-exclusions are used, 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) — use this specific workspace file instead of looking it up. 📓
  • -x VAL (absent DUNE_CROSS_TARGET env) — cross-compile using this toolchain. 🌍

💜 MORE HELP 💜

use dune COMMAND --help for help on a single command. because yes, every single one has its own page. slay. 💅

👑 EXIT STATUS 👑

dune utop exits with:

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

🌿 ENVIRONMENT 🌿

okay bestie so these are the env vars that literally change how utop runs under Dune. set them, unset them, whatever — they're vibes you can hand to the process. 💖

  • DUNE_BUILD_DIR — the build directory you want. lowkey, if you don't say anything it's _build.
  • DUNE_CACHE — turn the Dune cache on or off. it's one of disabled, enabled-except-user-rules or enabled. default is enabled-except-user-rules. periodt.
  • DUNE_CACHE_CHECK_PROBABILITY — this one re-executes randomly chosen rules and compares the results with what's stored in the Dune cache, you know, just to check build reproducibility. heads up bestie: crank up the probability and your build gets slower. default probability is zero, so like, no rules get checked at all. 🐢
  • DUNE_CACHE_STORAGE_MODE — the storage mode for the Dune cache. 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 — the shell command used to diff files. use - to disable printing the diff entirely. ✨
  • DUNE_DISABLE_PROMOTION — disables all the promotion rules.
  • DUNE_INSTRUMENT_WITH — enables instrumentation by BACKENDS. BACKENDS is a comma-separated list of library names, and each one of them must declare an instrumentation backend. no backend, no entry, iykyk.
  • 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, bestie).
  • DUNE_PROFILE — the build profile. it's dev if unspecified, or release if -p is set.
  • DUNE_ROOT — use this directory as the workspace root instead of letting Dune guess it. note that this option doesn't change how targets given on the command line are interpreted — it's only intended for scripts. 🤫
  • DUNE_SANDBOX — the sandboxing mode to use by default. (peep --sandbox for the details, k?)
  • DUNE_STORE_ORIG_SOURCE_DIR — store the original source location in the dune-package metadata.
  • DUNE_TARGET_EXEC — a wrapper command for running target binaries when you're cross-compiling. format is: TOOLCHAIN=CMD (e.g., 'windows=wine').
  • DUNE_WORKSPACE — use this specific workspace file instead of looking it up. no scavenger hunt needed. 🔍

🐛 BUGS 🐛

found something cursed? check the bug reports at https://github.com/ocaml/dune/issues — the maintainers live there, fr fr. 🙈

👀 SEE ALSO 👀

okay that's the whole page, bestie, you're officially a dune-utop scholar now 💅✨ this was Dune 3.24.1, page DUNE-UTOP(1), and yes the date line at the bottom is just part of the manpage furniture — slay, go build something iconic 🎀🦋

📦 where this page comes from