apple_support.md

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")

On this page:

• apple_support.action_required_attrs
• apple_support.action_required_env
• apple_support.action_required_execution_requirements
• apple_support.path_placeholders.platform_frameworks
• apple_support.path_placeholders.sdkroot
• apple_support.path_placeholders.xcode
• apple_support.run
• apple_support.run_shell

apple_support.action_required_attrs

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.

Returns

A dict object containing attributes to be added to rule implementations.

apple_support.action_required_env

apple_support.action_required_env(ctx, *,
xcode_config,
apple_fragment)

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.

Arguments

ctx	Optional; default is None The context of the rule registering the action. Required if xcode_config and apple_fragment are not provided. Deprecated.
xcode_config	Optional; default is None The apple_common.XcodeVersionConfig provider as found in the current rule or aspect's context. Typically from ctx.attr._xcode_config[apple_common.XcodeVersionConfig]. Required if ctx is not given.
apple_fragment	Optional; default is None A reference to the apple fragment. Typically from ctx.fragments.apple. Required if ctx is not given.

Returns

A dictionary with environment variables required for Xcode path resolution.

apple_support.action_required_execution_requirements

apple_support.action_required_execution_requirements(ctx, *, xcode_config)

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.

Arguments

ctx	Optional; default is None The context of the rule registering the action. Required if xcode_config is not provided. Deprecated.
xcode_config	Optional; default is None The apple_common.XcodeVersionConfig provider as found in the current rule or aspect's context. Typically from ctx.attr._xcode_config[apple_common.XcodeVersionConfig]. Required if ctx is not given.

Returns

A dictionary with execution requirements for running actions on Apple platforms.

apple_support.path_placeholders.platform_frameworks

apple_support.path_placeholders.platform_frameworks(ctx, *, apple_fragment)

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

Arguments

ctx	Optional; default is None The context of the rule registering the action. Required if apple_fragment is not provided. Deprecated.
apple_fragment	Optional; default is None A reference to the apple fragment. Typically from ctx.fragments.apple. Required if ctx is not given.

Returns

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

apple_support.path_placeholders.sdkroot

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.

Returns

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

apple_support.path_placeholders.xcode

apple_support.path_placeholders.xcode()

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.

Returns

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

apple_support.run

apple_support.run(ctx, xcode_path_resolve_level, *, actions, xcode_config, apple_fragment, xcode_path_wrapper, **kwargs)

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.

Arguments

ctx	Optional; default is None The context of the rule registering the action. Required if xcode_config and apple_fragment are not provided. Deprecated.
xcode_path_resolve_level	Optional; default is apple_support.xcode_path_resolve_level.none The level of Xcode path replacement required for the action.
actions	Optional; default is None The actions provider from ctx.actions. Required if ctx is not given.
xcode_config	Optional; default is None The apple_common.XcodeVersionConfig provider as found in the current rule or aspect's context. Typically from ctx.attr._xcode_config[apple_common.XcodeVersionConfig]. Required if ctx is not given.
apple_fragment	Optional; default is None A reference to the apple fragment. Typically from ctx.fragments.apple. Required if ctx is not given.
xcode_path_wrapper	Optional; default is None The Xcode path wrapper script. Required if ctx is not given and xcode_path_resolve_level is not apple_support.xcode_path_resolve_level.none.
**kwargs	See ctx.actions.run for the rest of the available arguments.

apple_support.run_shell

apple_support.run_shell(ctx, *, actions, xcode_config, apple_fragment, **kwargs)

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.

Arguments

ctx	Optional; default is None The context of the rule registering the action. Required if xcode_config and apple_fragment are not provided. Deprecated.
actions	Optional; default is None The actions provider from ctx.actions. Required if ctx is not given.
xcode_config	Optional; default is None The apple_common.XcodeVersionConfig provider as found in the current rule or aspect's context. Typically from ctx.attr._xcode_config[apple_common.XcodeVersionConfig]. Required if ctx is not given.
apple_fragment	Optional; default is None A reference to the apple fragment. Typically from ctx.fragments.apple. Required if ctx is not given.
**kwargs	See ctx.actions.run_shell for the rest of the available arguments.