src/main/java/com/google/devtools/build/docgen/templates/be-header.vm - bazel - Git at Google

 <html>
 <head>

   <title>Bazel BUILD Encyclopedia of Functions</title>
   <link href="docs_style.css" rel="stylesheet" type="text/css" />
 </head>

 <body>
 <div style="width:100%;">
 <div id="left-panel" style="margin-left:-80px;height:97%;float:left;position:fixed;overflow-y:scroll;overflow-x:hidden;border-right:thin solid #000000;resize:horizontal;">
 <h3 style="margin-left:0px">Rules:</h3>

 ${LEFT_PANEL}

 </div>
 <div id="main-panel" style="margin-left:200px">

 <h1>Bazel BUILD Encyclopedia of Functions</h1>
 <h2>Contents</h2>

   <h3>Concepts and terminology</h3>
   <table class="layout"><tr><td>
   <ul class="be-toc">
     <li><a href="#common-definitions">Common definitions</a>:
       <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">Common attributes</a></li>
       <li><a href="#common-attributes-tests">Common attributes for tests</a></li>
       <li><a href="#common-attributes-binaries">Common attributes for binaries</a></li>
       <li><a href="#configurable-attributes">Configurable attributes</a></li>
       <li><a href="#implicit-outputs">Implicit output targets</a></li>
       </ul>
     </li>
   </ul>
   </td><td>
   <ul class="be-toc">
     <li><a href="#make_variables">"Make" variables</a>
     <ul class="be-toc">
       <li><a href="#make-var-substitution">"Make" variable substitution</a></li>
       <li><a href="#predefined_variables">Predefined variables</a></li>

     </ul>
     <li><a href="#predefined-python-variables">Predefined Python Variables</a></li>
   </ul>
   </td><td>
   <ul class="be-toc">
     <li><a href="#load">load</a></li>

     <li><a href="#package">package</a></li>
     <li><a href="#package_group">package_group</a></li>

     <li><a href="#licenses">licenses</a></li>
     <li><a href="#exports_files">exports_files</a></li>
     <li><a href="#glob">glob</a></li>
     <li><a href="#select">select</a></li>
     <li><a href="#workspace">workspace</a></li>
   </ul>
   </td></tr></table>

   <h3>Rules</h3>

 <h4>Language-specific Rules</h4>

 #macro(summaryTable $ruleFamilies)
   <tbody>
   #foreach($ruleFamily in $ruleFamilies)
     <tr>
       <td class="lang">${ruleFamily.name}</td>
       <td>
     #foreach($ruleDoc in $ruleFamily.binaryRules)
         <a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
           ${ruleDoc.ruleName}
         </a>
         <br />
     #end
       </td>
       <td>
     #foreach($ruleDoc in $ruleFamily.libraryRules)
         <a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
           ${ruleDoc.ruleName}
         </a>
         <br />
     #end
       </td>
       <td>
     #foreach($ruleDoc in $ruleFamily.testRules)
         <a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
           ${ruleDoc.ruleName}
         </a>
         <br />
     #end
       </td>
       <td>
     #foreach($ruleDoc in $ruleFamily.otherRules1)
         <a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
           ${ruleDoc.ruleName}
         </a>
         <br />
     #end
       </td>
       <td>
     #foreach($ruleDoc in $ruleFamily.otherRules2)
         <a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
           ${ruleDoc.ruleName}
         </a>
         <br />
     #end
       </td>
     </tr>
   #end
   </tbody>
 #end

 <table class="table table-condensed table-striped" summary="Table of rules sorted by language">
   <colgroup span="6" width="20%"></colgroup>
   <thead>
     <tr>
       <th>Language</th>
       <th>Binary rules</th>
       <th>Library rules</th>
       <th>Test rules</th>
       <th>Other rules</th>
       <th></th>
     </tr>
   </thead>
 #summaryTable($langSpecificSummaryFamilies)

 </table>
 <h4>Rules that do not apply to a specific programming language</h4>

 <table class="table table-condensed table-striped" summary="Table of rules not specific to a programming language">
   <colgroup span="6" width="20%"></colgroup>
 #summaryTable($otherSummaryFamilies)

 </table>

 <h4>Rules implemented as Skylark extensions</h4>

 The Bazel team provides a set of supported build rules written using the
 <a href="/docs/skylark/index.html">Skylark</a> rules framework. These rules
 should be explicitly <a href="#load">load</a>ed. They allow you to build the
 following:

 <ul>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_rules/closure">
     Closure libraries</a>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/docker">
     Docker images</a>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/groovy">
     Groovy projects</a>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_rules/appengine">
     Java App Engine applications</a>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/d">
     D projects</a>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_rules/rust">
     Rust projects</a>
 <li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/scala">
     Scala projects</a> - experimental
 </ul>

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

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

 <h3 id='sh-tokenization'>Bourne shell tokenization</h3>
 <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>

 <h3 id='label-expansion'>Label expansion</h3>
 <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>

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

 #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)

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

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

 #commonAttributeDoc("test" $testAttributes)

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

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

 #commonAttributeDoc("binary" $binaryAttributes)

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

 <p>
   Most rule attributes can be "configured" so that their values can
   depend on the command-line flags passed to Bazel. This can be used,
   for example, to declare platform-dependent <code>srcs</code> or custom
   compiler flags depending on the
   <a href="bazel-user-manual.html#flag--compilation_mode">compilation
   mode</a>. This feature is very close in spirit to
   <a href="#cc_library.abi_deps">abi_deps</a>, except that it's not
   limited to <code>cc_*</code> rules and the <code>deps</code> attribute.
 </p>

 </p>

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

 <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>
	<html>
	<head>

	<title>Bazel BUILD Encyclopedia of Functions</title>
	<link href="docs_style.css" rel="stylesheet" type="text/css" />
	</head>

	<body>
	<div style="width:100%;">
	<div id="left-panel" style="margin-left:-80px;height:97%;float:left;position:fixed;overflow-y:scroll;overflow-x:hidden;border-right:thin solid #000000;resize:horizontal;">
	<h3 style="margin-left:0px">Rules:</h3>

	${LEFT_PANEL}

	</div>
	<div id="main-panel" style="margin-left:200px">

	<h1>Bazel BUILD Encyclopedia of Functions</h1>
	<h2>Contents</h2>

	<h3>Concepts and terminology</h3>
	<table class="layout"><tr><td>
	<ul class="be-toc">
	<li><a href="#common-definitions">Common definitions</a>:
	<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">Common attributes</a></li>
	<li><a href="#common-attributes-tests">Common attributes for tests</a></li>
	<li><a href="#common-attributes-binaries">Common attributes for binaries</a></li>
	<li><a href="#configurable-attributes">Configurable attributes</a></li>
	<li><a href="#implicit-outputs">Implicit output targets</a></li>
	</ul>
	</li>
	</ul>
	</td><td>
	<ul class="be-toc">
	<li><a href="#make_variables">"Make" variables</a>
	<ul class="be-toc">
	<li><a href="#make-var-substitution">"Make" variable substitution</a></li>
	<li><a href="#predefined_variables">Predefined variables</a></li>

	</ul>
	<li><a href="#predefined-python-variables">Predefined Python Variables</a></li>
	</ul>
	</td><td>
	<ul class="be-toc">
	<li><a href="#load">load</a></li>

	<li><a href="#package">package</a></li>
	<li><a href="#package_group">package_group</a></li>

	<li><a href="#licenses">licenses</a></li>
	<li><a href="#exports_files">exports_files</a></li>
	<li><a href="#glob">glob</a></li>
	<li><a href="#select">select</a></li>
	<li><a href="#workspace">workspace</a></li>
	</ul>
	</td></tr></table>

	<h3>Rules</h3>

	<h4>Language-specific Rules</h4>

	#macro(summaryTable $ruleFamilies)
	<tbody>
	#foreach($ruleFamily in $ruleFamilies)
	<tr>
	<td class="lang">${ruleFamily.name}</td>
	<td>
	#foreach($ruleDoc in $ruleFamily.binaryRules)
	<a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
	${ruleDoc.ruleName}
	</a>
	<br />
	#end
	</td>
	<td>
	#foreach($ruleDoc in $ruleFamily.libraryRules)
	<a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
	${ruleDoc.ruleName}
	</a>
	<br />
	#end
	</td>
	<td>
	#foreach($ruleDoc in $ruleFamily.testRules)
	<a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
	${ruleDoc.ruleName}
	</a>
	<br />
	#end
	</td>
	<td>
	#foreach($ruleDoc in $ruleFamily.otherRules1)
	<a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
	${ruleDoc.ruleName}
	</a>
	<br />
	#end
	</td>
	<td>
	#foreach($ruleDoc in $ruleFamily.otherRules2)
	<a href="#${ruleDoc.ruleName}"#if($ruleDoc.isDeprecated()) class="deprecated"#end>
	${ruleDoc.ruleName}
	</a>
	<br />
	#end
	</td>
	</tr>
	#end
	</tbody>
	#end

	<table class="table table-condensed table-striped" summary="Table of rules sorted by language">
	<colgroup span="6" width="20%"></colgroup>
	<thead>
	<tr>
	<th>Language</th>
	<th>Binary rules</th>
	<th>Library rules</th>
	<th>Test rules</th>
	<th>Other rules</th>
	<th></th>
	</tr>
	</thead>
	#summaryTable($langSpecificSummaryFamilies)

	</table>
	<h4>Rules that do not apply to a specific programming language</h4>

	<table class="table table-condensed table-striped" summary="Table of rules not specific to a programming language">
	<colgroup span="6" width="20%"></colgroup>
	#summaryTable($otherSummaryFamilies)

	</table>

	<h4>Rules implemented as Skylark extensions</h4>

	The Bazel team provides a set of supported build rules written using the
	<a href="/docs/skylark/index.html">Skylark</a> rules framework. These rules
	should be explicitly <a href="#load">load</a>ed. They allow you to build the
	following:

	<ul>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_rules/closure">
	Closure libraries</a>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/docker">
	Docker images</a>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/groovy">
	Groovy projects</a>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_rules/appengine">
	Java App Engine applications</a>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/d">
	D projects</a>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_rules/rust">
	Rust projects</a>
	<li> <a href="https://github.com/bazelbuild/bazel/tree/master/tools/build_defs/scala">
	Scala projects</a> - experimental
	</ul>

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

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

	<h3 id='sh-tokenization'>Bourne shell tokenization</h3>
	<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>

	<h3 id='label-expansion'>Label expansion</h3>
	<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>

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

	#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)

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

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

	#commonAttributeDoc("test" $testAttributes)

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

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

	#commonAttributeDoc("binary" $binaryAttributes)

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

	<p>
	Most rule attributes can be "configured" so that their values can
	depend on the command-line flags passed to Bazel. This can be used,
	for example, to declare platform-dependent <code>srcs</code> or custom
	compiler flags depending on the
	<a href="bazel-user-manual.html#flag--compilation_mode">compilation
	mode</a>. This feature is very close in spirit to
	<a href="#cc_library.abi_deps">abi_deps</a>, except that it's not
	limited to <code>cc_*</code> rules and the <code>deps</code> attribute.
	</p>

	</p>

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

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