Update from Google.
--
MOE_MIGRATED_REVID=85702957
diff --git a/docs/historical/build-ref.html b/docs/historical/build-ref.html
new file mode 100644
index 0000000..5f58b87
--- /dev/null
+++ b/docs/historical/build-ref.html
@@ -0,0 +1,1151 @@
+<!DOCTYPE html>
+
+<html>
+<head>
+ <meta charset="utf-8" />
+ <title>Bazel Concepts and Terminology</title>
+
+ <style type="text/css" id="internalStyle">
+ body {
+ background-color: #ffffff;
+ color: black;
+ margin-right: 10%;
+ margin-left: 10%;
+ }
+
+ h1, h2, h3, h4, h5, h6 {
+ color: #dd7755;
+ font-family: sans-serif;
+ }
+ @media print {
+ /* Darker version for printing */
+ h1, h2, h3, h4, h5, h6 {
+ color: #008000;
+ font-family: helvetica, sans-serif;
+ }
+ }
+
+ h1 {
+ text-align: center;
+ }
+ h2 {
+ margin-left: -0.5in;
+ }
+ h3 {
+ margin-left: -0.25in;
+ }
+ h4 {
+ margin-left: -0.125in;
+ }
+ hr {
+ margin-left: -1in;
+ }
+ address {
+ text-align: right;
+ }
+
+ /* A compact unordered list */
+ ul.tight > li {
+ margin-bottom: 0;
+ }
+
+ /* Use the <code> tag for bits of code and <var> for variable and object names. */
+ code,pre,samp,var {
+ color: #006000;
+ }
+ /* Use the <file> tag for file and directory paths and names. */
+ file {
+ color: #905050;
+ font-family: monospace;
+ }
+ /* Use the <kbd> tag for stuff the user should type. */
+ kbd {
+ color: #600000;
+ }
+ div.note p {
+ float: right;
+ width: 3in;
+ margin-right: 0%;
+ padding: 1px;
+ border: 2px solid #60a060;
+ background-color: #fffff0;
+ }
+
+ table.grid {
+ background-color: #ffffee;
+ border: 1px solid black;
+ border-collapse: collapse;
+ margin-left: 2mm;
+ margin-right: 2mm;
+ }
+
+ table.grid th,
+ table.grid td {
+ border: 1px solid black;
+ padding: 0 2mm 0 2mm;
+ }
+
+ /* Use pre.code for code listings.
+ Use pre.interaction for "Here's what you see when you run a.out.".
+ (Within pre.interaction, use <kbd> things the user types)
+ */
+ pre.code {
+ background-color: #FFFFEE;
+ border: 1px solid black;
+ color: #004000;
+ font-size: 10pt;
+ margin-left: 2mm;
+ margin-right: 2mm;
+ padding: 2mm;
+ -moz-border-radius: 12px 0px 0px 0px;
+ }
+
+ pre.interaction {
+ background-color: #EEFFEE;
+ color: #004000;
+ padding: 2mm;
+ }
+
+ pre.interaction kbd {
+ font-weight: bold;
+ color: #000000;
+ }
+
+ /* legacy style */
+ pre.interaction b.astyped {
+ color: #000000;
+ }
+
+ div.greenbox { background: #efe; padding: 1em;
+ margin: 1em; border: thin dotted green; }
+
+ .discouraged { text-decoration: line-through; }
+
+ table.layout { width: 980px; }
+ table.layout td { vertical-align: top; }
+
+ #maintainer { text-align: right; }
+ </style>
+</head>
+
+<body onload="GV_renderAllGraphs(); prettyPrint(); processSourcerLinks();">
+<h1>Bazel Concepts and Terminology</h1>
+
+<p>
+ This document provides an overview of concepts and terminology used
+ in Bazel.
+</p>
+
+<h2>Related Documentation</h2>
+<ul class="toc">
+ <li><a href="write_build_file.html">Getting Started with BUILD files</a></li>
+ <li><a href="build-ref.html">Bazel Concept Reference</a></li>
+ <li><a href="build-encyclopedia.html">Build Encyclopedia</a></li>
+ <li><a href="bazel-user-manual.html">User Manual</a></li>
+ <li><a href="bazel-query-v2.html">Bazel Query Reference</a></li>
+</ul>
+
+<h2>Table of Contents</h2>
+<ul>
+ <li><a href="#intro">Introduction</a></li>
+ <li><a href="#packages_targets">Packages and Targets</a>
+ <ul>
+ <li><a href="#packages">Packages</a></li>
+ <li><a href="#targets">Targets</a></li>
+ <li><a href="#labels">Labels</a></li>
+ <li><a href="#lexi">Lexical Specifications of a Label</a></li>
+ <li><a href="#rules">Rules</a></li>
+ </ul>
+ </li>
+ <li><a href="#BUILD_files">BUILD Files</a>
+ <ul>
+ <li><a href="#core_build_language">The Core Build Language</a></li>
+ <li><a href="#declaring_build_rules">Declaring Build Rules</a></li>
+ </ul>
+ </li>
+ <li><a href="#funcs">Types of Build Rules</a></li>
+ <li><a href="#dependencies">Dependencies</a>
+ <ul>
+ <li><a href="#actual_and_declared_dependencies">Actual and Declared Dependencies</a></li>
+ <li><a href="#types_of_dependencies">Types of Dependencies</a></li>
+ <li><a href="#label_directory">Using Labels to Reference Directories</a></li>
+ </ul>
+ </li>
+</ul>
+
+<div class="nav-2-levels" id="nav"></div>
+
+<h2 id='intro'>Introduction</h2>
+
+<p>Bazel can build and test software from source
+ code stored in any source tree that is organized as described
+ in this document. This source tree descends from a single top-level
+ directory and contains a nested hierarchy of packages, each of which contain
+ source files and metadata that specifies what software targets -- for
+ example, compiled executables or libraries -- can be built from the source.
+
+<h2 id="packages_targets"">Packages and Targets</h2>
+
+<h3 id="packages">Packages</h3>
+
+<p>
+ The primary unit of code organization in the source tree is
+ the <i>package</i>. A package is collection of related files and a
+ specification of the dependencies among them.
+</p>
+
+<p>
+ A package is defined as a directory containing a file
+ named <code>BUILD</code>, residing beneath the top-level directory in the
+ source tree. A package includes all files in its directory, plus all
+ subdirectories beneath it, except those which themselves contain a BUILD
+ file.
+</p>
+
+<p>
+ For example, in the following directory tree:
+</p>
+<pre>
+src/my/app/BUILD
+src/my/app/app.cc
+src/my/app/data/input.txt
+src/my/app/tests/BUILD
+src/my/app/tests/test.cc
+</pre>
+<p>
+ there are two packages, <code>my/app</code>,
+ and <code>my/app/tests</code>, a subpackage;
+ <code>my/app/data</code> is not a package, but a directory belonging to package
+ <code>my/app</code>.
+</p>
+
+<h3 id="targets">Targets</h3>
+
+<p>
+ A package is a container. The elements of a package are called
+ <i>targets</i>. Most targets are one of two principal kinds, <i>files</i>
+ and <i>rules</i>. Additionally, there is another kind of target,
+ <a href="build-encyclopedia.html#package_group">package groups</a>,
+ but they are far less numerous.
+</p>
+
+<div style='margin:auto; text-align: center'>
+<img src="images/package_targets.png" />
+<p><i>Hierarchy of targets.</i></p>
+</div>
+
+<p>
+ Files are further divided into two kinds.
+ <i>Source files</i> are usually written by the efforts of people,
+ and checked in to
+ the repository. <i>Generated files</i>, sometimes called derived files,
+ are not checked in, but are generated by the build tool from source
+ files according to specific rules.
+</p>
+
+<p>
+ The second kind of target is the <i>rule</i>. A rule specifies a
+ relationship between a set of inputs and a set of output files,
+ including the necessary steps to derive the outputs from the inputs.
+ The outputs of a rule are always generated files. The inputs to a
+ rule may be source files, but they may be generated files also;
+ consequently, outputs of one rule may be the inputs to another,
+ allowing long chains of rules to be constructed.
+</p>
+
+<p>
+ Whether the input to a rule is a source file or a generated file is
+ in most cases immaterial; what matters is only the contents of that
+ file. This fact makes it easy to replace a complex source file with
+ a generated file produced by a rule, such as happens when the burden
+ of manually maintaining a highly structured file becomes too
+ tiresome, and someone writes a program to derive it. No change is
+ required to the consumers of that file. Conversely, a generated
+ file may easily be replaced by a source file with only local
+ changes.
+</p>
+
+<p>
+ The inputs to a rule may also include <i>other rules</i>. The
+ precise meaning of such relationships is often quite complex and
+ language- or rule-dependent, but intuitively it is simple: a C++
+ library rule A might have another C++ library rule B for an input.
+ The effect of this dependency is that the B's header files are
+ available to A during compilation, B's symbols are available to A
+ during linking, and B's runtime data is available to A during
+ execution.
+</p>
+
+<p>
+ An invariant of all rules is that the files generated by a rule
+ always belong to the same package as the rule itself; it is not
+ possible to generate files into another package. It is not uncommon
+ for a rule's inputs to come from another package, though.
+</p>
+
+<p>
+ Package groups are sets of packages whose purpose is to limit accessibility
+ of certain rules. Package groups are defined by the <i>package_group</i>
+ function. They have two properties: the list of packages they contain and
+ their name. The only allowed ways to refer to them are from the
+ <i>visibility</i> attribute of rules or from the <i>default_visibility</i>
+ attribute of the <i>package</i> function; they do not generate or consume
+ files. For more information, refer to the appropriate section of the
+ <a href='build-encyclopedia.html#package_group'>Build Encyclopedia</a>.
+</p>
+
+
+<h3 id="labels">Labels</h3>
+
+<p>
+ All targets belong to exactly one package. The name of a target is
+ called its <em>label</em>, and a typical label in canonical form
+ looks like this:
+</p>
+
+<pre>
+ //my/app/main:app
+</pre>
+
+<p>
+ Each label has two parts, a package name (my/app/main) and a
+ target name (app). Every label uniquely identifies a target.
+ Labels sometimes appear in other forms; when
+ the colon is omitted, the target name is assumed to be the same as
+ the last component of the package name, so these two labels are
+ equivalent:
+</p>
+
+<pre>
+ //my/app
+ //my/app:app
+</pre>
+
+<p>
+ Short-form labels such as <code>//my/app</code> are not to
+ be confused with package names. Labels start with <code>//</code>,
+ but package names never do, thus <code>my/app</code> is the
+ package containing <code>//my/app</code>.
+
+ (A common misconception is that <code>//my/app</code> refers
+ to a package, or to <em>all</em> the targets in a package; neither
+ is true.)
+</p>
+
+<p>
+ Within a BUILD file, the package-name part of label may be omitted,
+ and optionally the colon too. So within the BUILD file for package
+ my/app (i.e. <code>//my/app:BUILD</code>), the
+ following "relative" labels are all equivalent:
+</p>
+
+<pre>
+ //my/app:app
+ //my/app
+ :app
+ app
+</pre>
+
+<p>
+ (It is a matter of convention that the colon is omitted for files,
+ but retained for rules, but it is not otherwise significant.)
+</p>
+
+<p>
+ Similarly, within a BUILD file, files belonging to the package may
+ be referenced by their unadorned name relative to the package
+ directory:
+</p>
+
+
+<pre>
+ generate.cc
+ testdata/input.txt
+</pre>
+
+<p>
+ but from other packages, or from the command-line, these file
+ targets must always be referred to by their complete label, e.g.
+ <code>//my/app:generate.cc</code>.
+</p>
+
+<p>
+ Relative labels cannot be used to refer to targets in other
+ packages; the complete package name must always be specified in this
+ case. For example, if the source tree contains both the package
+ <code>my/app</code> and the package
+ <code>my/app/testdata</code> (i.e., each of these two
+ packages has its own BUILD file). The latter package contains a
+ file named <code>testdepot.zip</code>. Here are two ways (one
+ wrong, one correct) to refer to this file within
+ <code>//my/app:BUILD</code>:
+</p>
+
+<pre>
+ <span style="text-decoration: line-through">testdata/testdepot.zip</span> # Wrong: testdata is a different package.
+ //my/app/testdata:testdepot.zip # Right.
+</pre>
+
+<p>
+ If, by mistake, you refer to <code>testdepot.zip</code> by the wrong
+ label, such as <code>//my/app:testdata/testdepot.zip</code>
+ or <code>//my:app/testdata/testdepot.zip</code>, you will get an
+ error from the build tool saying that the label "crosses a package
+ boundary". You should correct the label by putting the colon after
+ the directory containing the innermost enclosing BUILD file, i.e.,
+ <code>//my/app/testdata:testdepot.zip</code>.
+</p>
+
+<h3 id='lexi'>Lexical specification of a label</h3>
+
+<p>
+ The syntax of labels is intentionally strict, so as to
+ forbid metacharacters that have special meaning to the shell. This
+ helps to avoid inadvertent quoting problems, and makes it easier to
+ construct tools and scripts that manipulate labels, such as
+ the <a href='bazel-query-v2.html'>Bazel Query Language</a>.
+
+ All of the following are forbidden in labels: any sort of white
+ space, braces, brackets, or parentheses; wildcards such
+ as <code>*</code>; shell metacharacters such
+ as <code>></code>, <code>&</code> and <code>|</code>; etc.
+ This list is not comprehensive; the precise details are below.
+</p>
+
+<h4 id="name">Target names, <code>//...:<b>target-name</b></code></h4>
+
+<p><code>target-name</code> is the name of the target within the package.
+ The name of a rule is the value of the <code>name</code>
+ parameter in the rule's declaration in a BUILD file; the name
+ of a file is its pathname relative to the directory containing
+ the BUILD file.
+ Target names must be composed entirely of
+ characters drawn from the set a-z, A-Z, 0-9, and the punctuation
+ symbols <code>_/.+-=,@~</code>.
+ Do not use <code>..</code> to refer to files in other packages; use
+ <code>//<var>packagename</var>:<var>filename</var></code> instead.
+ Filenames must be relative pathnames in normal form, which means
+ they must neither start nor end with a slash
+ (e.g. <code>/foo</code> and <code>foo/</code> are forbidden) nor
+ contain multiple consecutive slashes as path separators
+ (e.g. <code>foo//bar</code>). Similarly, up-level references
+ (<code>..</code>) and current-directory references
+ (<code>./</code>) are forbidden. The sole exception to this
+ rule is that a target name may consist of exactly
+ '<code>.</code>'.
+</p>
+
+<p>While it is common to use <code>/</code> in the name of a file
+ target, we recommend that you avoid the use of <code>/</code> in the
+ names of rules. Especially when the shorthand form of a label is
+ used, it may confuse the reader. The
+ label <code>//foo/bar/wiz</code> is always a shorthand
+ for <code>//foo/bar/wiz:wiz</code>, even if there is no such package
+ <code>foo/bar/wiz</code>; it never refers to <code>//foo:bar/wiz</code>,
+ even if that target exists.</p>
+
+<p>However, there are some situations where use of a slash is
+ convenient, or sometimes even necessary. For example, the name of
+ certain rules must match their principal source file, which may
+ reside in a subdirectory of the package.</p>
+
+<h4>Package names, <code>//<b>package-name</b>:...</code></h4>
+<p>
+ The name of a package is the name of the directory containing its
+ BUILD file, relative to the top-level directory of the source tree.
+ For example: <code>my/app</code>.
+ Package names must start with a lower-case ASCII letter (a-z),
+ and must be composed entirely of characters drawn from the set
+ a-z, 0-9, '_', and '/'.
+</p>
+
+<p>
+ For a language with a directory structure that is significant
+ to its module system, it is important to choose directory names
+ that are valid identifiers in the language.
+</p>
+
+<p>
+ The limited exceptions above were permitted because those trees
+ contain other programming languages with incompatible naming
+ requirements, or because the owners of that tree
+ committed to use only a particular programming language within that
+ tree.
+</p>
+
+<p>
+ Package names may not contain the substring <code>//</code>, nor
+ end with a slash.
+</p>
+
+<h3 id="rules">Rules</h3>
+
+<p>
+ A rule specifies the relationship between inputs and output, and the
+ steps to build the outputs. Rules can be of one of many different
+ kinds or <i>classes</i>, which produce compiled
+ executables and libraries, test executables and other supported
+ outputs as described in the
+ <a href="build-encyclopedia.html">Build Encyclopedia</a>.
+</p>
+
+<p>
+ Every rule has a name, specified by the <code>name</code> attribute,
+ of type string. The name must be a syntactically valid target name,
+ as specified <a href='#name'>above</a>. In some cases, the name is
+ somewhat
+ arbitrary, and more interesting are the names of the files generated
+ by the rule; this is true of genrule rules in particular. In other
+ cases, the name is significant: for <code>*_binary</code>
+ and <code>*_test</code> rules, for example, the rule name determines
+ the name of the executable produced by the build.
+</p>
+
+<p>
+ Every rule has a set of <i>attributes</i>; the applicable attributes
+ for a given rule, and the significance and semantics of each
+ attribute are a function of the rule's class; see
+ the <a href='build-encyclopedia.html'>Build
+ Encyclopedia</a> for the full list of supported rules and their
+ corresponding attributes. Each attribute has a name and a
+ type. The full set of types that an attribute can have is: integer,
+ label, list of labels, string, list of strings, output label,
+ list of output labels. Not all attributes need to be specified in
+ every rule. Attributes thus form a dictionary from keys (names) to
+ optional, typed values.
+</p>
+
+<p>
+ The <code>srcs</code> attribute present in many rules has type "list
+ of label"; its value, if present, is a list of labels, each being
+ the name of a target that is an input to this rule.
+</p>
+
+<p>
+ The <code>outs</code> attribute present in many rules has type "list
+ of output labels"; this is similar to the type of
+ the <code>srcs</code> attribute, but differs in two significant
+ ways. Firstly, due to the invariant that the outputs of a rule
+ belong to the same package as the rule itself, output labels cannot
+ include a package component; they must be in one of the "relative"
+ forms shown above. Secondly, the relationship implied by an
+ (ordinary) label attribute is inverse to that implied by an output
+ label: a rule <i>depends on</i> its 'srcs', whereas a rule <i>is
+ depended on by</i> its outputs. The two types of label attributes
+ thus assign direction to the edges between targets, giving rise to a
+ dependency graph.
+</p>
+
+<p>
+ The figure below represents an example fragment of the build
+ dependency graph, and illustrates: files (circles) and rules
+ (boxes); dependencies from generated files to rules; dependencies
+ from rules to files, and from rules to other rules. Conventionally,
+ dependency arrows are represented as pointing from a target towards
+ its prerequisites.
+</p>
+
+<div style="margin:auto; text-align:center">
+<img src="images/source_rules_generated_files.png" />
+<p><i>Source files, rules, and generated files.</i></p>
+</div>
+
+<p>
+ This directed acyclic graph over targets is called the
+ "target graph" or "build dependency graph", and is the domain over
+ which
+ the <a href='bazel-query-v2.html'>Bazel Query tool</a> operates.
+</p>
+
+
+<h2 id="BUILD_files">BUILD Files</h2>
+
+<p>
+ The previous section described packages, targets and labels, and the
+ build dependency graph abstractly. In this section, we'll look at
+ the concrete syntax used to define a package.
+</p>
+
+<p>
+ By definition, every package contains a BUILD file, which is a short
+ program written in the Build Language. Most build files
+ appear to be little more than a series of declarations of build
+ rules; indeed, the declarative style is strongly encouraged when
+ writing BUILD files.
+</p>
+
+<p>
+ However, the build language is in fact an imperative language, and
+ BUILD files are interpreted as a sequential list of statements.
+ Build rule functions, such as <code>cc_library</code>, are procedures whose
+ side-effect is to create an abstract build rule inside the build tool.
+</p>
+
+<p>
+ The concrete syntax of BUILD files is a subset of Python.
+ Originally, the syntax <i>was</i> that of Python, but experience
+ showed that users rarely used more than a tiny subset of Python's
+ features, and when they did, it often resulted in complex and
+ fragile BUILD files. In many cases, the use of such features was
+ unnecessary, and the same result could be achieved by using an
+ external program, e.g. via a <code>genrule</code> BUILD rule.
+</p>
+
+<p>
+ The build language has two dialects, the <em>core</em> language and
+ the <em>extended</em> language. Each BUILD file can elect which
+ dialect it uses; the vast majority use the core language, which is a
+ strict subset of the extended language. The extended language is a
+ strict subset of Python 2.6.
+</p>
+
+<p>
+ Crucially, programs in the build language are unable to perform
+ arbitrary I/O (though many users try!). This invariant makes the
+ interpretation of BUILD files hermetic, i.e. dependent only on a
+ known set of inputs, which is essential for ensuring that builds are
+ reproducible.
+</p>
+
+<h3 id="core_build_language">The Core Build Language</h3>
+
+<p>
+ <b>Lexemes</b>: the lexical syntax of the core language is a strict
+ subset of Python 2.6, and we refer the reader to the <a
+ href='http://docs.python.org/reference/lexical_analysis.html'>Python
+ specification</a> for details.
+ Lexical features of Python that are not
+ supported include: floating-point literals, hexadecimal and Unicode
+ escapes within string literals.
+</p>
+
+<p>
+ BUILD files should be written using only ASCII characters,
+ although technically they are interpreted using the Latin-1
+ character set. The use
+ of <a href='http://www.python.org/dev/peps/pep-0263/'><code>coding:</code></a>
+ declarations is forbidden.
+</p>
+
+<p>
+ <b>Grammar</b>: the grammar of the core language is shown below,
+ using EBNF notation. Ambiguity is resolved using precedence, which
+ is defined as for Python.
+</p>
+
+<pre style='font-size: 90%; font-style: bold;'>
+ file_input ::= (simple_stmt? '\n')*
+
+ simple_stmt ::= small_stmt (';' small_stmt)* ';'?
+
+ small_stmt ::= expr
+ | assign_stmt
+
+ assign_stmt ::= IDENTIFIER '=' expr
+
+ expr ::= INTEGER
+ | STRING+
+ | IDENTIFIER
+ | IDENTIFIER '(' arg_list? ')'
+ | expr '.' IDENTIFIER
+ | expr '.' IDENTIFIER '(' arg_list? ')'
+ | '[' expr_list? ']'
+ | '[' expr ('for' IDENTIFIER 'in' expr)+ ']'
+ | '(' expr_list? ')'
+ | '{' dict_entry_list? '}'
+ | expr '+' expr
+ | expr '-' expr
+ | expr '%' expr
+ | '-' expr
+ | expr '[' expr? ':' expr? ']'
+ | expr '[' expr ']'
+
+ expr_list ::= (expr ',')* expr ','?
+
+ dict_entry_list ::= (dict_entry ',')* dict_entry ','?
+
+ dict_entry ::= expr ':' expr
+
+ arg_list ::= (arg ',')* arg ','?
+
+ arg ::= IDENTIFIER '=' expr
+ | expr
+
+</pre>
+
+<p>
+ For each expression of the core language, the semantics are
+ identical to the corresponding Python semantics, except in the
+ following cases:
+</p>
+<ul>
+ <li>certain overloads of the binary <code>%</code> operator are not
+ supported. Only the <code>int % int</code> and <code>str %
+ tuple</code> forms are supported. Only the <code>%s</code>
+ and <code>%d</code> format specifiers may be
+ used; <code>%(var)s</code> is illegal.</li>
+
+ <li>the <code>dict</code> datatype is absent. The <code>{key:value,
+ ...}</code> literal syntax exists, but unlike Python, it defines a
+ list of tuples <code>[(key, value), ...]</code>.</li>
+
+</ul>
+
+<p>
+ Many Python features are missing:
+
+ control-flow constructs (loops, conditionals, exceptions),
+
+ basic datatypes (floating-point numbers, big integers, dictionaries),
+
+ <code>import</code> and the module system,
+
+ support for definition of classes and functions (both named and
+ anonymous),
+
+ all of Python's built-in functions (<code>len()</code>, etc),
+
+ and most of the methods supported by the basic datatypes.
+</p>
+
+<p>
+ The initial environment in which BUILD files are evaluated is
+ defined by the Build Encyclopedia. In addition, the following
+ object methods are available with their usual Python meanings:
+</p>
+<pre>
+string datatype:
+ str.join(sequence) -> str
+ str.lower() -> str
+ str.replace(str old, str new [, int maxreplace]) -> str
+ str.split([str sep [,int maxsplit]]) -> list of str
+ str.rfind(str sub [,int start [,int end]]) -> int
+ str.find(str sub [,int start [,int end]]) -> int
+ str.endswith(str sub [,int start [,int end]]) -> bool
+ str.startswith(str [,int start [,int end]]) -> bool
+list datatype:
+ list.append(object)
+ list.extend(sequence)
+</pre>
+
+<h3 id="declaring_build_rules">Declaring build rules</h3>
+
+<p>
+ The build language is an imperative language, so in general, order
+ does matter: variables must be defined before they are used, for
+ example. However, most BUILD files consist only of declarations of
+ build rules, and the relative order of these statements is
+ immaterial; all that matters is <em>which</em> rules were declared,
+ and with what values, by the time package evaluation completes.
+
+ So, in simple BUILD files, rule declarations can be re-ordered
+ freely without changing the behavior.
+</p>
+
+<p>
+ Build file authors are encouraged to use comments liberally to
+ document the role of each build target, whether it is intended for
+ public use, and anything else that would help users and future
+ maintainers, including a <code># Description:</code> comment at the
+ top, explaining the role of the package.
+</p>
+
+<p>
+ The Python comment syntax of <code>#...</code> is supported.
+ Triple-quoted string literals may span multiple lines, and can be used
+ for multi-line comments.
+</p>
+
+<h2 id="funcs">Types of build rule</h2>
+
+<p>
+ The majority of build rules come in families, grouped together by
+ language. For
+ example, <code>cc_binary</code>, <code>cc_library</code>
+ and <code>cc_test</code> are the build rules for C++ binaries,
+ libraries, and tests, respectively. Other languages use the same
+ naming scheme, with a different prefix, e.g. <code>java_*</code> for
+ Java. These functions are all documented in
+ the <a href="build-encyclopedia.html">Build Encyclopedia</a>.
+</p>
+
+<ul>
+ <li><p>A <a href='build-encyclopedia.html#binary'><code>*_binary</code></a>
+
+ rule builds an executable program in a given language. After a
+ build, the executable will reside in the build tool's binary
+ output tree at the corresponding name for the rule's label,
+ so <code>//my:program</code> would appear at
+ (e.g.) <code>$(BINDIR)/my/program</code>. </p>
+
+ <p>Such rules also create a runfiles directory
+ containing all the files mentioned in a <code>data</code>
+ attribute belonging to the rule, or any rule in its transitive
+ closure of dependencies; this set of files is gathered together in
+ one place for ease of deployment to production.</p>
+ </li>
+
+ <li><p>A <a href='build-encyclopedia.html#test'><code>*_test</code></a>
+ rule is a specialization of a *_binary rule, used for automated
+ testing. Tests are simply programs that return zero on success.</p>
+
+ <p>
+ Like binaries, tests also have runfiles trees, and the files
+ beneath it are the only files that a test may legitimately open
+ at runtime. For example, a program <code>cc_test(name='x',
+ data=['//foo:bar])</code> may open and
+ read <code>$TEST_SRCDIR/path/foo/bar</code> during execution.
+ (Each programming language has its own utility function for
+ accessing the value of <code>$TEST_SRCDIR</code>, but they are all
+ equivalent to using the environment variable directly.)
+ Failure to observe the rule will cause the test to fail when it is
+ executed on a remote testing host.
+ </p>
+ </li>
+
+ <li>A <a href='build-encyclopedia.html#library'><code>*_library</code></a>
+ rule specifies a separately-compiled module in the given
+ programming language. Libraries can depend on other libraries,
+ and binaries and tests can depend on libraries, with the expected
+ separate-compilation behavior.
+ </li>
+</ul>
+
+<h2 id="dependencies">Dependencies</h2>
+
+<p>
+ A target <code>A</code> <i>depends upon</i> a target
+ <code>B</code> if <code>B</code> is needed by <code>A</code> at
+ build or execution time. The <i>depends upon</i> relation induces a
+ directed acyclic graph (DAG) over targets, and we call this a
+ <em>dependency graph</em>.
+
+ A target's <em>direct</em> dependencies are those other targets
+ reachable by a path of length 1 in the dependency graph. A target's
+ <em>transitive</em> dependencies are those targets upon which it
+ depends via a path of any length through the graph.
+</p>
+
+<p>
+ In fact, in the context of builds, there are two dependency graphs,
+ the graph of <em>actual dependencies</em> and the graph of
+ <em>declared dependencies</em>. Most of the time, the two graphs
+ are so similar that this distinction need not be made, but it is
+ useful for the discussion below.
+</p>
+
+<h3 id="actual_and_declared_dependencies">Actual and declared dependencies</h3>
+
+<p>
+ A target <code>X</code> is <i>actually dependent</i> on target
+ <code>Y</code> iff <code>Y</code> must be present, built and
+ up-to-date in order for <code>X</code> to be built correctly.
+ "Built" could mean generated, processed, compiled, linked,
+ archived, compressed, executed, or any of the other kinds of tasks
+ that routinely occur during a build.
+</p>
+
+<p>
+ A target <code>X</code> has a <i>declared dependency</i> on target
+ <code>Y</code> iff there is a dependency edge from <code>X</code> to
+ <code>Y</code> in the package of <code>X</code>.
+</p>
+
+<p>
+ For correct builds, the graph of actual dependencies <i>A</i> must
+ be a subgraph of the graph of declared dependencies <i>D</i>. That
+ is, every pair of directly-connected nodes <code>x --> y</code>
+ in <i>A</i> must also be directly connected in <i>D</i>. We say
+ <i>D</i> is an <em>overapproximation</em> of <i>A</i>. It is important
+ that it not be too much of an overapproximation, though, since
+ redundant declared dependencies can make builds slower and
+ binaries larger.
+</p>
+
+<p>
+ What this means for BUILD-file writers is that every rule must
+ explicitly declare all of its actual direct dependencies to the
+ build system, and no more.
+
+ Failure to observe this principle causes undefined behavior: the
+ build may fail, but worse, the build may depend on some prior
+ operations, or upon which transitive declared dependencies the target
+ happens to have. The build tool attempts aggressively to check for
+ missing dependencies and report errors, but it is not possible for
+ this checking to be complete in all cases.
+</p>
+
+<p>
+ You need not (and should not) attempt to list everything indirectly imported,
+ even if it is "needed" by A at execution time.
+</p>
+
+<p>
+ During a build of target <code>X</code>, the build tool inspects the
+ entire transitive closure of dependencies of <code>X</code> to ensure that
+ any changes in those targets are reflected in the final result,
+ rebuilding intermediates as needed.
+</p>
+
+<p>
+ The transitive nature of dependencies leads to a common mistake.
+ Through careless programming, code in one file may use code provided
+ by an <em>indirect</em> dependency, i.e. a transitive but not direct
+ edge in the declared dependency graph. Indirect dependencies do not
+ appear in the build file. Since the <code>BUILD</code> rule doesn't
+ directly depend on the provider, there is no way to track changes,
+ as shown in the following example timeline:
+</p>
+
+<div class="greenbox">
+<p><b>1. At first, everything works</b></p>
+
+<p>The code in package <code>a</code> uses code in package <code>b</code>.
+The code in package <code>b</code> uses code in package <code>c</code>,
+and thus <code>a</code> transitively depends on <code>c</code>.</p>
+
+<div style="float:left; width: 49%; margin-top: -20px;">
+<p><code>a/BUILD</code></p>
+<pre class="code">
+<b>rule(
+ name = "a",
+ srcs = "a.in",
+ deps = "//b:b",
+)</b>
+</pre>
+<p><code>a/a.in</code></p>
+<pre class="code">
+<b>import b;
+b.foo();</b>
+</pre>
+</div>
+<div style="float:right; width: 49%; margin-top: -20px; ">
+<p><code>b/BUILD</code></p>
+<pre class="code">
+<b>rule(
+ name = "b",
+ srcs = "b.in",
+ deps = "//c:c",
+)</b>
+</pre>
+<p><code>b/b.in</code></p>
+<pre class="code">
+<b>import c;
+function foo() {
+ c.bar();
+}</b>
+</pre>
+</div>
+<pre style="clear: both;">
+Declared dependency graph: a --> b --> c
+
+Actual dependency graph: a --> b --> c
+</pre>
+The declared dependencies overapproximate the actual dependencies.
+All is well.
+</div>
+
+<div class="greenbox">
+<p><b>2. A latent hazard is introduced.</b></p>
+<p>
+ Someone carelessly adds code to <code>a</code> that creates a direct
+ actual dependency on <code>c</code>, but forgets to declare it.
+</p>
+<div style="float:left; width: 49%; margin-top: -20px; ">
+<p><code>a/a.in</code></p>
+<pre class="code">
+import b;
+<b>import c;</b>
+b.foo();
+<b>c.garply();</b>
+</pre>
+</div>
+
+<pre style="clear: both;">
+Declared dependency graph: a --> b --> c
+
+Actual dependency graph: a --> b -->_c
+ \_________/|
+</pre>
+The declared dependencies no longer overapproximate the actual
+dependencies. This may build ok, because the transitive closures of
+the two graphs are equal, but masks a problem: <code>a</code> has an
+actual but undeclared dependency on <code>c</code>.
+</div>
+
+<div class="greenbox">
+<p><b>3. The hazard is revealed</b> </p>
+<p>
+ Someone refactors <code>b</code> so that it no longer depends on
+ <code>c</code>, inadvertently breaking <code>a</code> through no
+ fault of their own.
+</p>
+<div style="float:right; width: 49%; margin-top: -20px; ">
+<p><code>b/BUILD</code></p>
+<pre class="code">
+rule(
+ name = "b",
+ srcs = "b.in",
+ <b>deps = "//d:d"</b>,
+)
+</pre>
+<p><code>b/b.in</code></p>
+<pre class="code">
+<b>import d;</b>
+function foo() {
+ <b>d.baz();</b>
+}
+</pre>
+</div>
+<pre style="clear: both;">
+Declared dependency graph: a --> b c
+
+Actual dependency graph: a --> b _c
+ \_________/|
+</pre>
+<p>
+ The declared dependency graph is now an underapproximation of the
+ actual dependencies, even when transitively closed; the build is
+ likely to fail.
+
+ The problem could have been averted by ensuring that the actual
+ dependency from <code>a</code> to <code>c</code> introduced in Step
+ 2 was properly declared in the BUILD file.
+</div>
+
+<h3 id="types_of_dependencies">Types of dependencies</h3>
+
+<p>
+ Most build rules have three attributes for specifying different kinds
+ of generic dependencies: <code>srcs</code>, <code>deps</code> and
+ <code>data</code>. These are explained below. See also
+ <a href='build-encyclopedia.html#common-attributes'>Attributes common
+ to all rules</a> in the Build Encyclopedia.)
+</p>
+
+<p>
+ Many rules also have additional attributes for rule-specific kinds
+ of dependency, e.g. <code>compiler</code>, <code>resources</code>,
+ etc. These are detailed in the Build Encyclopedia.
+</p>
+
+<h4 id="srcs"><code>srcs</code> dependencies</h4>
+<p>
+ Files consumed directly by the rule or rules that output source files.
+</p>
+
+<h4 id="deps"><code>deps</code> dependencies</h4>
+<p>
+ Rule pointing to separately-compiled modules providing header files,
+ symbols, libraries, data, etc.
+</p>
+
+<h4 id="data"><code>data</code> dependencies</h4>
+<p>A build target might need some data files to run correctly. These
+ data files aren't source code: they don't affect how the target is
+ built. For example, a unit test might compare a function's output
+ to the contents of a file. When we build the unit test, we
+ don't need the file; but we do need it when we run the test. The
+ same applies to tools that are launched during execution.
+
+<p>The build system runs tests in an isolated directory where only files
+ listed as "data" are available. Thus, if a binary/library/test
+ needs some files to run, specify them (or a BUILD rule containing
+ them) in data. For example:
+</p>
+
+<pre>
+# I need a config file from a directory named runfiles:
+java_binary(
+ name = "setenv",
+ ...
+ data = [":runfiles/default_env.txt"],
+)
+
+# I need test data from another directory
+sh_test(
+ name = "regtest",
+ srcs = ["regtest.sh"],
+ data = [
+ "//data/find:file1.txt",
+ "//data/find:file2.txt",
+ ...
+ ],
+)
+</pre>
+
+<p>These files are available using the relative path
+<code>"./path/to/data/file"</code>. In tests, it is also possible to refer to
+them using
+<code>file::JoinPath(FLAGS_test_srcdir, "/path/to/data/file")</code> or
+<code>${TEST_SRCDIR}/path/to/data/file</code>. (The exact syntax
+depends on your programming language, of course.)</p>
+
+ <h3 id="label_directory">Using Labels to Reference Directories</h3>
+
+ <p>As you look over our <code>BUILD</code> files, you might notice
+ that some <code>data</code> labels refer to directories.
+ These labels end with "/." or "/" like so:
+
+<pre>
+<span style="text-decoration: line-through">data = ["//data/regression:unittest/."]</span> # don't use this
+</pre>
+<p>
+or like so:
+</p>
+<pre>
+<span style="text-decoration: line-through">data = ["testdata/."]</span> # don't use this
+</pre>
+
+<p>
+or like so:
+</p>
+
+<pre>
+<span style="text-decoration: line-through">data = ["testdata/"]</span> # don't use this
+</pre>
+ <p>This seems convenient, particularly for tests (since it allows a test to
+ use all the data files in the directory).
+ </p>
+
+ <p>But try not to do this. In order to ensure correct incremental rebuilds (and
+ re-execution of tests) after a change, the build system must be
+ aware of the complete set of files that are inputs to the build (or
+ test). When you specify a directory, the build system will perform
+ a rebuild only when the directory itself changes (due to addition or
+ deletion of files), but won't be able to detect edits to individual
+ files as those changes do not affect the enclosing directory.
+ Rather than specifying directories as inputs to the build system,
+ you should enumerate the set of files contained within them, either
+ explicitly or using the
+ <a href='build-encyclopedia.html#glob'><code>glob()</code></a> function.
+ (Use <code>**</code> to force the <a href='build-encyclopedia.html#glob'>
+ <code>glob()</code></a> to be recursive.)
+ </p>
+
+<pre>
+data = glob(["testdata/**"]) # use this instead
+</pre>
+
+ <p>Unfortunately, there are some scenarios where directory labels must be used.
+ For example, if the <code>testdata</code> directory contains files whose
+ names do not conform to the strict <a href='#lexi'>label syntax</a>
+ (e.g. they contain certain punctuation symbols), then explicit
+ enumeration of files, or use of the
+ <a href='build-encyclopedia.html#glob'><code>glob()</code></a> function will
+ produce an invalid labels error. You must use directory labels in this case,
+ but beware of the concomitant risk of incorrect rebuilds described above.
+ </p>
+
+ <p>If you must use directory labels, keep in mind that you can't refer to the parent
+ package with a relative "<code>../</code>" path; instead, use an absolute path like
+ "<code>//data/regression:insert_docs_unittest/.</code>".
+ </p>
+
+ <p>Note that directory labels are only valid for data dependencies. If you try to use
+ a directory as a label in an argument other than <code>data</code>, it
+ will fail and you will get a (probably cryptic) error message.
+ </p>
+
+ </body>
+</html>
