{namespace genrule}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'genrule()' /}
    {param prettify: true /}
    {param description}
      A rule that is used to generate a file from a shell command. It must
      produce a single output file.
    {/param}
    {param content}

{call buck.rule}
{param status: 'FROZEN' /}
{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>, using builtin {call buck.string_parameter_macros /}.
    This expansion takes two supported forms:
    <dl>
      <dt><code>$(classpath /&#2F;path/to:target)</code></dt>
      <dd>Expands a build rule for something that has a java classpath
      to the transitive classpath of that rule. If the rule does not
      have (or contribute to) a classpath, an exception will be thrown
      and the build will break.</dd>

      <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}

{/param} // examples

{/call} // buck.rule

 {/param}
  {/call}
{/template}