Build encyclopedia: mark attributes that don't work with
select() as "nonconfigurable", polish up general configurable
attributes docs.
--
MOS_MIGRATED_REVID=127440164
diff --git a/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java b/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java
index fa53ca8..02357ff 100644
--- a/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java
+++ b/src/main/java/com/google/devtools/build/docgen/RuleDocumentationAttribute.java
@@ -180,6 +180,7 @@
StringBuilder sb = new StringBuilder()
.append(TYPE_DESC.get(attribute.getType()))
.append("; " + (attribute.isMandatory() ? "required" : "optional"))
+ .append(!attribute.isConfigurable() ? "; nonconfigurable" : "")
.append(getDefaultValue());
return sb.toString();
}
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
index 8a49b6f..ff9e2a5 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/common-definitions.vm
@@ -109,13 +109,50 @@
<h2 id="configurable-attributes">Configurable attributes</h2>
<p>
- Most rule attributes can be "configured" so their values depend on Bazel
- command-line flags. This can be used, for example, to declare
+ Most attributes can be "configured" so their values depend on the flags passed
+ at the command line. This can be used, for example, to declare
platform-dependent <code>srcs</code> or custom compiler flags depending on the
<a href="../bazel-user-manual.html#flag--compilation_mode">compilation
mode</a>.
</p>
+<h4>Example</h4>
+
+<pre class="code">
+cc_library(
+ name = "multiplatform_lib",
+ srcs = select({
+ ":x86_mode": ["x86_impl.cc"],
+ ":arm_mode": ["arm_impl.cc"]
+ })
+)
+config_setting(
+ name = "x86_mode",
+ values = { "cpu": "x86" }
+)
+config_setting(
+ name = "arm_mode",
+ values = { "cpu": "arm" }
+)
+</pre>
+
+<p>
+ An attribute is made configurable by assigning it to a <code>select</code>.
+ This makes its value depend on which <code>config_setting</code> matches
+ the build. For example, <code>bazel build :multiplatform_lib --cpu=arm</code>
+ sets <code>multiplatform_lib</code>'s <code>srcs</code> to
+ <code>["arm_impl.cc"]</code>, while <code>bazel build :multiplatform_lib
+ --cpu=x86</code> sets <code>srcs</code> to <code>["x86_impl.cc"]</code>.
+</p>
+
+<p>
+ See the definitions of
+ <a href="functions.html#select">select</a> and
+ <a href="general.html#config_setting">config_setting</a> for more details.
+ Attributes marked <code>nonconfigurable</code> in their documentation cannot
+ use this feature (usually because Bazel has to know their values before flags
+ have been parsed).
+
</p>
<h2 id="implicit-outputs">Implicit output targets</h2>
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 3bea6a4..780716c 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
@@ -589,10 +589,9 @@
<pre>select({conditionA: valuesA, conditionB: valuesB, ...})</pre>
-<p><code>select()</code> is the helper function that makes an
- attribute for a
- rule <a href="common-definitions.html#configurable-attributes">configurable</a>. It can
- replace the right-hand side of
+<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
@@ -648,7 +647,8 @@
srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB":
["b.sh"]})</code> are valid expressions.
</li>
- <li><code>select</code> works with most, but not all, attributes.
+ <li><code>select</code> works with most, but not all, attributes. Incompatible
+ attributes are marked <code>nonconfigurable</code> in their documentation.
</li>
</ul>
