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

NAME

6       dune-install - Install packages.
7

SYNOPSIS

9       The installation directories used are defined by priority:
10       - directories set on the command line of dune install, or corresponding
11       environment variables
12       - directories set in dune binary. They are setup before the compilation
13       of dune with ./configure
14       - inferred from the environment variable OPAM_SWITCH_PREFIX if present
15

OPTIONS

17       --action-stderr-on-success=VAL
18           Same as --action-stdout-on-success but for the standard output for
19           error messages. A good default for large mono-repositories is
20           --action-stdout-on-success=swallow
21           --action-stderr-on-success=must-be-empty. This ensures that a
22           successful build has a "clean" empty output.
23
24       --action-stdout-on-success=VAL
25           Specify how to deal with the standard output of actions when they
26           succeed. Possible values are: print to just print it to Dune's
27           output, swallow to completely ignore it and must-be-empty to
28           enforce that the action printed nothing. With must-be-empty, Dune
29           will consider that the action failed if it printed something to its
30           standard output. The default is print.
31
32       --bindir=PATH
33           Manually override the directory to install public binaries. Only
34           absolute path accepted.
35
36       --build-info
37           Show build information.
38
39       --context=CONTEXT
40           Select context to install from. By default, install files from all
41           defined contexts.
42
43       --create-install-files
44           Do not directly install, but create install files in the root
45           directory and create substituted files if needed in destdir
46           (_destdir by default).
47
48       --datadir=PATH
49           Manually override the directory to install files from share
50           section. Only absolute path accepted.
51
52       --destdir=PATH (absent DESTDIR env)
53           This directory is prepended to all installed paths.
54
55       --docdir=PATH
56           Manually override the directory to install documentation files.
57           Only absolute path accepted.
58
59       --dry-run
60           Only display the file operations that would be performed.
61
62       --error-reporting=VAL (absent=deterministic)
63           Controls when the build errors are reported. early - report errors
64           as soon as they are discovered. deterministic - report errors at
65           the end of the build in a deterministic order. twice - report each
66           error twice: once as soon as the error is discovered and then again
67           at the end of the build, in a deterministic order.
68
69       --etcdir=PATH
70           Manually override the directory to install configuration files.
71           Only absolute path accepted.
72
73       -f, --force
74           Force actions associated to aliases to be re-executed even if their
75           dependencies haven't changed.
76
77       --file-watcher=VAL (absent=automatic)
78           Mechanism to detect changes in the source. Automatic to make dune
79           run an external program to detect changes. Manual to notify dune
80           that files have changed manually."
81
82       --libdir=PATH
83           Directory where library files are copied, relative to prefix or
84           absolute. If --prefix is specified the default is $prefix/lib. Only
85           absolute path accepted.
86
87       --libexecdir=PATH
88           Manually override the directory to install executable library
89           files. Only absolute path accepted.
90
91       --mandir=PATH
92           Manually override the directory to install man pages. Only absolute
93           path accepted.
94
95       --passive-watch-mode
96           Similar to [--watch], but only start a build when instructed
97           externally by an RPC.
98
99       --prefix=PREFIX (absent DUNE_INSTALL_PREFIX env)
100           Directory where files are copied. For instance binaries are copied
101           into $prefix/bin, library files into $prefix/lib, etc...
102
103       --react-to-insignificant-changes
104           react to insignificant file system changes; this is only useful for
105           benchmarking dune
106
107       --relocatable
108           Make the binaries relocatable (the installation directory can be
109           moved). The installation directory must be specified with --prefix
110
111       --sandbox=VAL (absent DUNE_SANDBOX env)
112           Sandboxing mode to use by default. Some actions require a certain
113           sandboxing mode, so they will ignore this setting. The allowed
114           values are: none, symlink, copy, hardlink.
115
116       --sbindir=PATH
117           Manually override the directory to install files from sbin section.
118           Only absolute path accepted.
119
120       --sections=VAL
121           sections that should be installed
122
123       -w, --watch
124           Instead of terminating build after completion, wait continuously
125           for file changes.
126
127       --wait-for-filesystem-clock
128           Dune digest file contents for better incrementally. These digests
129           are themselves cached. In some cases, Dune needs to drop some
130           digest cache entries in order for things to be reliable. This
131           option makes Dune wait for the file system clock to advance so that
132           it doesn't need to drop anything. You should probably not care
133           about this option; it is mostly useful for Dune developers to make
134           Dune tests of the digest cache more reproducible.
135

COMMON OPTIONS

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

MORE HELP

325       Use `dune COMMAND --help' for help on a single command.
326

EXIT STATUS

328       install exits with the following status:
329
330       0   on success.
331
332       123 on indiscriminate errors reported on standard error.
333
334       124 on command line parsing errors.
335
336       125 on unexpected internal errors (bugs).
337

ENVIRONMENT

339       These environment variables affect the execution of install:
340
341       DESTDIR
342           See option --destdir.
343
344       DUNE_BUILD_DIR
345           Specified build directory. _build if unspecified
346
347       DUNE_CACHE
348           Enable or disable Dune cache (either enabled or disabled). Default
349           is `disabled'.
350
351       DUNE_CACHE_CHECK_PROBABILITY
352           Check build reproducibility by re-executing randomly chosen rules
353           and comparing their results with those stored in Dune cache. Note:
354           by increasing the probability of such checks you slow down the
355           build. The default probability is zero, i.e. no rules are checked.
356
357       DUNE_CACHE_STORAGE_MODE
358           Dune cache storage mode (one of auto, hardlink or copy). Default is
359           `auto'.
360
361       DUNE_DIFF_COMMAND
362           Shell command to use to diff files. Use - to disable printing the
363           diff.
364
365       DUNE_DISABLE_PROMOTION
366           Disable all promotion rules
367
368       DUNE_INSTALL_PREFIX
369           See option --prefix.
370
371       DUNE_INSTRUMENT_WITH
372           "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
373           list of library names, each one of which must declare an
374           instrumentation backend.
375
376       DUNE_PROFILE
377           Build profile. dev if unspecified or release if -p is set.
378
379       DUNE_SANDBOX
380           Sandboxing mode to use by default. (see --sandbox)
381
382       DUNE_STORE_ORIG_SOURCE_DIR
383           Store original source location in dune-package metadata
384
385       DUNE_WORKSPACE
386           Use this specific workspace file instead of looking it up.
387

BUGS

389       Check bug reports at https://github.com/ocaml/dune/issues
390

SEE ALSO

392       dune(1)
393
394
395
396Dune n/a                                                       DUNE-INSTALL(1)
Impressum