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
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
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.
253 --trace-file=FILE
255 Output trace data in catapult format (compatible with
256 chrome://tracing)
257 --verbose
259 Same as --display verbose
260 --workspace=FILE (absent DUNE_WORKSPACE env)
262 Use this specific workspace file instead of looking it up.
263 -x VAL
265 Cross-compile using this toolchain.
266
268 Use `dune COMMAND --help' for help on a single command.
269
271 These environment variables affect the execution of dune:
272 DUNE_BUILD_DIR
274 Specified build directory. _build if unspecified
275 DUNE_CACHE
277 Activate binary cache (either `disabled' or `enabled'). Default is
278 `disabled'.
279 DUNE_CACHE_CHECK_PROBABILITY
281 Probability cached rules are rerun to check for reproducibility
282 DUNE_CACHE_DUPLICATION
284 Binary cache duplication mode
285 DUNE_CACHE_TRANSPORT
287 Binary cache protocol
288 DUNE_DISABLE_PROMOTION
290 Disable all promotion rules
291 DUNE_INSTRUMENT_WITH
293 "Enable instrumentation by BACKENDS. BACKENDS is a comma-separated
294 list of library names, each one of which must declare an
295 instrumentation backend.
296 DUNE_PROFILE
298 Build profile. dev if unspecified or release if -p is set.
299 DUNE_SANDBOX
301 Sandboxing mode to use by default. (see --sandbox)
302 DUNE_STORE_ORIG_SOURCE_DIR
304 Store original source location in dune-package metadata
305 DUNE_WORKSPACE
307 Use this specific workspace file instead of looking it up.
308
310 Check bug reports at https://github.com/ocaml/dune/issues
311
313 1. Initialise a new project named `foo':
314 dune init project foo
316 2. Build all targets in the current source tree:
318 dune build
320 3. Run the executable named `bar':
322 dune exec bar
324 4. Run all tests in the current source tree:
326 dune runtest
328 5. Install all components defined in the project:
330 dune install
332 6. Remove all build artefacts:
334 dune clean
336Dune n/a dune(1)