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