Documentation of built-in rules: document {disjoint_,}tree_overlay

1 files changed, 14 insertions, 0 deletions

diff --git a/doc/concepts/built-in-rules.md b/doc/concepts/built-in-rules.md
index e7a5e2e3..5c502668 100644
--- a/doc/concepts/built-in-rules.md
+++ b/doc/concepts/built-in-rules.md
@@ -148,6 +148,20 @@ of the `"tree"` target are a singleton map with the key the result of
 evaluating `"name"` (which has to evaluate to a single string) and value
 that tree.
 
+`"tree_overlay"` and `"disjoint_tree_overlay"`
+----------------------------------------------
+
+The rules `"tree_overlay"` and `"disjoint_tree_overlay"` allow to
+define a tree as the overlay of the trees given by the artifact
+stages of a list of given targets. More precisely, the field `"deps"`
+has to evaluate to a list of targets. For each target, a tree is
+formed from its artifact stage. A new tree is defined as the tree
+overlay, or disjoint tree overlay, of those trees. Both, artifacts
+and runfiles of the target are a singleton map with key the result
+of evaluating the field `"name"` which has to evaluate to a single
+string and value that (disjoint) tree overlay.
+
+
 `"symlink"`
 ------------