@apple_support@apple_support//lib:apple_support.bzl

`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:

load("@build_bazel_apple_support//lib:apple_support.bzl", "apple_support")

Functions & Macros

apple_support.action_required_attrs

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.

apple_support.path_placeholders.platform_frameworks

Returns the platform's frameworks directory, anchored to the Xcode path placeholder.

Parameters

*apple_fragment

A reference to the apple fragment. Typically from ctx.fragments.apple.

apple_support.path_placeholders.sdkroot

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.

apple_support.path_placeholders.xcode

Returns a placeholder value to be replaced with DEVELOPER_DIR during action execution.

apple_support.platform_constraint_attrs

Returns a dictionary of all known Apple platform constraints that can be resolved.

The returned dict can be added to the rule's attributes using Skylib's dicts.add() method.

apple_support.run

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.

Parameters

`*actions`	The actions provider from ctx.actions.
`*xcode_config`	The xcode_config as found in the current rule or aspect's context. Typically from `ctx.attr._xcode_config[apple_common.XcodeVersionConfig]`.
`*apple_fragment`	A reference to the apple fragment. Typically from `ctx.fragments.apple`.
`xcode_path_resolve_level`	The level of Xcode path replacement required for the action. Default: `None`
`kwargs`	See `ctx.actions.run` for the rest of the available arguments.

apple_support.run_shell

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.

Parameters

`*actions`	The actions provider from ctx.actions.
`*xcode_config`	The xcode_config as found in the current rule or aspect's context. Typically from `ctx.attr._xcode_config[apple_common.XcodeVersionConfig]`.
`*apple_fragment`	A reference to the apple fragment. Typically from `ctx.fragments.apple`.
`kwargs`	See `ctx.actions.run_shell` for the rest of the available arguments.

apple_support.target_arch_from_rule_ctx

Returns a String representing the target architecture based on constraints.

The returned String will represent a cpu architecture, such as arm64 or arm64e.

In order to use apple_support.target_arch_from_rule_ctx(), you'll need to modify your rule
definition to add the following:

Add the apple_support.platform_constraint_attrs() attributes to the attrs dictionary.
This can be done using the dicts.add() method from Skylib.

Parameters

`*ctx`	The context of the rule that has Apple platform constraint attributes.
`fail_on_missing_constraint`	Whether to fail if no constraint is found. (default: `True`) Default: `True`

apple_support.target_environment_from_rule_ctx

Returns a String representing the target environment based on constraints.

The returned String will represent an environment, such as device or simulator.

For consistency with other Apple platforms, macos is considered to be a device.

In order to use apple_support.target_environment_from_rule_ctx(), you'll need to modify your
rule definition to add the following:

Add the apple_support.platform_constraint_attrs() attributes to the attrs dictionary.
This can be done using the dicts.add() method from Skylib.

Parameters

`*ctx`	The context of the rule that has Apple platform constraint attributes.
`fail_on_missing_constraint`	Whether to fail if no constraint is found. (default: `True`) Default: `True`

apple_support.target_os_from_rule_ctx

Returns a String representing the target OS based on constraints.

The returned String will match an equivalent value from one of the platform definitions in
apple_common.platform_type, such as ios or macos.

In order to use apple_support.target_os_from_rule_ctx(), you'll need to modify your rule
definition to add the following:

Add the apple_support.platform_constraint_attrs() attributes to the attrs dictionary.
This can be done using the dicts.add() method from Skylib.

Parameters

`*ctx`	The context of the rule that has Apple platform constraint attributes.
`fail_on_missing_constraint`	Whether to fail if no constraint is found. (default: `True`) Default: `True`

@apple_support@apple_support//lib:xcode_support.bzl

`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:

load("@build_bazel_apple_support//lib:xcode_support.bzl", "xcode_support")

Functions & Macros

xcode_support.get_current_sdk

Returns the XcodeSdkVariantInfo provider for the current configuration.

Callers of this function must define the _xcode_config attribute in their
rule or aspect. This is best done using the
apple_support.action_required_attrs() helper.

Parameters

*ctx

The rule or aspect context.

xcode_support.get_current_xcode

Returns the XcodeVersionConfig provider for the current configuration.

Callers of this function must define the _xcode_config attribute in their
rule or aspect. This is best done using the
apple_support.action_required_attrs() helper.

Parameters

*ctx

The rule or aspect context.

xcode_support.is_xcode_at_least_version

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().

Parameters

`*xcode_config`	The XcodeVersionConfig provider from the `_xcode_config` attribute's value.
`*version`	The minimum desired Xcode version, as a dotted version string.

@apple_support@apple_support//rules:rules.doc.bzl

Helper rules for Apple platforms

Rules

apple_genrule

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 defined when the rule is executed:

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.

NOTE: DEVELOPER_DIR and SDKROOT are environment variables and not make
variables. To refer to them in cmd you must use environment variable
syntax (i.e. using $$). Example: cmd = "xcrun --sdkroot $$SDKROOT clang...

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*cmd`	`string`	The command to run. Subject the variable substitution.
`executable`	`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. Default: `False`
`*outs`	`list of labels`	A list of files generated by this rule. If the executable flag is set, outs must contain exactly one label.
`srcs`	`list of labels`	A list of inputs for this rule, such as source files to process. Default: `[]`
`message`	`string`	A progress message to be reported as the rule runs. Default: `""`
`tools`	`list of labels`	A list of tool dependencies for this rule, they will be available when the action is run. Default: `[]`
`no_sandbox`	`boolean`	If the sandbox should be disabled when the action is run. Default: `False`

toolchain_substitution

Register a subsitution, from a variable to a file, for use in arguments in a
target's attributes. Useful for passing custom tools to a compile or link.

Example:

load("@build_bazel_apple_support//rules:toolchain_substitution.bzl", "toolchain_substitution")

toolchain_substitution(
    name = "resource_rules",
    src = "resource_rules.plist",
    var_name = "RULES",
)

ios_application(
    ...
    codesignopts = ["--resource-rules=$(RULES)"],
    codesign_inputs = [":resource_rules"],
    toolchains = [":resource_rules"],
)

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*var_name`	`string`	Name of the variable to substitute, ex: FOO
`*src`	`label`	Source file to substitute

universal_binary

This rule produces a multi-architecture ("fat") binary targeting Apple macOS
platforms regardless of the architecture of the macOS host platform. The
lipo tool is used to combine built binaries of multiple architectures. For
non-macOS platforms, this simply just creates a symbolic link of the input
binary.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*binary`	`label`	Target to generate a 'fat' binary from.

@apple_support@apple_support//lib:apple_support.bzl

apple_support starlark module

Functions & Macros

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

@apple_support@apple_support//lib:xcode_support.bzl

xcode_support Starlark Module

Functions & Macros

Parameters

Parameters

Parameters

@apple_support@apple_support//rules:rules.doc.bzl

Helper rules for Apple platforms

Rules

Example:

`apple_support` starlark module

`xcode_support` Starlark Module