1DUNE(1) Dune Manual DUNE(1)
2
6 dune - composable build system for OCaml
7
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
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 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
28 build
29 Build the given targets, or all installable targets if none are
30 given.
31 cache
33 Manage the shared artifacts cache
34 clean
36 Clean the project.
37 compute
39 Compute internal function.
40 describe
42 Describe the workspace.
43 exec
45 Execute a command in a similar environment as if installation was
46 performed.
47 external-lib-deps
49 Print out external libraries needed to build the given targets.
50 format-dune-file
52 Format dune files
53 help
55 Additional Dune help
56 init
58 Initialize dune components
59 install
61 Install packages.
62 installed-libraries
64 Print out libraries installed on the system.
65 ocaml-merlin
67 Start a merlin configuration server
68 printenv
70 Print the environment of a directory
71 promote
73 Promote files from the last run
74 rules
76 Dump internal rules.
77 runtest
79 Run tests.
80 subst
82 Substitute watermarks in source files.
83 top Print a list of toplevel directives for including directories and
85 loading cma files.
86 uninstall
88 Uninstall packages.
89 upgrade
91 Upgrade jbuilder projects to dune
92 utop
94 Load library in utop
95
97 test
98 An alias for runtest.
99
101 --build-info
102 Show build information.
103 -f, --force
105 Force actions associated to aliases to be re-executed even if their
106 dependencies haven't changed.
107 --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 --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 --version
119 Show version information.
120 -w, --watch
122 Instead of terminating build after completion, wait continuously
123 for file changes.
124
126 These options are common to all commands.
127 --always-show-command-line
129 Always show the full command lines of programs executed by dune
130 --auto-promote
132 Automatically promote files. This is similar to running dune
133 promote after the build.
134 --build-dir=FILE (absent DUNE_BUILD_DIR env)
136 Specified build directory. _build if unspecified
137 --cache=VAL (absent DUNE_CACHE env)
139 Activate binary cache (either `disabled' or `enabled'). Default is
140 `disabled'.
141 --cache-check-probability=VAL (absent=0. or
143 DUNE_CACHE_CHECK_PROBABILITY env)
144 Probability cached rules are rerun to check for reproducibility
145 --cache-duplication=VAL (absent DUNE_CACHE_DUPLICATION env)
147 Binary cache duplication mode
148 --cache-transport=VAL (absent DUNE_CACHE_TRANSPORT env)
150 Binary cache protocol
151 --config-file=FILE
153 Load this configuration file instead of the default one.
154 --debug-artifact-substitution
156 Print debugging info about artifact substitution
157 --debug-backtraces
159 Always print exception backtraces.
160 --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 --debug-findlib
166 Debug the findlib sub-system.
167 --default-target=TARGET (absent=@@default)
169 Set the default target that when none is specified to dune build.
170 --diff-command=VAL
172 Shell command to use to diff files. Use - to disable printing the
173 diff.
174 --disable-promotion (absent DUNE_DISABLE_PROMOTION env)
176 Disable all promotion rules
177 --display=MODE
179 Control the display mode of Dune. See dune-config(5) for more
180 details.
181 --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 --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 -j JOBS
193 Run no more than JOBS commands simultaneously.
194 --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 --no-config
207 Do not load the configuration file
208 --no-print-directory
210 Suppress "Entering directory" messages
211 --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 -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 --profile=VAL (absent DUNE_PROFILE env)
227 Select the build profile, for instance dev or release. The default
228 is dev.
229 --promote-install-files[=VAL] (default=true)
231 Promote the generated <package>.install files to the source tree
232 --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 --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.
254 --trace-file=FILE
256 Output trace data in catapult format (compatible with
257 chrome://tracing)
258 --verbose
260 Same as --display verbose
261 --workspace=FILE (absent DUNE_WORKSPACE env)
263 Use this specific workspace file instead of looking it up.
264 -x VAL
266 Cross-compile using this toolchain.
267
269 Use `dune COMMAND --help' for help on a single command.
270
272 These environment variables affect the execution of dune:
273 DUNE_BUILD_DIR
275 Specified build directory. _build if unspecified
276 DUNE_CACHE
278 Activate binary cache (either `disabled' or `enabled'). Default is
279 `disabled'.
280 DUNE_CACHE_CHECK_PROBABILITY
282 Probability cached rules are rerun to check for reproducibility
283 DUNE_CACHE_DUPLICATION
285 Binary cache duplication mode
286 DUNE_CACHE_TRANSPORT
288 Binary cache protocol
289 DUNE_DISABLE_PROMOTION
291 Disable all promotion rules
292 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 DUNE_PROFILE
299 Build profile. dev if unspecified or release if -p is set.
300 DUNE_SANDBOX
302 Sandboxing mode to use by default. (see --sandbox)
303 DUNE_STORE_ORIG_SOURCE_DIR
305 Store original source location in dune-package metadata
306 DUNE_WORKSPACE
308 Use this specific workspace file instead of looking it up.
309
311 Check bug reports at https://github.com/ocaml/dune/issues
312
314 1. Initialise a new project named `foo':
315 dune init project foo
317 2. Build all targets in the current source tree:
319 dune build
321 3. Run the executable named `bar':
323 dune exec bar
325 4. Run all tests in the current source tree:
327 dune runtest
329 5. Install all components defined in the project:
331 dune install
333 6. Remove all build artefacts:
335 dune clean
337Dune n/a DUNE(1)