Prevent public usage of exec.bzl and exec_aspect.bzl (2/2)

Do this by moving the bzl files to an impl folder,
then adding wrapping macros with a deprecation
message. This is so that valid users like
hermetic_exec don't get the deprecation warning.

For better git history, this is done in two separate
changes.

Test: TH
Bug: 329305827
Change-Id: I57004ffe473f4ec17628a4a1da10071bccd1443a

9 files changed, 290 insertions, 8 deletions

diff --git a/dist/dist.bzl b/dist/dist.bzl
index 3d3ac66..154d09b 100644
--- a/dist/dist.bzl
+++ b/dist/dist.bzl
@@ -1,8 +1,9 @@
-# Rule to support Bazel in copying its output files to the dist dir outside of
-# the standard Bazel output user root.
+"""Rule to support Bazel in copying its output files to the dist dir outside of
+the standard Bazel output user root.
+"""
 
 load("@bazel_skylib//rules:copy_file.bzl", "copy_file")
-load("//build/bazel_common_rules/exec:embedded_exec.bzl", "embedded_exec")
+load("//build/bazel_common_rules/exec/impl:embedded_exec.bzl", "embedded_exec")
 
 def _label_list_to_manifest(lst):
     """Convert the outputs of a label list to manifest content."""
@@ -140,7 +141,7 @@ def copy_to_dist_dir(
           on reverse dependencies.
 
           See `dist.py` for allowed values and the default value.
-        kwargs: Additional attributes to the internal rule, e.g.
+        **kwargs: Additional attributes to the internal rule, e.g.
           [`visibility`](https://docs.bazel.build/versions/main/visibility.html).
 
           These additional attributes are only passed to the underlying embedded_exec rule.
diff --git a/exec/BUILD b/exec/BUILD
new file mode 100644
index 0000000..bb4a111
--- /dev/null
+++ b/exec/BUILD
@@ -0,0 +1,46 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# 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.
+
+load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+
+bzl_library(
+    name = "exec_aspect",
+    srcs = ["exec_aspect.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        "//build/bazel_common_rules/exec/impl:exec_aspect",
+    ],
+)
+
+bzl_library(
+    name = "embedded_exec",
+    srcs = ["embedded_exec.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":exec_aspect",
+        "//build/bazel_common_rules/exec/impl:embedded_exec",
+        "@bazel_skylib//lib:shell",
+    ],
+)
+
+bzl_library(
+    name = "exec",
+    srcs = ["exec.bzl"],
+    visibility = ["//visibility:public"],
+    deps = [
+        ":exec_aspect",
+        "//build/bazel_common_rules/exec/impl:exec",
+        "@bazel_skylib//lib:shell",
+    ],
+)
diff --git a/exec/embedded_exec.bzl b/exec/embedded_exec.bzl
new file mode 100644
index 0000000..e54f74d
--- /dev/null
+++ b/exec/embedded_exec.bzl
@@ -0,0 +1,24 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# 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.
+
+"""Helps embedding `args` of an executable target."""
+
+load(
+    "//build/bazel_common_rules/exec/impl:embedded_exec.bzl",
+    _embedded_exec = "embedded_exec",
+)
+
+visibility("public")
+
+embedded_exec = _embedded_exec
diff --git a/exec/exec.bzl b/exec/exec.bzl
new file mode 100644
index 0000000..f64cbdc
--- /dev/null
+++ b/exec/exec.bzl
@@ -0,0 +1,164 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# 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.
+
+"""Helps embedding `args` of an executable target."""
+
+load(
+    "//build/bazel_common_rules/exec/impl:exec.bzl",
+    _exec = "exec",
+    _exec_rule = "exec_rule",
+    _exec_test = "exec_test",
+)
+
+visibility("public")
+
+def exec(
+        name,
+        data = None,
+        hashbang = None,
+        script = None,
+        **kwargs):
+    """Runs a script when `bazel run` this target.
+
+    See [documentation] for the `args` attribute.
+
+    **NOTE**: Like [genrule](https://bazel.build/reference/be/general#genrule)s,
+    hermeticity is not enforced or guaranteed, especially if `script` accesses PATH.
+    See [`Genrule Environment`](https://bazel.build/reference/be/general#genrule-environment)
+    for details.
+
+    Args:
+        name: name of the target
+        data: A list of labels providing runfiles. Labels may be used in `script`.
+
+            Executables in `data` must not have the `args` and `env` attribute. Use
+            [`embedded_exec`](#embedded_exec) to wrap the depended target so its env and args
+            are preserved.
+        hashbang: hashbang of the script, default is `"/bin/bash -e"`.
+        script: The script.
+
+            Use `$(rootpath <label>)` to refer to the path of a target specified in `data`. See
+            [documentation](https://bazel.build/reference/be/make-variables#predefined_label_variables).
+
+            Use `$@` to refer to the args attribute of this target.
+
+            See `build/bazel_common_rules/exec/tests/BUILD` for examples.
+        **kwargs: Additional attributes to the internal rule, e.g.
+            [`visibility`](https://docs.bazel.build/versions/main/visibility.html).
+            See complete list
+            [here](https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes).
+
+    Deprecated:
+        Use `hermetic_exec` for stronger hermeticity.
+    """
+
+    # buildifier: disable=print
+    print("WARNING: {}: exec is deprecated. Use `hermetic_exec` instead.".format(
+        native.package_relative_label(name),
+    ))
+
+    kwargs.setdefault("deprecation", "Use hermetic_exec for stronger hermeticity")
+
+    _exec(
+        name = name,
+        data = data,
+        hashbang = hashbang,
+        script = script,
+        **kwargs
+    )
+
+def exec_test(
+        name,
+        data = None,
+        hashbang = None,
+        script = None,
+        **kwargs):
+    """Runs a script when `bazel test` this target.
+
+    See [documentation] for the `args` attribute.
+
+    **NOTE**: Like [genrule](https://bazel.build/reference/be/general#genrule)s,
+    hermeticity is not enforced or guaranteed, especially if `script` accesses PATH.
+    See [`Genrule Environment`](https://bazel.build/reference/be/general#genrule-environment)
+    for details.
+
+    Args:
+        name: name of the target
+        data: A list of labels providing runfiles. Labels may be used in `script`.
+
+            Executables in `data` must not have the `args` and `env` attribute. Use
+            [`embedded_exec`](#embedded_exec) to wrap the depended target so its env and args
+            are preserved.
+        hashbang: hashbang of the script, default is `"/bin/bash -e"`.
+        script: The script.
+
+            Use `$(rootpath <label>)` to refer to the path of a target specified in `data`. See
+            [documentation](https://bazel.build/reference/be/make-variables#predefined_label_variables).
+
+            Use `$@` to refer to the args attribute of this target.
+
+            See `build/bazel_common_rules/exec/tests/BUILD` for examples.
+        **kwargs: Additional attributes to the internal rule, e.g.
+            [`visibility`](https://docs.bazel.build/versions/main/visibility.html).
+            See complete list
+            [here](https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes).
+
+    Deprecated:
+        Use `hermetic_exec` for stronger hermeticity.
+    """
+
+    # buildifier: disable=print
+    print("WARNING: {}: exec_test is deprecated. Use `hermetic_exec_test` instead.".format(
+        native.package_relative_label(name),
+    ))
+
+    kwargs.setdefault("deprecation", "Use hermetic_exec_test for stronger hermeticity")
+
+    _exec_test(
+        name = name,
+        data = data,
+        hashbang = hashbang,
+        script = script,
+        **kwargs
+    )
+
+# buildifier: disable=unnamed-macro
+def exec_rule(
+        cfg = None,
+        attrs = None):
+    """Returns a rule() that is similar to `exec`, but with the given incoming transition.
+
+    **NOTE**: Like [genrule](https://bazel.build/reference/be/general#genrule)s,
+    hermeticity is not enforced or guaranteed for targets of the returned
+    rule, especially if a target specifies `script` that accesses PATH.
+    See [`Genrule Environment`](https://bazel.build/reference/be/general#genrule-environment)
+    for details.
+
+    Args:
+        cfg: [Incoming edge transition](https://bazel.build/extending/config#incoming-edge-transitions)
+            on the rule
+        attrs: Additional attributes to be added to the rule.
+
+            Specify `_allowlist_function_transition` if you need a transition.
+    Returns:
+        a rule
+    """
+
+    # buildifier: disable=print
+    print("WARNING: exec_rule is deprecated.")
+
+    _exec_rule(
+        cfg = cfg,
+        attrs = attrs,
+    )
diff --git a/exec/exec_aspect.bzl b/exec/exec_aspect.bzl
new file mode 100644
index 0000000..6e7aa1f
--- /dev/null
+++ b/exec/exec_aspect.bzl
@@ -0,0 +1,30 @@
+# Copyright (C) 2024 The Android Open Source Project
+#
+# 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.
+
+"""Helps embedding `args` of an executable target.
+
+**DEPRECTED**. This is an implementation detail and should not be relied upon.
+"""
+
+load(
+    "//build/bazel_common_rules/exec/impl:exec_aspect.bzl",
+    _ExecAspectInfo = "ExecAspectInfo",
+    _exec_aspect = "exec_aspect",
+)
+
+# TODO(b/329305827): make this private
+visibility("public")
+
+ExecAspectInfo = _ExecAspectInfo
+exec_aspect = _exec_aspect
diff --git a/exec/impl/embedded_exec.bzl b/exec/impl/embedded_exec.bzl
index 482902e..2ff33d9 100644
--- a/exec/impl/embedded_exec.bzl
+++ b/exec/impl/embedded_exec.bzl
@@ -12,9 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Impl of `embedded_exec`."""
+
 load("@bazel_skylib//lib:shell.bzl", "shell")
 load(":exec_aspect.bzl", "ExecAspectInfo", "exec_aspect")
 
+visibility([
+    "//build/bazel_common_rules/exec/...",
+    "//build/bazel_common_rules/dist/...",
+])
+
 def _impl(ctx):
     target = ctx.attr.actual
     files_to_run = target[DefaultInfo].files_to_run
diff --git a/exec/impl/exec.bzl b/exec/impl/exec.bzl
index 91e6385..b78728b 100644
--- a/exec/impl/exec.bzl
+++ b/exec/impl/exec.bzl
@@ -12,9 +12,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-load("@bazel_skylib//lib:shell.bzl", "shell")
+"""Impl of `exec`."""
+
 load(":exec_aspect.bzl", "ExecAspectInfo", "exec_aspect")
 
+visibility([
+    "//build/bazel_common_rules/exec/...",
+    "//build/kernel/kleaf/...",
+])
+
 _DEFAULT_HASHBANG = "/bin/bash -e"
 
 def _impl(ctx):
diff --git a/exec/impl/exec_aspect.bzl b/exec/impl/exec_aspect.bzl
index 900e10c..cd0c101 100644
--- a/exec/impl/exec_aspect.bzl
+++ b/exec/impl/exec_aspect.bzl
@@ -12,6 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Impl of `exec_aspect`."""
+
+visibility("//build/bazel_common_rules/exec/...")
+
 _attrs = ["args", "env", "data", "srcs", "deps"]
 
 ExecAspectInfo = provider(
@@ -19,7 +23,7 @@ ExecAspectInfo = provider(
     fields = {attr: attr + " of the target" for attr in _attrs},
 )
 
-def _aspect_impl(target, ctx):
+def _aspect_impl(_target, ctx):
     kwargs = {}
     for attr in _attrs:
         value = getattr(ctx.rule.attr, attr, None)
diff --git a/exec/tests/BUILD b/exec/tests/BUILD
index 299fe45..0a89a40 100644
--- a/exec/tests/BUILD
+++ b/exec/tests/BUILD
@@ -13,8 +13,8 @@
 # limitations under the License.
 
 # BUILD
-load("//build/bazel_common_rules/exec:embedded_exec.bzl", "embedded_exec")
-load("//build/bazel_common_rules/exec:exec.bzl", "exec")
+load("//build/bazel_common_rules/exec/impl:embedded_exec.bzl", "embedded_exec")
+load("//build/bazel_common_rules/exec/impl:exec.bzl", "exec")
 
 exec(
     name = "script_a",