unikernel/duniverse/dune_/doc/explanation/scopes.rst

@@ -0,0 +1,43 @@
+Dune Projects and Workspaces
+============================
+
+Whenever Dune builds anything, it does so at the level of a *Dune workspace*. A
+Dune workspace is a set of Dune projects. A typical workspace consists of a
+single Dune project.
+
+A *Dune project* is defined by the presence of a
+:doc:`/reference/dune-project/index` file. Each Dune project extends over the
+file tree rooted at the directory containing the
+:doc:`/reference/dune-project/index` file, excluding any nested Dune projects.
+
+Dune determines the root of the current workspace by finding the topmost
+ancestor containing a :doc:`/reference/dune-project/index` file or by the
+presence of a :doc:`/reference/dune-workspace/index` file (see
+:ref:`finding-root` and :ref:`forcing-root` for details).
+
+Different Dune projects within the same Dune workspace are independent of each
+other and no settings are shared between them, even if they are nested within
+each other.
+
+Settings in :doc:`/reference/dune-workspace/index`, on the other hand, are
+inherited by all Dune projects in the workspace. Some settings (those that make
+sense for all projects) can be specified both in
+:doc:`/reference/dune-project/index` and :doc:`/reference/dune-workspace/index`
+files, with the former taking precedence. Note that all
+:doc:`/reference/dune-workspace/index` files other than the one specifying the
+root of the workspace are ignored.
+
+Within a Dune project, :doc:`/reference/dune/index` files are used to define all
+objects of interest for Dune: libraries, executables, tests, etc. There are
+typically many :doc:`/reference/dune/index` files in a Dune project: one per
+directory, unless the directory does not contain anything relevant to Dune. In
+each :doc:`/reference/dune/index` file, references are resolved relative to the
+directory containing the file.
+
+Note that there are specific stanzas and actions that may result in exceptions
+to some of the rules stated in the previous paragraph. See, for example, the
+:doc:`/reference/dune/subdir` and :doc:`/reference/dune/include_subdirs`
+stanzas, as well as the :doc:`/reference/actions/chdir` action.
+
+Finally, note that only public items (public libraries, public executables) of a
+Dune project are visible to other Dune projects within the same Dune workspace.