Extensions > API reference > apple_common

apple_common

Functions for Starlark to access internals of the apple rule implementations.

apple_host_system_env

dict apple_common.apple_host_system_env(xcode_config)

Returns a dict of environment variables that should be set for actions that need to run build tools on an Apple host system, such as the version of Xcode that should be used. The keys are variable names and the values are their corresponding values.

Parameters

Parameter	Description
xcode_config	required A provider containing information about the xcode configuration.

apple_toolchain

apple_toolchain apple_common.apple_toolchain()

Utilities for resolving items from the apple toolchain.

AppleDebugOutputs

Provider apple_common.AppleDebugOutputs

The constructor/key for the AppleDebugOutputs provider.

If a target propagates the AppleDebugOutputs provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.AppleDebugOutputs]

AppleDylibBinary

Provider apple_common.AppleDylibBinary

The constructor/key for the AppleDylibBinary provider.

If a target propagates the AppleDylibBinary provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.AppleDylibBinary]

AppleDynamicFramework

Provider apple_common.AppleDynamicFramework

The constructor/key for the AppleDynamicFramework provider.

If a target propagates the AppleDynamicFramework provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.AppleDynamicFramework]

AppleExecutableBinary

Provider apple_common.AppleExecutableBinary

The constructor/key for the AppleExecutableBinary provider.

If a target propagates the AppleExecutableBinary provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.AppleExecutableBinary]

AppleLoadableBundleBinary

Provider apple_common.AppleLoadableBundleBinary

The constructor/key for the AppleLoadableBundleBinary provider.

If a target propagates the AppleLoadableBundleBinary provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.AppleLoadableBundleBinary]

AppleStaticLibrary

Provider apple_common.AppleStaticLibrary

The constructor/key for the AppleStaticLibrary provider.

If a target propagates the AppleStaticLibrary provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.AppleStaticLibrary]

dotted_version

DottedVersion apple_common.dotted_version(version)

Creates a new DottedVersion instance.

Parameters

Parameter	Description
version	required The string representation of the DottedVersion.

link_multi_arch_binary

struct apple_common.link_multi_arch_binary(ctx, avoid_deps=None, extra_linkopts=[], extra_link_inputs=[], stamp=-1, should_lipo=True)

Links a (potentially multi-architecture) binary targeting Apple platforms. This method comprises a bulk of the logic of the apple_binary rule, and is exposed as an API to iterate on migration of apple_binary to Starlark.

This API is highly experimental and subject to change at any time. Do not depend on the stability of this function at this time.

Parameters

Parameter	Description
ctx	required The Starlark rule context.
avoid_deps	sequence of Targets; or None; default = None A list of Targets that are in the dependency graph of the binary but whose libraries should not be linked into the binary. This is the case for dependencies that will be found at runtime in another image, such as the bundle loader or any dynamic libraries/frameworks that will be loaded by this binary.
extra_linkopts	sequence of strings; default = [] Extra linkopts to be passed to the linker action.
extra_link_inputs	sequence of Files; default = [] Extra files to pass to the linker action.
stamp	default = -1 Whether to include build information in the linked binary. If 1, build information is always included. If 0, build information is always excluded. If -1 (the default), then the behavior is determined by the --[no]stamp flag. This should be set to 0 when generating the executable output for test rules.
should_lipo	default = True If True, invoke lipo after linking to create a universal binary. This parameter is temporary and defaults to True for legacy purposes. After rules_apple has been updated to call this with False, the default will be changed to False and the support for invoking lipo inside link_multi_arch_binary will be removed, along with this parameter.

multi_arch_split

SplitTransitionProviderApi apple_common.multi_arch_split

A configuration transition for rule attributes to build dependencies in one or more Apple platforms.

Use of this transition requires that the 'platform_type' and 'minimum_os_version' string attributes are defined and mandatory on the rule.

The value of the platform_type attribute will dictate the target architectures for which dependencies along this configuration transition will be built.

Options are:

• ios: architectures gathered from --ios_multi_cpus.
• macos: architectures gathered from --macos_cpus.
• tvos: architectures gathered from --tvos_cpus.
• watchos: architectures gathered from --watchos_cpus.

minimum_os_version should be a dotted version string such as '7.3', and is used to set the minimum operating system on the configuration similarly based on platform type. For example, specifying platform_type 'ios' and minimum_os_version '8.0' will ensure that dependencies are built with minimum iOS version '8.0'.

new_dynamic_framework_provider

AppleDynamicFramework apple_common.new_dynamic_framework_provider(binary=None, objc, framework_dirs=None, framework_files=None)

Creates a new AppleDynamicFramework provider instance.

Parameters

Parameter	Description
binary	File; or None; default = None The dylib binary artifact of the dynamic framework.
objc	required An ObjcProvider which contains information about the transitive dependencies linked into the binary.
framework_dirs	depset of strings; or None; default = None The framework path names used as link inputs in order to link against the dynamic framework.
framework_files	depset of Files; or None; default = None The full set of artifacts that should be included as inputs to link against the dynamic framework

new_executable_binary_provider

AppleExecutableBinary apple_common.new_executable_binary_provider(binary=None, objc)

Creates a new AppleExecutableBinaryInfo provider instance.

Parameters

Parameter	Description
binary	File; or None; default = None The binary artifact of the executable.
objc	required An ObjcProvider which contains information about the transitive dependencies linked into the binary.

new_objc_provider

ObjcProvider apple_common.new_objc_provider(**kwargs)

Creates a new ObjcProvider instance.

Parameters

Parameter	Description
kwargs	default = {} Dictionary of arguments.

Objc

Provider apple_common.Objc

The constructor/key for the Objc provider.

If a target propagates the Objc provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.Objc]

platform

struct apple_common.platform

An enum-like struct that contains the following fields corresponding to Apple platforms:

• ios_device
• ios_simulator
• macos
• tvos_device
• tvos_simulator
• watchos_device
• watchos_simulator

These values can be passed to methods that expect a platform, like XcodeVersionConfig.sdk_version_for_platform.

platform_type

struct apple_common.platform_type

An enum-like struct that contains the following fields corresponding to Apple platform types:

• ios
• macos
• tvos
• watchos

These values can be passed to methods that expect a platform type, like the 'apple' configuration fragment's multi_arch_platform method.

Example:

ctx.fragments.apple.multi_arch_platform(apple_common.platform_type.ios)

target_apple_env

dict apple_common.target_apple_env(xcode_config, platform)

Returns a dict of environment variables that should be set for actions that build targets of the given Apple platform type. For example, this dictionary contains variables that denote the platform name and SDK version with which to build. The keys are variable names and the values are their corresponding values.

Parameters

Parameter	Description
xcode_config	required A provider containing information about the xcode configuration.
platform	required The apple platform.

XcodeProperties

Provider apple_common.XcodeProperties

The constructor/key for the XcodeVersionProperties provider.

If a target propagates the XcodeVersionProperties provider, use this as the key with which to retrieve it. Example:

dep = ctx.attr.deps[0]
p = dep[apple_common.XcodeVersionProperties]

XcodeVersionConfig

Provider apple_common.XcodeVersionConfig

The constructor/key for the XcodeVersionConfig provider.