Expose runfiles symlink functionality in Skylark

The Skylark rule context object has a runfiles method.  This adds two
optional parameters to that method, "symlinks" and "root_symlinks",
that expose functionality from the underlying Runfiles java class.
With this functionality, one can construct links in the runfiles tree
where the source and destination of the link have different names
and/or relative directories.  This might be useful for things like
AppEngine rules where a file in a subdirectory of the source tree
needs to appear in the root directory of the runfiles tree.

If either new parameter is used, the runfiles is subject to stricter
validity checking.  This checking propagates to other runfiles that
depend on it.

RELNOTES: Added "root_symlinks" and "symlinks" parameters to Skylark
runfiles() method.

--
MOS_MIGRATED_REVID=116879064

1 files changed, 32 insertions, 0 deletions

diff --git a/site/docs/skylark/rules.md b/site/docs/skylark/rules.md
index 8123a0a7e1..89caaf5df1 100644
--- a/site/docs/skylark/rules.md
+++ b/site/docs/skylark/rules.md
@@ -359,6 +359,38 @@ binary should know about them.
 Also note that if an action uses an executable, the executable's runfiles can
 be used when the action executes.
 
+Normally, the relative path of a file in the runfiles tree is the same as the
+relative path of that file in the source tree or generated output tree. If these
+need to be different for some reason, you can specify the `root_symlinks` or
+`symlinks` arguments.  The `root_symlinks` is a dictionary mapping paths to
+files, where the paths are relative to the root of the runfiles directory. The
+`symlinks` dictionary is the same, but paths are implicitly prefixed with the
+name of the workspace.
+
+```python
+    ...
+    runfiles = ctx.runfiles(
+        root_symlinks={"some/path/here.foo": ctx.file.some_data_file2}
+        symlinks={"some/path/here.bar": ctx.file.some_data_file3}
+    )
+    # Creates something like:
+    # sometarget.runfiles/
+    #     some/
+    #         path/
+    #             here.foo -> some_data_file2
+    #     <workspace_name>/
+    #         some/
+    #             path/
+    #                 here.bar -> some_data_file3
+```
+
+If `symlinks` or `root_symlinks` is used, be careful not to map two different
+files to the same path in the runfiles tree. This will cause the build to fail
+with an error describing the conflict. To fix, you will need to modify your
+`ctx.runfiles` arguments to remove the collision. This checking will be done for
+any targets using your rule, as well as targets of any kind that depend on those
+targets.
+
 ## Instrumented files
 
 Instrumented files are a set of files used by the coverage command. A rule can