1DUNE-DESCRIBE(1) Dune Manual DUNE-DESCRIBE(1)
2
6 dune-describe - Describe the workspace.
7
9 dune describe [COMMAND] …
10
12 Describe what is in the current workspace in either human or machine
13 readable form. By default, this command output a human readable
14 description of the current workspace. This output is aimed at human and
15 is not suitable for machine processing. In particular, it is not
16 versioned. If you want to interpret the output of this command from a
17 program, you must use the --format option to specify a machine readable
18 format as well as the --lang option to get a stable output.
19
21 aliases [OPTION]… [DIR]…
22 Print aliases in a given directory. Works similalry to ls.
23 env [OPTION]… [PATH]
25 Print the environment of a directory
26 external-lib-deps [OPTION]…
28 Print out external libraries needed to build the project. It's an
29 approximated set of libraries.
30 installed-libraries [OPTION]…
32 Print out libraries installed on the system.
33 opam-files [OPTION]…
35 Print information about the opam files that have been discovered.
36 package-entries [OPTION]…
38 prints information about the entries per package
39 pp [OPTION]… FILE
41 Build a given FILE and print the preprocessed output.
42 rules [OPTION]… [TARGET]…
44 Dump rules.
45 targets [OPTION]… [DIR]…
47 Print targets in a given directory. Works similalry to ls.
48 workspace [OPTION]… [DIRS]…
50 Print a description of the workspace's structure. If some
51 directories DIRS are provided, then only those directories of the
52 workspace are considered.
53
55 DIRS
56 prints a description of the workspace's structure. If some
57 directories DIRS are provided, then only those directories of the
58 workspace are considered.
59
61 --action-stderr-on-success=VAL
62 Same as --action-stdout-on-success but for the standard output for
63 error messages. A good default for large mono-repositories is
64 --action-stdout-on-success=swallow
65 --action-stderr-on-success=must-be-empty. This ensures that a
66 successful build has a "clean" empty output.
67 --action-stdout-on-success=VAL
69 Specify how to deal with the standard output of actions when they
70 succeed. Possible values are: print to just print it to Dune's
71 output, swallow to completely ignore it and must-be-empty to
72 enforce that the action printed nothing. With must-be-empty, Dune
73 will consider that the action failed if it printed something to its
74 standard output. The default is print.
75 --build-info
77 Show build information.
78 --context=CONTEXT (absent=default)
80 Build context to use.
81 --display-separate-messages
83 Separate error messages with a blank line.
84 --error-reporting=VAL (absent=deterministic)
86 Controls when the build errors are reported. early - report errors
87 as soon as they are discovered. deterministic - report errors at
88 the end of the build in a deterministic order. twice - report each
89 error twice: once as soon as the error is discovered and then again
90 at the end of the build, in a deterministic order.
91 -f, --force
93 Force actions associated to aliases to be re-executed even if their
94 dependencies haven't changed.
95 --file-watcher=VAL (absent=automatic)
97 Mechanism to detect changes in the source. Automatic to make dune
98 run an external program to detect changes. Manual to notify dune
99 that files have changed manually."
100 --format=FORMAT (absent=sexp)
102 FORMAT must be either sexp or csexp
103 --lang=VERSION (absent=0.1)
105 Behave the same as this version of Dune.
106 --passive-watch-mode
108 Similar to [--watch], but only start a build when instructed
109 externally by an RPC.
110 --react-to-insignificant-changes
112 react to insignificant file system changes; this is only useful for
113 benchmarking dune
114 --sandbox=VAL (absent DUNE_SANDBOX env)
116 Sandboxing mode to use by default. Some actions require a certain
117 sandboxing mode, so they will ignore this setting. The allowed
118 values are: none, symlink, copy, hardlink.
119 --sanitize-for-tests
121 Sanitize the absolute paths in workspace items, and the associated
122 UIDs, so that the output is reproducible.
123 -w, --watch
125 Instead of terminating build after completion, wait continuously
126 for file changes.
127 --wait-for-filesystem-clock
129 Dune digest file contents for better incrementally. These digests
130 are themselves cached. In some cases, Dune needs to drop some
131 digest cache entries in order for things to be reliable. This
132 option makes Dune wait for the file system clock to advance so that
133 it doesn't need to drop anything. You should probably not care
134 about this option; it is mostly useful for Dune developers to make
135 Dune tests of the digest cache more reproducible.
136 --with-deps
138 Whether the dependencies between modules should be printed.
139 --with-pps
141 Whether the dependencies towards ppx-rewriters (that are called at
142 compile time) should be taken into account.
143
145 These options are common to all commands.
146 --always-show-command-line
148 Always show the full command lines of programs executed by dune
149 --auto-promote
151 Automatically promote files. This is similar to running dune
152 promote after the build.
153 --build-dir=FILE (absent DUNE_BUILD_DIR env)
155 Specified build directory. _build if unspecified
156 --cache=VAL (absent DUNE_CACHE env)
158 Enable or disable Dune cache (either enabled or disabled). Default
159 is `disabled'.
160 --cache-check-probability=VAL (absent DUNE_CACHE_CHECK_PROBABILITY env)
162 Check build reproducibility by re-executing randomly chosen rules
163 and comparing their results with those stored in Dune cache. Note:
164 by increasing the probability of such checks you slow down the
165 build. The default probability is zero, i.e. no rules are checked.
166 --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env)
168 Dune cache storage mode (one of auto, hardlink or copy). Default is
169 `auto'.
170 --config-file=FILE
172 Load this configuration file instead of the default one.
173 --debug-artifact-substitution
175 Print debugging info about artifact substitution
176 --debug-backtraces
178 Always print exception backtraces.
179 --debug-cache=VAL
181 Show debug messages on cache misses for the given cache layers.
182 Value is a comma-separated list of cache layer names. All available
183 cache layers: shared,workspace-local,fs.
184 --debug-dependency-path
186 In case of error, print the dependency path from the targets on the
187 command line to the rule that failed.
188 --debug-digests
190 Explain why Dune decides to re-digest some files
191 --debug-load-dir
193 Print debugging info about directory loading
194 --debug-store-digest-preimage
196 Store digest preimage for all computed digests, so that it's
197 possible to reverse them later, for debugging. The digests are
198 stored in the shared cache (see --cache flag) as values, even if
199 cache is otherwise disabled. This should be used only for
200 debugging, since it's slow and it litters the shared cache.
201 --default-target=TARGET (absent=@@default)
203 Set the default target that when none is specified to dune build.
204 --diff-command=VAL (absent DUNE_DIFF_COMMAND env)
206 Shell command to use to diff files. Use - to disable printing the
207 diff.
208 --disable-promotion (absent DUNE_DISABLE_PROMOTION env)
210 Disable all promotion rules
211 --display=MODE
213 Control the display mode of Dune. See dune-config(5) for more
214 details. Valid values for this option are progress, verbose, short,
215 quiet or tui.
216 --dump-gc-stats=FILE
218 Dump the garbage collector stats to a file after the build is
219 complete.
220 --dump-memo-graph=FILE
222 Dumps the dependency graph to a file after the build is complete
223 --dump-memo-graph-format=FORMAT (absent=gexf)
225 File format to be used when dumping dependency graph
226 --dump-memo-graph-with-timing
228 With --dump-memo-graph, will re-run each cached node in the Memo
229 graph after building and include the runtime in the output. Since
230 all nodes contain a cached value, this will measure just the
231 runtime of each node
232 --help[=FMT] (default=auto)
234 Show this help in format FMT. The value FMT must be one of auto,
235 pager, groff or plain. With auto, the format is pager or plain
236 whenever the TERM env var is dumb or undefined.
237 --ignore-promoted-rules
239 Ignore rules with (mode promote), except ones with (only ...). The
240 variable %{ignoring_promoted_rules} in dune files reflects whether
241 this option was passed or not.
242 --instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env)
244 "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
245 list of library names, each one of which must declare an
246 instrumentation backend.
247 -j JOBS
249 Run no more than JOBS commands simultaneously.
250 --no-buffer
252 Do not buffer the output of commands executed by dune. By default
253 dune buffers the output of subcommands, in order to prevent
254 interleaving when multiple commands are executed in parallel.
255 However, this can be an issue when debugging long running tests.
256 With --no-buffer, commands have direct access to the terminal. Note
257 that as a result their output won't be captured in the log file.
258 You should use this option in conjunction with -j 1, to avoid
259 interleaving. Additionally you should use --verbose as well, to
260 make sure that commands are printed before they are being executed.
261 --no-config
263 Do not load the configuration file
264 --no-print-directory
266 Suppress "Entering directory" messages
267 --only-packages=PACKAGES
269 Ignore stanzas referring to a package that is not in PACKAGES.
270 PACKAGES is a comma-separated list of package names. Note that this
271 has the same effect as deleting the relevant stanzas from dune
272 files. It is mostly meant for releases. During development, it is
273 likely that what you want instead is to build a particular
274 <package>.install target.
275 -p PACKAGES, --for-release-of-packages=PACKAGES (required)
277 Shorthand for --release --only-packages PACKAGE. You must use this
278 option in your <package>.opam files, in order to build only what's
279 necessary when your project contains multiple packages as well as
280 getting reproducible builds.
281 --print-metrics
283 Print out various performance metrics after every build
284 --profile=VAL (absent DUNE_PROFILE env)
286 Select the build profile, for instance dev or release. The default
287 is dev.
288 --promote-install-files[=VAL] (default=true)
290 Promote the generated <package>.install files to the source tree
291 --release
293 Put dune into a reproducible release mode. This is in fact a
294 shorthand for --root . --ignore-promoted-rules --no-config
295 --profile release --always-show-command-line
296 --promote-install-files --default-target @install
297 --require-dune-project-file. You should use this option for release
298 builds. For instance, you must use this option in your
299 <package>.opam files. Except if you already use -p, as -p implies
300 this option.
301 --require-dune-project-file[=VAL] (default=true)
303 Fail if a dune-project file is missing.
304 --root=DIR
306 Use this directory as workspace root instead of guessing it. Note
307 that this option doesn't change the interpretation of targets given
308 on the command line. It is only intended for scripts.
309 --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env)
311 Store original source location in dune-package metadata
312 --terminal-persistence=MODE
314 Changes how the log of build results are displayed to the console
315 between rebuilds while in --watch mode. Supported modes: preserve,
316 clear-on-rebuild, clear-on-rebuild-and-flush-history.
317 --trace-extended
319 Output extended trace data (requires trace-file)
320 --trace-file=FILE
322 Output trace data in catapult format (compatible with
323 chrome://tracing)
324 --verbose
326 Same as --display verbose
327 --version
329 Show version information.
330 --watch-exclusions=REGEX
332 Adds a POSIX regular expression that will exclude matching
333 directories from `dune build --watch`. The option
334 --watch-exclusions can be repeated to add multiple exclusions.
335 Semicolons can be also used as a separator. If no exclusions are
336 provided, then a standard set of exclusions is used; however, if
337 one or more --watch-exclusions are used, none of the standard
338 exclusions are used. The standard exclusions are: ^_opam /_opam
339 ^_esy /_esy ^\.#.* /\.#.* ~$ ^#[^#]*#$ /#[^#]*#$ ^4913$ /4913$
340 /.git /.hg :/windows
341 --workspace=FILE (absent DUNE_WORKSPACE env)
343 Use this specific workspace file instead of looking it up.
344 -x VAL
346 Cross-compile using this toolchain.
347
349 Use `dune COMMAND --help' for help on a single command.
350
352 describe exits with the following status:
353 0 on success.
355 1 if an error happened.
357 130 if it was interrupted by a signal.
359
361 These environment variables affect the execution of describe:
362 DUNE_BUILD_DIR
364 Specified build directory. _build if unspecified
365 DUNE_CACHE
367 Enable or disable Dune cache (either enabled or disabled). Default
368 is `disabled'.
369 DUNE_CACHE_CHECK_PROBABILITY
371 Check build reproducibility by re-executing randomly chosen rules
372 and comparing their results with those stored in Dune cache. Note:
373 by increasing the probability of such checks you slow down the
374 build. The default probability is zero, i.e. no rules are checked.
375 DUNE_CACHE_STORAGE_MODE
377 Dune cache storage mode (one of auto, hardlink or copy). Default is
378 `auto'.
379 DUNE_DIFF_COMMAND
381 Shell command to use to diff files. Use - to disable printing the
382 diff.
383 DUNE_DISABLE_PROMOTION
385 Disable all promotion rules
386 DUNE_INSTRUMENT_WITH
388 "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
389 list of library names, each one of which must declare an
390 instrumentation backend.
391 DUNE_PROFILE
393 Build profile. dev if unspecified or release if -p is set.
394 DUNE_SANDBOX
396 Sandboxing mode to use by default. (see --sandbox)
397 DUNE_STORE_ORIG_SOURCE_DIR
399 Store original source location in dune-package metadata
400 DUNE_WORKSPACE
402 Use this specific workspace file instead of looking it up.
403
405 Check bug reports at https://github.com/ocaml/dune/issues
406
408 dune(1)
409Dune n/a DUNE-DESCRIBE(1)