DUNE-SUBST(1)

📦
version 3.24.1 · 13 versions
, in ubuntu stonking

💖 DUNE-SUBST(1) 💖

okay bestie, welcome to the Dune Manual ✨ this one's called dune-subst, and it's the lil glow-up fairy for your source files 🧚

✨ NAME ✨

dune-subst — swaps out watermarks in your source files 💅

🌸 SYNOPSIS 🌸

dune subst [--build-info] [OPTION]…

🦋 DESCRIPTION 🦋

So basically, dune subst goes through your source files and replaces %%ID%% strings — same vibe as what topkg does in its default configuration. no cap 💖

heads up tho: this command is only meant to be called when a user pins a package to its development version. it's not a casual everyday thing, it's a special-occasion thing 🎀

What it's doing: it swaps %%VERSION%% strings for the version it gets from the vcs. Currently only git is supported, and the version comes straight from the output of:

$ git describe --always --dirty --abbrev=7

And dune subst substitutes exactly the variables that topkg substitutes with the default configuration:

  • %%NAME%% — the name of the project (pulled from the dune-project file)
  • %%VERSION%% — output of git describe --always --dirty --abbrev=7
  • %%VERSION_NUM%% — same as %%VERSION%% but with a potential leading 'v' or 'V' dropped
  • %%VCS_COMMIT_ID%% — commit hash from the vcs
  • %%PKG_MAINTAINER%% — contents of the maintainer: field from the opam file
  • %%PKG_AUTHORS%% — contents of the authors: field from the opam file
  • %%PKG_HOMEPAGE%% — contents of the homepage: field from the opam file
  • %%PKG_ISSUES%% — contents of the issues: field from the opam file
  • %%PKG_DOC%% — contents of the doc: field from the opam file
  • %%PKG_LICENSE%% — contents of the license: field from the opam file
  • %%PKG_REPO%% — contents of the repo: field from the opam file

So like, when you want dune subst to run at the moment your package gets pinned, you just add this line to the build: field of your opam file:

[dune "subst"] {pinned}

periodt 💅

⚠️ lowkey important: this command is meant to be called only from opam files, and it behaves a bit differently from other dune commands. specifically, it doesn't try to detect the root, so you must call it from the root of the project. like, from the actual root. not a subdirectory. from the root, bestie 🙈

💅 OPTIONS 💅

  • --build-info — show build information. that's the whole thing 🫶

🌈 COMMON OPTIONS 🌈

these ones are common to all commands, so they're basically the shared friend group of every dune command 👑

  • --debug-backtraces — always print exception backtraces. no hiding, full drama 😭
  • --help[=FMT] (default=auto) — show this help in format FMT. the value 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 undefined. slay ✨
  • --version — show version information 🌸

🎀 MORE HELP 🎀

Want help on just one command? run:

`dune COMMAND --help'

for help on a single command 💖

⭐ EXIT STATUS ⭐

dune subst exits with:

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

🐛 BUGS 🐛

found a bug? check bug reports at https://github.com/ocaml/dune/issues — go be a main character and file it 🫶

👑 SEE ALSO 👑

dune(1)

okay that's the whole thing, bestie!! go substitute those watermarks, you've got this 💜

later, legend — this was Dune 3.24.1, the DUNE-SUBST(1) page, and yes it ate ✨💅🎀

📦 where this page comes from