Google Git
Sign in
bazel/bazel/a640dc240f79ef811fb4089436f1ba6d84ea6bc9/./docs/versions/8.1.0/reference/be/objective-c.mdx
blob: effb6a21db73b24f14bb9f4f1b3969895decf68f [file]
<html devsite>
<head>
<meta name="project_path" value="/_project.yaml">
<meta name="book_path" value="/versions/8.1.0/_book.yaml">
</head>
<body>
<!--
This document is synchronized with Bazel releases.
To edit, submit changes to the Bazel source code.
-->
<!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip -->
<html>
<body>
<h1 class="page-title">Objective-C Rules</h1>
{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %}
{% dynamic setvar version "8.1.0" %}
{% dynamic setvar original_path "/reference/be/objective-c" %}
{% include "_buttons.html" %}
<h2>Rules</h2>
<ul>
<li>
<a href="#objc_import">
objc_import </a>
</li>
<li>
<a href="#objc_library">
objc_library </a>
</li>
</ul>
<h2 id="objc_import">
objc_import
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_import.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">objc_import(<a href="#objc_import.name">name</a>, <a href="#objc_import.deps">deps</a>, <a href="#objc_import.hdrs">hdrs</a>, <a href="#objc_import.alwayslink">alwayslink</a>, <a href="#objc_import.archives">archives</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#objc_import.includes">includes</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#objc_import.sdk_dylibs">sdk_dylibs</a>, <a href="#objc_import.sdk_frameworks">sdk_frameworks</a>, <a href="#objc_import.sdk_includes">sdk_includes</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#objc_import.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#objc_import.weak_sdk_frameworks">weak_sdk_frameworks</a>)</pre>
<p>This rule encapsulates an already-compiled static library in the form of an
<code>.a</code> file. It also allows exporting headers and resources using the same
attributes supported by <code>objc_library</code>.</p>
<h3 id="objc_import_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="objc_import.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="objc_import.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of targets that this target depend on.
</td>
</tr>
<tr>
<td id="objc_import.hdrs">
<code>hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of C, C++, Objective-C, and Objective-C++ header files published
by this library to be included by sources in dependent rules.
<p>
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.
<p>
These will be compiled separately from the source if modules are enabled.
</td>
</tr>
<tr>
<td id="objc_import.alwayslink">
<code>alwayslink</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
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
<code>srcs</code> and <code>non_arc_srcs</code>, 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.
</td>
</tr>
<tr>
<td id="objc_import.archives">
<code>archives</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; required</p>
The list of <code>.a</code> files provided to Objective-C targets that
depend on this target.
</td>
</tr>
<tr>
<td id="objc_import.includes">
<code>includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of <code>#include/#import</code> 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
<code>#import/#include</code> statements.
<p>
The paths are interpreted relative to the package directory, and the
genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code>
and <code>blaze-out/pkg/includedir</code>) are included in addition to the
actual client root.
<p>
Unlike <a href="/versions/8.1.0/reference/be/objective-c.html#objc_library.copts">COPTS</a>, 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 <a href="/versions/8.1.0/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead.
</td>
</tr>
<tr>
<td id="objc_import.sdk_dylibs">
<code>sdk_dylibs</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_import.sdk_frameworks">
<code>sdk_frameworks</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore").
<p> When linking a top level Apple binary, all SDK frameworks listed in that binary's
transitive dependency graph are linked.
</td>
</tr>
<tr>
<td id="objc_import.sdk_includes">
<code>sdk_includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of <code>#include/#import</code> search paths to add to this target
and all depending targets, where each path is relative to
<code>$(SDKROOT)/usr/include</code>.
</td>
</tr>
<tr>
<td id="objc_import.textual_hdrs">
<code>textual_hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_import.weak_sdk_frameworks">
<code>weak_sdk_frameworks</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
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.
</td>
</tr>
</tbody>
</table>
<h2 id="objc_library">
objc_library
</h2>
<a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/starlark/builtins_bzl/common/objc/objc_library.bzl" target="_blank">
View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span>
</a>
<pre class="rule-signature">objc_library(<a href="#objc_library.name">name</a>, <a href="#objc_library.deps">deps</a>, <a href="#objc_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#objc_library.hdrs">hdrs</a>, <a href="#objc_library.alwayslink">alwayslink</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="#objc_library.conlyopts">conlyopts</a>, <a href="#objc_library.copts">copts</a>, <a href="#objc_library.cxxopts">cxxopts</a>, <a href="#objc_library.defines">defines</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="#objc_library.enable_modules">enable_modules</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#objc_library.implementation_deps">implementation_deps</a>, <a href="#objc_library.includes">includes</a>, <a href="#objc_library.linkopts">linkopts</a>, <a href="#objc_library.module_map">module_map</a>, <a href="#objc_library.module_name">module_name</a>, <a href="#objc_library.non_arc_srcs">non_arc_srcs</a>, <a href="#objc_library.pch">pch</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#objc_library.sdk_dylibs">sdk_dylibs</a>, <a href="#objc_library.sdk_frameworks">sdk_frameworks</a>, <a href="#objc_library.sdk_includes">sdk_includes</a>, <a href="#objc_library.stamp">stamp</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="#objc_library.textual_hdrs">textual_hdrs</a>, <a href="common-definitions.html#common.toolchains">toolchains</a>, <a href="common-definitions.html#common.visibility">visibility</a>, <a href="#objc_library.weak_sdk_frameworks">weak_sdk_frameworks</a>)</pre>
<p>This rule produces a static library from the given Objective-C source files.</p>
<h3 id="objc_library_args">Arguments</h3>
<table class="table table-condensed table-bordered table-params">
<colgroup>
<col class="col-param" />
<col class="param-description" />
</colgroup>
<thead>
<tr>
<th colspan="2">Attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td id="objc_library.name"><code>name</code></td>
<td>
<p><a href="/versions/8.1.0/concepts/labels#target-names">Name</a>; required</p>
<p>A unique name for this target.</p>
</td>
</tr>
<tr>
<td id="objc_library.deps">
<code>deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of targets that this target depend on.
</td>
</tr>
<tr>
<td id="objc_library.srcs">
<code>srcs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.hdrs">
<code>hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of C, C++, Objective-C, and Objective-C++ header files published
by this library to be included by sources in dependent rules.
<p>
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.
<p>
These will be compiled separately from the source if modules are enabled.
</td>
</tr>
<tr>
<td id="objc_library.alwayslink">
<code>alwayslink</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
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
<code>srcs</code> and <code>non_arc_srcs</code>, 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.
</td>
</tr>
<tr>
<td id="objc_library.conlyopts">
<code>conlyopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Extra flags to pass to the compiler for C files.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
These flags will only apply to this target, and not those upon which
it depends, or those which depend on it.
<p>
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.
</td>
</tr>
<tr>
<td id="objc_library.copts">
<code>copts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Extra flags to pass to the compiler.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
These flags will only apply to this target, and not those upon which
it depends, or those which depend on it.
<p>
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.
</td>
</tr>
<tr>
<td id="objc_library.cxxopts">
<code>cxxopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Extra flags to pass to the compiler for Objective-C++ and C++ files.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
These flags will only apply to this target, and not those upon which
it depends, or those which depend on it.
<p>
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.
</td>
</tr>
<tr>
<td id="objc_library.defines">
<code>defines</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Extra <code>-D</code> flags to pass to the compiler. They should be in
the form <code>KEY=VALUE</code> or simply <code>KEY</code> and are
passed not only to the compiler for this target (as <code>copts</code>
are) but also to all <code>objc_</code> dependers of this target.
Subject to <a href="/versions/8.1.0/reference/be/make-variables">"Make variable"</a> substitution and
<a href="/versions/8.1.0/reference/be/common-definitions#sh-tokenization">Bourne shell tokenization</a>.
</td>
</tr>
<tr>
<td id="objc_library.enable_modules">
<code>enable_modules</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
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;
</td>
</tr>
<tr>
<td id="objc_library.implementation_deps">
<code>implementation_deps</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
The list of other libraries that the library target depends on. Unlike with
<code>deps</code>, 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 <code>implementation_deps</code> are still linked
in binary targets that depend on this library.
</td>
</tr>
<tr>
<td id="objc_library.includes">
<code>includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of <code>#include/#import</code> 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
<code>#import/#include</code> statements.
<p>
The paths are interpreted relative to the package directory, and the
genfiles and bin roots (e.g. <code>blaze-genfiles/pkg/includedir</code>
and <code>blaze-out/pkg/includedir</code>) are included in addition to the
actual client root.
<p>
Unlike <a href="/versions/8.1.0/reference/be/objective-c.html#objc_library.copts">COPTS</a>, 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 <a href="/versions/8.1.0/reference/be/objective-c.html#objc_library.copts">COPTS</a> instead.
</td>
</tr>
<tr>
<td id="objc_library.linkopts">
<code>linkopts</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Extra flags to pass to the linker.
</td>
</tr>
<tr>
<td id="objc_library.module_map">
<code>module_map</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.module_name">
<code>module_name</code>
</td>
<td>
<p>String; default is <code>""</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.non_arc_srcs">
<code>non_arc_srcs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.pch">
<code>pch</code>
</td>
<td>
<p><a href="/versions/8.1.0/concepts/labels">Label</a>; default is <code>None</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.sdk_dylibs">
<code>sdk_dylibs</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.sdk_frameworks">
<code>sdk_frameworks</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
Names of SDK frameworks to link with (e.g. "AddressBook", "QuartzCore").
<p> When linking a top level Apple binary, all SDK frameworks listed in that binary's
transitive dependency graph are linked.
</td>
</tr>
<tr>
<td id="objc_library.sdk_includes">
<code>sdk_includes</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
List of <code>#include/#import</code> search paths to add to this target
and all depending targets, where each path is relative to
<code>$(SDKROOT)/usr/include</code>.
</td>
</tr>
<tr>
<td id="objc_library.stamp">
<code>stamp</code>
</td>
<td>
<p>Boolean; default is <code>False</code></p>
</td>
</tr>
<tr>
<td id="objc_library.textual_hdrs">
<code>textual_hdrs</code>
</td>
<td>
<p>List of <a href="/versions/8.1.0/concepts/labels">labels</a>; default is <code>[]</code></p>
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.
</td>
</tr>
<tr>
<td id="objc_library.weak_sdk_frameworks">
<code>weak_sdk_frameworks</code>
</td>
<td>
<p>List of strings; default is <code>[]</code></p>
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.
</td>
</tr>
</tbody>
</table>
<!-- Generated footer -->
</body>
</html>