.. post:: 2018-08-02
   :tags: OCaml, dune

What's coming in Dune 1.1.0?
============================

Now that 1.0.0 has been released, the team took a break from dune affairs.
However, now we're back to work, and although we're working at a more relaxed
pace, we still have some interesting features in store. Most of these were
already planned for quite a while, but simply had to be delayed to get 1.0.0 out
of the door. Hopefully this post convinces the reader that it was worth the
wait.

``name(s)`` Fields are Now Optional
-----------------------------------

I'm sure many of you had to write stanzas of the form many times:

.. code:: scheme

   (executables
    (names foo bar)
    (public_names foo bar))

   (library
    (name lib)
    (public_name lib))

In dune 1.1.0, we've decided to spare you from some of this boilerplate and
allow the omission of the ``name(s)`` field when ``public_name(s)`` is present.
The above can now be written as:

.. code:: scheme

   (executables (public_names foo bar))
   (library (public_name lib))

Proper Multi Directory Sources for Libraries
--------------------------------------------

Users have longed for the ability to define a library across many directories,
and our standard response was to use ``#copy_files``. While this isn't so bad,
we've introduced a more fluent approach. Simply include the following stanza
your dune file:

.. code:: scheme

   (include_subdirs unqualified)

   (library (public_name foo))

And now the library ``foo`` will be composed of the modules in all the sub
directories where this stanza is defined. For now, only ``unqualified`` is
supported, but we look forward to introduce qualified_ as well.

Per Context & Workspace Environments
------------------------------------

The ``env`` stanza introduced in 1.0 was a great start in making project
definitions more flexible. The ability to define various flags in a profile
dependent way and to avoid repetition when many stanzas shared the same flags is
quite useful. We've decided to extend this ability to allow setting the
environment for particular contexts and entire workspaces.

For example, you might want to have a context to check if your code compiles
with the ``-principal`` flag. This can be done with this workspace file:

.. code:: scheme

  (context
   (default
    (env
     (_ (flags (:standard -principal))))))

You can also set the environment for all contexts in an environment file with a
toplevel environment stanza. Since such environment definitions can override
each other, the priority is as follows:

* The environment at the toplevel of the workspace has the lowest priority
* Context specific environment overrides the workspace environment
* Environments defined in dune flies override those defined in the workspace

Faster Compilation in Development Mode
--------------------------------------

I'm not sure how many users are familiar with the ``-opaque`` compiler option,
so allow me to quote the manual:

::

  -opaque

    Interface file compiled with this option are marked so that other
    compilation units depending on it will not rely on any implementation
    details of the compiled implementation. The native compiler will not access
    the .cmx file of this unit -- nor warn if it is absent. This can improve
    speed of compilation, for both initial and incremental builds, at the
    expense of performance of the generated code.

Dune 1.1.0 will include this flag to generate rules without extra ``.cmx``
dependencies. As the manual states, this should make compilation faster at the
expense of cross module optimizations. Of course, this compilation mode will
only be used when the profile is set to ``dev``. In ``--profile release`` we
will favor rules the old rules that optimize for runtime performance.


Support for ppx_import_
-----------------------

To avoid preprocessing files more than once, dune restricted its ppx support to
only those rewriters that are parsetree transformations without any other
dependencies. While this covered a very wide set of plugins, it excluded some
very useful ones, in particular: ppx_import_. This is because ppx_import_ reads
``cmi`` files as part of its AST rewriting and must be ran in two stages (hence
the performance penalty). To use such a ppx we've introduced the ``staged_pps``
constructor. Here's an example:

.. code:: scheme

  (library
   (name foo)
   (preprocess (staged_pps ppx_import)))

Now this will not be usable until ppx_import_ supports the `ppx driver`_
interface. Hopefully this feature will create some incentive for the ppx_driver
maintainers to do just that.

Finally, dune is still missing support to define such rewriters. This feature is
marginally used so the dune team cannot prioritize it, but if anybody is
interested in implementing this, don't hesitate to contact us.

Reminder to update ``dune-project``
-----------------------------------

To use some of the features above, you will need to bump your dune lang version.
Simply update your ``dune-project`` file to read:

.. code:: scheme

  (lang dune 1.1)
  ...

Conclusion
----------

I've omitted some minor features and bug fixes that are also included in 1.1.0.
Please consult the changelog_ for a full list. As always, if anything isn't
clear regarding the features above, don't hesitate to ask a question or to open
a bug against the documentation.

.. _changelog: https://github.com/ocaml/dune/blob/master/CHANGES.md
.. _qualified: https://github.com/ocaml/dune/issues/1084
.. _ppx_import: https://github.com/ocaml-ppx/ppx_import
.. _ppx driver: https://github.com/ocaml-ppx/ocaml-migrate-parsetree/blob/master/src/migrate_parsetree_driver.mli#L50