Update blazerc documentation in the blaze/bazel user mannuals.

Update the docs for clarity and to explain the --expand_configs_in_place alternate expansion behavior.

RELNOTES: None.
PiperOrigin-RevId: 177183524

1 files changed, 121 insertions, 67 deletions

diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
index b1f64d4434..5140bb1f2d 100644
--- a/site/docs/user-manual.html
+++ b/site/docs/user-manual.html
@@ -124,31 +124,38 @@ title: User Manual
   server process doesn't interfere with proper versioning.
 </p>
 
-<h3 id='bazelrc'><code>.bazelrc</code>, the Bazel configuration file,
-the <code class='flag'>--bazelrc=<var>file</var></code> option, and the
-<code class='flag'>--config=<var>value</var></code> option</h3>
+<h3 id='bazelrc'>
+  <code>.bazelrc</code>, the Bazel configuration file,
+  the <code class='flag'>--bazelrc=<var>file</var></code> option, and
+  the <code class='flag'>--config=<var>value</var></code> option
+</h3>
 
 <p>
   Bazel accepts many options.  Typically, some of these are varied
   frequently (e.g. <code class='flag'>--subcommands</code>) while others stay the
   same across several builds (e.g. <code class='flag'>--package_path</code>).
-  To avoid having to specify these constant options every time you do
-  a build or run some other Bazel command, Bazel allows you to
-  specify options in a configuration file.
-</p>
-<p>
-  Bazel looks for an optional configuration file in the location
-  specified by the <code class='flag'>--bazelrc=<var>file</var></code> option.  If
-  this option is not specified then, by default, Bazel looks for the
-  file called <code>.bazelrc</code> in one of two directories: first,
-  in your base workspace directory, then in your home directory.  If
-  it finds a file in the first (workspace-specific) location, it will
-  not look at the second (global) location.
+  To avoid having to specify these unchanged options for every build (and other commands)
+  Bazel allows you to specify options in a configuration file.
 </p>
+
+<h4>Where are <code>.bazelrc</code> files?</h4>
 <p>
-  The <code class='flag'>--bazelrc=<var>file</var></code> option must
-  appear <em>before</em> the command name (e.g. <code>build</code>).
+  Bazel looks for an optional configuration file in the following locations,
+  in order. It will stop searching once it has successfully found a file.
 </p>
+<ol>
+  <li>
+    The path specified by the <code class='flag'>--bazelrc=<var>file</var></code>
+    statup option. If specified, this option must appear <em>before</em> the
+    command name (e.g. <code>build</code>)
+  </li>
+  <li>
+    A file named <code>.bazelrc</code> in your base workspace directory
+  </li>
+  <li>
+    A file named <code>.bazelrc</code> in your home directory
+  </li>
+</ol>
 <p>
   The option <code class='flag'>--bazelrc=/dev/null</code> effectively disables the
   use of a configuration file.  We strongly recommend that you use
@@ -157,73 +164,119 @@ the <code class='flag'>--bazelrc=<var>file</var></code> option, and the
 </p>
 
 <p>
-  Aside from the configuration file described above, Bazel also looks
-  for a master configuration file next to the binary, in the workspace
-  at <code>tools/bazel.rc</code> or system-wide at
-  <code>/etc/bazel.bazelrc</code>. These files are here to support
-  installation-wide options or options shared between users.
+  Aside from the optional configuration file described above, Bazel also looks
+  for a master rc file next to the binary, in the workspace at
+  <code>tools/bazel.rc</code> or system-wide at <code>/etc/bazel.bazelrc</code>.
+  These files are here to support installation-wide options or options shared
+  between users. Reading of this file can be disabled using the
+  <code class='flag'>--nomaster_bazelrc</code> option.
+</p>
+<h4><code>.bazelrc</code> syntax and semantics</h4>
+<p>
+  Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text file with
+  a line-based grammar.  Lines starting <code>#</code> are considered comments
+  and are ignored, as are blank lines.  Each line contains a sequence of words,
+  which are tokenized according to the same rules as the Bourne shell.
+</p>
+
+<h5>Imports</h5>
+<p>
+  Lines that start with <code>import</code> are special: if Bazel encounters such
+  a line in a <code>.bazelrc</code> file, it parses the contents of the file
+  referenced by the import statement, too. Options specified in an imported file
+  take precedence over options specified before the import statement. Options
+  specified after the import statement take precedence over the options in the
+  imported file. Options in files imported later take precedence over files
+  imported earlier. To specify a path that is relative to the workspace root,
+  write <code>import %workspace%/path/to/bazelrc</code>.
 </p>
+
+<h5>Option defaults</h5>
 <p>
-  Like all UNIX "rc" files, the <code>.bazelrc</code> file is a text
-  file with a line-based grammar.  Lines starting <code>#</code> are
-  considered comments and are ignored, as are blank lines.  Each line
-  contains a sequence of words, which are tokenized according to the
-  same rules as the Bourne shell.
-  The first word on each line is the name of a Bazel command, such
-  as <code>build</code> or <code>query</code>.  The remaining words
-  are the default options that apply to that command.
-  More than one line may be used for a command; the options are combined
-  as if they had appeared on a single line.
-  (Users of CVS, another tool with a "Swiss army knife" command-line
-  interface, will find the syntax familiar to that of <code>.cvsrc</code>.)
+  Most lines of a bazelrc define default option values. The first word on each
+  line specifies when these defaults are applied:
 </p>
+<ol>
+  <li>
+    <code>startup</code>: startup options, which go before the command, and
+    are described in <code>bazel help startup_options</code>.
+  </li>
+  <li>
+    <code>common</code>: options that apply to all Bazel commands.
+  </li>
+  <li>
+    <code><i>command</i></code>: Bazel command, such as <code>build</code>
+    or <code>query</code> to which the options apply. These options also apply
+    to all commands that inherit from the specified command. (For example,
+    <code>test</code> inherits from <code>build</code>.)
+  </li>
+</ol>
 <p>
-  Startup options may be specified in the
-  <code>.bazelrc</code> file using the command <code>startup</code>.
-  These options are described in the interactive help
-  at <code>bazel help startup_options</code>.
+  Each of these lines may be used more than once and the arguments that follow
+  the first word are combined as if they had appeared on a single line.
+  (Users of CVS, another tool with a "Swiss army knife" command-line interface,
+  will find the syntax familiar to that of <code>.cvsrc</code>.)
 </p>
 <p>
-  Options specified in the command line always take precedence over
-  those from a configuration file. In configuration files, lines for a more specific command take
-  precedence over lines for a less specific command (e.g. the 'test' command inherits all the
-  options from the 'build' command, so a 'test --foo=bar' line takes precedence over a
-  'build --foo=baz' line, regardless of which configuration files these two lines are in) and lines
-  equally specific for which command they apply have precedence based on the configuration file they
-  are in, with the user-specific configuration file taking precedence over the master one.
+  Options specified in the command line always take precedence over those from
+  a configuration file. Within the configuration file, precedence is
+  given by specificity. This means that lines for a more specific command take
+  precedence over lines for a less specific command, with <code>common</code>
+  getting lowest precedence (for example, the <code>test</code> command inherits
+  all the options from the <code>build</code> command, so the line
+  <code>test --foo=bar</code> takes precedence over the line
+  <code>build --foo=baz</code> line, regardless of which rc file or what order
+  these two lines are in). Two lines specifying options for the same command at
+  equal specificity are parsed in the order in which they appear within the file.
+  The user-specific configuration file takes precedence over the master file.
 </p>
 <p>
-  Options may include words other than flags, such as the names of
-  build targets, etc; these are always prepended to the explicit
-  argument list provided on the command-line, if any.
+  Because this precedence rule does not match the file order, we recommend
+  that the file follows the same order, with <code>common</code> options at the
+  top, and most-specific commands near the bottom. This way, the order in which
+  the options are read is the same as the order in which they are applied,
+  which is more intuitive.
 </p>
 <p>
-  Common command options may be specified in the
-  <code>.bazelrc</code> file using the command <code>common</code>.
+  The arguments specified on line of an rc file may include arguments that are
+  not options, such as the names of build targets, and so on. These, like the
+  options specified in the same files, have lower precedence than their siblings
+  on the command line, and are always prepended to the explicit list of non-
+  option arguments.
 </p>
+<h5><code>--config</code></h5>
 <p>
-  In addition, commands may have <code>:name</code> suffixes. These
-  options are ignored by default, but can be pulled in through the
-  <code>--config=<var>name</var></code> option, either on the command line or in
-  a <code>.bazelrc</code> file. The intention is that these bundle command line
-  options that are commonly used together, for example
-  <code>--config=memcheck</code>.
+  In addition to setting option defaults, the rc file can be used to group
+  options and provide a shorthand for common groupings. This is done by adding
+  a <code>:name</code> suffix to the command. These options are ignored by
+  default, but will be included when the option
+  <code>--config=<var>name</var></code> is present, either on the command line
+  or in a <code>.bazelrc</code> file, recursively, even inside of another
+  config definition. Only the options specified by <code>command:name</code>
+  for applicable commands will be expanded, in the precedence order described
+  above.
 </p>
 <p>
-  Note that some config sections are defined in the master bazelrc file.
-  To avoid conflicts, user-defined sections
-  should start with the '_' (underscore) character.
+  Note that configs can be defined in any <code>.bazelrc</code> file, and that
+  all lines of the form <code>command:name</code> (for applicable commands)
+  will be expanded, across the different rc files. In order to avoid name
+  conflicts, we suggest that configs defined in personal rc files start
+  with an underscore ('_') to avoid unintentional name sharing.
 </p>
 <p>
-  The command named <code>import</code> is special: if Bazel encounters such
-  a line in a <code>.bazelrc</code> file, it parses the contents of the file
-  referenced by the import statement, too. Options specified in an imported file
-  take precedence over ones specified before the import statement, options
-  specified after the import statement take precedence over the ones in the
-  imported file, and options in files imported later take precedence over files
-  imported earlier. To specify a path that is relative to the workspace root,
-  write <code>import %workspace%/path/to/bazelrc</code>.
+  The expansion behavior for these <code>--config=foo</code> options has
+  changed. The legacy behavior, still the default, is to expand these in a
+  fixed point expansion after all default rc options are loaded. This is
+  unintuitive and has caused debugging difficulties in the past. The new
+  behavior is to expand <code>--config=foo</code> to the options it expands to
+  "in-place" so that the options specified for the config have the same
+  precedence that the <code>--config=foo</code> option had. This is more
+  intuitive, and can be enabled using the startup flag
+  <code>--expand_configs_in_place</code>, which can be included in a bazelrc
+  file on a <code>startup</code> line.
 </p>
+
+<h5>Example</h5>
 <p>
   Here's an example <code>~/.bazelrc</code> file:
 </p>
@@ -236,6 +289,7 @@ the <code class='flag'>--bazelrc=<var>file</var></code> option, and the
   build --color=yes
   query --keep_going
 
+  # Definition of --config=memcheck
   build:memcheck --strip=never --test_timeout=3600
 </pre>