unikernel/duniverse/dune_/doc/reference/dune-workspace/context.rst

@@ -0,0 +1,84 @@
+context
+-------
+
+The ``(context ...)`` stanza declares a build context. The argument can be
+either ``default`` or ``(default)`` for the default build context, or it can be
+the description of an opam switch, as follows:
+
+.. code:: dune
+
+    (context (opam (switch <opam-switch-name>)
+                   <optional-fields>))
+
+``<optional-fields>`` are:
+
+-  ``(name <name>)`` is the subdirectory's name for ``_build``, where this
+   build's context artifacts will be stored.
+
+-  ``(lock_dir <path>)`` specifies the lock directory that will be used for
+   building this context (if any). If no lock directory is specified
+   ``dune.lock`` will be used. See the
+   :doc:`/reference/dune-workspace/lock_dir` stanza for lock directory
+   configuration options.
+
+-  ``(root <opam-root>)`` is the opam root. By default, it will take the opam
+   root defined by the environment in which ``dune`` is run, which is usually
+   ``~/.opam``.
+
+- ``(merlin)`` instructs Dune to use this build context for Merlin.
+
+- ``(generate_merlin_rules)`` instructs Dune to generate Merlin rules for this
+  context, even if it is not the one selected via ``(merlin)``.
+
+- ``(profile <profile>)`` sets a different profile for a :term:`build context`. This has
+  precedence over the command-line option ``--profile``.
+
+- ``(env <env>)`` sets the environment for a particular context. This is of
+  higher precedence than the root ``env`` stanza in the workspace file. This
+  field has the same options as the :doc:`/reference/dune/env` stanza.
+
+- ``(toolchain <findlib_toolchain>)`` sets a ``findlib`` toolchain for the
+  context.
+
+- ``(host <host_context>)`` chooses a different context to build binaries that
+  are meant to be executed on the host machine, such as preprocessors.
+
+- ``(paths (<var1> <val1>) .. (<varN> <valN>))`` allows you to set the value of
+  any ``PATH``-like variables in this context. If ``PATH`` itself is modified in
+  this way, its value will be used to resolve workspace binaries, including
+  finding the compiler and related tools. These variables will also be passed as
+  part of the environment to any program launched by Dune. For each variable,
+  the value is specified using the :doc:`/reference/ordered-set-language`.
+  Relative paths are interpreted with respect to the workspace root. See
+  :ref:`finding-root`.
+
+- ``(fdo <target_exe>)`` builds this context with feedback-direct optimizations.
+  It requires `OCamlFDO <https://github.com/gretay-js/ocamlfdo>`__.
+  ``<target_exe>`` is a path-interpreted relative to the workspace root (see
+  :ref:`finding-root`). ``<target_exe>`` specifies which executable to optimize.
+  Users should define a different context for each target executable built with
+  FDO. The context name is derived automatically from the default name and
+  ``<target-exe>``, unless explicitly specified using the ``(name ...)`` field.
+  For example, if ``<target_exe>`` is *src/foo.exe* in a default context, then
+  the name of the context is *default-fdo-foo* and the filename that contains
+  execution counters is *src/fdo.exe.fdo-profile*.  This feature is
+  **experimental** and no backwards compatibility is implied.
+
+- By default, Dune builds and installs dynamically-linked foreign archives
+  (usually named ``dll*.so``). It's possible to disable this by setting by
+  including ``(disable_dynamically_linked_foreign_archives true)`` in the
+  workspace file, so bytecode executables will be built with all foreign
+  archives statically linked into the runtime system.
+
+
+Both ``(default ...)`` and ``(opam ...)`` accept a ``targets`` field in order to
+setup cross compilation. See :ref:`cross-compilation` for more information.
+
+Merlin reads compilation artifacts, and it can only read the compilation
+artifacts of a single context. Usually, you should use the artifacts from the
+``default`` context, and if you have the ``(context default)`` stanza in your
+``dune-workspace`` file, that is the one Dune will use.
+
+For rare cases where this is not what you want, you can force Dune to use a
+different build contexts for Merlin by adding the field ``(merlin)`` to this
+context.