unikernel/duniverse/dune_/doc/advanced/ocaml-syntax.rst

@@ -0,0 +1,21 @@
+OCaml Syntax
+============
+
+.. TODO(diataxis)
+   - reference: files
+   - howto: using dynamic features
+
+If a ``dune`` file starts with ``(* -*- tuareg -*- *)``, then it is
+interpreted as an OCaml script that generates the ``dune`` file as described
+in the rest of this section. The code in the script will have access to a
+`Jbuild_plugin
+<https://github.com/ocaml/dune/blob/master/plugin/jbuild_plugin.mli>`__
+module containing details about the build context it's executed in.
+
+The OCaml syntax gives you an escape hatch for when the S-expression
+syntax is not enough. It isn't clear whether the OCaml syntax will be
+supported in the long term, as it doesn't work well with incremental
+builds. It is possible that it will be replaced by just an ``include``
+stanza where one can include a generated file.
+
+Consequently **you must not** build complex systems based on it.