doc: Extend documentation with 'symlink' built-in rule

2 files changed, 20 insertions, 0 deletions

diff --git a/doc/concepts/built-in-rules.md b/doc/concepts/built-in-rules.md
index 319d0d82..5591c174 100644
--- a/doc/concepts/built-in-rules.md
+++ b/doc/concepts/built-in-rules.md
@@ -140,6 +140,23 @@ 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.
 
+`"symlink"`
+------------
+
+The `"symlink"` rule allows to specify a non-upwards symbolic link with a
+given link target. To be able to accurately report about file names of
+artifacts or runfiles of other targets, they can be specified in the field
+`"deps"` which has to evaluate to a list of targets. The names of the
+artifacts and runfiles of a target specified in `"deps"` can be accessed
+through the functions `"outs"` and `"runfiles"`, respectively, during the
+evaluation of the arguments `"name"` and `"data"` which have to evaluate to
+a single string.
+
+Artifacts and runfiles of a `"symlink"` target are a singleton map with
+key the result of evaluating `"name"` and value a non-upwards symbolic link
+with target path the result of evaluating `"data"` (which must evaluate to
+a non-upwards path). The provides map is empty.
+
 `"configure"`
 -------------
 
diff --git a/doc/concepts/symlinks.md b/doc/concepts/symlinks.md
index 2d33e388..5a7114e4 100644
--- a/doc/concepts/symlinks.md
+++ b/doc/concepts/symlinks.md
@@ -118,6 +118,9 @@ permissions. As such, they locally use the existing file CAS. Remotely, the
 existing execution protocol already allows the handling of symbolic links via
 corresponding Protobuf messages, therefore no extensions are needed.
 
+Additionally, the built-in rules are extended with a `"symlink"` target,
+allowing the generation of a symlink with given non-upwards target path.
+
 ### Import resolved `git`-trees
 
 Finally, to be as flexible as possible in handling external repositories with