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

@@ -0,0 +1,6 @@
+``config`` stanzas
+------------------
+
+Starting in Dune 3.0, any of the stanzas from the :doc:`../config/index` file
+can be used in the ``dune-workspace`` file. In this case, the configuration
+stanza will only affect the current workspace.

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.

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

@@ -0,0 +1,7 @@
+env
+---
+
+The ``env`` stanza can be used to set the base environment for all contexts in
+this workspace. This environment has the lowest precedence of all other ``env``
+stanzas. The syntax for this stanza is the same as Dune's
+:doc:`../dune/env` stanza.

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

@@ -0,0 +1,54 @@
+dune-workspace
+==============
+
+A ``dune-workspace`` file (if present) marks the root of the current Dune
+workspace (see :doc:`/explanation/scopes`). It can be used to define compilation contexts
+(see :doc:`/reference/dune-workspace/context`) and specify settings common to
+all Dune projects contained within the workspace.
+
+By default, a workspace has only one build context named ``default`` which
+corresponds to the environment in which ``dune`` is run. You can define more
+contexts by writing a ``dune-workspace`` file.
+
+You can point Dune to an explicit ``dune-workspace`` file with the
+``--workspace`` option. For instance, it's good practice to write a
+``dune-workspace.dev`` in your project with all the OCaml versions your projects
+support, so developers can test that the code builds with all OCaml versions by
+simply running:
+
+.. code:: console
+
+    $ dune build --workspace dune-workspace.dev @all @runtest
+
+The ``dune-workspace`` file uses the S-expression syntax. This is what a typical
+``dune-workspace`` file looks like:
+
+.. code:: dune
+
+    (lang dune 3.14)
+    (context (opam (switch 4.08.1)))
+    (context (opam (switch 4.11.1)))
+    (context (opam (switch 4.14.2)))
+
+The rest of this section describe the stanzas available.
+
+Note that an empty ``dune-workspace`` file is interpreted the same as one
+containing exactly:
+
+.. code:: dune
+
+    (lang dune 3.2)
+    (context default)
+
+This allows you to use an empty ``dune-workspace`` file to mark the root of your
+project.
+
+.. toctree::
+
+  config
+  context
+  env
+  lock_dir
+  pin
+  profile
+  repository

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

@@ -0,0 +1,80 @@
+lock_dir
+========
+
+.. warning::
+
+   :doc:`Dune Package Management </explanation/package-management>` is not
+   final yet and the configuration options are subject to change.
+
+This stanza configures the lock directory settings for the current workspace.
+For the default workflow no configuration is necessary, but the defaults can be
+changed if desired.
+
+.. describe:: (lock_dir ...)
+
+   .. versionadded:: 3.13
+
+   Configures a specific lock directory to be created or used.
+
+   .. describe:: (path <string>)
+
+      The location in the source tree where the lock directory will be
+      created or read from. If not specified defaults to ``dune.lock``.
+
+   .. describe:: (repositories <name list>)
+
+      The repositories to be used for finding a package solution, specified
+      in priority order. Supports ``:standard`` which contains ``upstream`` and
+      ``overlay``.
+
+      Additional repositories can be defined using the
+      :doc:`/reference/dune-workspace/repository` stanza.
+
+   .. describe:: (solver_env ...)
+
+      The environment that is injected into the solver when creating the lock
+      directory.
+
+      It consists of a sequence of ``(<name> <value>)`` pairs.
+
+   .. describe:: (unset_variables <name list>)
+
+      A list of variables that are used in solving that are deliberately unset
+      even if the solver could provide bindings for them.
+
+      The variables here cannot overlap with those defined in ``solver_env``.
+
+   .. describe:: (pins <name list>)
+
+      .. versionadded:: 3.15
+
+      Define which pins are enabled for this particular lock dir. See
+      :doc:`/reference/dune-workspace/pin` for details on how to define pins.
+
+   .. describe:: (version_preference <string>)
+
+      Can be one of:
+
+      - ``newest`` (default): The solver will pick the newest available
+         version of a package that satisfies the constraints.
+      - ``oldest``: The solver will pick the lowest version that will satisfy
+         the constraints
+
+   .. describe:: (constraints <dep-specification>)
+
+      Adds additional solver constraints that are passed to the solver. Follows
+      the :token:`~pkg-dep:dep_specification` format.
+
+      .. note::
+
+         Names introduced through ``constraints`` are not considered
+         dependencies and not added to the lockfile. They exist solely to add
+         additional constraints if the packages to which the constraint is
+         applied are selected and don't do anything otherwise.
+
+   .. describe:: (depopts <name list>)
+
+      .. versionadded:: 3.19
+
+      Defines which optional packages names (``depopts``) the solver should
+      include when attempting to find a solution for the project.

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

@@ -0,0 +1,57 @@
+pin
+===
+
+.. warning::
+
+   :doc:`Dune Package Management </explanation/package-management>` is not
+   final yet and the configuration options are subject to change.
+
+This stanza is used to define additional package sources to use when locking a
+project and used for building dependencies.
+
+.. note::
+
+   Defining a pin does not enable it by default. It needs to be enabled in a
+   lock directory using the :doc:`/reference/dune-workspace/lock_dir` stanza.
+
+.. describe:: (pin ...)
+
+   .. versionadded:: 3.15
+
+   Defines a new package source.
+
+   .. describe:: (name <string>)
+
+      The name of the newly defined pin. This can be anything, it does not
+      have to match the package.
+
+      This must be specified.
+
+   .. describe:: (url <string>)
+
+      This can be a path to a directory on the local file system or remote Git
+      repository. Local paths can be absolute or relative, and may optionally
+      begin with ``file://`` though this is not necessary. Remote Git
+      repository URLs must begin with ``git+``, for example
+      ``git+https://github.com/user/repo`` or
+      ``git+git@github.com:user/repo.git``.
+
+      This must be specified.
+
+   .. describe:: (package ...)
+
+      Specifies the the packages to assign this pin to.
+
+      .. describe:: (name <string>)
+
+         The name of the package.
+
+         This must be specified.
+
+      .. describe:: (version <string>)
+
+         The version that the package should be assumed to be. Defaults to
+         ``dev`` if unspecified.
+
+.. seealso:: :doc:`pin stanza in dune-project </reference/dune-project/pin>` for
+   per-project pins.

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

@@ -0,0 +1,11 @@
+profile
+-------
+
+The build profile can be selected in the ``dune-workspace`` file by write a
+``(profile ...)`` stanza. For instance:
+
+.. code:: dune
+
+    (profile release)
+
+Note that the command line option ``--profile`` has precedence over this stanza.

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

@@ -0,0 +1,38 @@
+repository
+==========
+
+.. warning::
+
+   :doc:`Dune Package Management </explanation/package-management>` is not
+   final yet and the configuration options are subject to change.
+
+This stanza defines a new named package repository and attaches a source
+location to it.
+
+.. note::
+
+   Defining a repository does not enable it in project by default. It needs to be
+   enabled in a lock directory using the :doc:`/reference/dune-workspace/lock_dir`
+   stanza.
+
+.. describe:: (repository ...)
+
+   .. versionadded:: 3.12
+
+   Defines a named package repository.
+
+   .. describe:: (name <string>)
+
+      The name used to refer to the repository. Names have to be unique.
+
+      This must be specified.
+
+   .. describe:: (url <string>)
+
+      The location from which the repository will be loaded.
+
+      Both HTTP and Git locations can be specified, the latter allowing for
+      extensive control of the version by specifying an exact revision, tag or
+      branch.
+
+      This must be specified.