feat: add directory_path rule and DirectoryPathInfo for specifying fi…

…les within tree artifacts (#42)

docs/BUILD.bazel

@@ -3,7 +3,7 @@
 load("//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
 
 stardoc_with_diff_test(
-    bzl_library_target = "//lib/private:copy_to_directory",
+    bzl_library_target = "//lib:copy_to_directory",
     out_label = "//docs:copy_to_directory.md",
 )
 
@@ -43,6 +43,11 @@ stardoc_with_diff_test(
     out_label = "//docs:write_source_files.md",
 )
 
+stardoc_with_diff_test(
+    bzl_library_target = "//lib:directory_path",
+    out_label = "//docs:directory_path.md",
+)
+
 update_docs(
     name = "update",
     docs_folder = "docs",

docs/copy_to_directory.md

@@ -7,8 +7,8 @@ Copy files and directories to an output directory
 ## copy_to_directory
 
 <pre>
-copy_to_directory(<a href="#copy_to_directory-name">name</a>, <a href="#copy_to_directory-exclude_prefixes">exclude_prefixes</a>, <a href="#copy_to_directory-include_external_repositories">include_external_repositories</a>, <a href="#copy_to_directory-is_windows">is_windows</a>,
-                  <a href="#copy_to_directory-replace_prefixes">replace_prefixes</a>, <a href="#copy_to_directory-root_paths">root_paths</a>, <a href="#copy_to_directory-srcs">srcs</a>)
+copy_to_directory(<a href="#copy_to_directory-name">name</a>, <a href="#copy_to_directory-srcs">srcs</a>, <a href="#copy_to_directory-root_paths">root_paths</a>, <a href="#copy_to_directory-include_external_repositories">include_external_repositories</a>, <a href="#copy_to_directory-exclude_prefixes">exclude_prefixes</a>,
+                  <a href="#copy_to_directory-replace_prefixes">replace_prefixes</a>, <a href="#copy_to_directory-kwargs">kwargs</a>)
 </pre>
 
 Copies files and directories to an output directory.
@@ -17,35 +17,17 @@ Files and directories can be arranged as needed in the output directory using
 the `root_paths`, `exclude_prefixes` and `replace_prefixes` attributes.
 
 
-**ATTRIBUTES**
-
-
-| Name  | Description | Type | Mandatory | Default |
-| :------------- | :------------- | :------------- | :------------- | :------------- |
-| <a id="copy_to_directory-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
-| <a id="copy_to_directory-exclude_prefixes"></a>exclude_prefixes |  List of path prefixes to exclude from output directory.<br><br>If the output directory path for a file or directory starts with or is equal to a path in the list then that file is not copied to the output directory.<br><br>Exclude prefixes are matched *before* replace_prefixes are applied.   | List of strings | optional | [] |
-| <a id="copy_to_directory-include_external_repositories"></a>include_external_repositories |  List of external repository names to include in the output directory.<br><br>Files from external repositories are not copied into the output directory unless the external repository they come from is listed here.<br><br>When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is _not_ included in that path.<br><br>For example, the following copies <code>@external_repo//path/to:file</code> to <code>path/to/file</code> within the output directory.<br><br><pre><code> copy_to_directory(     name = "dir",     include_external_repositories = ["external_repo"],     srcs = ["@external_repo//path/to:file"], ) </code></pre><br><br>Files from external repositories are subject to <code>root_paths</code>, <code>exclude_prefixes</code> and <code>replace_prefixes</code> in the same way as files form the main repository.   | List of strings | optional | [] |
-| <a id="copy_to_directory-is_windows"></a>is_windows |  -   | Boolean | required |  |
-| <a id="copy_to_directory-replace_prefixes"></a>replace_prefixes |  Map of paths prefixes to replace in the output directory path when copying files.<br><br>If the output directory path for a file or directory starts with or is equal to a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key.<br><br>Forward slashes (<code>/</code>) should be used as path separators. The final path segment of the key can be a partial match in the corresponding segment of the output directory path.<br><br>If there are multiple keys that match, the longest match wins.   | <a href="https://bazel.build/docs/skylark/lib/dict.html">Dictionary: String -> String</a> | optional | {} |
-| <a id="copy_to_directory-root_paths"></a>root_paths |  List of paths that are roots in the output directory. If a file or directory being copied is in one of the listed paths or one of its subpaths, the output directory path is the path relative to the root path instead of the path relative to the file's workspace.<br><br>Forward slashes (<code>/</code>) should be used as path separators. Partial matches on the final path segment of a root path against the corresponding segment in the full workspace relative path of a file are not matched.<br><br>If there are multiple root paths that match, the longest match wins.<br><br>Defaults to [package_name()] so that the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths.   | List of strings | optional | [] |
-| <a id="copy_to_directory-srcs"></a>srcs |  Files and/or directories to copy into the output directory   | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
-
-
-<a id="#copy_to_directory_lib.impl"></a>
-
-## copy_to_directory_lib.impl
-
-<pre>
-copy_to_directory_lib.impl(<a href="#copy_to_directory_lib.impl-ctx">ctx</a>)
-</pre>
-
-
-
 **PARAMETERS**
 
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="copy_to_directory_lib.impl-ctx"></a>ctx |  <p align="center"> - </p>   |  none |
+| <a id="copy_to_directory-name"></a>name |  A unique name for this target.   |  none |
+| <a id="copy_to_directory-srcs"></a>srcs |  Files and/or directories or targets that provide DirectoryPathInfo to copy into the output directory.   |  <code>[]</code> |
+| <a id="copy_to_directory-root_paths"></a>root_paths |  List of paths that are roots in the output directory.<br><br>If a file or directory being copied is in one of the listed paths or one of its subpaths, the output directory path is the path relative to the root path instead of the path relative to the file's workspace.<br><br>Forward slashes (<code>/</code>) should be used as path separators. Partial matches on the final path segment of a root path against the corresponding segment in the full workspace relative path of a file are not matched.<br><br>If there are multiple root paths that match, the longest match wins.<br><br>Defaults to [package_name()] so that the output directory path of files in the target's package and and sub-packages are relative to the target's package and files outside of that retain their full workspace relative paths.   |  <code>None</code> |
+| <a id="copy_to_directory-include_external_repositories"></a>include_external_repositories |  List of external repository names to include in the output directory.<br><br>Files from external repositories are not copied into the output directory unless the external repository they come from is listed here.<br><br>When copied from an external repository, the file path in the output directory defaults to the file's path within the external repository. The external repository name is _not_ included in that path.<br><br>For example, the following copies <code>@external_repo//path/to:file</code> to <code>path/to/file</code> within the output directory.<br><br><pre><code> copy_to_directory(     name = "dir",     include_external_repositories = ["external_repo"],     srcs = ["@external_repo//path/to:file"], ) </code></pre><br><br>Files from external repositories are subject to <code>root_paths</code>, <code>exclude_prefixes</code> and <code>replace_prefixes</code> in the same way as files form the main repository.   |  <code>[]</code> |
+| <a id="copy_to_directory-exclude_prefixes"></a>exclude_prefixes |  List of path prefixes to exclude from output directory.<br><br>If the output directory path for a file or directory starts with or is equal to a path in the list then that file is not copied to the output directory.<br><br>Exclude prefixes are matched *before* replace_prefixes are applied.   |  <code>[]</code> |
+| <a id="copy_to_directory-replace_prefixes"></a>replace_prefixes |  Map of paths prefixes to replace in the output directory path when copying files.<br><br>If the output directory path for a file or directory starts with or is equal to a key in the dict then the matching portion of the output directory path is replaced with the dict value for that key.<br><br>Forward slashes (<code>/</code>) should be used as path separators. The final path segment of the key can be a partial match in the corresponding segment of the output directory path.<br><br>If there are multiple keys that match, the longest match wins.   |  <code>{}</code> |
+| <a id="copy_to_directory-kwargs"></a>kwargs |  Other common named parameters such as <code>tags</code> or <code>visibility</code>   |  none |
 
 

docs/directory_path.md

@@ -0,0 +1,136 @@
+<!-- Generated with Stardoc: http://skydoc.bazel.build -->
+
+Rule and corresponding provider that joins a label pointing to a TreeArtifact
+with a path nested within that directory
+
+
+<a id="#directory_path"></a>
+
+## directory_path
+
+<pre>
+directory_path(<a href="#directory_path-name">name</a>, <a href="#directory_path-directory">directory</a>, <a href="#directory_path-path">path</a>)
+</pre>
+
+Provide DirectoryPathInfo to reference some path within a directory.
+
+Otherwise there is no way to give a Bazel label for it.
+
+**ATTRIBUTES**
+
+
+| Name  | Description | Type | Mandatory | Default |
+| :------------- | :------------- | :------------- | :------------- | :------------- |
+| <a id="directory_path-name"></a>name |  A unique name for this target.   | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required |  |
+| <a id="directory_path-directory"></a>directory |  a TreeArtifact (ctx.actions.declare_directory)   | <a href="https://bazel.build/docs/build-ref.html#labels">Label</a> | required |  |
+| <a id="directory_path-path"></a>path |  path relative to the directory   | String | required |  |
+
+
+<a id="#DirectoryPathInfo"></a>
+
+## DirectoryPathInfo
+
+<pre>
+DirectoryPathInfo(<a href="#DirectoryPathInfo-directory">directory</a>, <a href="#DirectoryPathInfo-path">path</a>)
+</pre>
+
+Joins a label pointing to a TreeArtifact with a path nested within that directory.
+
+**FIELDS**
+
+
+| Name  | Description |
+| :------------- | :------------- |
+| <a id="DirectoryPathInfo-directory"></a>directory |  a TreeArtifact (ctx.actions.declare_directory)    |
+| <a id="DirectoryPathInfo-path"></a>path |  path relative to the directory    |
+
+
+<a id="#make_directory_path"></a>
+
+## make_directory_path
+
+<pre>
+make_directory_path(<a href="#make_directory_path-name">name</a>, <a href="#make_directory_path-directory">directory</a>, <a href="#make_directory_path-path">path</a>)
+</pre>
+
+Helper function to convert generate a directory_path target and return its label.
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="make_directory_path-name"></a>name |  Unique name for the generated <code>directory_path</code> target.   |  none |
+| <a id="make_directory_path-directory"></a>directory |  a TreeArtifact (ctx.actions.declare_directory)   |  none |
+| <a id="make_directory_path-path"></a>path |  path relative to the directory   |  none |
+
+**RETURNS**
+
+The label `name`
+
+
+<a id="#make_directory_paths"></a>
+
+## make_directory_paths
+
+<pre>
+make_directory_paths(<a href="#make_directory_paths-name">name</a>, <a href="#make_directory_paths-dict">dict</a>)
+</pre>
+
+Helper function to convert a dict of directory to path mappings to directory_path targets and labels.
+
+For example,
+
+```
+make_directory_paths("my_name", {
+    "//directory/artifact:target_1": "file/path",
+    "//directory/artifact:target_2": ["file/path1", "file/path2"],
+})
+```
+
+generates the targets,
+
+```
+directory_path(
+    name = "my_name_0",
+    directory = "//directory/artifact:target_1",
+    path = "file/path"
+)
+
+directory_path(
+    name = "my_name_1",
+    directory = "//directory/artifact:target_2",
+    path = "file/path1"
+)
+
+directory_path(
+    name = "my_name_2",
+    directory = "//directory/artifact:target_2",
+    path = "file/path2"
+)
+```
+
+and the list of targets is returned,
+
+```
+[
+    "my_name_0",
+    "my_name_1",
+    "my_name_2",
+]
+```
+
+
+**PARAMETERS**
+
+
+| Name  | Description | Default Value |
+| :------------- | :------------- | :------------- |
+| <a id="make_directory_paths-name"></a>name |  The target name to use for the generated targets & labels.<br><br>The names are generated as zero-indexed <code>name + "_" + i</code>   |  none |
+| <a id="make_directory_paths-dict"></a>dict |  The dictionary of directory keys to path or path list values.   |  none |
+
+**RETURNS**
+
+The label of the generated `directory_path` targets named `name + "_" + i`
+
+

lib/BUILD.bazel

@@ -56,6 +56,20 @@ bzl_library(
     deps = ["//lib/private:jq"],
 )
 
+bzl_library(
+    name = "directory_path",
+    srcs = ["directory_path.bzl"],
+    visibility = ["//visibility:public"],
+    deps = ["//lib/private:directory_path"],
+)
+
+bzl_library(
+    name = "copy_to_directory",
+    srcs = ["copy_to_directory.bzl"],
+    visibility = ["//visibility:public"],
+    deps = ["//lib/private:copy_to_directory"],
+)
+
 toolchain_type(
     name = "jq_toolchain_type",
     visibility = ["//visibility:public"],

lib/copy_to_directory.bzl

@@ -1,4 +1,4 @@
-"Public API for copy_to_directory"
+"Copy files and directories to an output directory"
 
 load(
     "//lib/private:copy_to_directory.bzl",
@@ -11,12 +11,95 @@ _copy_to_directory = rule(
     attrs = lib.attrs,
 )
 
-def copy_to_directory(name, root_paths = None, **kwargs):
+def copy_to_directory(
+        name,
+        srcs = [],
+        root_paths = None,
+        include_external_repositories = [],
+        exclude_prefixes = [],
+        replace_prefixes = {},
+        **kwargs):
+    """Copies files and directories to an output directory.
+
+    Files and directories can be arranged as needed in the output directory using
+    the `root_paths`, `exclude_prefixes` and `replace_prefixes` attributes.
+
+    Args:
+        name: A unique name for this target.
+
+        srcs: Files and/or directories or targets that provide DirectoryPathInfo to copy into the output directory.
+
+        root_paths: List of paths that are roots in the output directory.
+
+            If a file or directory being copied is in one of the listed paths or one of its subpaths,
+            the output directory path is the path relative to the root path instead of the path
+            relative to the file's workspace.
+
+            Forward slashes (`/`) should be used as path separators. Partial matches
+            on the final path segment of a root path against the corresponding segment
+            in the full workspace relative path of a file are not matched.
+
+            If there are multiple root paths that match, the longest match wins.
+
+            Defaults to [package_name()] so that the output directory path of files in the
+            target's package and and sub-packages are relative to the target's package and
+            files outside of that retain their full workspace relative paths.
+
+        include_external_repositories: List of external repository names to include in the output directory.
+
+            Files from external repositories are not copied into the output directory unless
+            the external repository they come from is listed here.
+
+            When copied from an external repository, the file path in the output directory
+            defaults to the file's path within the external repository. The external repository
+            name is _not_ included in that path.
+
+            For example, the following copies `@external_repo//path/to:file` to
+            `path/to/file` within the output directory.
+
+            ```
+            copy_to_directory(
+                name = "dir",
+                include_external_repositories = ["external_repo"],
+                srcs = ["@external_repo//path/to:file"],
+            )
+            ```
+
+            Files from external repositories are subject to `root_paths`, `exclude_prefixes`
+            and `replace_prefixes` in the same way as files form the main repository.
+
+        exclude_prefixes: List of path prefixes to exclude from output directory.
+
+            If the output directory path for a file or directory starts with or is equal to
+            a path in the list then that file is not copied to the output directory.
+
+            Exclude prefixes are matched *before* replace_prefixes are applied.
+
+        replace_prefixes: Map of paths prefixes to replace in the output directory path when copying files.
+
+            If the output directory path for a file or directory starts with or is equal to
+            a key in the dict then the matching portion of the output directory path is
+            replaced with the dict value for that key.
+
+            Forward slashes (`/`) should be used as path separators. The final path segment
+            of the key can be a partial match in the corresponding segment of the output
+            directory path.
+
+            If there are multiple keys that match, the longest match wins.
+
+        **kwargs: Other common named parameters such as `tags` or `visibility`
+    """
+
     if root_paths == None:
         root_paths = [native.package_name()]
+
     _copy_to_directory(
         name = name,
+        srcs = srcs,
         root_paths = root_paths,
+        include_external_repositories = include_external_repositories,
+        exclude_prefixes = exclude_prefixes,
+        replace_prefixes = replace_prefixes,
         is_windows = select({
             "@bazel_tools//src/conditions:host_windows": True,
             "//conditions:default": False,

lib/directory_path.bzl

@@ -0,0 +1,30 @@
+# Copyright 2019 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Rule and corresponding provider that joins a label pointing to a TreeArtifact
+with a path nested within that directory
+"""
+
+load(
+    "//lib/private:directory_path.bzl",
+    _DirectoryPathInfo = "DirectoryPathInfo",
+    _directory_path = "directory_path",
+    _make_directory_path = "make_directory_path",
+    _make_directory_paths = "make_directory_paths",
+)
+
+directory_path = _directory_path
+make_directory_path = _make_directory_path
+make_directory_paths = _make_directory_paths
+DirectoryPathInfo = _DirectoryPathInfo

lib/private/BUILD.bazel

@@ -8,8 +8,9 @@ exports_files(
 bzl_library(
     name = "copy_to_directory",
     srcs = ["copy_to_directory.bzl"],
-    visibility = ["//docs:__pkg__"],
+    visibility = ["//lib:__subpackages__"],
     deps = [
+        ":directory_path",
         ":paths",
         "@bazel_skylib//lib:paths",
     ],
@@ -62,13 +63,18 @@ bzl_library(
     name = "write_source_files",
     srcs = ["write_source_files.bzl"],
     visibility = ["//lib:__subpackages__"],
-    deps = [
-        "//lib:utils",
-    ],
+    deps = ["//lib:utils"],
 )
 
 bzl_library(
     name = "fail_with_message_test",
     srcs = ["fail_with_message_test.bzl"],
     visibility = ["//lib:__subpackages__"],
 )
+
+bzl_library(
+    name = "directory_path",
+    srcs = ["directory_path.bzl"],
+    visibility = ["//lib:__subpackages__"],
+    deps = ["//lib:utils"],
+)