executable¶
The executable
stanza must be used to describe an executable. The format of
executable stanzas is as follows:
(executable
(name <name>)
<optional-fields>)
<name>
is a module name that contains the executable’s main entry point.
There can be additional modules in the current directory; you only need to
specify the entry point. Given an executable
stanza with (name <name>)
,
Dune will know how to build <name>.exe
. If requested, it will also know how
to build <name>.bc
and <name>.bc.js
(Dune 2.0 and up also need specific
configuration (see the modes
optional field below)).
<name>.exe
is a native code executable, <name>.bc
is a bytecode
executable which requires ocamlrun
to run, and <name>.bc.js
is a
JavaScript generated using js_of_ocaml
.
Please note: in case native compilation is not available, <name>.exe
will be
a custom bytecode executable, in the sense of ocamlc -custom
. This means
it’s a native executable that embeds the ocamlrun
virtual machine as well as
the bytecode, so you can always rely on <name>.exe
being available.
Moreover, it is usually preferable to use <name>.exe
in custom rules or when
calling the executable by hand because running a bytecode executable often
requires loading shared libraries that are locally built. This requires
additional setup, such as setting specific environment variables, which Dune
doesn’t do at the moment.
Native compilation isn’t available when there is no ocamlopt
binary at the
same place as ocamlc
was found.
Executables can also be linked as object or shared object files. See linking modes for more information.
Starting from Dune 3.0, it’s possible to automatically generate empty interface files for executables. See executables_implicit_empty_intf.
<optional-fields>
are:
(public_name <public-name>)
specifies that the executable should be installed under this name. It’s the same as adding the following stanza to yourdune
file:(install (section bin) (files (<name>.exe as <public-name>)))
As a special case,
(public_name -)
is the same as if the field was absent.
Linking Modes¶
The modes
field allows selecting which linking modes will be used to link
executables. Each mode is a pair (<compilation-mode> <binary-kind>)
, where
<compilation-mode>
describes whether the bytecode or native code backend of
the OCaml compiler should be used and <binary-kind>
describes what kind of
file should be produced.
<compilation-mode>
must be byte
, native
, or best
, where best
is native
with a fallback to bytecode when native compilation isn’t
available.
<binary-kind>
is one of:
c
for producing OCaml bytecode embedded in a C fileexe
for normal executablesobject
for producing static object files that can be manually linked into C applicationsshared_object
for producing object files that can be dynamically loaded into an application. This mode can be used to write a plugin in OCaml for a non-OCaml application.js
for producing JavaScript from bytecode executables, see explicit_js_mode.plugin
for producing a plugin (.cmxs
if native or.cma
if bytecode).
For instance the following executables
stanza will produce bytecode
executables and native shared objects:
(executables
(names a b c)
(modes (byte exe) (native shared_object)))
Additionally, you can use the following shorthands:
c
for(byte c)
exe
for(best exe)
object
for(best object)
shared_object
for(best shared_object)
byte
for(byte exe)
native
for(native exe)
js
for(byte js)
plugin
for(best plugin)
For instance, the following modes
fields are all equivalent:
(modes (exe object shared_object))
(modes ((best exe)
(best object)
(best shared_object)))
Lastly, use the special mode byte_complete
for building a bytecode
executable as a native self-contained executable, i.e., an executable that
doesn’t require the ocamlrun
program to run and doesn’t require the C stubs
to be installed as shared object files.
The extensions for the various linking modes are chosen as follows:
%{ext_obj}
and %{ext_dll}
are the extensions for object and shared
object files. Their value depends on the OS. For instance, on Unix
%{ext_obj}
is usually .o
and %{ext_dll}
is usually .so
, while on
Windows %{ext_obj}
is .obj
and %{ext_dll}
is .dll
.
Up to version 3.0 of the Dune language, when byte
is specified but none of
native
, exe
, or byte_complete
are specified, Dune implicitly adds a
linking mode that’s the same as byte_complete
, but it uses the extension
.exe
. .bc
files require additional files at runtime that aren’t
currently tracked by Dune, so they don’t run .bc
files during the build. Run
the .bc.exe
or .exe
ones instead, as these are self-contained.
Lastly, note that .bc
executables cannot contain C stubs. If your executable
contains C stubs you may want to use (modes exe)
.
js_of_ocaml¶
In library
and executables
stanzas, you can specify js_of_ocaml
options using (js_of_ocaml (<js_of_ocaml-options>))
.
<js_of_ocaml-options>
are all optional:
(flags <flags>)
to specify flags passed tojs_of_ocaml compile
. This field supports(:include ...)
forms(build_runtime_flags <flags>)
to specify flags passed tojs_of_ocaml build-runtime
. This field supports(:include ...)
forms(link_flags <flags>)
to specify flags passed tojs_of_ocaml link
. This field supports(:include ...)
forms(javascript_files (<files-list>))
to specifyjs_of_ocaml
JavaScript runtime files.
<flags>
is specified in the Ordered Set Language.
The default value for (flags ...)
depends on the selected build profile. The
build profile dev
(the default) will enable sourcemap and the pretty
JavaScript output.
See JavaScript Compilation With Js_of_ocaml for more information.
executables¶
There is a very subtle difference in the naming of these stanzas. One is
executables
, plural, and the other is executable
, singular. The
executables
stanza is very similar as the executable
stanza but can be
used to to describe several executables sharing the same configuration, so the
plural executables
stanza is used to describe more than one executable.
It shares the same fields as the executable
stanza, except that instead of
(name ...)
and (public_name ...)
you must use the plural versions as
well:
(names <names>)
where<names>
is a list of entry point names. Compare withexecutable
, where you only need to specify the modules containing the entry point of each executable.(public_names <names>)
describes under what name to install each executable. The list of names must be of the same length as the list in the(names ...)
field. Moreover, you can use-
for executables that shouldn’t be installed.
However, using executables
the executables defined in the stanza are
allowed to share modules.
Given modules Foo
, Bar
and Baz
the usage of executables
can
simplify the code:
(executables
(names foo bar))
Instead of the more complex
(library
(name baz)
(modules baz))
(executable
(name foo)
(modules foo)
(libraries baz))
(executable
(name bar)
(modules bar)
(libraries baz))