1DUNE-RULES(1) Dune Manual DUNE-RULES(1)
2
6 dune-rules - Dump rules.
7
9 dune rules [OPTION]… [TARGET]…
10
12 Dump Dune rules for the given targets. If no targets are given, dump
13 all the rules.
14 By default the output is a list of S-expressions, one S-expression per
16 rule. Each S-expression is of the form:
17 ((deps (<dependencies>))
19 (targets (<targets>))
20 (context <context-name>)
21 (action <action>))
22 <context-name> is the context is which the action is executed. It is
24 omitted if the action is independent from the context.
25 <action> is the action following the same syntax as user actions, as
27 described in the manual.
28
30 --action-stderr-on-success=VAL
31 Same as --action-stdout-on-success but for the standard output for
32 error messages. A good default for large mono-repositories is
33 --action-stdout-on-success=swallow
34 --action-stderr-on-success=must-be-empty. This ensures that a
35 successful build has a "clean" empty output.
36 --action-stdout-on-success=VAL
38 Specify how to deal with the standard output of actions when they
39 succeed. Possible values are: print to just print it to Dune's
40 output, swallow to completely ignore it and must-be-empty to
41 enforce that the action printed nothing. With must-be-empty, Dune
42 will consider that the action failed if it printed something to its
43 standard output. The default is print.
44 --build-info
46 Show build information.
47 --display-separate-messages
49 Separate error messages with a blank line.
50 --error-reporting=VAL (absent=deterministic)
52 Controls when the build errors are reported. early - report errors
53 as soon as they are discovered. deterministic - report errors at
54 the end of the build in a deterministic order. twice - report each
55 error twice: once as soon as the error is discovered and then again
56 at the end of the build, in a deterministic order.
57 -f, --force
59 Force actions associated to aliases to be re-executed even if their
60 dependencies haven't changed.
61 --file-watcher=VAL (absent=automatic)
63 Mechanism to detect changes in the source. Automatic to make dune
64 run an external program to detect changes. Manual to notify dune
65 that files have changed manually."
66 -m, --makefile
68 Output the rules in Makefile syntax.
69 -o FILE
71 Output to a file instead of stdout.
72 --passive-watch-mode
74 Similar to [--watch], but only start a build when instructed
75 externally by an RPC.
76 -r, --recursive
78 Print all rules needed to build the transitive dependencies of the
79 given targets.
80 --react-to-insignificant-changes
82 react to insignificant file system changes; this is only useful for
83 benchmarking dune
84 --sandbox=VAL (absent DUNE_SANDBOX env)
86 Sandboxing mode to use by default. Some actions require a certain
87 sandboxing mode, so they will ignore this setting. The allowed
88 values are: none, symlink, copy, hardlink.
89 -w, --watch
91 Instead of terminating build after completion, wait continuously
92 for file changes.
93 --wait-for-filesystem-clock
95 Dune digest file contents for better incrementally. These digests
96 are themselves cached. In some cases, Dune needs to drop some
97 digest cache entries in order for things to be reliable. This
98 option makes Dune wait for the file system clock to advance so that
99 it doesn't need to drop anything. You should probably not care
100 about this option; it is mostly useful for Dune developers to make
101 Dune tests of the digest cache more reproducible.
102
104 These options are common to all commands.
105 --always-show-command-line
107 Always show the full command lines of programs executed by dune
108 --auto-promote
110 Automatically promote files. This is similar to running dune
111 promote after the build.
112 --build-dir=FILE (absent DUNE_BUILD_DIR env)
114 Specified build directory. _build if unspecified
115 --cache=VAL (absent DUNE_CACHE env)
117 Enable or disable Dune cache (either enabled or disabled). Default
118 is `disabled'.
119 --cache-check-probability=VAL (absent DUNE_CACHE_CHECK_PROBABILITY env)
121 Check build reproducibility by re-executing randomly chosen rules
122 and comparing their results with those stored in Dune cache. Note:
123 by increasing the probability of such checks you slow down the
124 build. The default probability is zero, i.e. no rules are checked.
125 --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env)
127 Dune cache storage mode (one of auto, hardlink or copy). Default is
128 `auto'.
129 --config-file=FILE
131 Load this configuration file instead of the default one.
132 --debug-artifact-substitution
134 Print debugging info about artifact substitution
135 --debug-backtraces
137 Always print exception backtraces.
138 --debug-cache=VAL
140 Show debug messages on cache misses for the given cache layers.
141 Value is a comma-separated list of cache layer names. All available
142 cache layers: shared,workspace-local,fs.
143 --debug-dependency-path
145 In case of error, print the dependency path from the targets on the
146 command line to the rule that failed.
147 --debug-digests
149 Explain why Dune decides to re-digest some files
150 --debug-load-dir
152 Print debugging info about directory loading
153 --debug-store-digest-preimage
155 Store digest preimage for all computed digests, so that it's
156 possible to reverse them later, for debugging. The digests are
157 stored in the shared cache (see --cache flag) as values, even if
158 cache is otherwise disabled. This should be used only for
159 debugging, since it's slow and it litters the shared cache.
160 --default-target=TARGET (absent=@@default)
162 Set the default target that when none is specified to dune build.
163 --diff-command=VAL (absent DUNE_DIFF_COMMAND env)
165 Shell command to use to diff files. Use - to disable printing the
166 diff.
167 --disable-promotion (absent DUNE_DISABLE_PROMOTION env)
169 Disable all promotion rules
170 --display=MODE
172 Control the display mode of Dune. See dune-config(5) for more
173 details. Valid values for this option are progress, verbose, short,
174 quiet or tui.
175 --dump-gc-stats=FILE
177 Dump the garbage collector stats to a file after the build is
178 complete.
179 --dump-memo-graph=FILE
181 Dumps the dependency graph to a file after the build is complete
182 --dump-memo-graph-format=FORMAT (absent=gexf)
184 File format to be used when dumping dependency graph
185 --dump-memo-graph-with-timing
187 With --dump-memo-graph, will re-run each cached node in the Memo
188 graph after building and include the runtime in the output. Since
189 all nodes contain a cached value, this will measure just the
190 runtime of each node
191 --help[=FMT] (default=auto)
193 Show this help in format FMT. The value FMT must be one of auto,
194 pager, groff or plain. With auto, the format is pager or plain
195 whenever the TERM env var is dumb or undefined.
196 --ignore-promoted-rules
198 Ignore rules with (mode promote), except ones with (only ...). The
199 variable %{ignoring_promoted_rules} in dune files reflects whether
200 this option was passed or not.
201 --instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env)
203 "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
204 list of library names, each one of which must declare an
205 instrumentation backend.
206 -j JOBS
208 Run no more than JOBS commands simultaneously.
209 --no-buffer
211 Do not buffer the output of commands executed by dune. By default
212 dune buffers the output of subcommands, in order to prevent
213 interleaving when multiple commands are executed in parallel.
214 However, this can be an issue when debugging long running tests.
215 With --no-buffer, commands have direct access to the terminal. Note
216 that as a result their output won't be captured in the log file.
217 You should use this option in conjunction with -j 1, to avoid
218 interleaving. Additionally you should use --verbose as well, to
219 make sure that commands are printed before they are being executed.
220 --no-config
222 Do not load the configuration file
223 --no-print-directory
225 Suppress "Entering directory" messages
226 --only-packages=PACKAGES
228 Ignore stanzas referring to a package that is not in PACKAGES.
229 PACKAGES is a comma-separated list of package names. Note that this
230 has the same effect as deleting the relevant stanzas from dune
231 files. It is mostly meant for releases. During development, it is
232 likely that what you want instead is to build a particular
233 <package>.install target.
234 -p PACKAGES, --for-release-of-packages=PACKAGES (required)
236 Shorthand for --release --only-packages PACKAGE. You must use this
237 option in your <package>.opam files, in order to build only what's
238 necessary when your project contains multiple packages as well as
239 getting reproducible builds.
240 --print-metrics
242 Print out various performance metrics after every build
243 --profile=VAL (absent DUNE_PROFILE env)
245 Select the build profile, for instance dev or release. The default
246 is dev.
247 --promote-install-files[=VAL] (default=true)
249 Promote the generated <package>.install files to the source tree
250 --release
252 Put dune into a reproducible release mode. This is in fact a
253 shorthand for --root . --ignore-promoted-rules --no-config
254 --profile release --always-show-command-line
255 --promote-install-files --default-target @install
256 --require-dune-project-file. You should use this option for release
257 builds. For instance, you must use this option in your
258 <package>.opam files. Except if you already use -p, as -p implies
259 this option.
260 --require-dune-project-file[=VAL] (default=true)
262 Fail if a dune-project file is missing.
263 --root=DIR
265 Use this directory as workspace root instead of guessing it. Note
266 that this option doesn't change the interpretation of targets given
267 on the command line. It is only intended for scripts.
268 --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env)
270 Store original source location in dune-package metadata
271 --terminal-persistence=MODE
273 Changes how the log of build results are displayed to the console
274 between rebuilds while in --watch mode. Supported modes: preserve,
275 clear-on-rebuild, clear-on-rebuild-and-flush-history.
276 --trace-extended
278 Output extended trace data (requires trace-file)
279 --trace-file=FILE
281 Output trace data in catapult format (compatible with
282 chrome://tracing)
283 --verbose
285 Same as --display verbose
286 --version
288 Show version information.
289 --watch-exclusions=REGEX
291 Adds a POSIX regular expression that will exclude matching
292 directories from `dune build --watch`. The option
293 --watch-exclusions can be repeated to add multiple exclusions.
294 Semicolons can be also used as a separator. If no exclusions are
295 provided, then a standard set of exclusions is used; however, if
296 one or more --watch-exclusions are used, none of the standard
297 exclusions are used. The standard exclusions are: ^_opam /_opam
298 ^_esy /_esy ^\.#.* /\.#.* ~$ ^#[^#]*#$ /#[^#]*#$ ^4913$ /4913$
299 /.git /.hg :/windows
300 --workspace=FILE (absent DUNE_WORKSPACE env)
302 Use this specific workspace file instead of looking it up.
303 -x VAL
305 Cross-compile using this toolchain.
306
308 Use `dune COMMAND --help' for help on a single command.
309
311 rules exits with the following status:
312 0 on success.
314 1 if an error happened.
316 130 if it was interrupted by a signal.
318
320 These environment variables affect the execution of rules:
321 DUNE_BUILD_DIR
323 Specified build directory. _build if unspecified
324 DUNE_CACHE
326 Enable or disable Dune cache (either enabled or disabled). Default
327 is `disabled'.
328 DUNE_CACHE_CHECK_PROBABILITY
330 Check build reproducibility by re-executing randomly chosen rules
331 and comparing their results with those stored in Dune cache. Note:
332 by increasing the probability of such checks you slow down the
333 build. The default probability is zero, i.e. no rules are checked.
334 DUNE_CACHE_STORAGE_MODE
336 Dune cache storage mode (one of auto, hardlink or copy). Default is
337 `auto'.
338 DUNE_DIFF_COMMAND
340 Shell command to use to diff files. Use - to disable printing the
341 diff.
342 DUNE_DISABLE_PROMOTION
344 Disable all promotion rules
345 DUNE_INSTRUMENT_WITH
347 "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
348 list of library names, each one of which must declare an
349 instrumentation backend.
350 DUNE_PROFILE
352 Build profile. dev if unspecified or release if -p is set.
353 DUNE_SANDBOX
355 Sandboxing mode to use by default. (see --sandbox)
356 DUNE_STORE_ORIG_SOURCE_DIR
358 Store original source location in dune-package metadata
359 DUNE_WORKSPACE
361 Use this specific workspace file instead of looking it up.
362
364 Check bug reports at https://github.com/ocaml/dune/issues
365
367 dune(1)
368Dune n/a DUNE-RULES(1)