Directory targets

A directory target corresponds to a file tree rooted at a specified root directory, for example, docs/*. Typical examples of rules producing directory targets are: unpacking an archive, running make in a vendored package, and building files with non-deterministic names (e.g. including the current date).

Declaring a directory target

To declare a directory target docs/*, use the syntax (target (dir docs)) in a rule stanza. The corresponding rule should create the directory docs and is free to populate it with an arbitrary number of files and/or subdirectories.

Like file targets, directory targets can be promoted to the source tree by adding (mode promote) to the rule stanza.

Depending on a directory target

There are two ways to depend on a directory target:

An opaque dependency on the whole file tree docs/*. Opaque dependencies are invalidated if the contents of the tree is changed in any way. To declare an opaque dependency on docs/*, use the syntax (dep (dir docs)) in a rule stanza.
A projection dependency on a specific file in the tree, e.g. docs/html/index.html. A projection dependency is declared using the standard syntax (dep docs/html/index.html) and works like a dependency on a normal file target. For example, if the docs/* directory is rebuilt and only docs/html/logo.png is modified, then the dependency on docs/html/index.html is considered to be up-to-date. Note that it is easy to make a mistake with such projection dependencies, for example, by forgetting that index.html actually does include the image docs/html/logo.png. In such cases, sandboxing will help since only the requested projection dependencies will be available in the sandbox (i.e., not the whole directory target).

Building a directory target

Users can request building whole directory targets or individual files via dune build docs and dune build docs/html/index.html commands.

Current limitations

It is not allowed to have two rules with the same directory target. That is, like file targets, directory targets are exclusive (but see shared directory targets below).
Directory targets cannot have nested file or directory targets, i.e. other rules are not allowed to declare targets within the file tree of a directory target.

Possible future extensions

Here are some possible extensions to consider:

Opaque directory targets: a rule may declare that its directory target is opaque, in which case projection dependencies on its content will be disallowed. One can also consider only partially opaque directory targets, where the contents of the directory is only partially visible.
Shared directory targets: we can allow multiple rules to write to the same directory target, as long as they do not write to the same files. In this case, depending on a directory target would mean depending on all of the rules that declare it as a target.

2.9 KiB Raw Blame History