1# Copyright (C) 2024 The Android Open Source Project
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7#       http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15"""Helps embedding `args` of an executable target."""
16
17load(
18    "//build/bazel_common_rules/exec/impl:exec.bzl",
19    _exec = "exec",
20    _exec_rule = "exec_rule",
21    _exec_test = "exec_test",
22)
23
24visibility("public")
25
26def exec(
27        name,
28        data = None,
29        hashbang = None,
30        script = None,
31        **kwargs):
32    """Runs a script when `bazel run` this target.
33
34    See [documentation] for the `args` attribute.
35
36    **NOTE**: Like [genrule](https://bazel.build/reference/be/general#genrule)s,
37    hermeticity is not enforced or guaranteed, especially if `script` accesses PATH.
38    See [`Genrule Environment`](https://bazel.build/reference/be/general#genrule-environment)
39    for details.
40
41    Args:
42        name: name of the target
43        data: A list of labels providing runfiles. Labels may be used in `script`.
44
45            Executables in `data` must not have the `args` and `env` attribute. Use
46            [`embedded_exec`](#embedded_exec) to wrap the depended target so its env and args
47            are preserved.
48        hashbang: hashbang of the script, default is `"/bin/bash -e"`.
49        script: The script.
50
51            Use `$(rootpath <label>)` to refer to the path of a target specified in `data`. See
52            [documentation](https://bazel.build/reference/be/make-variables#predefined_label_variables).
53
54            Use `$@` to refer to the args attribute of this target.
55
56            See `build/bazel_common_rules/exec/tests/BUILD` for examples.
57        **kwargs: Additional attributes to the internal rule, e.g.
58            [`visibility`](https://docs.bazel.build/versions/main/visibility.html).
59            See complete list
60            [here](https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes).
61
62    Deprecated:
63        Use `hermetic_exec` for stronger hermeticity.
64    """
65
66    # buildifier: disable=print
67    print("WARNING: {}: exec is deprecated. Use `hermetic_exec` instead.".format(
68        native.package_relative_label(name),
69    ))
70
71    kwargs.setdefault("deprecation", "Use hermetic_exec for stronger hermeticity")
72
73    _exec(
74        name = name,
75        data = data,
76        hashbang = hashbang,
77        script = script,
78        **kwargs
79    )
80
81def exec_test(
82        name,
83        data = None,
84        hashbang = None,
85        script = None,
86        **kwargs):
87    """Runs a script when `bazel test` this target.
88
89    See [documentation] for the `args` attribute.
90
91    **NOTE**: Like [genrule](https://bazel.build/reference/be/general#genrule)s,
92    hermeticity is not enforced or guaranteed, especially if `script` accesses PATH.
93    See [`Genrule Environment`](https://bazel.build/reference/be/general#genrule-environment)
94    for details.
95
96    Args:
97        name: name of the target
98        data: A list of labels providing runfiles. Labels may be used in `script`.
99
100            Executables in `data` must not have the `args` and `env` attribute. Use
101            [`embedded_exec`](#embedded_exec) to wrap the depended target so its env and args
102            are preserved.
103        hashbang: hashbang of the script, default is `"/bin/bash -e"`.
104        script: The script.
105
106            Use `$(rootpath <label>)` to refer to the path of a target specified in `data`. See
107            [documentation](https://bazel.build/reference/be/make-variables#predefined_label_variables).
108
109            Use `$@` to refer to the args attribute of this target.
110
111            See `build/bazel_common_rules/exec/tests/BUILD` for examples.
112        **kwargs: Additional attributes to the internal rule, e.g.
113            [`visibility`](https://docs.bazel.build/versions/main/visibility.html).
114            See complete list
115            [here](https://docs.bazel.build/versions/main/be/common-definitions.html#common-attributes).
116
117    Deprecated:
118        Use `hermetic_exec` for stronger hermeticity.
119    """
120
121    # buildifier: disable=print
122    print("WARNING: {}: exec_test is deprecated. Use `hermetic_exec_test` instead.".format(
123        native.package_relative_label(name),
124    ))
125
126    kwargs.setdefault("deprecation", "Use hermetic_exec_test for stronger hermeticity")
127
128    _exec_test(
129        name = name,
130        data = data,
131        hashbang = hashbang,
132        script = script,
133        **kwargs
134    )
135
136# buildifier: disable=unnamed-macro
137def exec_rule(
138        cfg = None,
139        attrs = None):
140    """Returns a rule() that is similar to `exec`, but with the given incoming transition.
141
142    **NOTE**: Like [genrule](https://bazel.build/reference/be/general#genrule)s,
143    hermeticity is not enforced or guaranteed for targets of the returned
144    rule, especially if a target specifies `script` that accesses PATH.
145    See [`Genrule Environment`](https://bazel.build/reference/be/general#genrule-environment)
146    for details.
147
148    Args:
149        cfg: [Incoming edge transition](https://bazel.build/extending/config#incoming-edge-transitions)
150            on the rule
151        attrs: Additional attributes to be added to the rule.
152
153            Specify `_allowlist_function_transition` if you need a transition.
154    Returns:
155        a rule
156    """
157
158    # buildifier: disable=print
159    print("WARNING: exec_rule is deprecated.")
160
161    _exec_rule(
162        cfg = cfg,
163        attrs = attrs,
164    )
165