unikernel/duniverse/dune_/doc/advanced/custom-cmxs.rst

@@ -0,0 +1,30 @@
+Building an Ad Hoc ``.cmxs``
+----------------------------
+
+.. TODO(diataxis) howto: Building an Ad Hoc ``.cmxs``
+
+In the model exposed by Dune, a ``.cmxs`` target is created for each
+library. However, the ``.cmxs`` format itself is more flexible and is
+capable to containing arbitrary ``.cmxa`` and ``.cmx`` files.
+
+For the specific cases where this extra flexibility is needed, one can use
+:ref:`variables-for-artifacts` to write explicit rules to build ``.cmxs`` files
+not associated to any library.
+
+Below is an example where we build ``my.cmxs`` containing ``foo.cmxa`` and
+``d.cmx``. Note how we use a :doc:`/reference/dune/library` stanza to set
+up the compilation of ``d.cmx``.
+
+.. code:: dune
+
+    (library
+     (name foo)
+     (modules a b c))
+
+    (library
+     (name dummy)
+     (modules d))
+
+    (rule
+     (targets my.cmxs)
+     (action (run %{ocamlopt} -shared -o %{targets} %{cmxa:foo} %{cmx:d})))

unikernel/duniverse/dune_/doc/advanced/findlib-dynamic.rst

@@ -0,0 +1,58 @@
+Dynamic Loading of Packages with Findlib
+========================================
+
+.. TODO(diataxis) this is an howto
+
+The preferred way for new development is to use :ref:`plugins`.
+
+Dune supports the ``findlib.dynload`` package from `Findlib
+<http://projects.camlcity.org/projects/findlib.html>`_ that enables
+dynamically-loading packages and their dependencies (using the OCaml Dynlink module).
+Adding the ability for an application to have plugins just requires adding
+``findlib.dynload`` to the set of library dependencies:
+
+.. code:: dune
+
+    (library
+      (name mytool)
+      (public_name mytool)
+      (modules ...)
+    )
+
+    (executable
+      (name main)
+      (public_name mytool)
+      (libraries mytool findlib.dynload)
+      (modules ...)
+    )
+
+
+Use ``Fl_dynload.load_packages l`` in your application to load 
+the list ``l`` of packages. The packages are loaded
+only once, so trying to load a package statically linked does nothing.
+
+A plugin creator just needs to link to your library:
+
+.. code:: dune
+
+    (library
+      (name mytool_plugin_a)
+      (public_name mytool-plugin-a)
+      (libraries mytool)
+    )
+
+For clarity, choose a naming convention. For example, all the plugins of
+``mytool`` should start with ``mytool-plugin-``. You can automatically
+load all the plugins installed for your tool by listing the existing packages:
+
+.. code:: ocaml
+
+    let () = Findlib.init ()
+    let () =
+      let pkgs = Fl_package_base.list_packages () in
+      let pkgs =
+        List.filter
+          (fun pkg -> 14 <= String.length pkg && String.sub pkg 0 14 = "mytool-plugin-")
+          pkgs
+      in
+      Fl_dynload.load_packages pkgs

unikernel/duniverse/dune_/doc/advanced/index.rst

@@ -0,0 +1,14 @@
+Advanced Topics
+===============
+
+These documents describe some advanced or very specific features of Dune.
+
+.. toctree::
+   :maxdepth: 1
+
+   findlib-dynamic
+   profiling-dune
+   package-version
+   ocaml-syntax
+   variables-artifacts
+   custom-cmxs

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.

unikernel/duniverse/dune_/doc/advanced/package-version.rst

@@ -0,0 +1,16 @@
+Package Version
+===============
+
+.. TODO(diataxis)
+   - reference: environment - packages
+
+Dune determines a package's version by looking at the ``version`` field in the
+:doc:`/reference/dune-project/package`. If the version field isn't set,
+it looks at the toplevel ``version`` field in the ``dune-project`` field. If
+neither are set, Dune assumes that we are in development mode and reads the
+version from the VCS, if any. The way it obtains the version from the VCS is
+described in :ref:`the build-info section <build-info>`.
+
+When installing the files of a package on the system, Dune
+automatically inserts the package version into various metadata files
+such as ``META`` and ``dune-package`` files.

unikernel/duniverse/dune_/doc/advanced/profiling-dune.rst

@@ -0,0 +1,15 @@
+Profiling Dune
+==============
+
+.. TODO(diataxis)
+   - reference: the CLI
+   - howto: profiling a dune build
+
+If ``--trace-file FILE`` is passed, Dune will write detailed data about internal
+operations, such as the timing of commands that Dune runs.
+
+The format is compatible with `Catapult trace-viewer`_. In particular, these
+files can be loaded into Chromium's ``chrome://tracing``. Note that the exact
+format is subject to change between versions.
+
+.. _Catapult trace-viewer: https://github.com/catapult-project/catapult/blob/master/tracing/README.md

unikernel/duniverse/dune_/doc/advanced/variables-artifacts.rst

@@ -0,0 +1,32 @@
+.. _variables-for-artifacts:
+
+Variables for Artifacts
+-----------------------
+
+.. TODO(diataxis) move to :doc:`../concepts/variables`
+
+For specific situations where one needs to refer to individual compilation
+artifacts, special variables (see :doc:`../concepts/variables`) are provided,
+so the user doesn't need to be aware of the particular naming conventions or
+directory layout implemented by Dune.
+
+These variables can appear wherever a :doc:`../concepts/dependency-spec` is
+expected and also inside :doc:`../reference/actions/index`. When used inside
+:doc:`../reference/actions/index`, they implicitly declare a dependency on the
+corresponding artifact.
+
+The variables have the form ``%{<ext>:<path>}``, where ``<path>`` is
+interpreted relative to the current directory:
+
+- ``cmo:<path>``, ``cmx:<path>``, and ``cmi:<path>`` expand to the corresponding
+  artifact's path for the module specified by ``<path>``. The basename of
+  ``<path>`` should be the name of a module as specified in a ``(modules)``
+  field.
+
+- ``cma:<path>`` and ``cmxa:<path>`` expands to the corresponding 
+  artifact's path for the library specified by ``<path>``. The basename of ``<path>``
+  should be the name of the library as specified in the ``(name)`` field of a
+  ``library`` stanza (*not* its public name).
+
+In each case, the expansion of the variable is a path pointing inside the build
+context (i.e., ``_build/<context>``).