Objective-C Rules

Rules

apple_binary
apple_static_library
j2objc_library
objc_import
objc_library

apple_binary

apple_binary(name, deps, data, binary_type, compatible_with, deprecation, distribs, dylibs, exec_compatible_with, exec_properties, extension_safe, features, licenses, linkopts, minimum_os_version, platform_type, restricted_to, sdk_dylibs, sdk_frameworks, tags, testonly, visibility, weak_sdk_frameworks)

This rule produces single- or multi-architecture ("fat") Objective-C libraries and/or binaries, typically used in creating apple bundles, such as frameworks, extensions, or applications.

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.

Implicit output targets

name_lipobin: the 'lipo'ed potentially multi-architecture binary. All transitive dependencies and srcs are linked.

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`deps`	`List of labels; optional` The list of targets that are linked together to form the final binary.
`binary_type`	`String; optional; default is "executable"` The type of binary that this target should build. Options are: `executable` (default): the output binary is an executable and must implement the main() function. `loadable_bundle`: the output binary is a loadable bundle that may be loaded at runtime. When building a bundle, you may also pass a bundle_loader binary that contains symbols referenced but not implemented in the loadable bundle. `dylib`: the output binary is meant to be loaded at load time (when the operating system is loading the binary into memory) and cannot be unloaded. Dylibs are usually consumed in frameworks, which are .framework bundles that contain the dylib as well as well as required resources to run.
`dylibs`	`List of labels; optional` A list of dynamic library targets to be linked against in this rule and included in the final binary. Libraries which are transitive dependencies of any such dylibs will not be statically linked in this target (even if they are otherwise transitively depended on via the `deps` attribute) to avoid duplicate symbols.
`extension_safe`	`Boolean; optional; nonconfigurable; default is False` This attribute is deprecated and will be removed soon. It currently has no effect. "Extension-safe" link options may be added using the `linkopts` attribute.
`linkopts`	`List of strings; optional` Extra flags to pass to the linker.
`minimum_os_version`	`String; optional` The minimum OS version that this target and its dependencies should be built for. This should be a dotted version string such as "7.3".
`platform_type`	`String; required` The type of platform for which to create artifacts in this rule. This dictates which Apple platform SDK is used for compilation/linking and which flag is used to determine the architectures for which to build. For example, if `ios` is selected, then the output binaries/libraries will be created combining all architectures specified in `--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`.
`sdk_dylibs`	`List of strings; optional` 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.
`sdk_frameworks`	`List of strings; optional` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). "UIKit" and "Foundation" are always included when building for the iOS, tvOS and watchOS platforms. For macOS, only "Foundation" is always included. When linking a top level binary (e.g. apple_binary), all SDK frameworks listed in that binary's transitive dependency graph are linked.
`weak_sdk_frameworks`	`List of strings; optional` 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.

apple_static_library

apple_static_library(name, deps, data, avoid_deps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, linkopts, minimum_os_version, platform_type, restricted_to, sdk_dylibs, sdk_frameworks, tags, testonly, visibility, weak_sdk_frameworks)

This rule produces single- or multi-architecture ("fat") Objective-C statically-linked libraries, typically used in creating static Apple Frameworks for distribution and re-use in multiple extensions or applications.

The lipo tool is used to combine files of multiple architectures; a build flag controls which architectures are targeted. The build flag examined depends on the platform_type attribute for this rule (and is described in its documentation).

Implicit output targets

name_lipo.a: a 'lipo'ed archive file. All transitive dependencies and srcs are linked, minus all transitive dependencies specified in avoid_deps.

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`deps`	`List of labels; optional` The list of targets that are linked together to form the final binary.
`avoid_deps`	`List of labels; optional` A list of targets which should not be included (nor their transitive dependencies included) in the outputs of this rule -- even if they are otherwise transitively depended on via the `deps` attribute. This attribute effectively serves to remove portions of the dependency tree from a static library, and is useful most commonly in scenarios where static libraries depend on each other. That is, suppose static libraries X and C are typically distributed to consumers separately. C is a very-common base library, and X contains less-common functionality; X depends on C, such that applications seeking to import library X must also import library C. The target describing X would set C's target in `avoid_deps`. In this way, X can depend on C without also containing C. Without this `avoid_deps` usage, an application importing both X and C would have duplicate symbols for C.
`linkopts`	`List of strings; optional` Extra flags to pass to the linker.
`minimum_os_version`	`String; optional` The minimum OS version that this target and its dependencies should be built for. This should be a dotted version string such as "7.3".
`platform_type`	`String; required` The type of platform for which to create artifacts in this rule. This dictates which Apple platform SDK is used for compilation/linking and which flag is used to determine the architectures for which to build. For example, if `ios` is selected, then the output binaries/libraries will be created combining all architectures specified in `--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`.
`sdk_dylibs`	`List of strings; optional` 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.
`sdk_frameworks`	`List of strings; optional` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). "UIKit" and "Foundation" are always included when building for the iOS, tvOS and watchOS platforms. For macOS, only "Foundation" is always included. When linking a top level binary (e.g. apple_binary), all SDK frameworks listed in that binary's transitive dependency graph are linked.
`weak_sdk_frameworks`	`List of strings; optional` 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.

j2objc_library

j2objc_library(name, deps, compatible_with, deprecation, distribs, entry_classes, features, jre_deps, licenses, restricted_to, tags, testonly, visibility)

This rule uses J2ObjC to translate Java source files to Objective-C, which then can be used used as dependencies of objc_library and objc_binary rules. Detailed information about J2ObjC itself can be found at the J2ObjC site

Custom J2ObjC transpilation flags can be specified using the build flag --j2objc_translation_flags in the command line.

Please note that the translated files included in a j2objc_library target will be compiled using the default compilation configuration, the same configuration as for the sources of an objc_library rule with no compilation options specified in attributes.

Plus, generated code is de-duplicated at target level, not source level. If you have two different Java targets that include the same Java source files, you may see a duplicate symbol error at link time. The correct way to resolve this issue is to move the shared Java source files into a separate common target that can be depended upon.

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`deps`	`List of labels; optional` A list of `j2objc_library`, `java_library` and `java_import` targets that contain Java files to be transpiled to Objective-C. All `java_library` and `java_import` targets that can be reached transitively through `exports`, `deps` and `runtime_deps` will be translated and compiled. Currently there is no support for files generated by Java annotation processing or `java_import` targets with no `srcjar` specified. The J2ObjC translation works differently depending on the type of source Java source files included in the transitive closure. For each .java source files included in `srcs` of `java_library`, a corresponding .h and .m source file will be generated. For each source jar included in `srcs` of `java_library` or `srcjar` of `java_import`, a corresponding .h and .m source file will be generated with all the code for that jar. Users can import the J2ObjC-generated header files in their code. The import paths for these files are the root-relative path of the original Java artifacts. For example, `//some/package/foo.java` has an import path of `some/package/foo.h` and `//some/package/bar.srcjar` has `some/package/bar.h` If proto_library rules are in the transitive closure of this rule, J2ObjC protos will also be generated, compiled and linked-in at the binary level. For proto `//some/proto/foo.proto`, users can reference the generated code using import path `some/proto/foo.j2objc.pb.h`.
`entry_classes`	`List of strings; optional` The list of Java classes whose translated ObjC counterparts will be referenced directly by user ObjC code. This attibute is required if flag `--j2objc_dead_code_removal` is on. The Java classes should be specified in their canonical names as defined by the Java Language Specification. When flag `--j2objc_dead_code_removal` is specified, the list of entry classes will be collected transitively and used as entry points to perform dead code analysis. Unused classes will then be removed from the final ObjC app bundle.
`jre_deps`	`List of labels; optional` The list of additional JRE emulation libraries required by all Java code translated by this `j2objc_library` rule. Only core JRE functionality is linked by default.

objc_import

objc_import(name, hdrs, alwayslink, archives, compatible_with, deprecation, distribs, features, includes, licenses, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, tags, testonly, textual_hdrs, visibility, weak_sdk_frameworks)

This rule encapsulates an already-compiled static library in the form of an .a file. It also allows exporting headers and resources using the same attributes supported by objc_library.

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`hdrs`	`List of labels; optional` The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead. These will be compiled separately from the source if modules are enabled.
`alwayslink`	`Boolean; optional; default is False` If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in `srcs` and `non_arc_srcs`, 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, e.g., if your code registers to receive some callback provided by some service.
`archives`	`List of labels; required` The list of `.a` files provided to Objective-C targets that depend on this target.
`includes`	`List of strings; optional` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `bazel-genfiles/pkg/includedir` and `bazel-out/pkg/includedir`) are included in addition to the actual client root. Unlike COPTS, 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. When in doubt, add "-iquote" flags to COPTS instead.
`sdk_dylibs`	`List of strings; optional` 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.
`sdk_frameworks`	`List of strings; optional` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). "UIKit" and "Foundation" are always included when building for the iOS, tvOS and watchOS platforms. For macOS, only "Foundation" is always included. When linking a top level binary (e.g. apple_binary), all SDK frameworks listed in that binary's transitive dependency graph are linked.
`sdk_includes`	`List of strings; optional` List of `#include/#import` search paths to add to this target and all depending targets, where each path is relative to `$(SDKROOT)/usr/include`.
`textual_hdrs`	`List of labels; optional` The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the sources.
`weak_sdk_frameworks`	`List of strings; optional` 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.

objc_library

objc_library(name, deps, srcs, data, hdrs, alwayslink, compatible_with, copts, defines, deprecation, distribs, enable_modules, exec_compatible_with, exec_properties, features, includes, licenses, module_map, module_name, non_arc_srcs, pch, restricted_to, runtime_deps, sdk_dylibs, sdk_frameworks, sdk_includes, tags, testonly, textual_hdrs, toolchains, visibility, weak_sdk_frameworks)

This rule produces a static library from the given Objective-C source files.

Implicit output targets

name_fully_linked.a: A fully linked static library that contains the full transitive closure of library dependencies.

Arguments

Attributes
`name`	`Name; required` A unique name for this target.
`deps`	`List of labels; optional` The list of targets that are linked together to form the final bundle.
`srcs`	`List of labels; optional` The list of C, C++, Objective-C, and Objective-C++ source and header files that are processed to create the library target. These are your checked-in files, plus any generated files. Source files are compiled into .o files with Clang. Header files may be included/imported by any source or header in the srcs attribute of this target, but not by headers in hdrs or any targets that depend on this rule. Additionally, precompiled .o files may be given as srcs. Be careful to ensure consistency in the architecture of provided .o files and that of the build to avoid missing symbol linker errors.
`hdrs`	`List of labels; optional` The list of C, C++, Objective-C, and Objective-C++ header files published by this library to be included by sources in dependent rules. These headers describe the public interface for the library and will be made available for inclusion by sources in this rule or in dependent rules. Headers not meant to be included by a client of this library should be listed in the srcs attribute instead. These will be compiled separately from the source if modules are enabled.
`alwayslink`	`Boolean; optional; default is False` If 1, any bundle or binary that depends (directly or indirectly) on this library will link in all the object files for the files listed in `srcs` and `non_arc_srcs`, 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, e.g., if your code registers to receive some callback provided by some service.
`copts`	`List of strings; optional` Extra flags to pass to the compiler. Subject to "Make variable" substitution and Bourne shell tokenization. These flags will only apply to this target, and not those upon which it depends, or those which depend on it. Note that for the generated Xcode project, directory paths specified using "-I" flags in copts are parsed out, prepended with "$(WORKSPACE_ROOT)/" if they are relative paths, and added to the header search paths for the associated Xcode target.
`defines`	`List of strings; optional` Extra `-D` flags to pass to the compiler. They should be in the form `KEY=VALUE` or simply `KEY` and are passed not only to the compiler for this target (as `copts` are) but also to all `objc_` dependers of this target. Subject to "Make variable" substitution and Bourne shell tokenization.
`enable_modules`	`Boolean; optional; default is False` Enables clang module support (via -fmodules). Setting this to 1 will allow you to @import system headers and other targets: @import UIKit; @import path_to_package_target;
`includes`	`List of strings; optional` List of `#include/#import` search paths to add to this target and all depending targets. This is to support third party and open-sourced libraries that do not specify the entire workspace path in their `#import/#include` statements. The paths are interpreted relative to the package directory, and the genfiles and bin roots (e.g. `bazel-genfiles/pkg/includedir` and `bazel-out/pkg/includedir`) are included in addition to the actual client root. Unlike COPTS, 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. When in doubt, add "-iquote" flags to COPTS instead.
`module_map`	`Label; optional` A custom Clang module map for this target. Use of a custom module map is discouraged. Most users should use module maps generated by Bazel. If specified, Bazel will not generate a module map for this target, but will pass the provided module map to the compiler.
`module_name`	`String; optional` Sets the 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.
`non_arc_srcs`	`List of labels; optional` The list of Objective-C files that are processed to create the library target that DO NOT use ARC. The files in this attribute are treated very similar to those in the srcs attribute, but are compiled without ARC enabled.
`pch`	`Label; optional` Header file to prepend to every source file being compiled (both arc and non-arc). Use of pch files is actively discouraged in BUILD files, and this should be considered deprecated. Since pch files are not actually precompiled this is not a build-speed enhancement, and instead is just a global dependency. From a build efficiency point of view you are actually better including what you need directly in your sources where you need it.
`runtime_deps`	`List of labels; optional` The list of framework targets that are late loaded at runtime. They are included in the app bundle but not linked against at build time.
`sdk_dylibs`	`List of strings; optional` 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.
`sdk_frameworks`	`List of strings; optional` Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore"). "UIKit" and "Foundation" are always included when building for the iOS, tvOS and watchOS platforms. For macOS, only "Foundation" is always included. When linking a top level binary (e.g. apple_binary), all SDK frameworks listed in that binary's transitive dependency graph are linked.
`sdk_includes`	`List of strings; optional` List of `#include/#import` search paths to add to this target and all depending targets, where each path is relative to `$(SDKROOT)/usr/include`.
`textual_hdrs`	`List of labels; optional` The list of C, C++, Objective-C, and Objective-C++ files that are included as headers by source files in this rule or by users of this library. Unlike hdrs, these will not be compiled separately from the sources.
`toolchains`	`List of labels; optional` The set of toolchains that supply "Make variables" that this target can use in some of its attributes. Some rules have toolchains whose Make variables they can use by default.
`weak_sdk_frameworks`	`List of strings; optional` 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.