aboutsummaryrefslogtreecommitdiffhomepage
path: root/site/docs/user-manual.html
diff options
context:
space:
mode:
authorGravatar ccalvarin <ccalvarin@google.com>2017-11-28 10:39:54 -0800
committerGravatar Copybara-Service <copybara-piper@google.com>2017-11-28 10:42:03 -0800
commita3cdd93430bf6e3eabed3016ba8850b762831a02 (patch)
tree1140974272070adbf2769e8de8bedf65e5f4529f /site/docs/user-manual.html
parent6e978a3fe2c38c4a2dcfba27778c4961e1d38c9c (diff)
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
Diffstat (limited to 'site/docs/user-manual.html')
-rw-r--r--site/docs/user-manual.html188
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>