From e6dc7d6679e9036868e2e1b24ff08dbc6f2ebdb1 Mon Sep 17 00:00:00 2001
From: Greg Estren <gregce@google.com>
Date: Fri, 16 Sep 2016 17:41:25 +0000
Subject: Adds no_match_error documentation to select, example usage.

--
MOS_MIGRATED_REVID=133401134
---
 .../build/docgen/templates/be/functions.vm         | 58 +++++++++++++++++++---
 1 file changed, 51 insertions(+), 7 deletions(-)

(limited to 'src/main/java')

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
index 4b7ddfa3f3..293b043302 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/functions.vm
@@ -593,18 +593,22 @@ $ bazel query '//foo:all' | sort
 
 <h2 id="select">select</h2>
 
-<pre>select({conditionA: valuesA, conditionB: valuesB, ...})</pre>
+<pre>
+select(
+    {conditionA: valuesA, conditionB: valuesB, ...},
+    no_match_error = "custom message"
+)
+</pre>
 
 <p><code>select()</code> is the helper function that makes a rule attribute
   <a href="common-definitions.html#configurable-attributes">configurable</a>.
   It can replace the right-hand side of
 
   <i>almost</i>
-  any attribute assignment so that the attribute's value depends on the
-  Bazel flags passed in at the command line. This can be used, for
-  example, to define platform-specific dependencies or to embed
-  different resources depending on whether a rule is built in
-  "developer" vs. "release" mode.
+  any attribute assignment so its value depends on command-line Bazel flags.
+  This can be used, for example, to define platform-specific dependencies or to
+  embed different resources depending on whether a rule is built in "developer"
+  vs. "release" mode.
 </p>
 
 <p>Basic usage is as follows:</p>
@@ -637,7 +641,7 @@ sh_binary(
   <li>Exactly one condition is selected on any invocation.
   </li>
   <li>If two conditions match and one is a specialization of the other
-    (e.g. it matches on the same flags as the other plus additional flags),
+    (i.e. it matches on the same flags as the other plus additional ones),
     the specialization takes precedence.
   </li>
   <li>If two conditions match and neither is a specialization of the other,
@@ -659,6 +663,46 @@ sh_binary(
   </li>
 </ul>
 
+By default, Bazel produces the following error when no conditions match:
+<pre class="code">
+Configurable attribute "foo" doesn't match this configuration (would a default
+condition help?).
+Conditions checked:
+ //pkg:conditionA.
+ //pkg:conditionB.
+</pre>
+
+<code>no_match_error</code> can be used to signal more precise errors.
+
+<h3 id="select_example">Examples</h3>
+
+<pre class="code">
+config_setting(
+    name = "windows",
+    values = {
+        "crosstool_top": "//crosstools/windows",
+    },
+)
+
+cc_binary(
+    name = "multiplatform_app",
+    ...
+    linkopts = select({
+        ":windows": [
+            "-Wl,windows_support1.lib",
+            "-Wl,windows_support2.lib",
+        ],
+        "//conditions:default": [],
+    ...
+)
+</pre>
+
+<p>In the above example, <code>multiplatform_app</code> links with additional
+  options when invoked with <code>bazel build //pkg:multiplatform_app
+  --crosstool_top=//crosstools/windows </code>.
+
+<p>
+
 <!-- =================================================================
                               workspace()
      =================================================================
-- 
cgit v1.2.3