1DUNE-FMT(1)                       Dune Manual                      DUNE-FMT(1)
2
3
4

NAME

6       dune-fmt - Format source code.
7

SYNOPSIS

9       dune fmt [OPTION]…
10

DESCRIPTION

12       dune fmt runs the formatter on the source code. The formatter is
13       automatically selected. ocamlformat is used to format OCaml source code
14       (*.ml and *.mli files) and refmt is used to format Reason source code
15       (*.re and *.rei files).
16

OPTIONS

18       --action-stderr-on-success=VAL
19           Same as --action-stdout-on-success but for the standard output for
20           error messages. A good default for large mono-repositories is
21           --action-stdout-on-success=swallow
22           --action-stderr-on-success=must-be-empty. This ensures that a
23           successful build has a "clean" empty output.
24
25       --action-stdout-on-success=VAL
26           Specify how to deal with the standard output of actions when they
27           succeed. Possible values are: print to just print it to Dune's
28           output, swallow to completely ignore it and must-be-empty to
29           enforce that the action printed nothing. With must-be-empty, Dune
30           will consider that the action failed if it printed something to its
31           standard output. The default is print.
32
33       --build-info
34           Show build information.
35
36       --error-reporting=VAL (absent=deterministic)
37           Controls when the build errors are reported. early - report errors
38           as soon as they are discovered. deterministic - report errors at
39           the end of the build in a deterministic order. twice - report each
40           error twice: once as soon as the error is discovered and then again
41           at the end of the build, in a deterministic order.
42
43       -f, --force
44           Force actions associated to aliases to be re-executed even if their
45           dependencies haven't changed.
46
47       --file-watcher=VAL (absent=automatic)
48           Mechanism to detect changes in the source. Automatic to make dune
49           run an external program to detect changes. Manual to notify dune
50           that files have changed manually."
51
52       --passive-watch-mode
53           Similar to [--watch], but only start a build when instructed
54           externally by an RPC.
55
56       --react-to-insignificant-changes
57           react to insignificant file system changes; this is only useful for
58           benchmarking dune
59
60       --sandbox=VAL (absent DUNE_SANDBOX env)
61           Sandboxing mode to use by default. Some actions require a certain
62           sandboxing mode, so they will ignore this setting. The allowed
63           values are: none, symlink, copy, hardlink.
64
65       -w, --watch
66           Instead of terminating build after completion, wait continuously
67           for file changes.
68
69       --wait-for-filesystem-clock
70           Dune digest file contents for better incrementally. These digests
71           are themselves cached. In some cases, Dune needs to drop some
72           digest cache entries in order for things to be reliable. This
73           option makes Dune wait for the file system clock to advance so that
74           it doesn't need to drop anything. You should probably not care
75           about this option; it is mostly useful for Dune developers to make
76           Dune tests of the digest cache more reproducible.
77

COMMON OPTIONS

79       These options are common to all commands.
80
81       --always-show-command-line
82           Always show the full command lines of programs executed by dune
83
84       --auto-promote
85           Automatically promote files. This is similar to running dune
86           promote after the build.
87
88       --build-dir=FILE (absent DUNE_BUILD_DIR env)
89           Specified build directory. _build if unspecified
90
91       --cache=VAL (absent DUNE_CACHE env)
92           Enable or disable Dune cache (either enabled or disabled). Default
93           is `disabled'.
94
95       --cache-check-probability=VAL (absent DUNE_CACHE_CHECK_PROBABILITY env)
96           Check build reproducibility by re-executing randomly chosen rules
97           and comparing their results with those stored in Dune cache. Note:
98           by increasing the probability of such checks you slow down the
99           build. The default probability is zero, i.e. no rules are checked.
100
101       --cache-storage-mode=VAL (absent DUNE_CACHE_STORAGE_MODE env)
102           Dune cache storage mode (one of auto, hardlink or copy). Default is
103           `auto'.
104
105       --config-file=FILE
106           Load this configuration file instead of the default one.
107
108       --debug-artifact-substitution
109           Print debugging info about artifact substitution
110
111       --debug-backtraces
112           Always print exception backtraces.
113
114       --debug-cache=VAL
115           Show debug messages on cache misses for the given cache layers.
116           Value is a comma-separated list of cache layer names. All available
117           cache layers: shared,workspace-local,fs.
118
119       --debug-dependency-path
120           In case of error, print the dependency path from the targets on the
121           command line to the rule that failed.
122
123       --debug-digests
124           Explain why Dune decides to re-digest some files
125
126       --debug-findlib
127           Debug the findlib sub-system.
128
129       --debug-load-dir
130           Print debugging info about directory loading
131
132       --debug-store-digest-preimage
133           Store digest preimage for all computed digests, so that it's
134           possible to reverse them later, for debugging. The digests are
135           stored in the shared cache (see --cache flag) as values, even if
136           cache is otherwise disabled. This should be used only for
137           debugging, since it's slow and it litters the shared cache.
138
139       --default-target=TARGET (absent=@@default)
140           Set the default target that when none is specified to dune build.
141
142       --diff-command=VAL (absent DUNE_DIFF_COMMAND env)
143           Shell command to use to diff files. Use - to disable printing the
144           diff.
145
146       --disable-promotion (absent DUNE_DISABLE_PROMOTION env)
147           Disable all promotion rules
148
149       --display=MODE
150           Control the display mode of Dune. See dune-config(5) for more
151           details.
152
153       --dump-memo-graph=FILE
154           Dumps the dependency graph to a file after the build is complete
155
156       --dump-memo-graph-format=FORMAT (absent=gexf)
157           File format to be used when dumping dependency graph
158
159       --dump-memo-graph-with-timing
160           With --dump-memo-graph, will re-run each cached node in the Memo
161           graph after building and include the runtime in the output. Since
162           all nodes contain a cached value, this will measure just the
163           runtime of each node
164
165       --help[=FMT] (default=auto)
166           Show this help in format FMT. The value FMT must be one of auto,
167           pager, groff or plain. With auto, the format is pager or plain
168           whenever the TERM env var is dumb or undefined.
169
170       --ignore-promoted-rules
171           Ignore rules with (mode promote), except ones with (only ...). The
172           variable %{ignoring_promoted_rules} in dune files reflects whether
173           this option was passed or not.
174
175       --instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env)
176           "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
177           list of library names, each one of which must declare an
178           instrumentation backend.
179
180       -j JOBS
181           Run no more than JOBS commands simultaneously.
182
183       --no-buffer
184           Do not buffer the output of commands executed by dune. By default
185           dune buffers the output of subcommands, in order to prevent
186           interleaving when multiple commands are executed in parallel.
187           However, this can be an issue when debugging long running tests.
188           With --no-buffer, commands have direct access to the terminal. Note
189           that as a result their output won't be captured in the log file.
190           You should use this option in conjunction with -j 1, to avoid
191           interleaving. Additionally you should use --verbose as well, to
192           make sure that commands are printed before they are being executed.
193
194       --no-config
195           Do not load the configuration file
196
197       --no-print-directory
198           Suppress "Entering directory" messages
199
200       --only-packages=PACKAGES
201           Ignore stanzas referring to a package that is not in PACKAGES.
202           PACKAGES is a comma-separated list of package names. Note that this
203           has the same effect as deleting the relevant stanzas from dune
204           files. It is mostly meant for releases. During development, it is
205           likely that what you want instead is to build a particular
206           <package>.install target.
207
208       -p PACKAGES, --for-release-of-packages=PACKAGES (required)
209           Shorthand for --release --only-packages PACKAGE. You must use this
210           option in your <package>.opam files, in order to build only what's
211           necessary when your project contains multiple packages as well as
212           getting reproducible builds.
213
214       --print-metrics
215           Print out various performance metrics after every build
216
217       --profile=VAL (absent DUNE_PROFILE env)
218           Select the build profile, for instance dev or release. The default
219           is dev.
220
221       --promote-install-files[=VAL] (default=true)
222           Promote the generated <package>.install files to the source tree
223
224       --release
225           Put dune into a reproducible release mode. This is in fact a
226           shorthand for --root . --ignore-promoted-rules --no-config
227           --profile release --always-show-command-line
228           --promote-install-files --default-target @install
229           --require-dune-project-file. You should use this option for release
230           builds. For instance, you must use this option in your
231           <package>.opam files. Except if you already use -p, as -p implies
232           this option.
233
234       --require-dune-project-file[=VAL] (default=true)
235           Fail if a dune-project file is missing.
236
237       --root=DIR
238           Use this directory as workspace root instead of guessing it. Note
239           that this option doesn't change the interpretation of targets given
240           on the command line. It is only intended for scripts.
241
242       --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env)
243           Store original source location in dune-package metadata
244
245       --terminal-persistence=MODE
246           Changes how the log of build results are displayed to the console
247           between rebuilds while in --watch mode. Supported modes: preserve,
248           clear-on-rebuild, clear-on-rebuild-and-flush-history.
249
250       --trace-file=FILE
251           Output trace data in catapult format (compatible with
252           chrome://tracing)
253
254       --verbose
255           Same as --display verbose
256
257       --version
258           Show version information.
259
260       --workspace=FILE (absent DUNE_WORKSPACE env)
261           Use this specific workspace file instead of looking it up.
262
263       -x VAL
264           Cross-compile using this toolchain.
265

MORE HELP

267       Use `dune COMMAND --help' for help on a single command.
268

EXIT STATUS

270       fmt exits with the following status:
271
272       0   on success.
273
274       123 on indiscriminate errors reported on standard error.
275
276       124 on command line parsing errors.
277
278       125 on unexpected internal errors (bugs).
279

ENVIRONMENT

281       These environment variables affect the execution of fmt:
282
283       CLICOLOR
284           If different than 0, ANSI colors are supported and should be used
285           when the program isn’t piped. If equal to 0, don’t output ANSI
286           color escape codes
287
288       CLICOLOR_FORCE
289           If different than 0, ANSI colors should be enabled no matter what.
290
291       DUNE_BUILD_DIR
292           Specified build directory. _build if unspecified
293
294       DUNE_CACHE
295           Enable or disable Dune cache (either enabled or disabled). Default
296           is `disabled'.
297
298       DUNE_CACHE_CHECK_PROBABILITY
299           Check build reproducibility by re-executing randomly chosen rules
300           and comparing their results with those stored in Dune cache. Note:
301           by increasing the probability of such checks you slow down the
302           build. The default probability is zero, i.e. no rules are checked.
303
304       DUNE_CACHE_STORAGE_MODE
305           Dune cache storage mode (one of auto, hardlink or copy). Default is
306           `auto'.
307
308       DUNE_DIFF_COMMAND
309           Shell command to use to diff files. Use - to disable printing the
310           diff.
311
312       DUNE_DISABLE_PROMOTION
313           Disable all promotion rules
314
315       DUNE_INSTRUMENT_WITH
316           "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
317           list of library names, each one of which must declare an
318           instrumentation backend.
319
320       DUNE_PROFILE
321           Build profile. dev if unspecified or release if -p is set.
322
323       DUNE_SANDBOX
324           Sandboxing mode to use by default. (see --sandbox)
325
326       DUNE_STORE_ORIG_SOURCE_DIR
327           Store original source location in dune-package metadata
328
329       DUNE_WORKSPACE
330           Use this specific workspace file instead of looking it up.
331

BUGS

333       Check bug reports at https://github.com/ocaml/dune/issues
334

SEE ALSO

336       dune(1)
337
338
339
340Dune n/a                                                           DUNE-FMT(1)
Impressum