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

NAME

6       dune-build - Build the given targets, or all installable targets if
7       none are given.
8

SYNOPSIS

10       dune build [OPTION]… [TARGET]…
11

DESCRIPTION

13       Targets starting with a @ are interpreted as aliases.
14

OPTIONS

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

COMMON OPTIONS

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

MORE HELP

265       Use `dune COMMAND --help' for help on a single command.
266

EXIT STATUS

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

ENVIRONMENT

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

BUGS

331       Check bug reports at https://github.com/ocaml/dune/issues
332

SEE ALSO

334       dune(1)
335

EXAMPLES

337       1.  Build all targets in the current source tree:
338
339             dune build
340
341       2.  Build targets in the `./foo/bar' directory:
342
343             dune build ./foo/bar
344
345       3.  Build the minimal set of targets required for tooling such as
346           Merlin (useful for quickly detecting errors):
347
348             dune build @check
349
350       4.  Run all code formatting tools in-place:
351
352             dune build --auto-promote @fmt
353
354
355
356Dune n/a                                                         DUNE-BUILD(1)
Impressum