Rewrote and updated several pages in the Blaze docs. Updates include:
- Rewrote Writing BUILD files page as build-files.md. b/183718088
- Wrote Getting Started with Blaze.
- Cleaned up Overview.
- Updated Sitemap.
- Started cleaning up Concepts and Guide.
- Added link redirect to METADATA.
- Cleaned up broken links.
TODO: update[]
Looking for review input on the possibly outdated tutorials in build-files.md.
PiperOrigin-RevId: 370481159
diff --git a/site/docs/build-ref.html b/site/docs/build-ref.html
index e418a0a..1179f95 100644
--- a/site/docs/build-ref.html
+++ b/site/docs/build-ref.html
@@ -95,7 +95,7 @@
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,
+ <i>Generated files</i>, sometimes called derived files or output files,
are not checked in, but are generated by the build tool from source
files according to specific rules.
</p>
@@ -143,8 +143,8 @@
<p>
Package groups are sets of packages whose purpose is to limit accessibility
of certain rules. Package groups are defined by the
- <code>package_group</code> function. They have two properties: the list of
- packages they contain and their name. The only allowed ways to refer to them
+ <code>package_group</code> function. They have three properties: the list of
+ packages they contain, their name, and other package groups they include. The only allowed ways to refer to them
are from the <code>visibility</code> attribute of rules or from the
<code>default_visibility</code> attribute of the <code>package</code>
function; they do not generate or consume files. For more information, refer
@@ -246,7 +246,7 @@
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
+ directories 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>:
@@ -266,7 +266,11 @@
looks for <code>//a/b/c</code> in the external repository itself.
This is especially relevant when writing rules in the main
repository that refer to targets in the main repository, and will be
- used from external repositories. For information about the different ways
+ used from external repositories.
+</p>
+
+<p>
+For information about the different ways
you can refer to targets, see
[target patterns](guide.html#specifying-targets-to-build).
</p>
@@ -275,12 +279,9 @@
<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>.
+ Label syntax discourages use of 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>.
The precise details of allowed target names are below.
</p>
@@ -304,9 +305,7 @@
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>'.
+ (<code>./</code>) are forbidden.
</p>
<p>While it is common to use <code>/</code> in the name of a file
@@ -408,21 +407,6 @@
</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 <code>srcs</code>, whereas a rule <i>is
- depended on by</i> its <code>outs</code>. The two types of label attributes
- thus assign direction to the edges between targets, giving rise to a
- dependency graph.
-</p>
-
-<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> operates.
@@ -466,7 +450,7 @@
To encourage a clean separation between code and data, BUILD files cannot
contain function definitions, <code>for</code> statements or
<code>if</code> statements (but list comprehensions and <code>if</code>
- expressions are allowed). Functions should be declared in <code>.bzl</code>
+ expressions are allowed). Functions can be declared in <code>.bzl</code>
files instead. Additionally, <code>*args</code> and <code>**kwargs</code>
arguments are not allowed in BUILD files; instead list all the arguments
explicitly.
@@ -560,7 +544,7 @@
so <code>//my:program</code> would appear at
(e.g.) <code>$(BINDIR)/my/program</code>. </p>
- <p>Such rules also create a runfiles directory
+ <p>In some languages, 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
@@ -974,8 +958,7 @@
<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
+ names do not conform to the <a href='#lexi'>label syntax</a>, then explicit
enumeration of files, or use of the
<a href='be/functions.html#glob'><code>glob()</code></a> function will
produce an invalid labels error. You must use directory labels in this case,
