Provide documentation for the what the modules provides.

No long have to read the bzl files! \o/

RELNOTES: None.
PiperOrigin-RevId: 232701066

4 files changed, 505 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..dcd0dc0
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,42 @@
+# Apple Support Starlark Modules and Rules
+
+Apple Support provides a collection of Starlark helpers for rule authors
+targeting Apple Platforms (and Xcode) as well as some Rules directly.
+
+## Starlark Modules
+
+<table class="table table-condensed table-bordered table-params">
+  <thead>
+    <tr>
+      <th><code>.bzl</code> file</th>
+      <th>Module</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td valign="top"><code>@build_bazel_apple_support//lib:apple_support.bzl</code></td>
+      <td valign="top"><code><a href="apple_support.md">apple_support</a></code><br/></td>
+    </tr>
+    <tr>
+      <td valign="top"><code>@build_bazel_apple_support//lib:xcode_support.bzl</code></td>
+      <td valign="top"><code><a href="xcode_support.md">xcode_support</a></code><br/></td>
+    </tr>
+  </tbody>
+</table>
+
+## Rules
+
+<table class="table table-condensed table-bordered table-params">
+  <thead>
+    <tr>
+      <th><code>.bzl</code> file</th>
+      <th>Rules</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td valign="top"><code>@build_bazel_apple_support//rules:apple_genrule.bzl</code></td>
+      <td valign="top"><code><a href="rules.md#apple_genrule">apple_genrule</a></code><br/></td>
+    </tr>
+  </tbody>
+</table>
diff --git a/doc/apple_support.md b/doc/apple_support.md
new file mode 100644
index 0000000..0004fcc
--- /dev/null
+++ b/doc/apple_support.md
@@ -0,0 +1,292 @@
+# `apple_support` Starlark Module
+
+
+A module of helpers for rule authors to aid in writing actions that
+target Apple platforms.
+
+To use these in your Starlark code, simply load the module; for example:
+
+```build
+load("@build_bazel_apple_support//lib:apple_support.bzl", "apple_support")
+```
+
+On this page:
+
+  * [apple_support.action_required_attrs](#apple_support.action_required_attrs)
+  * [apple_support.action_required_env](#apple_support.action_required_env)
+  * [apple_support.action_required_execution_requirements](#apple_support.action_required_execution_requirements)
+  * [apple_support.path_placeholders.platform_frameworks](#apple_support.path_placeholders.platform_frameworks)
+  * [apple_support.path_placeholders.sdkroot](#apple_support.path_placeholders.sdkroot)
+  * [apple_support.path_placeholders.xcode](#apple_support.path_placeholders.xcode)
+  * [apple_support.run](#apple_support.run)
+  * [apple_support.run_shell](#apple_support.run_shell)
+
+
+<a name="apple_support.action_required_attrs"></a>
+## apple_support.action_required_attrs
+
+<pre style="white-space: pre-wrap">
+apple_support.action_required_attrs()
+</pre>
+
+Returns a dictionary with required attributes for registering actions on Apple platforms.
+
+This method adds private attributes which should not be used outside of the apple_support
+codebase. It also adds the following attributes which are considered to be public for rule
+maintainers to use:
+
+ * `_xcode_config`: Attribute that references a target containing the single
+   `apple_common.XcodeVersionConfig` provider. This provider can be used to inspect Xcode-related
+   properties about the Xcode being used for the build, as specified with the `--xcode_version`
+   Bazel flag. The most common way to retrieve this provider is:
+   `ctx.attr._xcode_config[apple_common.XcodeVersionConfig]`.
+
+The returned `dict` can be added to the rule's attributes using Skylib's `dicts.add()` method.
+
+<a name="apple_support.action_required_attrs.returns"></a>
+### Returns
+
+A `dict` object containing attributes to be added to rule implementations.
+
+<a name="apple_support.action_required_env"></a>
+## apple_support.action_required_env
+
+<pre style="white-space: pre-wrap">
+apple_support.action_required_env(<a href="#apple_support.action_required_env.ctx">ctx</a>)
+</pre>
+
+Returns a dictionary with the environment variables required for Xcode path resolution.
+
+In most cases, you should _not_ use this API. It exists solely for using it on test rules,
+where the test action registration API is not available in Starlark.
+
+To use these environment variables for a test, your test rule needs to propagate the
+`testing.TestEnvironment` provider, which takes a dictionary with environment variables to set
+during the test execution.
+
+<a name="apple_support.action_required_env.arguments"></a>
+### Arguments
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="apple_support.action_required_env.ctx">
+      <td><code>ctx</code></td>
+      <td><p><code>Required</code></p><p>The context of the rule registering the action.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<a name="apple_support.action_required_env.returns"></a>
+### Returns
+
+A dictionary with environment variables required for Xcode path resolution.
+
+<a name="apple_support.action_required_execution_requirements"></a>
+## apple_support.action_required_execution_requirements
+
+<pre style="white-space: pre-wrap">
+apple_support.action_required_execution_requirements()
+</pre>
+
+Returns a dictionary with the execution requirements for running actions on Apple platforms.
+
+In most cases, you should _not_ use this API. It exists solely for using it on test rules,
+where the test action registration API is not available in Starlark.
+
+To use these environment variables for a test, your test rule needs to propagate the
+`testing.TestExecution` provider, which takes a dictionary with execution requirements for the
+test action.
+
+<a name="apple_support.action_required_execution_requirements.returns"></a>
+### Returns
+
+A dictionary with execution requirements for running actions on Apple platforms.
+
+
+<a name="apple_support.path_placeholders.platform_frameworks"></a>
+## apple_support.path_placeholders.platform_frameworks
+
+<pre style="white-space: pre-wrap">
+apple_support.path_placeholders.platform_frameworks(<a href="#apple_support.path_placeholders.platform_frameworks.ctx">ctx</a>)
+</pre>
+
+Returns the platform's frameworks directory, anchored to the Xcode path placeholder.
+
+<a name="apple_support.path_placeholders.platform_frameworks.arguments"></a>
+### Arguments
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="apple_support.path_placeholders.platform_frameworks.ctx">
+      <td><code>ctx</code></td>
+      <td><p><code>Required</code></p><p>The context of the rule that will register an action.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<a name="apple_support.path_placeholders.platform_frameworks.returns"></a>
+### Returns
+
+Returns a string with the platform's frameworks directory, anchored to the Xcode path
+placeholder.
+
+<a name="apple_support.path_placeholders.sdkroot"></a>
+## apple_support.path_placeholders.sdkroot
+
+<pre style="white-space: pre-wrap">
+apple_support.path_placeholders.sdkroot()
+</pre>
+
+Returns a placeholder value to be replaced with SDKROOT during action execution.
+
+In order to get this values replaced, you'll need to use the `apple_support.run()` API by
+setting the `xcode_path_resolve_level` argument to either the
+`apple_support.xcode_path_resolve_level.args` or
+`apple_support.xcode_path_resolve_level.args_and_files` value.
+
+<a name="apple_support.path_placeholders.sdkroot.returns"></a>
+### Returns
+
+Returns a placeholder value to be replaced with SDKROOT during action execution.
+
+<a name="apple_support.path_placeholders.xcode"></a>
+## apple_support.path_placeholders.xcode
+
+<pre style="white-space: pre-wrap">
+apple_support.path_placeholders.xcode()
+</pre>
+
+Returns a placeholder value to be replaced with DEVELOPER_DIR during action execution.
+
+In order to get this values replaced, you'll need to use the `apple_support.run()` API by
+setting the `xcode_path_resolve_level` argument to either the
+`apple_support.xcode_path_resolve_level.args` or
+`apple_support.xcode_path_resolve_level.args_and_files` value.
+
+<a name="apple_support.path_placeholders.xcode.returns"></a>
+### Returns
+
+Returns a placeholder value to be replaced with DEVELOPER_DIR during action execution.
+
+
+<a name="apple_support.run"></a>
+## apple_support.run
+
+<pre style="white-space: pre-wrap">
+apple_support.run(<a href="#apple_support.run.ctx">ctx</a>, <a href="#apple_support.run.xcode_path_resolve_level">xcode_path_resolve_level</a>=None, <a href="#apple_support.run.**kwargs">**kwargs</a>)
+</pre>
+
+Registers an action to run on an Apple machine.
+
+In order to use `apple_support.run()`, you'll need to modify your rule definition to add the
+following:
+
+  * `fragments = ["apple"]`
+  * Add the `apple_support.action_required_attrs()` attributes to the `attrs` dictionary. This
+    can be done using the `dicts.add()` method from Skylib.
+
+This method registers an action to run on an Apple machine, configuring it to ensure that the
+`DEVELOPER_DIR` and `SDKROOT` environment variables are set.
+
+If the `xcode_path_resolve_level` is enabled, this method will replace the given `executable`
+with a wrapper script that will replace all instances of the `__BAZEL_XCODE_DEVELOPER_DIR__` and
+`__BAZEL_XCODE_SDKROOT__` placeholders in the given arguments with the values of `DEVELOPER_DIR`
+and `SDKROOT`, respectively.
+
+In your rule implementation, you can use references to Xcode through the
+`apple_support.path_placeholders` API, which in turn uses the placeholder values as described
+above. The available APIs are:
+
+  * `apple_support.path_placeholders.xcode()`: Returns a reference to the Xcode.app
+    installation path.
+  * `apple_support.path_placeholders.sdkroot()`: Returns a reference to the SDK root path.
+  * `apple_support.path_placeholders.platform_frameworks(ctx)`: Returns the Frameworks path
+    within the Xcode installation, for the requested platform.
+
+If the `xcode_path_resolve_level` value is:
+
+  * `apple_support.xcode_path_resolve_level.none`: No processing will be done to the given
+    `arguments`.
+  * `apple_support.xcode_path_resolve_level.args`: Only instances of the placeholders in the
+     argument strings will be replaced.
+  * `apple_support.xcode_path_resolve_level.args_and_files`: Instances of the placeholders in
+     the arguments strings and instances of the placeholders within response files (i.e. any
+     path argument beginning with `@`) will be replaced.
+
+<a name="apple_support.run.arguments"></a>
+### Arguments
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="apple_support.run.ctx">
+      <td><code>ctx</code></td>
+      <td><p><code>Required</code></p><p>The context of the rule registering the action.</p></td>
+    </tr>
+    <tr id="apple_support.run.xcode_path_resolve_level">
+      <td><code>xcode_path_resolve_level</code></td>
+      <td><p><code>Optional; default is None</code></p><p>The level of Xcode path replacement required for the action.</p></td>
+    </tr>
+    <tr id="apple_support.run.**kwargs">
+      <td><code>**kwargs</code></td>
+      <td><p>See <code>ctx.actions.run</code> for the rest of the available arguments.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<a name="apple_support.run_shell"></a>
+## apple_support.run_shell
+
+<pre style="white-space: pre-wrap">
+apple_support.run_shell(<a href="#apple_support.run_shell.ctx">ctx</a>, <a href="#apple_support.run_shell.**kwargs">**kwargs</a>)
+</pre>
+
+Registers a shell action to run on an Apple machine.
+
+In order to use `apple_support.run_shell()`, you'll need to modify your rule definition to add
+the following:
+
+  * `fragments = ["apple"]`
+  * Add the `apple_support.action_required_attrs()` attributes to the `attrs` dictionary. This
+    can be done using the `dicts.add()` method from Skylib.
+
+This method registers an action to run on an Apple machine, configuring it to ensure that the
+`DEVELOPER_DIR` and `SDKROOT` environment variables are set.
+
+`run_shell` does not support placeholder substitution. To achieve placeholder substitution,
+please use `run` instead.
+
+<a name="apple_support.run_shell.arguments"></a>
+### Arguments
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="apple_support.run_shell.ctx">
+      <td><code>ctx</code></td>
+      <td><p><code>Required</code></p><p>The context of the rule registering the action.</p></td>
+    </tr>
+    <tr id="apple_support.run_shell.**kwargs">
+      <td><code>**kwargs</code></td>
+      <td><p>See <code>ctx.actions.run</code> for the rest of the available arguments.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+
+
+
diff --git a/doc/rules.md b/doc/rules.md
new file mode 100644
index 0000000..6e6c354
--- /dev/null
+++ b/doc/rules.md
@@ -0,0 +1,113 @@
+# Build Rules
+
+
+Build Rules provided by Apple Support.
+
+On this page:
+
+  * [apple_genrule](#apple_genrule)
+
+<a name="apple_genrule"></a>
+## apple_genrule
+
+<pre style="white-space: pre-wrap">
+apple_genrule(<a href="#apple_genrule.name">name</a>, <a href="#apple_genrule.cmd">cmd</a>, <a href="#apple_genrule.executable">executable</a>=False, <a href="#apple_genrule.outs">outs</a>=[], <a href="#apple_genrule.srcs">srcs</a>=[], <a href="#apple_genrule.message">message</a>=None, <a href="#apple_genrule.tools">tools</a>=[], <a href="#apple_genrule.no_sandbox">no_sandbox</a>=False, <a href="#apple_genrule.**kwargs">**kwargs</a>)
+</pre>
+
+Genrule which provides Apple specific environment and make variables.
+
+This mirrors the native genrule except that it provides a different set of
+make variables. This rule will only run on a Mac.
+
+Example of use:
+
+```
+load("@build_bazel_apple_support//rules:apple_genrule.bzl", "apple_genrule")
+
+apple_genrule(
+    name = "world",
+    outs = ["hi"],
+    cmd = "touch $@",
+)
+```
+
+This rule also does location expansion, much like the native genrule.
+For example, `$(location hi)` may be used to refer to the output in the
+above example.
+
+The set of make variables that are supported for this rule:
+
+* `OUTS`: The outs list. If you have only one output file, you can also use
+          `$@`.
+* `SRCS`: The srcs list (or more precisely, the pathnames of the files
+          corresponding to labels in the srcs list). If you have only one
+          source file, you can also use `$<`.
+* `<`: srcs, if it's a single file.
+* `@`: outs, if it's a single file.
+* `@D`: The output directory. If there is only one filename in outs, this
+        expands to the directory containing that file. If there are
+        multiple filenames, this variable instead expands to the package's
+        root directory in the genfiles tree, even if all the generated
+        files belong to the same subdirectory.
+
+The following environment variables are added to the rule action:
+
+* `DEVELOPER_DIR`: The base developer directory as defined on Apple
+                   architectures, most commonly used in invoking Apple
+                   tools such as xcrun.
+* `SDKROOT`: The base SDK directory as defined on Apple architectures, most
+             commonly used in invoking Apple tools such as xcrun.
+
+<a name="apple_genrule.arguments"></a>
+### Arguments
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="apple_genrule.name">
+      <td><code>name</code></td>
+      <td><p><code>Required</code></p><p>The name of the target.</p></td>
+    </tr>
+    <tr id="apple_genrule.cmd">
+      <td><code>cmd</code></td>
+      <td><p><code>Required</code></p><p>The command to run. Subject the variable substitution.</p></td>
+    </tr>
+    <tr id="apple_genrule.executable">
+      <td><code>executable</code></td>
+      <td><p><code>Optional; default is False</code></p><p>Boolean. Declare output to be executable. Setting this flag to
+1 means the output is an executable file and can be run using the run
+command. The genrule must produce exactly one output in this case.</p></td>
+    </tr>
+    <tr id="apple_genrule.outs">
+      <td><code>outs</code></td>
+      <td><p><code>Optional; default is []</code></p><p>A list of files generated by this rule. If the executable flag is
+set, outs must contain exactly one label.</p></td>
+    </tr>
+    <tr id="apple_genrule.srcs">
+      <td><code>srcs</code></td>
+      <td><p><code>Optional; default is []</code></p><p>A list of inputs for this rule, such as source files to process.</p></td>
+    </tr>
+    <tr id="apple_genrule.message">
+      <td><code>message</code></td>
+      <td><p><code>Optional; default is None</code></p><p>A progress message to be reported as the rule runs.</p></td>
+    </tr>
+    <tr id="apple_genrule.tools">
+      <td><code>tools</code></td>
+      <td><p><code>Optional; default is []</code></p><p>A list of tool dependencies for this rule, they will be available
+when the action is run.</p></td>
+    </tr>
+    <tr id="apple_genrule.no_sandbox">
+      <td><code>no_sandbox</code></td>
+      <td><p><code>Optional; default is False</code></p><p>If the sandbox should be disabled when the action is run.</p></td>
+    </tr>
+    <tr id="apple_genrule.**kwargs">
+      <td><code>**kwargs</code></td>
+      <td><p>Extra args meant to just be the common rules for all rules
+(tags, etc.).</p></td>
+    </tr>
+  </tbody>
+</table>
+
diff --git a/doc/xcode_support.md b/doc/xcode_support.md
new file mode 100644
index 0000000..cb4c25d
--- /dev/null
+++ b/doc/xcode_support.md
@@ -0,0 +1,58 @@
+# `xcode_support` Starlark Module
+
+
+A modules of helpers for rule authors to aid in writing rules that
+need to change what they do based on attributes of the active Xcode.
+
+To use these in your Starlark code, simply load the module; for example:
+
+```build
+load("@build_bazel_apple_support//lib:xcode_support.bzl", "xcode_support")
+```
+
+On this page:
+
+  * [xcode_support.is_xcode_at_least_version](#xcode_support.is_xcode_at_least_version)
+
+
+<a name="xcode_support.is_xcode_at_least_version"></a>
+## xcode_support.is_xcode_at_least_version
+
+<pre style="white-space: pre-wrap">
+xcode_support.is_xcode_at_least_version(<a href="#xcode_support.is_xcode_at_least_version.xcode_config">xcode_config</a>, <a href="#xcode_support.is_xcode_at_least_version.version">version</a>)
+</pre>
+
+Returns True if Xcode version is at least a given version.
+
+This method takes as input an `XcodeVersionConfig` provider, which can be obtained from the
+`_xcode_config` attribute (e.g. `ctx.attr._xcode_config[apple_common.XcodeVersionConfig]`). This
+provider should contain the Xcode version parameters with which this rule is being built with.
+If you need to add this attribute to your rule implementation, please refer to
+`apple_support.action_required_attrs()`.
+
+<a name="xcode_support.is_xcode_at_least_version.arguments"></a>
+### Arguments
+
+<table class="params-table">
+  <colgroup>
+    <col class="col-param" />
+    <col class="col-description" />
+  </colgroup>
+  <tbody>
+    <tr id="xcode_support.is_xcode_at_least_version.xcode_config">
+      <td><code>xcode_config</code></td>
+      <td><p><code>Required</code></p><p>The XcodeVersionConfig provider from the <code>_xcode_config</code> attribute's value.</p></td>
+    </tr>
+    <tr id="xcode_support.is_xcode_at_least_version.version">
+      <td><code>version</code></td>
+      <td><p><code>Required</code></p><p>The minimum desired Xcode version, as a dotted version string.</p></td>
+    </tr>
+  </tbody>
+</table>
+
+<a name="xcode_support.is_xcode_at_least_version.returns"></a>
+### Returns
+
+True if the given `xcode_config` version at least as high as the requested version.
+
+