ryanfitz / rules_apple

Bazel rules to build apps for Apple platforms.

Apple Rules for Bazel

⚠️ NOTE: At the time of this writing, the most recent Bazel release is 0.4.5. These rules are not compatible with that release; they are only compatible with Bazel at master. Until the next release of Bazel, you will need to build Bazel from source if you wish to use them.

This repository contains rules for Bazel that can be used to bundle applications for Apple platforms. They replace the bundling rules defined in Bazel itself (such as ios_application, ios_extension, and apple_watch2_extension).

These rules handle the linking and bundling of applications and extensions (that is, the formation of an .app with an executable and resources, archived in an .ipa). Compilation is still performed by the existing objc_library rule in Bazel; to link those dependencies, these bundling rules use Bazel's apple_binary rule under the hood.

Rules

• ios_application
• ios_extension
• ios_framework (experimental)
• tvos_application
• tvos_extension
• watchos_application
• watchos_extension
• swift_library

Other types

• apple_product_type

Setup

Add the following to your WORKSPACE file to add the external repositories, replacing the version number in the tag attribute with the version of the rules you wish to depend on:

git_repository(
    name = "build_bazel_rules_apple",
    remote = "https://github.com/bazelbuild/rules_apple.git",
    tag = "0.0.1",
)

Examples

Minimal example:

load("@build_bazel_rules_apple//apple:ios.bzl", "ios_application")

objc_library(
    name = "Lib",
    srcs = glob([
        "**/*.h",
        "**/*.m",
    ]),
    resources = [
        ":Main.storyboard",
    ],
)

# Links code from "deps" into an executable, collects and compiles resources
# from "deps" and places them with the executable in an .app bundle, and then
# outputs an .ipa with the bundle in its Payload directory.
ios_application(
    name = "App",
    bundle_id = "com.example.app",
    families = ["iphone", "ipad"],
    infoplists = [":Info.plist"],
    deps = [":Lib"],
)

See the examples directory for sample applications.

Migrating from the built-in rules

Even though the rules in this repository have the same names as their built-in counterparts, they cannot be intermixed; for example, an ios_application from this repository cannot have an extension that is a built-in ios_extension or vice versa.

The wiki for this repository contains a migration guide describing in detail the differences between the old and new rules and how to update your build targets.

Coming soon

• macOS support
• Support for compiling texture atlases
• Improved rules for creating resource bundles

ios_application

ios_application(name, app_icons, bundle_id, entitlements, extensions, families,
frameworks, infoplists, ipa_post_processor, launch_images, launch_storyboard,
linkopts, product_type, provisioning_profile, settings_bundle, strings, deps)

Builds and bundles an iOS application.

The named target produced by this macro is an IPA file. This macro also creates a target named {name}.apple_binary that represents the linked executable inside the application bundle.

Attributes
name	Name, required A unique name for the target.
app_icons	List of labels; optional Files that comprise the app icons for the application. Each file must have a containing directory named *.xcassets/*.appiconset and there may be only one such .appiconset directory in the list.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the application.
entitlements	Label; optional The entitlements file required for device builds of the application. If absent, the default entitlements from the provisioning profile will be used. The following variables are substituted in the entitlements file: $(CFBundleIdentifier) with the bundle ID of the application and $(AppIdentifierPrefix) with the value of the ApplicationIdentifierPrefix key from the target's provisioning profile.
extensions	List of labels; optional A list of extensions (see ios_extension) to include in the final application bundle.
families	List of strings; required A list of device families supported by this application. Valid values are iphone and ipad; at least one must be specified.
frameworks	List of labels; optional A list of framework targets (see ios_framework) that this application depends on.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the application. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's IPA output after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the IPA (that is, the Payload directory will be present in this directory). Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
launch_images	List of labels; optional Files that comprise the launch images for the application. Each file must have a containing directory named*.xcassets/*.launchimage and there may be only one such .launchimage directory in the list. It is recommended that you use a launch_storyboard instead if you are targeting only iOS 8 and later.
launch_storyboard	Label; optional The .storyboard or .xib file that should be used as the launch screen for the application. The provided file will be compiled into the appropriate format (.storyboardc or .nib) and placed in the root of the final bundle. The generated file will also be registered in the bundle's Info.plist under the key UILaunchStoryboardName.
linkopts	List of strings; optional A list of strings representing extra flags that the underlying apple_binary target created by this rule should pass to the linker.
product_type	String; optional An optional string denoting a special type of application, such as a Messages Application in iOS 10 and higher. See apple_product_type.
provisioning_profile	Label; optional The provisioning profile (.mobileprovision file) to use when bundling the application. This value is optional (and unused) for simulator builds but required for device builds.
settings_bundle	List of labels; optional An objc_bundle target that contains the files that make up the application's settings bundle. These files will be copied into the root of the final application bundle in a directory named Settings.bundle.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final application bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
watch_application	Label; optional A watchos_application target that represents an Apple Watch application that should be embedded in the application.
deps	List of labels; optional A list of dependencies targets that are passed into the apple_binary rule to be linked. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final application.

ios_extension

ios_extension(name, app_icons, bundle_id, entitlements, families, frameworks,
infoplists, ipa_post_processor, linkopts, product_type, provisioning_profile,
strings, deps)

Builds and bundles an iOS application extension.

The named target produced by this macro is a ZIP file. This macro also creates a target named {name}.apple_binary that represents the linked binary executable inside the extension bundle.

Attributes
name	Name, required A unique name for the target.
app_icons	List of labels; optional Files that comprise the app icons for the extension. Each file must have a containing directory named*.xcassets/*.appiconset and there may be only one such .appiconset directory in the list.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the extension.
entitlements	Label; optional The entitlements file required for device builds of the extension. If absent, the default entitlements from the provisioning profile will be used. The following variables are substituted in the entitlements file: $(CFBundleIdentifier) with the bundle ID of the extension and $(AppIdentifierPrefix) with the value of the ApplicationIdentifierPrefix key from the target's provisioning profile.
families	List of strings; required A list of device families supported by this extension. Valid values are iphone and ipad; at least one must be specified.
frameworks	List of labels; optional A list of framework targets (see ios_framework) that this extension depends on.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the extension. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's archive after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the archive; the *.appex bundle for the extension will be the directory's only contents. Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
linkopts	List of strings; optional A list of strings representing extra flags that the underlying apple_binary target created by this rule should pass to the linker.
product_type	String; optional An optional string denoting a special type of extension, such as a Messages Extension in iOS 10 and higher. See apple_product_type.
provisioning_profile	Label; optional The provisioning profile (.mobileprovision file) to use when bundling the extension. This value is optional (and unused) for simulator builds but required for device builds.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final extension bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
deps	List of labels; optional A list of dependencies targets that are passed into the apple_binary rule to be linked. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final extension.

ios_framework

ios_framework(name, bundle_id, families, infoplists, ipa_post_processor,
linkopts, strings, deps)

Builds and bundles an iOS dynamic framework.

The named target produced by this macro is a ZIP file. This macro also creates a target named {name}.apple_binary that represents the linked dynamic library inside the framework bundle.

Attributes
name	Name, required A unique name for the target.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the framework.
families	List of strings; required A list of device families supported by this framework. Valid values are iphone and ipad; at least one must be specified.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the framework. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's archive after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the archive; the *.framework bundle for the extension will be the directory's only contents. Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
linkopts	List of strings; optional A list of strings representing extra flags that the underlying apple_binary target created by this rule should pass to the linker.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final extension bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
deps	List of labels; optional A list of dependencies targets that are passed into the apple_binary rule to be linked. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final framework.

tvos_application

tvos_application(name, app_icons, bundle_id, entitlements, extensions,
infoplists, ipa_post_processor, launch_images, launch_storyboard, linkopts,
provisioning_profile, settings_bundle, strings, deps)

Builds and bundles a tvOS application.

The named target produced by this macro is an IPA file. This macro also creates a target named {name}.apple_binary that represents the linked executable inside the application bundle.

Attributes
name	Name, required A unique name for the target.
app_icons	List of labels; optional Files that comprise the app icons for the application. Each file must have a containing directory named*.xcassets/*.appiconset and there may be only one such .appiconset directory in the list.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the application.
entitlements	Label; optional The entitlements file required for device builds of the application. If absent, the default entitlements from the provisioning profile will be used. The following variables are substituted in the entitlements file: $(CFBundleIdentifier) with the bundle ID of the application and $(AppIdentifierPrefix) with the value of the ApplicationIdentifierPrefix key from the target's provisioning profile.
extensions	List of labels; optional A list of extensions (see tvos_extension) to include in the final application bundle.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the application. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's IPA output after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the IPA (that is, the Payload directory will be present in this directory). Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
launch_images	List of labels; optional Files that comprise the launch images for the application. Each file must have a containing directory named*.xcassets/*.launchimage and there may be only one such .launchimage directory in the list. It is recommended that you use a launch_storyboard instead if you are targeting only iOS 8 and later.
launch_storyboard	Label; optional The .storyboard or .xib file that should be used as the launch screen for the application. The provided file will be compiled into the appropriate format (.storyboardc or .nib) and placed in the root of the final bundle. The generated file will also be registered in the bundle's Info.plist under the key UILaunchStoryboardName.
linkopts	List of strings; optional A list of strings representing extra flags that the underlying apple_binary target created by this rule should pass to the linker.
provisioning_profile	Label; optional The provisioning profile (.mobileprovision file) to use when bundling the application. This value is optional (and unused) for simulator builds but required for device builds.
settings_bundle	List of labels; optional An objc_bundle target that contains the files that make up the application's settings bundle. These files will be copied into the root of the final application bundle in a directory named Settings.bundle.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final application bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
deps	List of labels; optional A list of dependencies targets that are passed into the apple_binary rule to be linked. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final application.

tvos_extension

tvos_extension(name, bundle_id, entitlements, infoplists, ipa_post_processor,
linkopts, strings, deps)

Builds and bundles a tvOS extension.

The named target produced by this macro is a ZIP file. This macro also creates a target named {name}.apple_binary that represents the linked binary executable inside the extension bundle.

Attributes
name	Name, required A unique name for the target.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the extension.
entitlements	Label; optional The entitlements file required for device builds of the extension. If absent, the default entitlements from the provisioning profile will be used. The following variables are substituted in the entitlements file: $(CFBundleIdentifier) with the bundle ID of the extension and $(AppIdentifierPrefix) with the value of the ApplicationIdentifierPrefix key from the target's provisioning profile.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the extension. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's archive after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the archive; the *.appex bundle for the extension will be the directory's only contents. Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
linkopts	List of strings; optional A list of strings representing extra flags that the underlying apple_binary target created by this rule should pass to the linker.
provisioning_profile	Label; optional The provisioning profile (.mobileprovision file) to use when bundling the extension. This value is optional (and unused) for simulator builds but required for device builds.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final extension bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
deps	List of labels; optional A list of dependencies targets that are passed into the apple_binary rule to be linked. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final extension.

watchos_application

watchos_application(name, app_icons, bundle_id, entitlements, extension,
infoplists, ipa_post_processor, provisioning_profile, storyboards, strings,
deps)

Builds and bundles a watchOS application.

This rule only supports watchOS 2.0 and higher. Apple no longer supports or accepts submissions of apps written for watchOS 1.x, so these bundling rules do not support that version of the platform.

The named target produced by this macro is a ZIP file. The watch application is not executable or installable by itself; the target must be added to a companion ios_application using the watch_application attribute on that rule.

Attributes
name	Name, required A unique name for the target.
app_icons	List of labels; optional Files that comprise the app icons for the application. Each file must have a containing directory named*.xcassets/*.appiconset and there may be only one such .appiconset directory in the list.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the application.
entitlements	Label; optional The entitlements file required for device builds of the application. If absent, the default entitlements from the provisioning profile will be used. The following variables are substituted in the entitlements file: $(CFBundleIdentifier) with the bundle ID of the application and $(AppIdentifierPrefix) with the value of the ApplicationIdentifierPrefix key from the target's provisioning profile.
extension	Label; required The watchos_extension that is bundled with the watch application.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the application. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's IPA output after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the IPA (that is, the Payload directory will be present in this directory). Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
provisioning_profile	Label; optional The provisioning profile (.mobileprovision file) to use when bundling the application. This value is optional (and unused) for simulator builds but required for device builds.
storyboards	List of labels; optional A list of .storyboard files, often localizable. These files are compiled and placed in the root of the final application bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final application bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
deps	List of labels; optional A list of targets whose resources will be included in the final application. Since a watchOS application does not contain any code of its own, any code in the dependent libraries will be ignored.

watchos_extension

watchos_extension(name, app_icons, bundle_id, entitlements, infoplists,
ipa_post_processor, linkopts, provisioning_profile, strings, deps)

Builds and bundles a watchOS extension.

This rule only supports watchOS 2.0 and higher. Apple no longer supports or accepts submissions of apps written for watchOS 1.x, so these bundling rules do not support that version of the platform.

The named target produced by this macro is a ZIP file. This macro also creates a target named {name}.apple_binary that represents the linked binary executable inside the extension bundle.

Attributes
name	Name, required A unique name for the target.
app_icons	List of labels; optional Files that comprise the app icons for the extension. Each file must have a containing directory named*.xcassets/*.appiconset and there may be only one such .appiconset directory in the list.
bundle_id	String; required The bundle ID (reverse-DNS path followed by app name) of the extension.
entitlements	Label; optional The entitlements file required for device builds of the extension. If absent, the default entitlements from the provisioning profile will be used. The following variables are substituted in the entitlements file: $(CFBundleIdentifier) with the bundle ID of the extension and $(AppIdentifierPrefix) with the value of the ApplicationIdentifierPrefix key from the target's provisioning profile.
infoplists	List of labels; required A list of .plist files that will be merged to form the Info.plist that represents the extension. At least one file must be specified.
ipa_post_processor	Label; optional A tool that edits this target's archive after it is assembled but before it is signed. The tool is invoked with a single command-line argument that denotes the path to a directory containing the unzipped contents of the archive; the *.appex bundle for the extension will be the directory's only contents. Any changes made by the tool must be made in this directory, and the tool's execution must be hermetic given these inputs to ensure that the result can be safely cached.
linkopts	List of strings; optional A list of strings representing extra flags that the underlying apple_binary target created by this rule should pass to the linker.
provisioning_profile	Label; optional The provisioning profile (.mobileprovision file) to use when bundling the extension. This value is optional (and unused) for simulator builds but required for device builds.
strings	List of labels; optional A list of .strings files, often localizable. These files are converted to binary plists (if they are not already) and placed in the root of the final extension bundle, unless a file's immediate containing directory is named *.lproj, in which case it will be placed under a directory with the same name in the bundle.
deps	List of labels; optional A list of dependencies targets that are passed into the apple_binary rule to be linked. Any resources, such as asset catalogs, that are referenced by those targets will also be transitively included in the final extension.

swift_library

swift_library(name, srcs, deps, module_name, defines, copts)

Produces a static library from Swift sources. The output is a pair of .a and .swiftmodule files.

Attributes
name	Name, required A unique name for the target.
srcs	List of labels; required Sources to compile into this library. Only *.swift is allowed.
deps	List of labels; optional A list of Swift or Objective-C libraries to link together.
module_name	String; optional Sets the Swift module name for this target. By default the module name is the target path with all special symbols replaced by _, e.g. //foo/baz:bar can be imported as foo_baz_bar.
defines	List of strings; optional Values to be passed with -D flag to the compiler for this target and all swift_library dependents of this target.
copts	List of strings; optional Additional compiler flags. Passed to the compile actions of this target only.

apple_product_type

A struct containing product type identifiers used by special application and extension types.

Some applications and extensions, such as Messages Extensions and Sticker Packs in iOS 10, receive special treatment when building (for example, some product types bundle a stub executable instead of a user-defined binary, and some pass extra arguments to tools like the asset compiler). These behaviors are captured in the product type identifier. The product types currently supported are:

Product types
messages_application	Applies to ios_application targets built for iOS 10 and above. A "stub" application used to distribute a standalone Messages Extension or Sticker Pack. This application must include an ios_extension whose product type is messages_extension or messages_sticker_pack_extension (or it can include both). This product type does not contain a user-provided binary; any code in its deps will be ignored. This stub application is not displayed on the home screen and its features are only accessible through the Messages user interface. If you are building a Messages Extension or Sticker Pack as part of a larger application that is launchable, do not use this product type; simply add those extensions to the existing application.
messages_extension	Applies to ios_extension targets built for iOS 10 and above. An extension that integrates custom behavior into the Apple Messages application. Such extensions can present a custom user interface in the keyboard area of the app and interact with users' conversations.
messages_sticker_pack_extension	Applies to ios_extension targets built for iOS 10 and above. An extension that defines custom sticker packs for the Apple Messages app. Stickers are provided by including an asset catalog named *.xcstickers in the extension's asset_catalogs attribute. This product type does not contain a user-provided binary; any code in its deps will be ignored.

Example usage:

load("@build_bazel_rules_apple//apple:ios.bzl",
     "apple_product_type", "ios_application", "ios_extension")

ios_application(
    name = "StickerPackApp",
    extensions = [":StickerPackExtension"],
    product_type = apple_product_type.messages_application,
    # other attributes...
)

ios_extension(
    name = "StickerPackExtension",
    product_type = apple_product_type.messages_sticker_pack_extension,
    # other attributes...
)