diff options
| author |  Kristina Chodorow <kchodorow@google.com> | 2015-04-03 15:31:53 +0000 |
|---|---|---|
| committer | Kristina Chodorow <kchodorow@google.com> | 2015-04-03 20:37:00 +0000 |
| commit | 5608a7aa9b3125738b605fee4836b7c6c9551d99 (patch) | |
| tree | 06b5f4b3f8984d523e59b101a51bf6d538738cb9 /site/docs/build-ref.html | |
| parent | 9d51432b6b51dd5d4abe5896470e6ca6a0d58d95 (diff) | |
Change the mover paths for docs to be under site/
--
MOS_MIGRATED_REVID=90252678
Diffstat (limited to 'site/docs/build-ref.html')
| -rw-r--r-- | site/docs/build-ref.html | 1320 |
1 files changed, 1320 insertions, 0 deletions
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html new file mode 100644 index 0000000000..1d849126f9 --- /dev/null +++ b/site/docs/build-ref.html @@ -0,0 +1,1320 @@ +<!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> + +<h1>Bazel: Concepts and Terminology</h1> +<p> + This document provides an overview of concepts and terminology used + in Bazel. +</p> +<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> + +<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. +</p> +<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'> +<svg width="582pt" height="188pt" + viewBox="0.00 0.00 581.89 188.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 184)"> +<title>G1</title> +<polygon fill="white" stroke="none" points="-4,4 -4,-184 577.888,-184 577.888,4 -4,4"/> +<!-- Target --> +<g id="node1" class="node"><title>Target</title> +<ellipse fill="none" stroke="black" cx="376.795" cy="-162" rx="40.0939" ry="18"/> +<text text-anchor="middle" x="376.795" y="-158.3" font-family="arial" font-size="14.00">Target</text> +</g> +<!-- Rule --> +<g id="node2" class="node"><title>Rule</title> +<ellipse fill="none" stroke="black" cx="241.795" cy="-90" rx="30.5947" ry="18"/> +<text text-anchor="middle" x="241.795" y="-86.3" font-family="arial" font-size="14.00">Rule</text> +</g> +<!-- Target->Rule --> +<g id="edge1" class="edge"><title>Target->Rule</title> +<path fill="none" stroke="black" d="M351.402,-147.834C329.151,-136.296 296.735,-119.487 272.926,-107.142"/> +<polygon fill="black" stroke="black" points="274.432,-103.98 263.943,-102.484 271.21,-110.195 274.432,-103.98"/> +</g> +<!-- File --> +<g id="node6" class="node"><title>File</title> +<ellipse fill="none" stroke="black" cx="376.795" cy="-90" rx="30.5947" ry="18"/> +<text text-anchor="middle" x="376.795" y="-86.3" font-family="arial" font-size="14.00">File</text> +</g> +<!-- Target->File --> +<g id="edge5" class="edge"><title>Target->File</title> +<path fill="none" stroke="black" d="M376.795,-143.697C376.795,-135.983 376.795,-126.712 376.795,-118.112"/> +<polygon fill="black" stroke="black" points="380.295,-118.104 376.795,-108.104 373.295,-118.104 380.295,-118.104"/> +</g> +<!-- Package group --> +<g id="node9" class="node"><title>Package group</title> +<ellipse fill="none" stroke="black" cx="499.795" cy="-90" rx="74.187" ry="18"/> +<text text-anchor="middle" x="499.795" y="-86.3" font-family="arial" font-size="14.00">Package group</text> +</g> +<!-- Target->Package group --> +<g id="edge8" class="edge"><title>Target->Package group</title> +<path fill="none" stroke="black" d="M400.802,-147.337C418.506,-137.262 442.911,-123.373 463.059,-111.906"/> +<polygon fill="black" stroke="black" points="465.018,-114.819 471.978,-106.831 461.555,-108.735 465.018,-114.819"/> +</g> +<!-- cc_library --> +<g id="node3" class="node"><title>cc_library</title> +<ellipse fill="none" stroke="black" cx="59.7947" cy="-18" rx="59.5901" ry="18"/> +<text text-anchor="middle" x="59.7947" y="-14.3" font-family="arial" font-size="14.00">cc_library</text> +</g> +<!-- Rule->cc_library --> +<g id="edge2" class="edge"><title>Rule->cc_library</title> +<path fill="none" stroke="black" d="M216.87,-79.4136C188.038,-68.3243 140.006,-49.8505 104.633,-36.2453"/> +<polygon fill="black" stroke="black" points="105.607,-32.8704 95.0176,-32.5473 103.095,-39.4038 105.607,-32.8704"/> +</g> +<!-- java_test --> +<g id="node4" class="node"><title>java_test</title> +<ellipse fill="none" stroke="black" cx="191.795" cy="-18" rx="54.6905" ry="18"/> +<text text-anchor="middle" x="191.795" y="-14.3" font-family="arial" font-size="14.00">java_test</text> +</g> +<!-- Rule->java_test --> +<g id="edge3" class="edge"><title>Rule->java_test</title> +<path fill="none" stroke="black" d="M230.449,-73.1159C224.298,-64.5051 216.557,-53.6674 209.621,-43.9567"/> +<polygon fill="black" stroke="black" points="212.453,-41.9004 203.793,-35.7973 206.757,-45.9691 212.453,-41.9004"/> +</g> +<!-- ... --> +<g id="node5" class="node"><title>...</title> +<ellipse fill="none" stroke="black" cx="291.795" cy="-18" rx="27" ry="18"/> +<text text-anchor="middle" x="291.795" y="-14.3" font-family="arial" font-size="14.00">...</text> +</g> +<!-- Rule->... --> +<g id="edge4" class="edge"><title>Rule->...</title> +<path fill="none" stroke="black" d="M253.14,-73.1159C259.469,-64.2555 267.482,-53.0373 274.57,-43.1152"/> +<polygon fill="black" stroke="black" points="277.529,-44.9929 280.494,-34.8212 271.833,-40.9242 277.529,-44.9929"/> +</g> +<!-- Source --> +<g id="node7" class="node"><title>Source</title> +<ellipse fill="none" stroke="black" cx="376.795" cy="-18" rx="40.0939" ry="18"/> +<text text-anchor="middle" x="376.795" y="-14.3" font-family="arial" font-size="14.00">Source</text> +</g> +<!-- File->Source --> +<g id="edge6" class="edge"><title>File->Source</title> +<path fill="none" stroke="black" d="M376.795,-71.6966C376.795,-63.9827 376.795,-54.7125 376.795,-46.1124"/> +<polygon fill="black" stroke="black" points="380.295,-46.1043 376.795,-36.1043 373.295,-46.1044 380.295,-46.1043"/> +</g> +<!-- Generated --> +<g id="node8" class="node"><title>Generated</title> +<ellipse fill="none" stroke="black" cx="489.795" cy="-18" rx="54.6905" ry="18"/> +<text text-anchor="middle" x="489.795" y="-14.3" font-family="arial" font-size="14.00">Generated</text> +</g> +<!-- File->Generated --> +<g id="edge7" class="edge"><title>File->Generated</title> +<path fill="none" stroke="black" d="M396.997,-76.4854C413.512,-66.2547 437.203,-51.579 456.513,-39.6169"/> +<polygon fill="black" stroke="black" points="458.378,-42.579 465.036,-34.3375 454.691,-36.6283 458.378,-42.579"/> +</g> +</g> +</svg> +<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_binary +</pre> + +<p> + + Each label has two parts, a package name (<code>my/app/main</code>) + and a target name (<code>app_binary</code>). 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 + <code>my/app</code> (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 class="discouraged">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="query.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 <code>a</code>–<code>z</code>, + <code>A</code>–<code>Z</code>, <code>0</code>–<code>9</code>, + 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 + (<code>a</code>–<code>z</code>), + and must be composed entirely of characters drawn from the set + <code>a</code>–<code>z</code>, <code>0</code>–<code>9</code>, + '<code>_</code>', and '<code>/</code>'. +</p> + +<p> + For a language with a directory structure that is significant + to its module system (e.g. Java), it is important to choose directory names + that are valid identifiers in the language. +</p> + +<p> + Although Bazel allows a package at the build root (e.g. <code>//:foo</code>), this + is not advised and projects should attempt to use more descriptively named + packages. +</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 genrules. 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"> +<svg width="157pt" height="246pt" + viewBox="0.00 0.00 156.50 246.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> +<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 242)"> +<title>G1</title> +<polygon fill="white" stroke="none" points="-4,4 -4,-242 152.5,-242 152.5,4 -4,4"/> +<!-- r1 --> +<g id="node1" class="node"><title>r1</title> +<polygon fill="none" stroke="black" points="88.5,-173 34.5,-173 34.5,-137 88.5,-137 88.5,-173"/> +<text text-anchor="middle" x="61.5" y="-152.5" font-family="arial" font-size="10.00" fill="#006000">rule</text> +</g> +<!-- s1 --> +<g id="node3" class="node"><title>s1</title> +<ellipse fill="none" stroke="black" cx="14.5" cy="-223.5" rx="14.5" ry="14.5"/> +<text text-anchor="middle" x="14.5" y="-221" font-family="arial" font-size="10.00" fill="#006000">in</text> +</g> +<!-- r1->s1 --> +<g id="edge1" class="edge"><title>r1->s1</title> +<path fill="none" stroke="black" d="M49.3963,-173.125C42.9655,-182.224 35.0324,-193.449 28.3559,-202.895"/> +<polygon fill="black" stroke="black" points="25.3432,-201.094 22.4297,-211.28 31.0596,-205.134 25.3432,-201.094"/> +</g> +<!-- s2 --> +<g id="node4" class="node"><title>s2</title> +<ellipse fill="none" stroke="black" cx="61.5" cy="-223.5" rx="14.5" ry="14.5"/> +<text text-anchor="middle" x="61.5" y="-221" font-family="arial" font-size="10.00" fill="#006000">in</text> +</g> +<!-- r1->s2 --> +<g id="edge2" class="edge"><title>r1->s2</title> +<path fill="none" stroke="black" d="M61.5,-173.125C61.5,-180.918 61.5,-190.27 61.5,-198.729"/> +<polygon fill="black" stroke="black" points="58.0001,-198.782 61.5,-208.782 65.0001,-198.782 58.0001,-198.782"/> +</g> +<!-- s3 --> +<g id="node5" class="node"><title>s3</title> +<ellipse fill="none" stroke="black" cx="108.5" cy="-223.5" rx="14.5" ry="14.5"/> +<text text-anchor="middle" x="108.5" y="-221" font-family="arial" font-size="10.00" fill="#006000">in</text> +</g> +<!-- r1->s3 --> +<g id="edge3" class="edge"><title>r1->s3</title> +<path fill="none" stroke="black" d="M73.6037,-173.125C80.0345,-182.224 87.9676,-193.449 94.6441,-202.895"/> +<polygon fill="black" stroke="black" points="91.9404,-205.134 100.57,-211.28 97.6568,-201.094 91.9404,-205.134"/> +</g> +<!-- r2 --> +<g id="node2" class="node"><title>r2</title> +<polygon fill="none" stroke="black" points="148.5,-101 94.5,-101 94.5,-65 148.5,-65 148.5,-101"/> +<text text-anchor="middle" x="121.5" y="-80.5" font-family="arial" font-size="10.00" fill="#006000">rule</text> +</g> +<!-- r2->r1 --> +<g id="edge5" class="edge"><title>r2->r1</title> +<path fill="none" stroke="black" d="M106.669,-101.303C99.4753,-109.695 90.7033,-119.93 82.8097,-129.139"/> +<polygon fill="black" stroke="black" points="80.0114,-127.025 76.1609,-136.896 85.3262,-131.581 80.0114,-127.025"/> +</g> +<!-- s4 --> +<g id="node6" class="node"><title>s4</title> +<ellipse fill="none" stroke="black" cx="121.5" cy="-155" rx="14.5" ry="14.5"/> +<text text-anchor="middle" x="121.5" y="-152.5" font-family="arial" font-size="10.00" fill="#006000">in</text> +</g> +<!-- r2->s4 --> +<g id="edge4" class="edge"><title>r2->s4</title> +<path fill="none" stroke="black" d="M121.5,-101.303C121.5,-110.01 121.5,-120.7 121.5,-130.171"/> +<polygon fill="black" stroke="black" points="118,-130.175 121.5,-140.175 125,-130.176 118,-130.175"/> +</g> +<!-- o1 --> +<g id="node7" class="node"><title>o1</title> +<ellipse fill="none" stroke="black" cx="61.5" cy="-83" rx="14.5" ry="14.5"/> +<text text-anchor="middle" x="61.5" y="-80.5" font-family="arial" font-size="10.00" fill="#006000">out</text> +</g> +<!-- o1->r1 --> +<g id="edge6" class="edge"><title>o1->r1</title> +<path fill="none" stroke="black" d="M61.5,-97.8297C61.5,-106.081 61.5,-116.847 61.5,-126.744"/> +<polygon fill="black" stroke="black" points="58.0001,-126.981 61.5,-136.981 65.0001,-126.981 58.0001,-126.981"/> +</g> +<!-- o2 --> +<g id="node8" class="node"><title>o2</title> +<ellipse fill="none" stroke="black" cx="121.5" cy="-14.5" rx="14.5" ry="14.5"/> +<text text-anchor="middle" x="121.5" y="-12" font-family="arial" font-size="10.00" fill="#006000">out</text> +</g> +<!-- o2->r2 --> +<g id="edge7" class="edge"><title>o2->r2</title> +<path fill="none" stroke="black" d="M121.5,-29.2788C121.5,-36.6355 121.5,-45.9556 121.5,-54.7067"/> +<polygon fill="black" stroke="black" points="118,-54.9286 121.5,-64.9286 125,-54.9286 118,-54.9286"/> +</g> +</g> +</svg> +<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="query.html">Bazel Query tool</a></li>. + 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> +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> + +</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/workspace/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>. +</p> + +<p> + 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:file1.txt", + "//data: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 by joining the paths of the test's source directory and the workspace-relative +path, e.g. <code>${TEST_SRCDIR}/path/to/data/file</code>. (The exact syntax +depends on your programming language, of course.)</p> + +<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: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> |