blob: 038e1e461865dff83d1c01bda3cc8fa0d97d2590 [file] [log] [blame]
{namespace genrule}
/***/
{template .soyweb}
{call buck.page}
{param title: 'genrule()' /}
{param prettify: true /}
{param content}
{call buck.rule}
{param overview}
A <code>genrule()</code> is used to generate a file from a shell
command. It must produce a single output file.
{/param}
{param args}
{call buck.arg}
{param name: 'name' /}
{param desc}
The name of the genrule.
{/param}
{/call}
{call buck.arg}
{param name: 'srcs' /}
{param default: '[]' /}
{param desc}
A list of files to be used in the shell command.
{/param}
{/call}
{call buck.arg}
{param name: 'cmd' /}
{param default: 'None' /}
{param desc}
The shell command to run to generate the output file. It is the fallback of <code>bash</code>
{sp}and <code>cmd_exe</code>.
It will be subject to the following environment variable substitutions:
<dl>
<dt><code>SRCS</code><dt>
<dd>A space-delimited string expansion of the <code>srcs</code>
{sp}argument where each element of <code>srcs</code> will be
translated into an absolute path.</dd>
<dt><code>SRCDIR</code><dt>
<dd>The absolute path to a directory to which sources are copied
to prior to running the command.</dd>
<dt><code>OUT</code></dt>
<dd>The output file for the <code>genrule()</code>. The file
specified by this variable must always be written by this
command. If not, the execution of this rule will be considered a
failure, halting the build process.</dd>
</dl>
It is also possible to expand references to other rules within the
{sp}<code>cmd</code>. This expansion takes two supported forms:
<dl>
<dt><code>$(exe /&#x2F;path/to:target)</code></dt>
<dd>Expands a build rule that results in an executable to the commands
necessary to execute that command. For example, a <code>java_binary()
</code> may expand to a call to <code>java -jar path/to/target.jar
</code>. Files that are executable (perhaps generated by a <code>
genrule()</code>) will also be expanded. If the build rule does
not generate an executable output an exception will be thrown and
the build will break.</dd>
<dt><code>$(location /&#x2F;path/to:target)</code></dt>
<dd>Expands to the location of the output of the build rule. This
means that you can refer to these without needing to be aware of how
Buck is storing data on the disk mid-build.</dd>
</dl>
Note that all build rules expanded in the command must be listed in the
{sp}<code>deps</code> parameter of the <code>genrule()</code>.
{/param}
{/call}
{call buck.arg}
{param name: 'bash' /}
{param default: 'None' /}
{param desc}
The platform-specific version of parameter <code>cmd</code>.
It runs on UNIX in which <code>bash</code> is installed and has a higher priority than
{sp}<code>cmd</code>. Command specified will be run with <code>/bin/bash -c</code>.
{/param}
{/call}
{call buck.arg}
{param name: 'cmd_exe' /}
{param default: 'None' /}
{param desc}
The platform-specific version of parameter <code>cmd</code>. It runs on Windows and has a higher
{sp}priority than <code>cmd</code>. Command specified will be run with <code>cmd.exe /c</code>.
{/param}
{/call}
{call buck.arg}
{param name: 'out' /}
{param desc}
The name of the output file. Must be unique within the build file
in which the <code>genrule()</code> is declared.
{/param}
{/call}
{call buck.arg}
{param name: 'deps' /}
{param default: '[]' /}
{param desc}
A list of rules that must be built before this rule. These may be
accessed within the <code>cmd</code> by treating the target as a
brace-wrapped variable: <code>$(location /&#x2F;like:this)</code>.
{/param}
{/call}
{call buck.visibility_arg /}
{/param} // args
{param examples}
This genrule() uses a Python script to derive a new
{sp}<code>AndroidManifest.xml</code> from an
{sp}<code>AndroidManifest.xml</code> in the source tree.
{literal}<pre class="prettyprint lang-py">
genrule(
name = 'generate_manifest',
srcs = [
'AndroidManifest.xml',
],
bash = 'python $(exe //python/android:basic_to_full) ' \
'$SRCDIR/AndroidManifest.xml > $OUT',
cmd_exe = 'python.exe $(exe //python/android:basic_to_full) ' \
'%SRCDIR%\\AndroidManifest.xml > %OUT%',
out = 'AndroidManifest.xml',
deps = [
'//python/android:basic_to_full',
]
)
</pre>{/literal}
<h2>See Also</h2>
<a href="{ROOT}function/genfile.html"><code>genfile()</code></a>
{sp}function.
{/param} // examples
{/call} // buck.rule
{/param}
{/call}
{/template}