unikernel/duniverse/dune_/doc/reference/ordered-set-language.rst

@@ -0,0 +1,36 @@
+Ordered Set Language
+====================
+
+A few fields take an ordered set as argument and can be specified using a small
+DSL.
+
+Dune interprets this DSL into an ordered set of strings using the
+following rules:
+
+- ``:standard`` denotes the standard value of the field when it's 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
+- ``(<sets1> \ <sets2>)`` is the set composed of elements of ``<sets1>`` that do
+  not appear in ``<sets2>``
+
+In addition, some fields support the inclusion of an external file using the
+syntax ``(:include <filename>)``. For instance, this is useful when you need to
+run a script to figure out some compilation flags. ``<filename>`` is expected to
+contain a single S-expression and cannot contain ``(:include ...)`` forms.
+
+Note that inside an ordered set, a list's first element cannot be
+an atom except if it starts with ``-`` or ``:``. The reason for this is
+that we're planning to add simple programmatic features in the
+future so that one may write:
+
+.. code::
+
+   (flags (if (>= %{ocaml_version} 4.08) ...))
+
+This restriction will allow you to add this feature without introducing
+breaking changes. If you want to write a list where the first element
+doesn't start with ``-``, you can simply quote it: ``("x" y z)``.
+
+Most fields using the ordered set language also support
+:doc:`../concepts/variables`. Variables are expanded after the set language is
+interpreted.