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

NAME

6       dune - composable build system for OCaml
7

SYNOPSIS

9       dune build [--watch]
10       dune runtest [--watch]
11       dune exec NAME
12       dune utop [DIR]
13       dune install
14       dune init project NAME [PATH] [--libs=l1,l2 --ppx=p1,p2 --inline-tests]
15

DESCRIPTION

17       Dune is a build system designed for OCaml projects only. It focuses on
18       providing the user with a consistent experience and takes care of most
19       of the low-level details of OCaml compilation. All you have to do is
20       provide a description of your project and Dune will do the rest.
21
22       The scheme it implements is inspired from the one used inside Jane
23       Street and adapted to the open source world. It has matured over a long
24       time and is used daily by hundreds of developers, which means that it
25       is highly tested and productive.
26

COMMANDS

28       build
29           Build the given targets, or all installable targets if none are
30           given.
31
32       cache
33           Manage the shared artifacts cache
34
35       clean
36           Clean the project.
37
38       compute
39           Compute internal function.
40
41       describe
42           Describe the workspace.
43
44       exec
45           Execute a command in a similar environment as if installation was
46           performed.
47
48       external-lib-deps
49           Print out external libraries needed to build the given targets.
50
51       format-dune-file
52           Format dune files
53
54       help
55           Additional Dune help
56
57       init
58           Initialize dune components
59
60       install
61           Install packages.
62
63       installed-libraries
64           Print out libraries installed on the system.
65
66       ocaml-merlin
67           Start a merlin configuration server
68
69       printenv
70           Print the environment of a directory
71
72       promote
73           Promote files from the last run
74
75       rules
76           Dump internal rules.
77
78       runtest
79           Run tests.
80
81       subst
82           Substitute watermarks in source files.
83
84       top Print a list of toplevel directives for including directories and
85           loading cma files.
86
87       uninstall
88           Uninstall packages.
89
90       upgrade
91           Upgrade jbuilder projects to dune
92
93       utop
94           Load library in utop
95

COMMAND ALIASES

97       test
98           An alias for runtest.
99

OPTIONS

101       --build-info
102           Show build information.
103
104       -f, --force
105           Force actions associated to aliases to be re-executed even if their
106           dependencies haven't changed.
107
108       --help[=FMT] (default=auto)
109           Show this help in format FMT. The value FMT must be one of `auto',
110           `pager', `groff' or `plain'. With `auto', the format is `pager` or
111           `plain' whenever the TERM env var is `dumb' or undefined.
112
113       --sandbox=VAL (absent DUNE_SANDBOX env)
114           Sandboxing mode to use by default. Some actions require a certain
115           sandboxing mode, so they will ignore this setting. The allowed
116           values are: none, symlink, copy.
117
118       --version
119           Show version information.
120
121       -w, --watch
122           Instead of terminating build after completion, wait continuously
123           for file changes.
124

COMMON OPTIONS

126       These options are common to all commands.
127
128       --always-show-command-line
129           Always show the full command lines of programs executed by dune
130
131       --auto-promote
132           Automatically promote files. This is similar to running dune
133           promote after the build.
134
135       --build-dir=FILE (absent DUNE_BUILD_DIR env)
136           Specified build directory. _build if unspecified
137
138       --cache=VAL (absent DUNE_CACHE env)
139           Activate binary cache (either `disabled' or `enabled'). Default is
140           `disabled'.
141
142       --cache-check-probability=VAL (absent=0. or
143       DUNE_CACHE_CHECK_PROBABILITY env)
144           Probability cached rules are rerun to check for reproducibility
145
146       --cache-duplication=VAL (absent DUNE_CACHE_DUPLICATION env)
147           Binary cache duplication mode
148
149       --cache-transport=VAL (absent DUNE_CACHE_TRANSPORT env)
150           Binary cache protocol
151
152       --config-file=FILE
153           Load this configuration file instead of the default one.
154
155       --debug-artifact-substitution
156           Print debugging info about artifact substitution
157
158       --debug-backtraces
159           Always print exception backtraces.
160
161       --debug-dependency-path
162           In case of error, print the dependency path from the targets on the
163           command line to the rule that failed.
164
165       --debug-findlib
166           Debug the findlib sub-system.
167
168       --default-target=TARGET (absent=@@default)
169           Set the default target that when none is specified to dune build.
170
171       --diff-command=VAL
172           Shell command to use to diff files. Use - to disable printing the
173           diff.
174
175       --disable-promotion (absent DUNE_DISABLE_PROMOTION env)
176           Disable all promotion rules
177
178       --display=MODE
179           Control the display mode of Dune. See dune-config(5) for more
180           details.
181
182       --ignore-promoted-rules
183           Ignore rules with (mode promote), except ones with (only ...). The
184           variable %{ignoring_promoted_rules} in dune files reflects whether
185           this option was passed or not.
186
187       --instrument-with=BACKENDS (absent DUNE_INSTRUMENT_WITH env)
188           "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
189           list of library names, each one of which must declare an
190           instrumentation backend.
191
192       -j JOBS
193           Run no more than JOBS commands simultaneously.
194
195       --no-buffer
196           Do not buffer the output of commands executed by dune. By default
197           dune buffers the output of subcommands, in order to prevent
198           interleaving when multiple commands are executed in parallel.
199           However, this can be an issue when debugging long running tests.
200           With --no-buffer, commands have direct access to the terminal. Note
201           that as a result their output won't be captured in the log file.
202           You should use this option in conjunction with -j 1, to avoid
203           interleaving. Additionally you should use --verbose as well, to
204           make sure that commands are printed before they are being executed.
205
206       --no-config
207           Do not load the configuration file
208
209       --no-print-directory
210           Suppress "Entering directory" messages
211
212       --only-packages=PACKAGES
213           Ignore stanzas referring to a package that is not in PACKAGES.
214           PACKAGES is a comma-separated list of package names. Note that this
215           has the same effect as deleting the relevant stanzas from dune
216           files. It is mostly meant for releases. During development, it is
217           likely that what you want instead is to build a particular
218           <package>.install target.
219
220       -p PACKAGES, --for-release-of-packages=PACKAGES (required)
221           Shorthand for --release --only-packages PACKAGE. You must use this
222           option in your <package>.opam files, in order to build only what's
223           necessary when your project contains multiple packages as well as
224           getting reproducible builds.
225
226       --profile=VAL (absent DUNE_PROFILE env)
227           Select the build profile, for instance dev or release. The default
228           is dev.
229
230       --promote-install-files[=VAL] (default=true)
231           Promote the generated <package>.install files to the source tree
232
233       --release
234           Put dune into a reproducible release mode. This is in fact a
235           shorthand for --root . --ignore-promoted-rules --no-config
236           --profile release --always-show-command-line
237           --promote-install-files --default-target @install. You should use
238           this option for release builds. For instance, you must use this
239           option in your <package>.opam files. Except if you already use -p,
240           as -p implies this option.
241
242       --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
247       --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env)
248           Store original source location in dune-package metadata
249
250       --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.
254
255       --trace-file=FILE
256           Output trace data in catapult format (compatible with
257           chrome://tracing)
258
259       --verbose
260           Same as --display verbose
261
262       --workspace=FILE (absent DUNE_WORKSPACE env)
263           Use this specific workspace file instead of looking it up.
264
265       -x VAL
266           Cross-compile using this toolchain.
267

MORE HELP

269       Use `dune COMMAND --help' for help on a single command.
270

ENVIRONMENT

272       These environment variables affect the execution of dune:
273
274       DUNE_BUILD_DIR
275           Specified build directory. _build if unspecified
276
277       DUNE_CACHE
278           Activate binary cache (either `disabled' or `enabled'). Default is
279           `disabled'.
280
281       DUNE_CACHE_CHECK_PROBABILITY
282           Probability cached rules are rerun to check for reproducibility
283
284       DUNE_CACHE_DUPLICATION
285           Binary cache duplication mode
286
287       DUNE_CACHE_TRANSPORT
288           Binary cache protocol
289
290       DUNE_DISABLE_PROMOTION
291           Disable all promotion rules
292
293       DUNE_INSTRUMENT_WITH
294           "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
295           list of library names, each one of which must declare an
296           instrumentation backend.
297
298       DUNE_PROFILE
299           Build profile. dev if unspecified or release if -p is set.
300
301       DUNE_SANDBOX
302           Sandboxing mode to use by default. (see --sandbox)
303
304       DUNE_STORE_ORIG_SOURCE_DIR
305           Store original source location in dune-package metadata
306
307       DUNE_WORKSPACE
308           Use this specific workspace file instead of looking it up.
309

BUGS

311       Check bug reports at https://github.com/ocaml/dune/issues
312

EXAMPLES

314       1.  Initialise a new project named `foo':
315
316             dune init project foo
317
318       2.  Build all targets in the current source tree:
319
320             dune build
321
322       3.  Run the executable named `bar':
323
324             dune exec bar
325
326       4.  Run all tests in the current source tree:
327
328             dune runtest
329
330       5.  Install all components defined in the project:
331
332             dune install
333
334       6.  Remove all build artefacts:
335
336             dune clean
337
338
339
340Dune n/a                                                               DUNE(1)
Impressum