Expose to Skylark a merge() method for runfiles objects

This is a quick way to make it possible for Skylark rules to aggregate
and pass on symlinks from their dependencies.

--
PiperOrigin-RevId: 143111353
MOS_MIGRATED_REVID=143111353
diff --git a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java
index 80d6757..25fc4ca 100644
--- a/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java
+++ b/src/main/java/com/google/devtools/build/lib/analysis/Runfiles.java
@@ -784,7 +784,18 @@
      *     created.
      */
     public Builder(String workspace, boolean legacyExternalRunfiles) {
-      this.suffix = new PathFragment(workspace);
+      this(new PathFragment(workspace), legacyExternalRunfiles);
+    }
+
+    /**
+     * Creates a builder with the given suffix.
+     * @param suffix is the PathFragment wrapping the string specified in workspace() in the
+     *     WORKSPACE file.
+     * @param legacyExternalRunfiles if the wsname/external/repo symlinks should also be
+     *     created.
+     */
+    private Builder(PathFragment suffix, boolean legacyExternalRunfiles) {
+      this.suffix = suffix;
       this.legacyExternalRunfiles = legacyExternalRunfiles;
     }
 
@@ -1106,4 +1117,19 @@
       }
     }
   }
+
+  /**
+   * Provides a Skylark-visible way to merge two Runfiles objects. 
+   */
+  @SkylarkCallable(
+    name = "merge",
+    doc = "Returns a new runfiles object that includes all the contents of this one and the "
+        + "argument."
+  )
+  public Runfiles merge(Runfiles other) {
+    Runfiles.Builder builder = new Runfiles.Builder(suffix, false);
+    builder.merge(this);
+    builder.merge(other);
+    return builder.build();
+  }
 }