src/main/java/com/google/devtools/build/docgen/templates/build-encyclopedia.vm

#parse("com/google/devtools/build/docgen/templates/header-comment.vm")

#parse("com/google/devtools/build/docgen/templates/be-header.vm")

#macro(ruledoc $ruleDocs)
  #foreach ($rule in $ruleDocs)
    <h3 id="${rule.ruleName}"#if($rule.isDeprecated()) class="deprecated"#end>
      ${rule.ruleName}
    </h3>

    <pre class="rule-signature">${rule.attributeSignature}</pre>

    $rule.htmlDocumentation

    <h4 id="${rule.ruleName}_args">Arguments</h4>
    <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>
        <tr>
          <td id="${rule.ruleName}.name"><code>name</code></td>
          <td>
            <p><code><a href="build-ref.html#name">Name</a>; required</code></p>
            <p>A unique name for this rule.</p>
            ${rule.nameExtraHtmlDoc}
          </td>
        </tr>
      #foreach ($attribute in $rule.attributes)
        #if (!$attribute.isCommonType())
        <tr>
          <td id="${rule.ruleName.toLowerCase()}.${attribute.attributeName}"#if($attribute.isDeprecated()) class="deprecated"#end>
            <code>${attribute.attributeName}</code>
          </td>
          <td>
            #if (!$attribute.synopsis.isEmpty())
            <p><code>${attribute.synopsis}</code></p>
            #end
            $attribute.htmlDocumentation
          </td>
        </tr>
        #end
      #end
      </tbody>
    </table>
    #if ($rule.isPublicByDefault())
      The default visibility is public: <code>visibility = ["//visibility:public"]</code>.
    #end
  #end
#end

<!-- ============================================
                      binary
     ============================================
-->
<h2 id="binary">*_binary</h2>

<p>A <code>*_binary</code> rule compiles an application. This might be
   an executable, a <code>.jar</code> file, and/or a collection of scripts.</p>

#ruledoc($binaryDocs)

<!-- ============================================
                      library
     ============================================
-->
<h2 id="library">*_library</h2>

<p>A <code>*_library()</code> rule compiles some sources into a library.
   In general, a <code><var>language</var>_library</code> rule works like
   the corresponding <code><var>language</var>_binary</code> rule, but
   doesn't generate an executable.</p>

#ruledoc($libraryDocs)

<!-- ============================================
                      test
     ============================================
-->
<h2 id="test">*_test</h2>

<p>A <code>*_test</code> rule compiles a test.

#ruledoc($testDocs)

<!-- ============================================
                      variables
     ============================================
-->
<h2 id="make_variables">"Make" Variables</h2>


<p>
  This section describes how to use a special class of built-in string variables
  that are called the "Make" environment.

  Defining custom "Make" variables is not supported.
</p>

<p>(The reason for the term "Make" is historical: the syntax and semantics of
  these variables are somewhat similar to those of GNU Make.)
</p>

<p>To see the list of all common "Make" variables and their values,
  run <code>bazel info --show_make_env</code>.
</p>

<p>Build rules can introduce additional rule specific variables. One example is
  the <a href="#genrule.cmd"><code>cmd</code> attribute of a genrule</a>.
</p>

<h3 id='make-var-substitution'>"Make" variable substitution</h3>

<p>Variables can be referenced in attributes

  using <code>$(FOO)</code>
  where <code>FOO</code> is
  the variable name. In the attribute documentation of rules, it is mentioned
  when an attribute is subject to "Make" variable substitution. For those
  attributes this means that any substrings of the form <code>$(X)</code>
  within those attributes will be interpreted as references to the "Make"
  variable <var>X</var>, and will be replaced by the appropriate value of that
  variable for the applicable build configuration. The parens may be omitted
  for variables whose name is a single character.
</p>
<p>
  It is an error if such attributes contain embedded strings of the
  form <code>$(X)</code> where <var>X</var> is not the name of a
  "Make" variable, or unclosed references such as <code>$(</code> not
  matched by a corresponding <code>)</code>.
</p>
<p>
  Within such attributes, literal dollar signs must be escaped
  as <code>$$</code> to prevent this expansion.
</p>
<p>
  Those attributes that are subject to this substitution are
  explicitly indicated as such in their definitions in this document.
</p>

<h3 id="predefined_variables">Predefined "Make" Variables</h3>

<p>Bazel defines a set of "Make" variables for you.</p>

<p>The build system also provides a consistent PATH environment variable for
genrules and tests which need to execute shell commands. For genrules, you can
indirect your commands using the "Make" variables below.  For basic Unix
utilities, prefer relying on the PATH environment variable to guarantee correct
results. For genrules involving compiler and platform invocation, you must use
the "Make" variable syntax.  The same basic command set is also available during
tests. Simply rely on the PATH.</p>

<p><strong>Compiler and Platforms available to genrules</strong></p>
These tools may not be in the PATH, therefore you must use "Make" variable syntax
in your genrule's cmd attribute.
<ul>
  <li> <code>CC</code>: The C compiler command. It is strongly recommended to
    always use <code>CC_FLAGS</code> when invoking the C compiler.</li>
  <li> <code>JAVA</code>: The "java" command (a Java virtual machine). Note that
    this can be a relative path. If you must change directories before invoking
    <code>java</code>, you need to capture the working directory before changing
    it.</li>
  <li> <code>JAVAC</code>: The "javac" command (a Java compiler). Note that
    this can be a relative path. Also, this may not be the same compiler that is
    used to compile normal Java rules (this may change in the future).</li>

  <li> <code>STRIP</code>: The strip command from the same suite as the C
    compiler.</li>
  <li> <code>AR</code>: The "ar" command from crosstool. </li>
  <li> <code>NM</code>: The "nm" command from crosstool. </li>
  <li> <code>OBJCOPY</code>: The objcopy command from the same suite as the C
    compiler. </li>
  <li> <code>C_COMPILER</code>:
    The C compiler frontend, e.g. "gcc". </li>
</ul>

<p><strong>Tool option Variables</strong></p>

<ul><!--  keep alphabetically sorted  -->
  <li><code>BINMODE</code>: "-dbg" or "-opt"

    . (<i>When using Bazel's <code>-c fastbuild</code> option,
      this variable has the value <code>-dbg</code>.</i>) </li>
  <li><code>CC_FLAGS</code>: A minimal set of flags for the C compiler to be
    used by genrules. In particular, it contains flags to select the correct
    architecture if CC supports multiple architectures. </li>
  <li><code>COMPILATION_MODE</code>: "fastbuild", "dbg", or "opt".</li>

</ul>

<p><strong>Path Variables</strong></p>

<ul><!--  keep alphabetically sorted  -->
  <li><code>BINDIR</code>: The base of the generated binary tree for the target
    architecture.  (Note that a different tree may be used for
    programs that run during the build on the host architecture,
    to support cross-compiling.  If you want to run a tool from
    within a genrule, the recommended way of specifying the path to
    the tool is to use <code>$(location <i>toolname</i>)</code>,
    where <i>toolname</i> must be listed in the <code>tools</code>
    attribute for the genrule.</li>
  <li><code>GENDIR</code>: The base of the generated code
    tree for the target architecture.</li>
  <li><code>JAVABASE</code>:
    The base directory containing the Java utilities.
    It will have a "bin" subdirectory.</li>
</ul>

<p><strong>Architecture Variables</strong></p>

<ul><!--  keep alphabetically sorted  -->
  <li><code>ABI</code>:
    The C++ ABI version; currently "gcc-3.4". </li>

  <li> <code>TARGET_CPU</code>: The target architecture's cpu,
    e.g. "piii" or "k8". </li>
</ul>

<p id="predefined_variables.genrule.cmd">
  <strong>
    Other Variables available to <a href="#genrule.cmd">the cmd attribute of a genrule</a>
  </strong>
</p>
<ul><!--  keep alphabetically sorted  -->
  <li><code>OUTS</code>: The <code>outs</code> list. If you have only one output
    file, you can also use <code>$@</code>.</li>
  <li><code>SRCS</code>: The <code>srcs</code> list (or more
    precisely, the pathnames of the files corresponding to
    labels in the <code>srcs</code> list).  If you have only one
    source file, you can also use <code>$&lt;</code>.</li>
  <li><code>&lt;</code>: <code>srcs</code>, if it is a single file.</li>
  <li><code>@</code>: <code>outs</code>, if it is a single file.</li>
  <li><code>@D</code>: The output directory.  If there is only
    one filename in <code>outs</code>, this expands to the
    directory containing that file.  If there are multiple
    filenames, this variable instead expands to the package's root
    directory in the <code>genfiles</code> tree, <i>even if all
    the generated files belong to the same subdirectory</i>!
    <!-- (as a consequence of the "middleman" implementation) -->
    If the genrule needs to generate temporary intermediate files
    (perhaps as a result of using some other tool like a compiler)
    then it should attempt to write the temporary files to
    <code>@D</code> (although <code>/tmp</code> will also be
    writable), and to remove any such generated temporary files.
    Especially, avoid writing to directories containing inputs -
    they may be on read-only filesystems, and even if they aren't,
    doing so would trash the source tree.</li>
</ul>

<h2 id="location">"$(location)" substitution</h2>

<p>
  In attributes that support it, all occurrences of
  <code>$(location <i>label</i>)</code> are replaced by the path to the
  file denoted by <i>label</i>. Use <code>location</code> if the <i>label</i>
  outputs exactly one filename. This allows bazel to perform a check and give
  an error if no or more than one files are represented by the given label; a
  label referring to a source file always represents a single file, but a label
  referring to a rule refers to all output files of that rule. Otherwise use
  <code>$(location<b>s</b> <i>label</i>)</code>; bazel will then raise an error
  if no files are generated. In both cases, if the label is malformed then an
  error is raised.
</p>
<p>
  The <i>label</i> needs not be in canonical form:
  <code>foo</code>, <code>:foo</code> and <code>//somepkg:foo</code> are
  all fine. It may also be the name of an output file from the
  <code>outs</code> attribute.
</p>
<p>
  The expanded paths are relative to the runfiles directory of the
  <code>*_test</code> or <code>*_binary</code> rule.
</p>

<h2 id="predefined-python-variables">Predefined Python Variables</h2>

<h3 id="packagename">PACKAGE_NAME</h3>
<p>
  This is a string variable with the name
  of the package being evaluated. The value is unaffected by subinclude.
</p>

<!-- ============================================
                      other
     ============================================
-->
<h2 id="misc">Other Stuff</h2>

#ruledoc($otherDocs)


#parse("com/google/devtools/build/docgen/templates/be-footer.vm")