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 dune-project file. Each Dune project extends over the file tree rooted at the directory containing the dune-project file, excluding any nested Dune projects.

Dune determines the root of the current workspace by finding the topmost ancestor containing a dune-project file or by the presence of a dune-workspace file (see Finding the Root and Forcing the Root (for Scripts) 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 dune-workspace, 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 dune-project and dune-workspace files, with the former taking precedence. Note that all dune-workspace files other than the one specifying the root of the workspace are ignored.

Within a Dune project, dune files are used to define all objects of interest for Dune: libraries, executables, tests, etc. There are typically many dune files in a Dune project: one per directory, unless the directory does not contain anything relevant to Dune. In each dune 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 subdir and include_subdirs stanzas, as well as the 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.