diff options
Diffstat (limited to 'src/main/java/com/google/devtools/build/docgen/templates/build-encyclopedia.vm')
| -rw-r--r-- | src/main/java/com/google/devtools/build/docgen/templates/build-encyclopedia.vm | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/src/main/java/com/google/devtools/build/docgen/templates/build-encyclopedia.vm b/src/main/java/com/google/devtools/build/docgen/templates/build-encyclopedia.vm new file mode 100644 index 0000000000..aa7f4fa82f --- /dev/null +++ b/src/main/java/com/google/devtools/build/docgen/templates/build-encyclopedia.vm @@ -0,0 +1,246 @@ +#parse("com/google/devtools/build/docgen/templates/header-comment.vm") + +#parse("com/google/devtools/build/docgen/templates/be-header.vm") + +<!-- ============================================ + binary + ============================================ +--> +<h2 id="binary">*_binary</h2> + +<p>A <code>*_binary</code> rule compiles an application. This might be + an executable, a <code>.jar</code> file, and/or a collection of scripts.</p> + +${SECTION_BINARY} + +<!-- ============================================ + library + ============================================ +--> +<h2 id="library">*_library</h2> + +<p>A <code>*_library()</code> rule compiles some sources into a library. + In general, a <code><var>language</var>_library</code> rule works like + the corresponding <code><var>language</var>_binary</code> rule, but + doesn't generate an executable.</p> + +${SECTION_LIBRARY} + +<!-- ============================================ + test + ============================================ +--> +<h2 id="test">*_test</h2> + +<p>A <code>*_test</code> rule compiles a test. + + +${SECTION_TEST} + +<!-- ============================================ + variables + ============================================ +--> +<h2 id="make_variables">"Make" Variables</h2> + + +<p> + This section describes how to use a special class of built-in string variables + that are called the "Make" environment. + + Defining custom "Make" variables is not supported. +</p> + +<p>(The reason for the term "Make" is historical: the syntax and semantics of + these variables are somewhat similar to those of GNU Make.) +</p> + +<p>To see the list of all common "Make" variables and their values, + run <code>bazel info --show_make_env</code>. +</p> + +<p>Build rules can introduce additional rule specific variables. One example is + the <a href="#genrule.cmd"><code>cmd</code> attribute of a genrule</a>. +</p> + +<h3 id='make-var-substitution'>"Make" variable substitution</h3> + +<p>Variables can be referenced in attributes + + using <code>$(FOO)</code> + where <code>FOO</code> is + the variable name. In the attribute documentation of rules, it is mentioned + when an attribute is subject to "Make" variable substitution. For those + attributes this means that any substrings of the form <code>$(X)</code> + within those attributes will be interpreted as references to the "Make" + variable <var>X</var>, and will be replaced by the appropriate value of that + variable for the applicable build configuration. The parens may be omitted + for variables whose name is a single character. +</p> +<p> + It is an error if such attributes contain embedded strings of the + form <code>$(X)</code> where <var>X</var> is not the name of a + "Make" variable, or unclosed references such as <code>$(</code> not + matched by a corresponding <code>)</code>. +</p> +<p> + Within such attributes, literal dollar signs must be escaped + as <code>$$</code> to prevent this expansion. +</p> +<p> + Those attributes that are subject to this substitution are + explicitly indicated as such in their definitions in this document. +</p> + +<h3 id="predefined_variables">Predefined "Make" Variables</h3> + +<p>Bazel defines a set of "Make" variables for you.</p> + +<p>The build system also provides a consistent PATH environment variable for +genrules and tests which need to execute shell commands. For genrules, you can +indirect your commands using the "Make" variables below. For basic Unix +utilities, prefer relying on the PATH environment variable to guarantee correct +results. For genrules involving compiler and platform invocation, you must use +the "Make" variable syntax. The same basic command set is also available during +tests. Simply rely on the PATH.</p> + +<p><strong>Compiler and Platforms available to genrules</strong></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> <code>JAVAC</code>: The "javac" command (a Java compiler). Note that + this can be a relative path. Also, this may not be the same compiler that is + used to compile normal Java rules (this may change in the future).</li> + + <li> <code>STRIP</code>: The strip command from the same suite as the C + compiler.</li> + <li> <code>AR</code>: The "ar" command from crosstool. </li> + <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>BINMODE</code>: "-dbg" or "-opt" + + . (<i>When using Bazel's <code>-c fastbuild</code> option, + this variable has the value <code>-dbg</code>.</i>) </li> + <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><code>COMPILATION_MODE</code>: "fastbuild", "dbg", or "opt".</li> + +</ul> + +<p><strong>Path Variables</strong></p> + +<ul><!-- keep alphabetically sorted --> + <li><code>BINDIR</code>: The base of the generated binary tree for the target + architecture. (Note that a different tree may be used for + programs that run during the build on the host architecture, + to support cross-compiling. If you want to run a tool from + within a genrule, the recommended way of specifying the path to + the tool is to use <code>$(location <i>toolname</i>)</code>, + where <i>toolname</i> must be listed in the <code>tools</code> + 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> +</ul> + +<p><strong>Architecture Variables</strong></p> + +<ul><!-- keep alphabetically sorted --> + <li><code>ABI</code>: + The C++ ABI version; currently "gcc-3.4". </li> + + <li> <code>TARGET_CPU</code>: The target architecture's cpu, + e.g. "piii" or "k8". </li> +</ul> + +<p id="predefined_variables.genrule.cmd"> + <strong> + Other Variables available to <a href="#genrule.cmd">the cmd attribute of a genrule</a> + </strong> +</p> +<ul><!-- keep alphabetically sorted --> + <li><code>OUTS</code>: The <code>outs</code> list. If you have only one output + file, you can also use <code>$@</code>.</li> + <li><code>SRCS</code>: The <code>srcs</code> list (or more + precisely, the pathnames of the files corresponding to + labels in the <code>srcs</code> list). If you have only one + source file, you can also use <code>$<</code>.</li> + <li><code><</code>: <code>srcs</code>, if it is a single file.</li> + <li><code>@</code>: <code>outs</code>, if it is a single file.</li> + <li><code>@D</code>: The output directory. If there is only + one filename in <code>outs</code>, this expands to the + directory containing that file. If there are multiple + filenames, this variable instead expands to the package's root + directory in the <code>genfiles</code> tree, <i>even if all + the generated files belong to the same subdirectory</i>! + <!-- (as a consequence of the "middleman" implementation) --> + If the genrule needs to generate temporary intermediate files + (perhaps as a result of using some other tool like a compiler) + then it should attempt to write the temporary files to + <code>@D</code> (although <code>/tmp</code> will also be + writable), and to remove any such generated temporary files. + Especially, avoid writing to directories containing inputs - + they may be on read-only filesystems, and even if they aren't, + doing so would trash the source tree.</li> +</ul> + +<h2 id="location">"$(location)" substitution</h2> + +<p> + In attributes that support it, all occurrences of + <code>$(location <i>label</i>)</code> are replaced by the path to the + file denoted by <i>label</i>. Use <code>location</code> if the <i>label</i> + outputs exactly one filename. This allows bazel to perform a check and give + an error if no or more than one files are represented by the given label; a + label referring to a source file always represents a single file, but a label + referring to a rule refers to all output files of that rule. Otherwise use + <code>$(location<b>s</b> <i>label</i>)</code>; bazel will then raise an error + if no files are generated. In both cases, if the label is malformed then an + error is raised. +</p> +<p> + The <i>label</i> needs not be in canonical form: + <code>foo</code>, <code>:foo</code> and <code>//somepkg:foo</code> are + all fine. It may also be the name of an output file from the + <code>outs</code> attribute. +</p> +<p> + The expanded paths are relative to the runfiles directory of the + <code>*_test</code> or <code>*_binary</code> rule. +</p> + +<h2 id="predefined-python-variables">Predefined Python Variables</h2> + +<h3 id="packagename">PACKAGE_NAME</h3> +<p> + This is a string variable with the name + of the package being evaluated. The value is unaffected by subinclude. +</p> + +<!-- ============================================ + other + ============================================ +--> +<h2 id="misc">Other Stuff</h2> + +${SECTION_OTHER} + + +#parse("com/google/devtools/build/docgen/templates/be-footer.vm") |