src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm

#if (!$singlePage)
---
layout: documentation
title: Common Definitions
---
#end
#if (!$singlePage)
#parse("com/google/devtools/build/docgen/templates/be/header.vm")
#end

<h1 id="common-definitions">Common definitions</h1>

<p>This section defines various terms and concepts that are common to
many functions or build rules below.
</p>

#if (!$singlePage)
<div class="toc">
  <h1>Contents</h1>
  <ul>
    <li><a href="#sh-tokenization">Bourne shell tokenization</a></li>
    <li><a href="#label-expansion">Label Expansion</a></li>
    <li><a href="#common-attributes">Attributes common to all build rules</a></li>
    <li><a href="#common-attributes-tests">Attributes common to all test rules (*_test)</a></li>
    <li><a href="#common-attributes-binaries">Attributes common to all binary rules (*_binary)</a></li>
    <li><a href="#configurable-attributes">Configurable attributes</a></li>
    <li><a href="#implicit-outputs">Implicit output targets</a></li>
  </ul>
</div>
#end
<h2 id='sh-tokenization'>Bourne shell tokenization</h2>
<p>
  Certain string attributes of some rules are split into multiple
  words according to the tokenization rules of the Bourne shell:
  unquoted spaces delimit separate words, and single- and
  double-quotes characters and backslashes are used to prevent
  tokenization.
</p>
<p>
  Those attributes that are subject to this tokenization are
  explicitly indicated as such in their definitions in this document.
</p>
<p>
  Attributes subject to "Make" variable expansion and Bourne shell
  tokenization are typically used for passing arbitrary options to
  compilers and other tools. Examples of such attributes are
  <code>cc_library.copts</code> and <code>java_library.javacopts</code>.
  Together these substitutions allow a
  single string variable to expand into a configuration-specific list
  of option words.
</p>

<h2 id='label-expansion'>Label expansion</h2>
<p>
  Some string attributes of a very few rules are subject to label
  expansion: if those strings contain a valid label as a
  substring, such as <code>//mypkg:target</code>, and that label is a
  declared prerequisite of the current rule, it is expanded into the
  pathname of the file represented by the target <code>//mypkg:target</code>.
</p>

<p>
  Example attributes include <code>genrule.cmd</code> and
  <code>cc_binary.linkopts</code>.  The details may vary significantly in
  each case, over such issues as: whether relative labels are
  expanded; how labels that expand to multiple files are
  treated, etc.  Consult the rule attribute documentation for
  specifics.
</p>

<h2 id="common-attributes">Attributes common to all build rules</h2>

#macro(commonAttributeDoc $type $attributeMap)
  <table class="table table-condensed table-bordered table-params">
    <colgroup>
      <col class="col-param" />
      <col class="param-description" />
    </colgroup>
    <thead>
      <tr>
        <th>Attribute</th>
        <th>Description</th>
      </tr>
    </thead>
    <tbody>
  #foreach ($name in $attributeMap.keySet())
      <tr>
        <td id="${type}.${name}"><code>${name}</code></td>
        <td>${attributeMap.get($name).htmlDocumentation}</td>
      </tr>
  #end
    </tbody>
  </table>
#end

<p>This section describes attributes that are common to all build rules.<br/>
Please note that it is an error to list the same label twice in a list of
labels attribute.
</p>

#commonAttributeDoc("common" $commonAttributes)

<h2 id="common-attributes-tests">Attributes common to all test rules (*_test)</h2>

<p>This section describes attributes that are common to all test rules.</p>

#commonAttributeDoc("test" $testAttributes)

<h2 id="common-attributes-binaries">Attributes common to all binary rules (*_binary)</h2>

<p>This section describes attributes that are common to all binary rules.</p>

#commonAttributeDoc("binary" $binaryAttributes)

<h2 id="configurable-attributes">Configurable attributes</h2>

<p>
  Most attributes are "configurable", meaning that their values may change when
  the target is built in different ways. Specifically, configurable attributes
  may vary based on the flags passed to the Bazel command line, or what
  downstream dependency is requesting the target. This can be used, for
  instance, to customize the target for multiple platforms or compilation modes.
</p>

<p>
  The following example declares different sources for different target
  architectures. Running <code>bazel build :multiplatform_lib --cpu x86</code>
  will build the target using <code>x86_impl.cc</code>, while substituting
  <code>--cpu arm</code> will instead cause it to use <code>arm_impl.cc</code>.
</p>

<pre class="code">
cc_library(
    name = "multiplatform_lib",
    srcs = select({
        ":x86_mode": ["x86_impl.cc"],
        ":arm_mode": ["arm_impl.cc"]
    })
)
config_setting(
    name = "x86_mode",
    values = { "cpu": "x86" }
)
config_setting(
    name = "arm_mode",
    values = { "cpu": "arm" }
)
</pre>

<p>
  The <a href="$expander.expandRef("select")"><code>select()</code></a> function
  chooses among different alternative values for a configurable attribute based
  on which <a href="$expander.expandRef("config_setting")">
  <code>config_setting</code></a> criteria is satisfied in the current
  configuration.
</p>

<p>
  Configurable attributes are evaluated after the processing of macros and
  before the processing of rules (technically, between the
  <a href="https://docs.bazel.build/versions/master/skylark/concepts.html#evaluation-model">
  loading and analysis phases</a>.
  Any processing that Bazel does before the <code>select()</code> is evaluated
  will not know which branch will be chosen. In particular, macros can't change
  their behavior based on the chosen branch, and <code>bazel query</code> can
  only make conservative guesses about the configurable dependencies of a
  target. Conversely, when authoring a new type of rule, you do not need to
  worry about the ambiguity of configurable attributes because all
  <code>select()</code> expressions have already been replaced by their resolved
  values. See
  <a href="https://docs.bazel.build/versions/master/configurable-attributes.html#faq">
  this FAQ</a>
  for more on using <code>select()</code> with rules and macros.
</p>

<p>
  Attributes marked <code>nonconfigurable</code> in their documentation cannot
  use this feature. Usually an attribute is nonconfigurable because Bazel
  internally needs to know its value before it can determine how to choose the
  <code>select()</code> branch.
</p>

<p>
  See <a href="https://docs.bazel.build/versions/master/configurable-attributes.html">
  Configurable Build Attributes</a> for more information.
</p>

<h2 id="implicit-outputs">Implicit output targets</h2>

<p>
  <i>Implicit outputs in C++ are deprecated. Please refrain from using it
  in other languages where possible. We don't have a deprecation path yet
  but they will eventually be deprecated too.</i>
</p>

<p>When you define a build rule in a BUILD file, you are explicitly
  declaring a new, named rule target in a package.  Many build rule
  functions also <i>implicitly</i> entail one or more output file
  targets, whose contents and meaning are rule-specific.

  For example, when you explicitly declare a
  <code>java_binary(name='foo', ...)</code> rule, you are also
  <i>implicitly</i> declaring an output file
  target <code>foo_deploy.jar</code> as a member of the same package.
  (This particular target is a self-contained Java archive suitable
  for deployment.)
</p>

<p>
  Implicit output targets are first-class members of the global
  target graph.  Just like other targets, they are built on demand,
  either when specified in the top-level built command, or when they
  are necessary prerequisites for other build targets.  They can be
  referenced as dependencies in BUILD files, and can be observed in
  the output of analysis tools such as <code>bazel query</code>.
</p>

<p>
  For each kind of build rule, the rule's documentation contains a
  special section detailing the names and contents of any implicit
  outputs entailed by a declaration of that kind of rule.
</p>

<p>
  An important but somewhat subtle distinction between the
  two namespaces used by the build system:
  <a href="../build-ref.html#labels">labels</a> identify <em>targets</em>,
  which may be rules or files, and file targets may be divided into
  either source (or input) file targets and derived (or output) file
  targets.  These are the things you can mention in BUILD files,
  build from the command-line, or examine using <code>bazel query</code>;
  this is the <em>target namespace</em>.  Each file target corresponds
  to one actual file on disk (the "file system namespace"); each rule
  target may correspond to zero, one or more actual files on disk.
  There may be files on disk that have no corresponding target; for
  example, <code>.o</code> object files produced during C++ compilation
  cannot be referenced from within BUILD files or from the command line.
  In this way, the build tool may hide certain implementation details of
  how it does its job. This is explained more fully in
  the <a href="../build-ref.html">BUILD Concept Reference</a>.
</p>

#if (!$singlePage)
#parse("com/google/devtools/build/docgen/templates/be/footer.vm")
#end