diff options
author | 2017-11-28 10:39:54 -0800 | |
---|---|---|
committer | 2017-11-28 10:42:03 -0800 | |
commit | a3cdd93430bf6e3eabed3016ba8850b762831a02 (patch) | |
tree | 1140974272070adbf2769e8de8bedf65e5f4529f /site/docs/user-manual.html | |
parent | 6e978a3fe2c38c4a2dcfba27778c4961e1d38c9c (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.html | 188 |
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> |