1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
|
#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 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>
<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>
</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
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>
</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="$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
|
