Introduce language to clearly warn against usage of $(CC) and $(JAVA).

--
MOS_MIGRATED_REVID=134062471

1 files changed, 37 insertions, 14 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm b/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
index 35454f922b..eeff7dc3c8 100644
--- a/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
+++ b/src/main/java/com/google/devtools/build/docgen/templates/be/make-variables.vm
@@ -87,12 +87,30 @@ tests. Simply rely on the PATH.</p>
 These tools may not be in the PATH, therefore you must use "Make" variable syntax
 in your genrule's cmd attribute.
 <ul>
-  <li> <code>CC</code>: The C compiler command. It is strongly recommended to
-    always use <code>CC_FLAGS</code> when invoking the C compiler.</li>
-  <li> <code>JAVA</code>: The "java" command (a Java virtual machine). Note that
-    this can be a relative path. If you must change directories before invoking
-    <code>java</code>, you need to capture the working directory before changing
-    it.</li>
+  <li class="harmful"> <code>CC</code>: The C compiler command. The built-in C++
+    rules are much more sophisticated than "run the compiler on it". In order to
+    support compilation modes as diverse as *SAN, LIPO, ThinLTO, with/without
+    modules, and carefully optimized binaries at the same time as fast running
+    tests on multiple platforms, the built-in rules go to great lengths to
+    ensure the correct inputs, outputs, and command-line flags are set on each
+    of potentially multiple internally generated actions.
+
+    <p>These environment variables are a fallback mechanism to be used by
+    language experts in rare cases. If you are tempted to use them, please talk
+    to us first.
+
+    <p>It is strongly recommended to always use <code>CC_FLAGS</code> in
+    combination with <code>CC</code>. Fail to do so at your own risk.
+  </li>
+  <li class="harmful"> <code>C_COMPILER</code>:
+    The C compiler frontend, e.g. "gcc".
+  </li>
+  <li class="harmful"> <code>JAVA</code>: The "java" command (a Java virtual
+    machine). Avoid this, and use a <code>java_binary</code> rule instead where
+    possible. May be a relative path. If you must change
+    directories before invoking <code>java</code>, you need to capture the
+    working directory before changing it.
+  </li>
 
   <li> <code>STRIP</code>: The strip command from the same suite as the C
     compiler.</li>
@@ -100,16 +118,15 @@ in your genrule's cmd attribute.
   <li> <code>NM</code>: The "nm" command from crosstool. </li>
   <li> <code>OBJCOPY</code>: The objcopy command from the same suite as the C
     compiler. </li>
-  <li> <code>C_COMPILER</code>:
-    The C compiler frontend, e.g. "gcc". </li>
 </ul>
 
 <p><strong>Tool option Variables</strong></p>
 
 <ul><!--  keep alphabetically sorted  -->
-  <li><code>CC_FLAGS</code>: A minimal set of flags for the C compiler to be
-    used by genrules. In particular, it contains flags to select the correct
-    architecture if CC supports multiple architectures. </li>
+  <li class="harmful"><code>CC_FLAGS</code>: A minimal set of flags for the C
+    compiler to be used by genrules. In particular, it contains flags to select
+    the correct architecture if <code>CC</code> supports multiple architectures.
+  </li>
   <li><code>COMPILATION_MODE</code>: "fastbuild", "dbg", or "opt".</li>
 
 </ul>
@@ -127,9 +144,15 @@ in your genrule's cmd attribute.
     attribute for the genrule.</li>
   <li><code>GENDIR</code>: The base of the generated code
     tree for the target architecture.</li>
-  <li><code>JAVABASE</code>:
-    The base directory containing the Java utilities.
-    It will have a "bin" subdirectory.</li>
+  <li class="harmful"><code>JAVABASE</code>: for Java, most of the tools in the
+    JDK should not be used as-is. The built-in Java rules use much more
+    sophisticated approaches to Java compilation and packaging than the upstream
+    tools can express, such as interface Jars, header interface Jars, and highly
+    optimized Jar packaging and merging implementations.
+
+    <p>The base directory containing the Java utilities. May be a relative path.
+    It will have a "bin" subdirectory.</p>
+  </li>
 </ul>
 
 <p><strong>Architecture Variables</strong></p>