unikernel/duniverse/dune_/doc/reference/dune-project/dialect.rst

@@ -0,0 +1,93 @@
+dialect
+-------
+
+.. describe:: (dialect ...)
+
+   Declare a new :term:`dialect`.
+
+   .. describe:: (name <name>)
+
+      The name of the dialect being defined. It must be unique in a given
+      project.
+
+      This field is required.
+
+   .. describe:: (implementation ...)
+
+      Details related to the implementation files (corresponding to `*.ml`).
+
+      .. versionchanged:: 3.9 This field is made optional.
+
+      .. describe:: (extension <string>)
+
+         Specify the file extension used for this dialect.
+
+         The extension string must not start with a period and be unique in a
+         given project (so that a given extension can be mapped back to a
+         corresponding dialect). In Dune 3.9 and later, the extension string may
+         contain periods (e.g., `cppo.ml`).
+
+         This field is required.
+
+      .. describe:: (preprocess <action>)
+
+         Run `<action>` to produce a valid OCaml abstract syntax tree.
+
+         This action is expected to read the file given in the variable named
+         ``%{input-file}`` and output a *binary* abstract syntax tree on its
+         standard output.
+
+         If the field is not present, it is assumed that the corresponding
+         source code is already valid OCaml code and can be passed to the OCaml
+         compiler as-is.
+
+         .. seealso:: :ref:`preprocessing-actions`
+
+      .. describe:: (format <action>)
+
+         Run `<action>` to format source code for this dialect.
+
+         The action is expected to read the file given in the variable named
+         ``%{input-file}`` and output the formatted source code on its standard
+         output.
+
+         If the field is not present, the behavior depends on the presence of
+         ``(preprocess)``: if it is also not present (that is, the dialect
+         consists of valid OCaml code), then the dialect will be formatted as
+         any other OCaml code. Otherwise no special formatting will be done.
+
+         .. seealso:: :doc:`/howto/formatting`
+
+   .. describe:: (interface ...)
+
+      Details related to the interface files (corresponding to `*.mli`).
+
+      This field supports the same sub-fields as ``implementation``.
+
+      .. versionchanged:: 3.9 This field is made optional.
+
+   .. describe:: (merlin_reader <program> <args>...)
+
+      Configure Merlin to use `<program> <args>...` as READER. Merlin's READER
+      is a mechanism to extend Merlin to support OCaml dialects by providing
+      a program that transforms a dialect AST into an OCaml AST.
+
+      .. seealso:: `merlin/src/extend/extend_protocol.ml <https://github.com/ocaml/merlin/blob/4.14-502_preview2/src/extend/extend_protocol.ml>`_ for the protocol specification.
+
+      This field is optional.
+
+      .. versionadded:: 3.16
+
+
+Default dialects
+----------------
+
+Dune ships with two dialects pre-configured and enabled:
+
+* ``ocaml`` for the default OCaml syntax which consumes `.ml` and `.mli` files
+  and uses ``ocamlformat`` for formatting.
+* ``reason`` for the Reason syntax and enabled in `.re`/`.rei` files. ``refmt``
+  is used for formatting.
+
+A third dialect, ``rescript``, is added when Melange support (see :doc:`/melange`)
+is enabled in the project.