diff options
author | laszlocsomor <laszlocsomor@google.com> | 2018-02-05 00:48:35 -0800 |
---|---|---|
committer | Copybara-Service <copybara-piper@google.com> | 2018-02-05 00:50:02 -0800 |
commit | 45a0ffedf7b4cb3a9e8a12199565a89b05f29833 (patch) | |
tree | 8bd844c45158f2959ce685ec59033ec9de780df4 /site/docs/user-manual.html | |
parent | ea2d4c475febdbd59ca0e0ba46adc7be759f84e0 (diff) |
docs: document --workspace_status_command
Add docs for the --workspace_status_command flag.
Fixes https://github.com/bazelbuild/bazel/issues/4220
RELNOTES: none
PiperOrigin-RevId: 184492241
Diffstat (limited to 'site/docs/user-manual.html')
-rw-r--r-- | site/docs/user-manual.html | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/site/docs/user-manual.html b/site/docs/user-manual.html index 0c4a9b5900..46a9fce911 100644 --- a/site/docs/user-manual.html +++ b/site/docs/user-manual.html @@ -2412,6 +2412,107 @@ either to the terminal, or to additional log files. for copying and pasting to a shell prompt. </p> +<h3 id='workspace_status'>Options that control how Bazel embeds workspace status information +into binaries ("stamping")</h3> + +<p> + Use these options to "stamp" Bazel-built binaries: to embed additional information into the + binaries, such as the source control revision or other workspace-related information. You can use + this mechanism with rules that support the <code>stamp</code> attribute, such as + <code>genrule</code>, <code>cc_binary</code>, and more. +</p> + +<h4 id='flag--workspace_status_command'><code class='flag'>--workspace_status_command <var>program</var></code></h4> +<p> + This flag lets you specify a binary that Bazel runs before each build. The program can report + information about the status of the workspace, such as the current source control revision. +</p> +<p> + The flag's value must be a path to a native program. On Linux/macOS this may be any executable. + On Windows this must be a native binary, typically an ".exe", ".bat", or a ".cmd" file. +</p> + +<p> + The program should print zero or more key/value pairs to standard output, one entry on each line, + then exit with zero (otherwise the build fails). The key names can be anything but they may only + use upper case letters and underscores. The first space after the key name separates it from the + value. The value is the rest of the line (including additional whitespaces). +</p> +<p> + Bazel partitions the keys into two buckets: "stable" and "volatile". (The names "stable" and + "volatile" are a bit counter-intuitive, so don't think much about them.) +</p> + +<p>Bazel then writes the key-value pairs into two files:</p> +<ul> + <li> + <code>bazel-out/stable-status.txt</code> contains all keys and values where the key's name + starts with <code>STABLE_</code> + </li> + <li><code>bazel-out/volatile-status.txt</code> contains the rest of the keys and their values</li> +</ul> + +<p>The contract is:</p> +<ul> + <li> + <p> + "stable" keys' values should change rarely, if possible. If the contents of + <code>stable-status.txt</code> change, it invalidates the actions that depend on them. In + other words, if a stable key's value changes, it'll make Bazel rebuild stamped actions. + Therefore the stable status should not contain things like timestamps, because they change all + the time, and would make Bazel rebuild the stamped actions with each build. + </p> + <p>Bazel always outputs the following stable keys:</p> + <ul> + <li><code>BUILD_EMBED_LABEL</code>: value of <code class='flag'>--embed_label</code></li> + <li><code>BUILD_HOST</code>: the name of the host machine that Bazel is running on</li> + <li><code>BUILD_USER</code>: the name of the user that Bazel is running as</li> + </ul> + </li> + <li> + <p> + "volatile" keys' values may change often. Bazel expects them to change all the time, like + timestamps do, and duly updates the <code>volatile-status.txt</code> file. In order to avoid + rebuilding stamped actions all the time though, <b>Bazel pretends that the volatile file never + changes</b>. In other words, if the volatile status file is the only one whose contents + changed, that will not invalidate actions that depend on it. If other inputs of the actions + have changed, then Bazel rebuilds that action, and the action will use the updated volatile + status, but just the volatile status changing alone will not invalidate the action. + </p> + <p>Bazel always outputs the following volatile keys:</p> + <ul> + <li> + <code>BUILD_TIMESTAMP</code>: time of the build in milliseconds since the Unix Epoch (the + value of <code>System.currentTimeMillis()</code>) + </li> + </ul> + </li> +</ul> + +<p> + On Linux/macOS you can pass <code class='flag'>--workspace_status_command=/bin/true</code> to + disable retrieving workspace status, because <code>true</code> does nothing successfully (exits + with zero) and prints no output. On Windows you can pass the path of MSYS's <code>true.exe</code> + for the same effect. +</p> + +<p>If the workspace status command fails (exits non-zero) for any reason, the build will fail.</p> + +<p>Example program on Linux using Git:</p> + +<pre> +#!/bin/bash +echo "CURRENT_TIME $(date +%s)" +echo "RANDOM_HASH $(cat /dev/urandom | head -c16 | md5sum 2>/dev/null | cut -f1 -d' ')" +echo "STABLE_GIT_COMMIT $(git rev-parse HEAD)" +echo "STABLE_USER_NAME $USER" +</pre> + +<p> + Pass this program's path with <code>--workspace_status_command</code>, and the stable status file + will include the STABLE lines and the volatile status file will include the rest of the lines. +</p> + <h4 id='flag--stamp'><code class='flag'>--[no]stamp</code></h4> <p> This option controls whether stamping is enabled for |