Skip to content

Latest commit

 

History

History
executable file
·
510 lines (376 loc) · 47.4 KB

rules-apple.md

File metadata and controls

executable file
·
510 lines (376 loc) · 47.4 KB
Raw

Rules that apply to all Apple platforms.

apple_dynamic_framework_import

apple_dynamic_framework_import(name, deps, bundle_only, dsym_imports, framework_imports)

This rule encapsulates an already-built dynamic framework. It is defined by a list of files in exactly one .framework directory. apple_dynamic_framework_import targets need to be added to library targets through the deps attribute.

Examples

apple_dynamic_framework_import(
    name = "my_dynamic_framework",
    framework_imports = glob(["my_dynamic_framework.framework/**"]),
)

objc_library(
    name = "foo_lib",
    ...,
    deps = [
        ":my_dynamic_framework",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will be linked into that target. List of labels optional []
bundle_only Avoid linking the dynamic framework, but still include it in the app. This is useful when you want to manually dlopen the framework at runtime. Boolean optional False
dsym_imports The list of files under a .dSYM directory, that is the imported framework's dSYM bundle. List of labels optional []
framework_imports The list of files under a .framework directory which are provided to Apple based targets that depend on this target. List of labels required

apple_dynamic_xcframework_import

apple_dynamic_xcframework_import(name, deps, bundle_only, library_identifiers, xcframework_imports)

This rule encapsulates an already-built XCFramework. Defined by a list of files in a .xcframework directory. apple_xcframework_import targets need to be added as dependencies to library targets through the deps attribute.

Example

apple_dynamic_xcframework_import(
    name = "my_dynamic_xcframework",
    xcframework_imports = glob(["my_dynamic_framework.xcframework/**"]),
)

objc_library(
    name = "foo_lib",
    ...,
    deps = [
        ":my_dynamic_xcframework",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of targets that are dependencies of the target being built, which will provide headers and be linked into that target. List of labels optional []
bundle_only Avoid linking the dynamic framework, but still include it in the app. This is useful when you want to manually dlopen the framework at runtime. Boolean optional False
library_identifiers Unnecssary and ignored, will be removed in the future. Dictionary: String -> String optional {}
xcframework_imports List of files under a .xcframework directory which are provided to Apple based targets that depend on this target. List of labels required

apple_static_framework_import

apple_static_framework_import(name, deps, data, alwayslink, framework_imports, has_swift,
                              sdk_dylibs, sdk_frameworks, weak_sdk_frameworks)

This rule encapsulates an already-built static framework. It is defined by a list of files in exactly one .framework directory. apple_static_framework_import targets need to be added to library targets through the deps attribute.

Examples

apple_static_framework_import(
    name = "my_static_framework",
    framework_imports = glob(["my_static_framework.framework/**"]),
)

objc_library(
    name = "foo_lib",
    ...,
    deps = [
        ":my_static_framework",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of targets that are dependencies of the target being built, which will provide headers and be linked into that target. List of labels optional []
data List of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
alwayslink If true, any binary that depends (directly or indirectly) on this framework will link in all the object files for the framework file, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary; for example, if you rely on runtime checks for protocol conformances added in extensions in the library but do not directly reference any other symbols in the object file that adds that conformance. Boolean optional False
framework_imports The list of files under a .framework directory which are provided to Apple based targets that depend on this target. List of labels required
has_swift A boolean indicating if the target has Swift source code. This helps flag Apple frameworks that do not include Swift interface or Swift module files. Boolean optional False
sdk_dylibs Names of SDK .dylib libraries to link with. For instance, libz or libarchive. libc++ is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. List of strings optional []
sdk_frameworks Names of SDK frameworks to link with (e.g. AddressBook, QuartzCore). UIKit and Foundation are always included when building for the iOS, tvOS, visionOS, and watchOS platforms. For macOS, only Foundation is always included. When linking a top level binary, all SDK frameworks listed in that binary's transitive dependency graph are linked. List of strings optional []
weak_sdk_frameworks Names of SDK frameworks to weakly link with. For instance, MediaAccessibility. In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they are not present at runtime. List of strings optional []

apple_static_library

apple_static_library(name, deps, data, additional_linker_inputs, avoid_deps, linkopts,
                     minimum_os_version, platform_type, sdk_dylibs, sdk_frameworks,
                     weak_sdk_frameworks)

This rule produces single- or multi-architecture ("fat") static libraries targeting Apple platforms.

The lipo tool is used to combine files of multiple architectures. One of several flags may control which architectures are included in the output, depending on the value of the platform_type attribute.

NOTE: In most situations, users should prefer the platform- and product-type-specific rules, such as apple_static_xcframework. This rule is being provided for the purpose of transitioning users from the built-in implementation of apple_static_library in Bazel core so that it can be removed.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of dependencies targets that will be linked into this target's binary. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final bundle. List of labels optional []
data Files to be made available to the library archive upon execution. List of labels optional []
additional_linker_inputs A list of input files to be passed to the linker. List of labels optional []
avoid_deps A list of library targets on which this framework depends in order to compile, but the transitive closure of which will not be linked into the framework's binary. List of labels optional []
linkopts A list of strings representing extra flags that should be passed to the linker. List of strings optional []
minimum_os_version A required string indicating the minimum OS version supported by the target, represented as a dotted version number (for example, "9.0"). String required
platform_type The target Apple platform for which to create a binary. This dictates which SDK is used for compilation/linking and which flag is used to determine the architectures to target. For example, if ios is specified, then the output binaries/libraries will be created combining all architectures specified by --ios_multi_cpus. Options are:

* ios: architectures gathered from --ios_multi_cpus. * macos: architectures gathered from --macos_cpus. * tvos: architectures gathered from --tvos_cpus. * visionos: architectures gathered from --visionos_cpus. * watchos: architectures gathered from --watchos_cpus.		 String required
sdk_dylibs Names of SDK .dylib libraries to link with (e.g., libz or libarchive). libc++ is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. List of strings optional []
sdk_frameworks Names of SDK frameworks to link with (e.g., AddressBook, QuartzCore). UIKit and Foundation are always included, even if this attribute is provided and does not list them.

This attribute is discouraged; in general, targets should list system framework dependencies in the library targets where that framework is used, not in the top-level bundle.		 List of strings optional []
weak_sdk_frameworks Names of SDK frameworks to weakly link with (e.g., MediaAccessibility). Unlike regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause the binary to fail to load if they are not present in the version of the framework available at runtime.

This attribute is discouraged; in general, targets should list system framework dependencies in the library targets where that framework is used, not in the top-level bundle.		 List of strings optional []

apple_static_xcframework

apple_static_xcframework(name, deps, avoid_deps, bundle_name, executable_name, families_required,
                         ios, minimum_deployment_os_versions, minimum_os_versions, public_hdrs,
                         umbrella_header)

Generates an XCFramework with static libraries for third-party distribution.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of files directly referencing libraries to be represented for each given platform split in the XCFramework. These libraries will be embedded within each platform split. List of labels required
avoid_deps A list of library targets on which this framework depends in order to compile, but the transitive closure of which will not be linked into the framework's binary. List of labels optional []
bundle_name The desired name of the XCFramework bundle (without the extension) and the binaries for all embedded static libraries. If this attribute is not set, then the name of the target will be used instead. String optional ""
executable_name The desired name of the executable, if the bundle has an executable. If this attribute is not set, then the name of the bundle_name attribute will be used if it is set; if not, then the name of the target will be used instead. String optional ""
families_required A list of device families supported by this extension, with platforms such as ios as keys. Valid values are iphone and ipad for ios; at least one must be specified if a platform is defined. Currently, this only affects processing of ios resources. Dictionary: String -> List of strings optional {}
ios A dictionary of strings indicating which platform variants should be built for the ios platform ( device or simulator) as keys, and arrays of strings listing which architectures should be built for those platform variants (for example, x86_64, arm64) as their values. Dictionary: String -> List of strings optional {}
minimum_deployment_os_versions A dictionary of strings indicating the minimum deployment OS version supported by the target, represented as a dotted version number (for example, "9.0") as values, with their respective platforms such as ios as keys. This is different from minimum_os_versions, which is effective at compile time. Ensure version specific APIs are guarded with available clauses. Dictionary: String -> String optional {}
minimum_os_versions A dictionary of strings indicating the minimum OS version supported by the target, represented as a dotted version number (for example, "8.0") as values, with their respective platforms such as ios as keys. Dictionary: String -> String required
public_hdrs A list of files directly referencing header files to be used as the publicly visible interface for each of these embedded libraries. These header files will be embedded within each platform split, typically in a subdirectory such as Headers. List of labels optional []
umbrella_header An optional single .h file to use as the umbrella header for this framework. Usually, this header will have the same name as this target, so that clients can load the header using the #import <MyFramework/MyFramework.h> format. If this attribute is not specified (the common use case), an umbrella header will be generated under the same name as this target. Label optional None

apple_static_xcframework_import

apple_static_xcframework_import(name, deps, data, alwayslink, has_swift, includes,
                                library_identifiers, linkopts, sdk_dylibs, sdk_frameworks,
                                weak_sdk_frameworks, xcframework_imports)

This rule encapsulates an already-built XCFramework with static libraries. Defined by a list of files in a .xcframework directory. apple_xcframework_import targets need to be added as dependencies to library targets through the deps attribute.

Examples

apple_static_xcframework_import(
    name = "my_static_xcframework",
    xcframework_imports = glob(["my_static_framework.xcframework/**"]),
)

objc_library(
    name = "foo_lib",
    ...,
    deps = [
        ":my_static_xcframework",
    ],
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps List of targets that are dependencies of the target being built, which will provide headers and be linked into that target. List of labels optional []
data List of files needed by this target at runtime.

Files and targets named in the data attribute will appear in the *.runfiles area of this target, if it has one. This may include data files needed by a binary or library, or other programs needed by it.		 List of labels optional []
alwayslink If true, any binary that depends (directly or indirectly) on this XCFramework will link in all the object files for the XCFramework bundle, even if some contain no symbols referenced by the binary. This is useful if your code isn't explicitly called by code in the binary; for example, if you rely on runtime checks for protocol conformances added in extensions in the library but do not directly reference any other symbols in the object file that adds that conformance. Boolean optional False
has_swift A boolean indicating if the target has Swift source code. This helps flag XCFrameworks that do not include Swift interface files. Boolean optional False
includes List of #include/#import search paths to add to this target and all depending targets.

The paths are interpreted relative to the single platform directory inside the XCFramework for the platform being built.

These flags are added for this rule and every rule that depends on it. (Note: not the rules it depends upon!) Be very careful, since this may have far-reaching effects.		 List of strings optional []
library_identifiers Unnecssary and ignored, will be removed in the future. Dictionary: String -> String optional {}
linkopts A list of strings representing extra flags that should be passed to the linker. List of strings optional []
sdk_dylibs Names of SDK .dylib libraries to link with. For instance, libz or libarchive. libc++ is included automatically if the binary has any C++ or Objective-C++ sources in its dependency tree. When linking a binary, all libraries named in that binary's transitive dependency graph are used. List of strings optional []
sdk_frameworks Names of SDK frameworks to link with (e.g. AddressBook, QuartzCore). UIKit and Foundation are always included when building for the iOS, tvOS, visionOS and watchOS platforms. For macOS, only Foundation is always included. When linking a top level binary, all SDK frameworks listed in that binary's transitive dependency graph are linked. List of strings optional []
weak_sdk_frameworks Names of SDK frameworks to weakly link with. For instance, MediaAccessibility. In difference to regularly linked SDK frameworks, symbols from weakly linked frameworks do not cause an error if they are not present at runtime. List of strings optional []
xcframework_imports List of files under a .xcframework directory which are provided to Apple based targets that depend on this target. List of labels required

apple_universal_binary

apple_universal_binary(name, binary, forced_cpus, minimum_deployment_os_version, minimum_os_version,
                       platform_type)

This rule produces a multi-architecture ("fat") binary targeting Apple platforms. The lipo tool is used to combine built binaries of multiple architectures.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
binary Target to generate a 'fat' binary from. Label required
forced_cpus An optional list of target CPUs for which the universal binary should be built.

If this attribute is present, the value of the platform-specific CPU flag (--ios_multi_cpus, --macos_cpus, --tvos_cpus, --visionos_cpus, or --watchos_cpus) will be ignored and the binary will be built for all of the specified architectures instead.

This is primarily useful to force macOS tools to be built as universal binaries using forced_cpus = ["x86_64", "arm64"], without requiring the user to pass additional flags when invoking Bazel.		 List of strings optional []
minimum_deployment_os_version A required string indicating the minimum deployment OS version supported by the target, represented as a dotted version number (for example, "9.0"). This is different from minimum_os_version, which is effective at compile time. Ensure version specific APIs are guarded with available clauses. String optional ""
minimum_os_version A required string indicating the minimum OS version supported by the target, represented as a dotted version number (for example, "9.0"). String required
platform_type The target Apple platform for which to create a binary. This dictates which SDK is used for compilation/linking and which flag is used to determine the architectures to target. For example, if ios is specified, then the output binaries/libraries will be created combining all architectures specified by --ios_multi_cpus. 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.		 String required

apple_xcframework

apple_xcframework(name, deps, data, additional_linker_inputs, bundle_id, bundle_name,
                  codesign_inputs, codesignopts, exported_symbols_lists, extension_safe,
                  families_required, infoplists, ios, linkopts, minimum_deployment_os_versions,
                  minimum_os_versions, public_hdrs, stamp, tvos, umbrella_header, version)

Builds and bundles an XCFramework for third-party distribution.

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
deps A list of dependent targets that will be linked into this target's binary(s). Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final bundle(s). List of labels optional []
data A list of resources or files bundled with the bundle. The resources will be stored in the appropriate resources location within each of the embedded framework bundles. List of labels optional []
additional_linker_inputs A list of input files to be passed to the linker. List of labels optional []
bundle_id The bundle ID (reverse-DNS path followed by app name) for each of the embedded frameworks. If present, this value will be embedded in an Info.plist within each framework bundle. String required
bundle_name The desired name of the xcframework bundle (without the extension) and the bundles for all embedded frameworks. If this attribute is not set, then the name of the target will be used instead. String optional ""
codesign_inputs A list of dependencies targets that provide inputs that will be used by codesign (referenced with codesignopts). List of labels optional []
codesignopts A list of strings representing extra flags that should be passed to codesign. List of strings optional []
exported_symbols_lists A list of targets containing exported symbols lists files for the linker to control symbol resolution.

Each file is expected to have a list of global symbol names that will remain as global symbols in the compiled binary owned by this framework. All other global symbols will be treated as if they were marked as __private_extern__ (aka visibility=hidden) and will not be global in the output file.

See the man page documentation for ld(1) on macOS for more details.		 List of labels optional []
extension_safe If true, compiles and links this framework with -application-extension, restricting the binary to use only extension-safe APIs. Boolean optional False
families_required A list of device families supported by this extension, with platforms such as ios as keys. Valid values are iphone and ipad for ios; at least one must be specified if a platform is defined. Currently, this only affects processing of ios resources. Dictionary: String -> List of strings optional {}
infoplists A list of .plist files that will be merged to form the Info.plist for each of the embedded frameworks. At least one file must be specified. Please see Info.plist Handling for what is supported. List of labels required
ios A dictionary of strings indicating which platform variants should be built for the iOS platform ( device or simulator) as keys, and arrays of strings listing which architectures should be built for those platform variants (for example, x86_64, arm64) as their values. Dictionary: String -> List of strings optional {}
linkopts A list of strings representing extra flags that should be passed to the linker. List of strings optional []
minimum_deployment_os_versions A dictionary of strings indicating the minimum deployment OS version supported by the target, represented as a dotted version number (for example, "9.0") as values, with their respective platforms such as ios as keys. This is different from minimum_os_versions, which is effective at compile time. Ensure version specific APIs are guarded with available clauses. Dictionary: String -> String optional {}
minimum_os_versions A dictionary of strings indicating the minimum OS version supported by the target, represented as a dotted version number (for example, "8.0") as values, with their respective platforms such as ios, or tvos as keys:

minimum_os_versions = { "ios": "13.0", "tvos": "15.0", }		 Dictionary: String -> String required
public_hdrs A list of files directly referencing header files to be used as the publicly visible interface for each of these embedded frameworks. These header files will be embedded within each bundle, typically in a subdirectory such as Headers. List of labels optional []
stamp Enable link stamping. Whether to encode build information into the binary. Possible values:

* stamp = 1: Stamp the build information into the binary. Stamped binaries are only rebuilt when their dependencies change. Use this if there are tests that depend on the build information. * stamp = 0: Always replace build information by constant values. This gives good build result caching. * stamp = -1: Embedding of build information is controlled by the --[no]stamp flag.		 Integer optional -1
tvos A dictionary of strings indicating which platform variants should be built for the tvOS platform ( device or simulator) as keys, and arrays of strings listing which architectures should be built for those platform variants (for example, x86_64, arm64) as their values. Dictionary: String -> List of strings optional {}
umbrella_header An optional single .h file to use as the umbrella header for this framework. Usually, this header will have the same name as this target, so that clients can load the header using the #import <MyFramework/MyFramework.h> format. If this attribute is not specified (the common use case), an umbrella header will be generated under the same name as this target. Label optional None
version An apple_bundle_version target that represents the version for this target. See apple_bundle_version. Label optional None

local_provisioning_profile

local_provisioning_profile(name, profile_name, team_id)

This rule declares a bazel target that you can pass to the 'provisioning_profile' attribute of rules that require it. It discovers a provisioning profile for the given attributes either on the user's local machine, or with the optional 'fallback_profiles' passed to 'provisioning_profile_repository'. This will automatically pick the newest profile if there are multiple profiles matching the given criteria. By default this rule will search for a profile with the same name as the rule itself, you can pass profile_name to use a different name, and you can pass team_id if you'd like to disambiguate between 2 Apple developer accounts that have the same profile name.

Example

load("//apple:apple.bzl", "local_provisioning_profile")

local_provisioning_profile(
    name = "app_debug_profile",
    profile_name = "Development App",
    team_id = "abc123",
)

ios_application(
    name = "app",
    ...
    provisioning_profile = ":app_debug_profile",
)

local_provisioning_profile(
    name = "app_release_profile",
)

ios_application(
    name = "release_app",
    ...
    provisioning_profile = ":app_release_profile",
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this target. Name required
profile_name Name of the profile to use, if it's not provided the name of the rule is used String optional ""
team_id Team ID of the profile to find. This is useful for disambiguating between multiple profiles with the same name on different developer accounts. String optional ""

experimental_mixed_language_library

experimental_mixed_language_library(name, srcs, deps, enable_modules, enable_header_map,
                                    module_name, objc_copts, swift_copts, swiftc_inputs, testonly,
                                    kwargs)

Compiles and links Objective-C and Swift code into a static library.

This is an experimental macro that supports compiling mixed Objective-C and Swift source files into a static library.

Due to build performance reasons, in general it's not recommended to have mixed Objective-C and Swift modules, but it isn't uncommon to see mixed language modules in some codebases. This macro is meant to make it easier to migrate codebases with mixed language modules to Bazel without having to demix them first.

PARAMETERS

Name Description Default Value
name A unique name for this target. none
srcs The list of Objective-C and Swift source files to compile. none
deps A list of targets that are dependencies of the target being built, which will be linked into that target. []
enable_modules Enables clang module support for the Objective-C target. False
enable_header_map Enables header map support for the Swift and Objective-C target. False
module_name The name of the mixed language module being built. If left unspecified, the module name will be the name of the target. None
objc_copts Additional compiler options that should be passed to clang. []
swift_copts Additional compiler options that should be passed to swiftc. These strings are subject to $(location ...) and "Make" variable expansion. []
swiftc_inputs Additional files that are referenced using $(location...) in swift_copts. []
testonly If True, only testonly targets (such as tests) can depend on this target. Default False. False
kwargs Other arguments to pass through to the underlying objc_library. none

provisioning_profile_repository

provisioning_profile_repository(name, fallback_profiles, repo_mapping)

This rule declares an external repository for discovering locally installed provisioning profiles. This is consumed by local_provisioning_profile. You can optionally set 'fallback_profiles' to point at a stable location of profiles if a newer version of the desired profile does not exist on the local machine. This is useful for checking in the current version of the profile, but not having to update it every time a new device or certificate is added.

Example

In your MODULE.bazel file:

You only need this in the case you want to setup fallback profiles, otherwise it can be ommitted when using bzlmod.

provisioning_profile_repository = use_extension("@build_bazel_rules_apple//apple:apple.bzl", "provisioning_profile_repository_extension")
provisioning_profile_repository.setup(
    fallback_profiles = "//path/to/some:filegroup", # Profiles to use if one isn't found locally
)

In your WORKSPACE file:

load("//apple:apple.bzl", "provisioning_profile_repository")

provisioning_profile_repository(
    name = "local_provisioning_profiles",
    fallback_profiles = "//path/to/some:filegroup", # Optional profiles to use if one isn't found locally
)

In your BUILD files (see local_provisioning_profile for more examples):

load("//apple:apple.bzl", "local_provisioning_profile")

local_provisioning_profile(
    name = "app_debug_profile",
    profile_name = "Development App",
    team_id = "abc123",
)

ios_application(
    name = "app",
    ...
    provisioning_profile = ":app_debug_profile",
)

ATTRIBUTES

Name Description Type Mandatory Default
name A unique name for this repository. Name required
fallback_profiles - Label optional None
repo_mapping In WORKSPACE context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository.

For example, an entry "@foo": "@bar" declares that, for any time this repository depends on @foo (such as a dependency on @foo//some:target, it should actually resolve that dependency within globally-declared @bar (@bar//some:target).

This attribute is not supported in MODULE.bazel context (when invoking a repository rule inside a module extension's implementation function).		 Dictionary: String -> String optional

ENVIRONMENT VARIABLES

This repository rule depends on the following environment variables:

  • HOME

provisioning_profile_repository_extension

provisioning_profile_repository_extension = use_extension("@rules_apple//apple:apple.bzl", "provisioning_profile_repository_extension")
provisioning_profile_repository_extension.setup(fallback_profiles)

See provisioning_profile_repository for more information and examples.

TAG CLASSES

setup

Attributes

Name Description Type Mandatory Default
fallback_profiles - Label optional None