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 printenv
67 Print the environment of a directory
68 promote
70 Promote files from the last run
71 rules
73 Dump internal rules.
74 runtest
76 Run tests.
77 subst
79 Substitute watermarks in source files.
80 top Print a list of toplevel directives for including directories and
82 loading cma files.
83 uninstall
85 Uninstall packages.
86 upgrade
88 Upgrade jbuilder projects to dune
89 utop
91 Load library in utop
92
94 test
95 An alias for runtest.
96
98 --build-info
99 Show build information.
100 -f, --force
102 Force actions associated to aliases to be re-executed even if their
103 dependencies haven't changed.
104 --help[=FMT] (default=auto)
106 Show this help in format FMT. The value FMT must be one of `auto',
107 `pager', `groff' or `plain'. With `auto', the format is `pager` or
108 `plain' whenever the TERM env var is `dumb' or undefined.
109 --sandbox=VAL (absent DUNE_SANDBOX env)
111 Sandboxing mode to use by default. Some actions require a certain
112 sandboxing mode, so they will ignore this setting. The allowed
113 values are: none, symlink, copy.
114 --version
116 Show version information.
117 -w, --watch
119 Instead of terminating build after completion, wait continuously
120 for file changes.
121
123 These options are common to all commands.
124 --always-show-command-line
126 Always show the full command lines of programs executed by dune
127 --auto-promote
129 Automatically promote files. This is similar to running dune
130 promote after the build.
131 --build-dir=FILE (absent DUNE_BUILD_DIR env)
133 Specified build directory. _build if unspecified
134 --cache=VAL (absent DUNE_CACHE env)
136 Activate binary cache (either `disabled' or `enabled'). Default is
137 `disabled'.
138 --cache-check-probability=VAL (absent=0. or
140 DUNE_CACHE_CHECK_PROBABILITY env)
141 Probability cached rules are rerun to check for reproducibility
142 --cache-duplication=VAL (absent DUNE_CACHE_DUPLICATION env)
144 Binary cache duplication mode
145 --cache-transport=VAL (absent DUNE_CACHE_TRANSPORT env)
147 Binary cache protocol
148 --config-file=FILE
150 Load this configuration file instead of the default one.
151 --debug-backtraces
153 Always print exception backtraces.
154 --debug-dependency-path
156 In case of error, print the dependency path from the targets on the
157 command line to the rule that failed.
158 --debug-findlib
160 Debug the findlib sub-system.
161 --default-target=TARGET (absent=@@default)
163 Set the default target that when none is specified to dune build.
164 --diff-command=VAL
166 Shell command to use to diff files. Use - to disable printing the
167 diff.
168 --disable-promotion (absent DUNE_DISABLE_PROMOTION env)
170 Disable all promotion rules
171 --display=MODE
173 Control the display mode of Dune. See dune-config(5) for more
174 details.
175 --ignore-promoted-rules
177 Ignore rules with (mode promote), except ones with (only ...). The
178 variable %{ignoring_promoted_rules} in dune files reflects whether
179 this option was passed or not.
180 -j JOBS
182 Run no more than JOBS commands simultaneously.
183 --no-buffer
185 Do not buffer the output of commands executed by dune. By default
186 dune buffers the output of subcommands, in order to prevent
187 interleaving when multiple commands are executed in parallel.
188 However, this can be an issue when debugging long running tests.
189 With --no-buffer, commands have direct access to the terminal. Note
190 that as a result their output won't be captured in the log file.
191 You should use this option in conjunction with -j 1, to avoid
192 interleaving. Additionally you should use --verbose as well, to
193 make sure that commands are printed before they are being executed.
194 --no-config
196 Do not load the configuration file
197 --no-print-directory
199 Suppress "Entering directory" messages
200 --only-packages=PACKAGES
202 Ignore stanzas referring to a package that is not in PACKAGES.
203 PACKAGES is a comma-separated list of package names. Note that this
204 has the same effect as deleting the relevant stanzas from dune
205 files. It is mostly meant for releases. During development, it is
206 likely that what you want instead is to build a particular
207 <package>.install target.
208 -p PACKAGES, --for-release-of-packages=PACKAGES
210 Shorthand for --release --only-packages PACKAGE. You must use this
211 option in your <package>.opam files, in order to build only what's
212 necessary when your project contains multiple packages as well as
213 getting reproducible builds.
214 --profile=VAL (absent DUNE_PROFILE env)
216 Select the build profile, for instance dev or release. The default
217 is dev.
218 --promote-install-files
220 Promote the generated <package>.install files to the source tree
221 --release
223 Put dune into a reproducible release mode. This is in fact a
224 shorthand for --root . --ignore-promoted-rules --no-config
225 --profile release --always-show-command-line
226 --promote-install-files --default-target @install. You should use
227 this option for release builds. For instance, you must use this
228 option in your <package>.opam files. Except if you already use -p,
229 as -p implies this option.
230 --root=DIR
232 Use this directory as workspace root instead of guessing it. Note
233 that this option doesn't change the interpretation of targets given
234 on the command line. It is only intended for scripts.
235 --store-orig-source-dir (absent DUNE_STORE_ORIG_SOURCE_DIR env)
237 Store original source location in dune-package metadata
238 --terminal-persistence=MODE
240 Changes how the log of build results are displayed to the console
241 between rebuilds while in --watch mode.
242 --trace-file=FILE
244 Output trace data in catapult format (compatible with
245 chrome://tracing)
246 --verbose
248 Same as --display verbose
249 --workspace=FILE (absent DUNE_WORKSPACE env)
251 Use this specific workspace file instead of looking it up.
252 -x VAL
254 Cross-compile using this toolchain.
255
257 Use `dune COMMAND --help' for help on a single command.
258
260 These environment variables affect the execution of dune:
261 DUNE_BUILD_DIR
263 Specified build directory. _build if unspecified
264 DUNE_CACHE
266 Activate binary cache (either `disabled' or `enabled'). Default is
267 `disabled'.
268 DUNE_CACHE_CHECK_PROBABILITY
270 Probability cached rules are rerun to check for reproducibility
271 DUNE_CACHE_DUPLICATION
273 Binary cache duplication mode
274 DUNE_CACHE_TRANSPORT
276 Binary cache protocol
277 DUNE_DISABLE_PROMOTION
279 Disable all promotion rules
280 DUNE_PROFILE
282 Build profile. dev if unspecified or release if -p is set.
283 DUNE_SANDBOX
285 Sandboxing mode to use by default. (see --sandbox)
286 DUNE_STORE_ORIG_SOURCE_DIR
288 Store original source location in dune-package metadata
289 DUNE_WORKSPACE
291 Use this specific workspace file instead of looking it up.
292
294 Check bug reports at https://github.com/ocaml/dune/issues
295
297 1. Initialise a new project named `foo':
298 dune init project foo
300 2. Build all targets in the current source tree:
302 dune build
304 3. Run the executable named `bar':
306 dune exec bar
308 4. Run all tests in the current source tree:
310 dune runtest
312 5. Install all components defined in the project:
314 dune install
316 6. Remove all build artefacts:
318 dune clean
320Dune n/a dune(1)