Objective-C Rules

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Rules

j2objc_library

View rule source 
j2objc_library(name, deps, compatible_with, deprecation, distribs, entry_classes, features, jre_deps, licenses, restricted_to, tags, target_compatible_with, 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; default is []

A list of j2objc_library, java_library, java_import and java_proto_library 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, including files generated by Java annotation processing. There is no support for code>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; default is []

The list of Java classes whose translated ObjC counterparts will be referenced directly by user ObjC code. This attribute 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; default is []

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

View rule source 
objc_import(name, deps, hdrs, alwayslink, archives, compatible_with, deprecation, distribs, features, includes, licenses, restricted_to, sdk_dylibs, sdk_frameworks, sdk_includes, tags, target_compatible_with, 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.
deps

List of labels; default is []

The list of targets that this target depend on.
hdrs

List of labels; default is []

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.

Boolean; 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; default is []

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. blaze-genfiles/pkg/includedir and blaze-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; default is []

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; default is []

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 Apple binary, all SDK frameworks listed in that binary's transitive dependency graph are linked.

sdk_includes

List of strings; default is []

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; default is []

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; default is []

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

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

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

Arguments

Attributes
name

Name; required

A unique name for this target.
deps

List of labels; default is []

The list of targets that are linked together to form the final bundle.
srcs

List of labels; default is []

The list of C, C++, Objective-C, and Objective-C++ source and header files, and/or (`.s`, `.S`, or `.asm`) assembly source 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; default is []

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.

Boolean; 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; default is []

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; default is []

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; 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;
implementation_deps

List of labels; default is []

The list of other libraries that the library target depends on. Unlike with deps, the headers and include paths of these libraries (and all their transitive deps) are only used for compilation of this library, and not libraries that depend on it. Libraries specified with implementation_deps are still linked in binary targets that depend on this library.
includes

List of strings; default is []

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. blaze-genfiles/pkg/includedir and blaze-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.

linkopts

List of strings; default is []

Extra flags to pass to the linker.
module_map

Label; default is None

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; default is ""

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; default is []

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; default is None

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.
sdk_dylibs

List of strings; default is []

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; default is []

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 Apple binary, all SDK frameworks listed in that binary's transitive dependency graph are linked.

sdk_includes

List of strings; default is []

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; default is []

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; default is []

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.

available_xcodes

View rule source 
available_xcodes(name, default, deprecation, distribs, features, licenses, tags, testonly, versions, visibility)

Two targets of this rule can be depended on by an xcode_config rule instance to indicate the remotely and locally available xcode versions. This allows selection of an official xcode version from the collectively available xcodes.

Arguments

Attributes
name

Name; required

A unique name for this target.
default

Label; nonconfigurable; required

The default xcode version for this platform.
versions

List of labels; nonconfigurable; default is []

The xcode versions that are available on this platform.

xcode_config

View rule source 
xcode_config(name, default, deprecation, distribs, features, licenses, local_versions, remote_versions, tags, testonly, versions, visibility)

A single target of this rule can be referenced by the --xcode_version_config build flag to translate the --xcode_version flag into an accepted official xcode version. This allows selection of an official xcode version from a number of registered aliases.

Arguments

Attributes
name

Name; required

A unique name for this target.
default

Label; nonconfigurable; default is None

The default official version of xcode to use. The version specified by the provided xcode_version target is to be used if no xcode_version build flag is specified. This is required if any versions are set. This may not be set if remote_versions or local_versions is set.
local_versions

Label; nonconfigurable; default is None

The xcode_version targets that are available locally. These are used along with local_versions to select a mutually available version. This may not be set if versions is set.
remote_versions

Label; nonconfigurable; default is None

The xcode_version targets that are available remotely. These are used along with remote_versions to select a mutually available version. This may not be set if versions is set.
versions

List of labels; nonconfigurable; default is []

Accepted xcode_version targets that may be used. If the value of the xcode_version build flag matches one of the aliases or version number of any of the given xcode_version targets, the matching target will be used. This may not be set if remote_versions or local_versions is set.

xcode_version

View rule source 
xcode_version(name, default_ios_sdk_version, default_macos_sdk_version, default_tvos_sdk_version, default_visionos_sdk_version, default_watchos_sdk_version, deprecation, distribs, features, licenses, tags, testonly, version, visibility)

Represents a single official xcode version with acceptable aliases for that xcode version. See the xcode_config rule.

Arguments

Attributes
name

Name; required

A unique name for this target.
default_ios_sdk_version

String; nonconfigurable; default is ""

The ios sdk version that is used by default when this version of xcode is being used. The ios_sdk_version build flag will override the value specified here.
default_macos_sdk_version

String; nonconfigurable; default is ""

The macosx sdk version that is used by default when this version of xcode is being used. The macos_sdk_version build flag will override the value specified here.
default_tvos_sdk_version

String; nonconfigurable; default is ""

The tvos sdk version that is used by default when this version of xcode is being used. The tvos_sdk_version build flag will override the value specified here.
default_visionos_sdk_version

String; nonconfigurable; default is ""

The visionos sdk version that is used by default when this version of xcode is being used. The visionos_sdk_version build flag will override the value specified here.
default_watchos_sdk_version

String; nonconfigurable; default is ""

The watchos sdk version that is used by default when this version of xcode is being used. The watchos_sdk_version build flag will override the value specified here.
version

String; nonconfigurable; required

The official version number of a version of Xcode.