Change the list of rc files accepted.

The old list was, in order:
- %workspace%/tools/bazel.rc (unless --nomaster_bazelrc)
- %binary_dir%/bazel.bazelrc (unless --nomaster_bazelrc)
- system rc, /etc/bazel.bazelrc or in %ProgramData% for Windows (unless --nomaster_bazelrc)
- the first of the following gets called the "user" bazelrc
  - path passed by flag --bazelrc
  - %workspace%/.bazelrc
  - $HOME/.bazelrc

The new list is hopefully a bit more consistent, as:
- system rc (unless --nosystem_rc)
- workspace, %workspace%/.bazelrc (unless --noworkspace_rc)
- user, $HOME/.bazelrc (unless --nohome_rc)
- command-line provided, passed as --bazelrc or nothing if the flag is absent.

This list removes two less than useful locations, duplication in the Workspace directory, and the rc next to the bazel binary. This location made sense at Google but is generally nonsensical elsewhere so we are removing it. It also stops the user local rc file from being overriden by passing in a custom file in --bazelrc.

In both old and new, --ignore_all_rc_files disables all of the above.
For a transition period, any file that you would have loaded but was not read will cause a WARNING to be printed. If you want the old file to still be read without moving its location, you can always import it into one of the new standard locations, or create a symlink.

Closes #4502, except for cleanup to remove the warning after a transition period of 1 Bazel version has passed.

RELNOTES[INC]: New bazelrc file list.

PiperOrigin-RevId: 207189212

1 files changed, 26 insertions, 24 deletions

diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html
index 5488052e1d..c4c947bb70 100644
--- a/site/docs/user-manual.html
+++ b/site/docs/user-manual.html
@@ -134,41 +134,43 @@ title: User Manual
   Bazel allows you to specify options in a configuration file.
 </p>
 
-<h4>Where are <code>.bazelrc</code> files?</h4>
+
+<h4>Where are the <code>.bazelrc</code> files?</h4>
 <p>
   Bazel looks for an optional configuration file in the following locations,
-  in order. It will stop searching once it has successfully found a file.
+  in the order shown below. The options are interpreted in this order, so
+  options in later files can override a value from an earlier file if a
+  conflict arises. All options to control which of these files are loaded are
+  startup options, which means they much occur after <code>bazel</code> and
+  before the command (<code>build</code>, etc).
 </p>
 <ol>
   <li>
-    The path specified by the <code class='flag'>--bazelrc=<var>file</var></code>
-    startup option. If specified, this option must appear <em>before</em> the
-    command name (e.g. <code>build</code>)
+    Unless the <code class='flag'>--nosystem_rc</code> is present, Bazel looks for
+    the system .bazelrc file: on Unix, it lives at <code>/etc/bazel.bazelrc</code>,
+    and on Windows at <code>%%ProgramData%%/bazel.bazelrc</code>.
+
+    If another system-specified location is required, this value can be
+    changed by setting <code>BAZEL_SYSTEM_BAZELRC_PATH</code> in
+    <code>src/main/cpp:option_processor</code> and using this custom Bazel binary.
   </li>
   <li>
-    A file named <code>.bazelrc</code> in your base workspace directory
+    Unless the <code class='flag'>--noworkspace_rc</code> is present, Bazel looks
+    for the <code>.bazelrc</code> file in your workspace directory.
+  </li>
+  <li>
+    Unless the <code class='flag'>--nohome_rc</code> is present, Bazel looks for
+    the home, or user, bazelrc: the file <code>.bazelrc</code> in your home
+    directory.
   </li>
   <li>
-    A file named <code>.bazelrc</code> in your home directory
+    An additional .rc file can be specified by the
+    <code class='flag'>--bazelrc=<var>file</var></code> startup option. If this
+    option is not present, no additional file is loaded. Unlike in the three
+    default locations specified above, an incorrect path or non-existent file
+    will fail if passed explicitly.
   </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
-  this option when performing release builds, or automated tests that
-  invoke Bazel.
-</p>
-
-<p>
-  Aside from the optional configuration file described above, Bazel also looks
-  for a master rc file named <code>bazel.bazelrc</code> 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. These files do not
-  override one another; if all of these files exist, all of them will be loaded.
-  Reading of these files 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