| #if (!$singlePage) |
| --- |
| layout: documentation |
| title: Make Variables |
| --- |
| #end |
| #if (!$singlePage) |
| #parse("com/google/devtools/build/docgen/templates/be/header.vm") |
| #end |
| |
| <!-- ============================================ |
| variables |
| ============================================ |
| --> |
| <h1 id="make-variables">"Make" Variables</h1> |
| |
| #if (!$singlePage) |
| <div class="toc"> |
| <ul> |
| <li><a href="#make-var-substitution">"Make" variable subsitution</a></li> |
| <li><a href="#predefined_variables">Predefined variables</a></li> |
| <li><a href="#location">"$(location)" substitution</a></li> |
| </ul> |
| </div> |
| #end |
| <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="$expander.expandRef("genrule.cmd")"><code>cmd</code> attribute of a genrule</a>. |
| </p> |
| |
| <h2 id='make-var-substitution'>"Make" variable substitution</h2> |
| |
| <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> |
| |
| <h2 id="predefined_variables">Predefined "Make" Variables</h2> |
| |
| <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 class="harmful"> <code>CC</code>: The C and 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, 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/C++ compiler identifier, e.g. "llvm". |
| </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. This variable is only available if the |
| Java runtime, that is, |
| |
| <code>@bazel_tools//tools/jdk:current_java_runtime</code> |
| or its host version (<code>current_host_java_runtime</code>) is in the |
| <code>toolchains</code> attribute. |
| </li> |
| |
| <li> <code>STRIP</code>: The strip command from the same suite as the C/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/C++ |
| compiler. </li> |
| </ul> |
| |
| <p><strong>Tool option Variables</strong></p> |
| |
| <ul><!-- keep alphabetically sorted --> |
| <li class="harmful"><code>CC_FLAGS</code>: A minimal set of flags for the C/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> |
| |
| <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 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> |
| |
| <p>This variable is only available if the Java runtime, that is, |
| |
| <code>@bazel_tools//tools/jdk:current_java_runtime</code> |
| or its host version (<code>current_host_java_runtime</code>) is in the |
| <code>toolchains</code> attribute.</p> |
| </li> |
| </ul> |
| |
| <p><strong>Architecture Variables</strong></p> |
| |
| <ul><!-- keep alphabetically sorted --> |
| <li><code>ABI</code>: |
| The C++ ABI version. </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="$expander.expandRef("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> |
| |
| #if (!$singlePage) |
| #parse("com/google/devtools/build/docgen/templates/be/footer.vm") |
| #end |