executable ---------- The ``executable`` stanza must be used to describe an executable. The format of executable stanzas is as follows: .. code:: dune (executable (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 )``, Dune will know how to build ``.exe``. If requested, it will also know how to build ``.bc``, ``.bc.js`` and ``.bc.wasm.js`` (Dune 2.0 and up also needs specific configuration (see the ``modes`` optional field below)). ``.exe`` is a native code executable, ``.bc`` is a bytecode executable which requires ``ocamlrun`` to run, ``.bc.js`` is a JavaScript generated using ``js_of_ocaml``, and ``.bc.wasm.js`` is a Wasm loader script generated using ``wasm_of_ocaml`` (the Wasm modules are included in directory ``.bc.wasm.assets``). Please note: in case native compilation is not available, ``.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 ``.exe`` being available. Moreover, it is usually preferable to use ``.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 :doc:`/reference/dune-project/executables_implicit_empty_intf`. ```` are: - ``(public_name )`` specifies that the executable should be installed under this name. It's the same as adding the following stanza to your ``dune`` file: .. code:: dune (install (section bin) (files (.exe as ))) As a special case, ``(public_name -)`` is the same as if the field was absent. .. _shared-exe-fields: - ``(package )`` if there is a ``(public_name ...)`` field, this specifies the package the executables are part of it. - ``(libraries )`` specifies the library dependencies. See :doc:`/reference/library-dependencies` for more details. - ``(link_flags )`` specifies additional flags to pass to the linker. This field supports ``(:include ...)`` forms. - ``(link_deps ())`` specifies the dependencies used only by the linker, i.e., when using a version script. See :doc:`/concepts/dependency-spec` for more details. - ``(modules )`` specifies which modules in the current directory Dune should consider when building this executable. Modules not listed here will be ignored and cannot be used inside the executable described by the current stanza. It is interpreted in the same way as the ``(modules ...)`` field of :doc:`library`. - ``(root_module )`` specifies a ``root_module`` that collects all listed dependencies in ``libraries``. See the documentation for ``root_module`` in the library stanza. - ``(modes ())`` sets the `linking modes`_. The default is ``(exe)``. Before Dune 2.0, it formerly was ``(byte exe)``. - ``(preprocess )`` is the same as the ``(preprocess ...)`` field of :doc:`library`. - ``(preprocessor_deps ())`` is the same as the ``(preprocessor_deps ...)`` field of :doc:`library`. - ``js_of_ocaml``: See the section about :ref:`jsoo-field` - ``wasm_of_ocaml``: See the section about :ref:`wasmoo-field` - ``flags``, ``ocamlc_flags``, and ``ocamlopt_flags``: See :doc:`/concepts/ocaml-flags`. - ``(modules_without_implementation )`` is the same as the corresponding field of :doc:`library`. - ``(allow_overlapping_dependencies)`` is the same as the corresponding field of :doc:`library`. - ``(optional)`` is the same as the corresponding field of :doc:`library`. - ``(enabled_if )`` is the same as the corresponding field of :doc:`library`. - ``(promote )`` allows promoting the linked executables to the source tree. The options are the same as for the :ref:`rule promote mode `. Adding ``(promote (until-clean))`` to an ``executable`` stanza will cause Dune to copy the ``.exe`` files to the source tree and use ``dune clean`` to delete them. - ``(foreign_stubs )`` specifies foreign source files, e.g., C or C++ stubs, to be linked into the executable. See :doc:`/reference/foreign-stubs` for more details. - ``(foreign_archives )`` specifies archives of foreign object files to be linked into the executable. See the section :doc:`/reference/foreign-archives` for more details. - ``(forbidden_libraries )`` ensures that the given libraries are not linked in the resulting executable. If they end up being pulled in, either through a direct or transitive dependency, Dune fails with an error message explaining how the library was pulled in. This field has been available since Dune 2.0. - ``(embed_in_plugin_libraries )`` specifies a list of libraries to link statically when using the ``plugin`` linking mode. By default, no libraries are linked in. Note that you may need to also use the ``-linkall`` flag if some of the libraries listed here are not referenced from any of the plugin modules. - ``(ctypes )`` instructs Dune to use ctypes stubgen to process your type and function descriptions for binding system libraries, vendored libraries, or other foreign code. See :ref:`ctypes-stubgen` for a full reference. This field is available since the 3.0 version of the Dune language. - ``(empty_module_interface_if_absent)`` causes the generation of empty interfaces for every module that does not have an interface file already. Useful when modules are used solely for their side-effects. This field is available since the 3.0 version of the Dune language. Linking Modes ~~~~~~~~~~~~~ The ``modes`` field allows selecting which linking modes will be used to link executables. Each mode is a pair ``( )``, where ```` describes whether the bytecode or native code backend of the OCaml compiler should be used and ```` describes what kind of file should be produced. ```` must be ``byte``, ``native``, or ``best``, where ``best`` is ``native`` with a fallback to bytecode when native compilation isn't available. ```` is one of: - ``c`` for producing OCaml bytecode embedded in a C file - ``exe`` for normal executables - ``object`` for producing static object files that can be manually linked into C applications - ``shared_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 :doc:`/reference/dune-project/explicit_js_mode`. - ``wasm`` for producing JavaScript from bytecode executables. - ``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: .. code:: dune (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)`` - ``wasm`` for ``(byte wasm)`` - ``plugin`` for ``(best plugin)`` For instance, the following ``modes`` fields are all equivalent: .. code:: dune (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: .. =========================== ================= .. linking mode extensions .. --------------------------- ----------------- .. byte .bc .. native/best .exe .. byte_complete .bc.exe .. (byte object) .bc%{ext_obj} .. (native/best object) .exe%{ext_obj} .. (byte shared_object) .bc%{ext_dll} .. (native/best shared_object) %{ext_dll} .. c .bc.c .. js .bc.js .. wasm .bc.wasm.js .. (best plugin) %{ext_plugin} .. (byte plugin) .cma .. (native plugin) .cmxs .. =========================== ================= ``%{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)``. .. _jsoo-field: js_of_ocaml ~~~~~~~~~~~ In ``library`` and ``executable`` stanzas, you can specify ``js_of_ocaml`` options using ``(js_of_ocaml ())``. ```` are all optional: - ``(flags )`` to specify flags passed to ``js_of_ocaml compile``. This field supports ``(:include ...)`` forms - ``(build_runtime_flags )`` to specify flags passed to ``js_of_ocaml build-runtime``. This field supports ``(:include ...)`` forms - ``(link_flags )`` to specify flags passed to ``js_of_ocaml link``. This field supports ``(:include ...)`` forms - ``(javascript_files ())`` to specify ``js_of_ocaml`` JavaScript runtime files. - ``(compilation_mode )`` where ``>`` is either ``whole_program`` or ``separate``. This is only available inside ``executable`` stanzas. - ``(sourcemap )`` where ``>`` is one of ``no``, ``file`` or ``inline``. This is only available inside ``executable`` stanzas. - ``(enabled_if )`` to specify whether the ``js`` mode is enabled. It is enabled by default. This is only available inside ``executable`` stanzas. ```` is specified in the :doc:`/reference/ordered-set-language`. ```` is specified using the :doc:`/reference/boolean-language`, The default values for ``flags``, ``compilation_mode`` and ``sourcemap`` depend on the selected build profile. The build profile ``dev`` (the default) will enable inline sourcemap, separate compilation and pretty JavaScript output. See :ref:`jsoo` for more information. .. _wasmoo-field: wasm_of_ocaml ~~~~~~~~~~~~~ In ``library`` and ``executable`` stanzas, you can specify ``wasm_of_ocaml`` options using ``(wasm_of_ocaml ())``. ```` are all optional. They are the same as the ```` above plus: - ``(wasm_files ())`` to specify ``wasm_of_ocaml`` Wasm runtime files. For the ``(sourcemap )`` option, ```` must be one of ``no`` or ``inline``. Source maps are put within the ``.bc.wasm.assets`` directory. The default values for ``flags``, ``compilation_mode`` and ``sourcemap`` depend on the selected build profile. The build profile ``dev`` (the default) will enable sourcemaps, separate compilation and pretty Wasm output. See :ref:`wasmoo` 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 )`` where ```` is a list of entry point names. Compare with ``executable``, where you only need to specify the modules containing the entry point of each executable. - ``(public_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: .. code:: dune (executables (names foo bar)) Instead of the more complex .. code:: dune (library (name baz) (modules baz)) (executable (name foo) (modules foo) (libraries baz)) (executable (name bar) (modules bar) (libraries baz))