********** dune files ********** ``dune`` files are the main part of dune. They are used to describe libraries, executables, tests, and everything dune needs to know about. The syntax of ``dune`` files is described in :ref:`metadata-format` section. Stanzas ======= ``dune`` files are composed of stanzas. For instance a typical ``dune`` looks like: .. code:: scheme (library (name mylib) (libraries base lwt)) (rule (targets foo.ml) (deps generator/gen.exe) (action (run %{deps} -o %{targets}))) The following sections describe the available stanzas and their meaning. jbuild_version -------------- Deprecated. This stanza is no longer used and will be removed in the future. library ------- The ``library`` stanza must be used to describe OCaml libraries. The format of library stanzas is as follows: .. code:: scheme library (name ) ```` is the real name of the library. It determines the names of the archive files generated for the library as well as the module name under which the library will be available, unless ``(wrapped false)`` is used (see below). It must be a valid OCaml module name but doesn't need to start with a uppercase letter. For instance, the modules of a library named ``foo`` will be available as ``Foo.XXX`` outside of ``foo`` itself. It is however allowed to write an explicit ``Foo`` module, in which case this will be the interface of the library and you are free to expose only the modules you want. Note that by default libraries and other things that consume OCaml/Reason modules only consume modules from the directory where the stanza appear. In order to declare a multi-directory library, you need to use the :ref:`include_subdirs` stanza. ```` are: - ``(public_name )`` this is the name under which the library can be referred to as a dependency when it is not part of the current workspace, i.e. when it is installed. Without a ``(public_name ...)`` field, the library will not be installed by dune. The public name must start by the package name it is part of and optionally followed by a dot and anything else you want. The package name must be one of the packages that dune knows about, as determined by the :ref:`opam-files` - ``(synopsis )`` should give a one-line description of the library. This is used by tools that list installed libraries - ``(modules )`` specifies what modules are part of the library. By default dune will use all the .ml/.re files in the same directory as the ``dune`` file. This include ones that are present in the file system as well as ones generated by user rules. You can restrict this list by using a ``(modules )`` field. ```` uses the `Ordered set language`_ where elements are module names and don't need to start with a uppercase letter. For instance to exclude module ``Foo``: ``(modules (:standard \ foo))`` - ``(libraries )`` is used to specify the dependencies of the library. See the section about `Library dependencies`_ for more details - ``(wrapped )`` specifies whether the modules of the library should be available only through the top-level library module, or should all be exposed at the top level. The default is ``true`` and it is highly recommended to keep it this way. Because OCaml top-level modules must all be unique when linking an executables, polluting the top-level namespace will make your library unusable with other libraries if there is a module name clash. This option is only intended for libraries that manually prefix all their modules by the library name and to ease porting of existing projects to dune - ``(wrapped (transition ))`` Is the same as ``(wrapped true)`` except that it will also generate unwrapped (not prefixed by the library name) modules to preserve compatibility. This is useful for libraries that would like to transition from ``(wrapped false)`` to ``(wrapped true)`` without breaking compatibility for users. The ```` will be included in the deprecation notice for the unwrapped modules. - ``(preprocess )`` specifies how to preprocess files if needed. The default is ``no_processing``. Other options are described in the `Preprocessing specification`_ section - ``(preprocessor_deps ())`` specifies extra dependencies of the preprocessor, for instance if the preprocessor reads a generated file. The specification of dependencies is described in the `Dependency specification`_ section - ``(optional)``, if present it indicates that the library should only be built and installed if all the dependencies are available, either in the workspace or in the installed world. You can use this to provide extra features without adding hard dependencies to your project - ``(c_names ())``, if your library has stubs, you must list the C files in this field, without the ``.c`` extension - ``(cxx_names ())`` is the same as ``c_names`` but for C++ stubs - ``(install_c_headers ())``, if your library has public C header files that must be installed, you must list them in this field, without the ``.h`` extension - ``(modes )`` modes which should be built by default. The most common use for this feature is to disable native compilation when writing libraries for the OCaml toplevel. The following modes are available: ``byte``, ``native`` and ``best``. ``best`` is ``native`` or ``byte`` when native compilation is not available - ``(no_dynlink)`` is to disable dynamic linking of the library. This is for advanced use only, by default you shouldn't set this option - ``(kind )`` is the kind of the library. The default is ``normal``, other available choices are ``ppx_rewriter`` and ``ppx_deriver`` and must be set when the library is intended to be used as a ppx rewriter or a ``[@@deriving ...]`` plugin. The reason why ``ppx_rewriter`` and ``ppx_deriver`` are split is historical and hopefully we won't need two options soon - ``(ppx_runtime_libraries ())`` is for when the library is a ppx rewriter or a ``[@@deriving ...]`` plugin and has runtime dependencies. You need to specify these runtime dependencies here - ``(virtual_deps ()``. Sometimes opam packages enable a specific feature only if another package is installed. This is for instance the case of ``ctypes`` which will only install ``ctypes.foreign`` if the dummy ``ctypes-foreign`` package is installed. You can specify such virtual dependencies here. You don't need to do so unless you use dune to synthesize the ``depends`` and ``depopts`` sections of your opam file - ``js_of_ocaml``. See the section about :ref:`dune-jsoo` - ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about `OCaml flags`_ - ``(library_flags ())`` is a list of flags that are passed as it to ``ocamlc`` and ``ocamlopt`` when building the library archive files. You can use this to specify ``-linkall`` for instance. ```` is a list of strings supporting `Variables expansion`_ - ``(c_flags )`` specifies the compilation flags for C stubs, using the `Ordered set language`_. This field supports ``(:include ...)`` forms - ``(cxx_flags )`` is the same as ``c_flags`` but for C++ stubs - ``(c_library_flags )`` specifies the flags to pass to the C compiler when constructing the library archive file for the C stubs. ```` uses the `Ordered set language`_ and supports ``(:include ...)`` forms. When you are writing bindings for a C library named ``bar``, you should typically write ``-lbar`` here, or whatever flags are necessary to to link against this library - ``(self_build_stubs_archive )`` indicates to dune that the library has stubs, but that the stubs are built manually. The aim of the field is to embed a library written in foreign language and/or building with another build system. It is not for casual uses, see the `re2 library `__ for an example of use - ``(modules_without_implementation )`` specifies a list of modules that have only a ``.mli`` or ``.rei`` but no ``.ml`` or ``.re`` file. Such modules are usually referred as *mli only modules*. They are not officially supported by the OCaml compiler, however they are commonly used. Such modules must only define types. Since it is not reasonably possible for dune to check that this is the case, dune requires the user to explicitly list such modules to avoid surprises. ```` must be a subset of the modules listed in the ``(modules ...)`` field. - ``(allow_overlapping_dependencies)`` allows external dependencies to overlap with libraries that are present in the workspace - ``(no_keep_locs)`` undocumented, it is a necessary hack until this is implemented: https://github.com/ocaml/dune/issues/921 Note that when binding C libraries, dune doesn't provide special support for tools such as ``pkg-config``, however it integrates easily with configurator_ by using ``(c_flags (:include ...))`` and ``(c_library_flags (:include ...))``. .. _configurator: https://github.com/janestreet/configurator executable ---------- The ``executable`` stanza must be used to describe an executable. The format of executable stanzas is as follows: .. code:: scheme (executable (name ) ) ```` is a module name that contains the main entry point of the executable. 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``, ``.bc`` and ``.bc.js``. ``.exe`` is a native code executable, ``.bc`` is a bytecode executable which requires ``ocamlrun`` to run and ``.bc.js`` is a JavaScript generated using js_of_ocaml. Note that in case native compilation is not available, ``.exe`` will in fact be a custom byte-code executable. Custom in the sense of ``ocamlc -custom``, meaning that it is a native executable that embeds the ``ocamlrun`` virtual machine as well as the byte code. As such 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. This is because running a byte-code executable often requires loading shared libraries that are locally built, and so requires additional setup such as setting specific environment variables and dune doesn't do at the moment. Native compilation is considered not available when there is no ``ocamlopt`` binary at the same place as where ``ocamlc`` was found. Executables can also be linked as object or shared object files. See `linking modes`_ for more information. ```` are: - ``(public_name )`` specifies that the executable should be installed under that name. It is the same as adding the following stanza to your ``dune`` file: .. code:: scheme (install (section bin) (files (.exe as ))) .. _shared-exe-fields: - ``(package )`` if there is a ``(public_name ...)`` field, this specifies the package the executables are part of - ``(libraries )`` specifies the library dependencies. See the section about `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, for example when using a version script. See the `Dependency specification`_ section 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 `library`_ - ``(modes ())`` sets the `linking modes`_. The default is ``(byte exe)`` - ``(preprocess )`` is the same as the ``(preprocess ...)`` field of `library`_ - ``(preprocessor_deps ())`` is the same as the ``(preprocessor_deps ...)`` field of `library`_ - ``js_of_ocaml``. See the section about `js_of_ocaml`_ - ``flags``, ``ocamlc_flags`` and ``ocamlopt_flags``. See the section about specifying `OCaml flags`_ - ``(modules_without_implementation )`` is the same as the corresponding field of `library`_ - ``(allow_overlapping_dependencies)`` is the same as the corresponding field of `library`_ Linking modes ~~~~~~~~~~~~~ The ``modes`` field allows to select what linking modes should be used to link executables. Each mode is a pair ``( )`` where ```` describes whether the byte code 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 byte-code when native compilation is not available. ```` is one of: - ``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. For instance the following ``executables`` stanza will produce byte code executables and native shared objects: .. code:: scheme (executables ((names (a b c)) (modes ((byte exe) (native shared_object))))) Additionally, you can use the following short-hands: - ``exe`` for ``(best exe)`` - ``object`` for ``(best object)`` - ``shared_object`` for ``(best shared_object)`` - ``byte`` for ``(byte exe)`` - ``native`` for ``(native exe)`` For instance the following ``modes`` fields are all equivalent: .. code:: scheme (modes (exe object shared_object)) (modes ((best exe) (best object) (best shared_object))) The extensions for the various linking modes are chosen as follows: ================ ============= ================= compilation mode binary kind extensions ---------------- ------------- ----------------- byte exe .bc and .bc.js native/best exe .exe byte object .bc%{ext_obj} native/best object .exe%{ext_obj} byte shared_object .bc%{ext_dll} native/best shared_object %{ext_dll} ================ ============= ================= Where ``%{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``. Note that when ``(byte exe)`` is specified but neither ``(best exe)`` nor ``(native exe)`` are specified, Jbuilkd still knows how to build an executable with the extension ``.exe``. In such case, the ``.exe`` version is the same as the ``.bc`` one except that it is linked with the ``-custom`` option of the compiler. You should always use the ``.exe`` rather that the ``.bc`` inside build rules. executables ----------- The ``executables`` stanza is the same as the ``executable`` stanza, except that it is used to describe several executables sharing the same configuration. It shares the same fields as the ``executable`` stanza, except that instead of ``(name ...)`` and ``(public_name ...)`` you must use: - ``(names )`` where ```` is a list of entry point names. As for ``executable`` you only need to specify the modules containing the entry point of each executable - ``(public_names )`` describes under what name each executable should be installed. 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 rule ---- The ``rule`` stanza is used to create custom user rules. It tells dune how to generate a specific set of files from a specific set of dependencies. The syntax is as follows: .. code:: scheme (rule (targets ) (action ) ) ```` is a list of file names. Note that currently dune only support user rules with targets in the current directory. ```` is the action to run to produce the targets from the dependencies. See the `User actions`_ section for more details. ```` are: - ``(deps )`` to specify the dependencies of the rule. See the `Dependency specification`_ section for more details. - ``(mode )`` to specify how to handle the targets, see `modes`_ for details - ``(fallback)`` is deprecated and is the same as ``(mode fallback)`` - ``(locks ())`` specify that the action must be run while holding the following locks. See the `Locks`_ section for more details. Note that contrary to makefiles or other build systems, user rules currently don't support patterns, such as a rule to produce ``%.y`` from ``%.x`` for any given ``%``. This might be supported in the future. modes ~~~~~ By default, the target of a rule must not exist in the source tree and dune will error out when this is the case. However, it is possible to change this behavior using the ``mode`` field. The following modes are available: - ``standard``, this is the standard mode - ``fallback``, in this mode, when the targets are already present in the source tree, dune will ignore the rule. It is an error if only a subset of the targets are present in the tree. The common use of fallback rules is to generate default configuration files that may be generated by a configure script. - ``promote``, in this mode, the files in the source tree will be ignored. Once the rule has been executed, the targets will be copied back to the source tree - ``promote-until-clean`` is the same as ``promote`` except than ``dune clean`` will remove the promoted files from the source tree There are two use cases for promote rules. The first one is when the generated code is easier to review than the generator, so it's easier to commit the generated code and review it. The second is to cut down dependencies during releases: by passing ``--ignore-promoted-rules`` to dune, rules will ``(mode promote)`` will be ignored and the source files will be used instead. The ``-p/--for-release-of-packages`` flag implies ``--ignore-promote-rules``. inferred rules ~~~~~~~~~~~~~~ When using the action DSL (see `User actions`_), it is most of the time obvious what are the dependencies and targets. For instance: .. code:: scheme (rule (targets b) (deps a) (action (copy %{deps} %{targets}))) In this example it is obvious by inspecting the action what the dependencies and targets are. When this is the case you can use the following shorter syntax, where dune infers dependencies and targets for you: .. code:: scheme (rule ) For instance: .. code:: scheme (rule (copy a b)) Note that in dune, targets must always be known statically. Especially, this mean that dune must be able to statically determine all targets. For instance, this ``(rule ...)`` stanza is rejected by dune: .. code:: scheme (rule (copy a b.%{read:file})) ocamllex -------- ``(ocamllex )`` is essentially a shorthand for: .. code:: scheme (rule (targets .ml) (deps .mll) (action (chdir %{workspace_root} (run %{bin:ocamllex} -q -o %{targets} %{deps})))) To use a different rule mode, use the long form: .. code:: scheme (ocamllex (modules ) (mode )) ocamlyacc --------- ``(ocamlyacc )`` is essentially a shorthand for: .. code:: scheme (rule (targets .ml .mli) (deps .mly) (action (chdir %{workspace_root} (run %{bin:ocamlyacc} %{deps})))) To use a different rule mode, use the long form: .. code:: scheme (ocamlyacc (modules ) (mode )) menhir ------ A ``menhir`` stanza is available to support the menhir_ parser generator. See the :ref:`menhir-main` section for details. .. _alias-stanza: alias ----- The ``alias`` stanza lets you add dependencies to an alias, or specify an action to run to construct the alias. The syntax is as follows: .. code:: scheme (alias (name ) (deps ) ) ```` is an alias name such as ``runtest``. .. _alias-fields: ```` specifies the dependencies of the alias. See the `Dependency specification`_ section for more details. ```` are: - ````, an action to run when constructing the alias. See the `User actions`_ section for more details. - ``(package )`` indicates that this alias stanza is part of package ```` and should be filtered out if ```` is filtered out from the command line, either with ``--only-packages `` or ``-p `` - ``(locks ())`` specify that the action must be run while holding the following locks. See the `Locks`_ section for more details. - ``(enabled_if )`` specifies the boolean condition that must be true for the tests to run. The condition is specified using the blang_, and the field allows for variables_ to appear in the expressions. The typical use of the ``alias`` stanza is to define tests: .. code:: scheme (alias (name runtest) (action (run %{exe:my-test-program.exe} blah))) See the section about :ref:`running-tests` for details. Note that if your project contains several packages and you run test the tests from the opam file using a ``build-test`` field, then all your ``runtest`` alias stanzas should have a ``(package ...)`` field in order to partition the set of tests. install ------- The ``install`` stanza is what lets you describe what dune should install, either when running ``dune install`` or through opam. Libraries and executables don't need an ``install`` stanza to be installed, just a ``public_name`` field. Everything else needs an ``install`` stanza. The syntax is as follows: .. code:: scheme (install (section
) (files ) ) ``
`` is the installation section, as described in the opam manual. The following sections are available: - ``lib`` - ``lib_root`` - ``libexec`` - ``libexec_root`` - ``bin`` - ``sbin`` - ``toplevel`` - ``share`` - ``share_root`` - ``etc`` - ``doc`` - ``stublibs`` - ``man`` - ``misc`` ```` is the list of files to install. Each element in the list must be either a literal filename or a S-expression of the form: .. code:: scheme ( as ) where ```` describe how the file will be installed. For instance, to install a file ``mylib.el`` as ``emacs/site-lisp/mylib.el`` in the ``share_root`` section: .. code:: scheme (install (section share_root) (files (mylib.el as emacs/site-lisp/mylib.el))) ```` are: - ``(package )``. If there are no ambiguities, you can omit this field. Otherwise you need it to specify which package these files are part of. The package is not ambiguous when the first parent directory to contain a ``.opam`` file contains exactly one ``.opam`` file Handling of the .exe extension on Windows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Under Microsoft Windows, executables must be suffixed with ``.exe``. Dune tries to make sure that executables are always installed with this extension on Windows. More precisely, when installing a file via an ``(install ...)`` stanza, if the source file has extension ``.exe`` or ``.bc``, then dune implicitly adds the ``.exe`` extension to the destination, if not already present. copy_files ---------- The ``copy_files`` and ``copy_files#`` stanzas allow to specify that files from another directory could be copied if needed to the current directory. The syntax is as follows: .. code:: scheme (copy_files ) ```` represents the set of files to copy, see the :ref:`glob ` for details. The difference between ``copy_files`` and ``copy_files#`` is the same as the difference between the ``copy`` and ``copy#`` action. See the `User actions`_ section for more details. include ------- The ``include`` stanza allows to include the contents of another file into the current dune file. Currently, the included file cannot be generated and must be present in the source tree. This feature is intended to be used in conjunction with promotion, when parts of a dune file are to be generated. For instance: .. code:: scheme (include dune.inc) (rule (with-stdout-to dune.inc.gen (run ./gen-dune.exe))) (alias (name runtest) (action (diff dune.inc dune.inc.gen))) With this dune file, running dune as follow will replace the ``dune.inc`` file in the source tree by the generated one: .. code:: shell $ dune build @runtest --auto-promote .. _tests-stanza: tests ----- The ``tests`` stanza allows one to easily define multiple tests. For example we can define two tests at once with: .. code:: scheme (tests (names mytest expect_test) ) This will define an executable named ``mytest.exe`` that will be executed as part of the ``runtest`` alias. If the directory also contains an ``expect_test.expected`` file, then ``expect_test`` will be used to define an expect test. That is, the test will be executed and its output will be compared to ``expect_test.expected``. The optional fields that are supported are a subset of the alias and executables fields. In particular, all fields except for ``public_names`` are supported from the `executables stanza `_. Alias fields apart from ``name`` and ``action`` are allowed. test ---- The ``test`` stanza is the singular form of ``tests``. The only difference is that it's of the form: .. code:: scheme (test (name foo) ) where the ``name`` field is singular. The same optional fields are supported. .. _dune-env: env --- The ``env`` stanza allows to modify the environment. The syntax is as follow: .. code:: scheme (env ( ) ( ) ... ( )) The first form ``( )`` that correspond to the selected build profile will be used to modify the environment in this directory. You can use ``_`` to match any build profile. Currently ```` can be any OCaml flags field, see `OCaml flags`_ for more details. .. _dune-ignored_subdirs: ignored_subdirs --------------- The ``ignored_subdirs`` stanza allows to tell Dune to ignore one or more sub-directories. The syntax is as follow: .. code:: scheme (ignored_subdirs ( ...)) A directory that is ignored will not be eagerly scanned by Dune. Any ``dune`` or other special files in it won't be interpreted either and will be treated as raw data. It is however possible to depend on files inside ignored sub-directories. .. _include_subdirs: include_subdirs --------------- The ``include_subdirs`` stanza is used to control how dune considers sub-directories of the current directory. The syntax is as follow: .. code:: scheme (include_subdirs ) Where ```` maybe be one of: - ``no``, the default - ``unqualified`` When the ``include_subdirs`` stanza is not present or ```` is ``no``, dune considers sub-directories as independent. When ```` is ``unqualified``, dune will assume that the sub-directories of the current directory are part of the same group of directories. In particular, dune will scan all these directories at once when looking for OCaml/Reason files. This allows you to split a library between several directories. ``unqualified`` means that modules in sub-directories are seen as if they were all in the same directory. In particular, you cannot have two modules with the same name in two different directories. It is planned to add a ``qualified`` mode in the future. Note that sub-directories are included recursively, however the recursion will stop when encountering a sub-directory that contains another ``include_subdirs`` stanza. Additionally, it is not allowed for a sub-directory of a directory with ``(include_subdirs )`` where ```` is not ``no`` to contain one of the following stanzas: - ``library`` - ``executable(s)`` - ``test(s)`` Common items ============ .. _ordered-set-language: Ordered set language -------------------- A few fields takes as argument an ordered set and can be specified using a small DSL. This DSL is interpreted by dune into an ordered set of strings using the following rules: - ``:standard`` denotes the standard value of the field when it is absent - an atom not starting with a ``:`` is a singleton containing only this atom - a list of sets is the concatenation of its inner sets - ``( \ )`` is the set composed of elements of ```` that do not appear in ```` In addition, some fields support the inclusion of an external file using the syntax ``(:include )``. This is useful for instance when you need to run a script to figure out some compilation flags. ```` is expected to contain a single S-expression and cannot contain ``(:include ...)`` forms. Note that inside an ordered set, the first element of a list cannot be an atom except if it starts with `-` or `:`. The reason for this is that we are planning to add simple programmatic features in the futures so that one may write: .. code:: (flags (if (>= %{ocaml_version} 4.06) ...)) This restriction will allow to add this feature without introducing a breaking changes. If you want to write a list where the first element doesn't start by `-`, you can simply quote it: ``("x" y z)``. Most fields using the ordered set language also support `Variables expansion`_. Variables are expanded after the set language is interpreted. .. _blang: Boolean Language ---------------- The boolean language allows the user to define simple boolean expressions that dune can evaluate. Here's a semi formal specification of the language: .. code:: op := '=' | '<' | '>' | '<>' | '>=' | '<=' expr := (and +) | (or +) | (