{namespace buck.string_parameter_macros}

/***/

{template .soyweb}

{call buck.page}

{param title: 'String Parameter Macros' /}

{param navid: 'function_string_parameter_macros' /}

{param prettify: true /}

{param description}

Parameter macros provide more expressive power to a rule's string parameters.

{/param}

{param content}

{call buck.function}

{param status: 'UNFROZEN' /}

{param overview}

<p>

Some rules allow the use of specialized macros embedded within the

strings of their parameters. These <em>string parameter macros</em> provide

additional functionality, such as exposing the output paths of

other rules.

</p>

<p>

Examples of rules that use string parameter macros are:

</p>

<ul>

<li>{call buck.ruleLink}{param name : 'genrule' /}{/call}</li>

<li>{call buck.ruleLink}{param name : 'apk_genrule' /}{/call}</li>

<li>{call buck.ruleLink}{param name : 'cxx_genrule' /}{/call}</li>

</ul>

String parameter macros have the form

<p>

<pre>

{literal}

$(<em>macroname</em> [ <em>argument</em> ... ])

{/literal}

</pre>

</p>

<p>

String parameter macros take a space-separated list of arguments,

where each argument is a {call buck.build_target_pattern /}.

</p>

<p>

If you need to prevent expansion of a string parameter macro, prefix the

macro with a backslash.

</p>

<p>

<pre>

{literal}

\$(dirname ...)

{/literal}

</pre>

</p>

<p>

For an example of preventing expansion in the context of a rule, see

the <strong>Examples</strong> section below.

</p>

<h2>

Supported macros

</h2>

<ul>

<li>

<code> {literal}$(classpath //:foo){/literal} </code>

expands to the set of JARs that are in the classpath of the given

target.

</li>

<li>

<code> {literal} $(classpath_abi //:foo) {/literal} </code>

expands to the set of Application Binary Interface (ABI) JARs that are in the classpath of

the given target. For more information about using ABI JARs with Buck, see the

topic {call buck.concept_link}{param page: 'java_abis' /}{param name: 'Java ABIs' /}{/call}.

</li>

<li>

<code> {literal}$(exe //:foo){/literal} </code>

expands to the executable output of the

given target&mdash;if the target produces such an executable.

</li>

<li>

<code> {literal}$(location //:foo){/literal} </code>

expands to the output file or directory of the given target.

</li>

<li>

<code> {literal}$(location //:foo[output]){/literal} </code>

expands to the named output file or directory of the given target,

for rules that expose supplementary outputs.

</li>

<li>

<code> {literal}$(maven_coords //:foo){/literal} </code>

expands to the maven coordinates associated with the given target.

</li>

<li>

<code> {literal}$(output name){/literal} </code>

expands to the path of the named output of the rule in which you use

this macro. Used only for rules that allow named supplementary outputs.

</li>

<li>

<code> {literal}$(query_targets "<em>queryfunction</em>(//:foo)"){/literal} </code>

executes the given query and expands to the list of targets that match.

See the <strong>Query functions</strong> section below for the list of

supported <em>queryfunction</em>s.

</li>

<li>

<code> {literal}$(query_outputs "<em>queryfunction</em>(//:foo)"){/literal} </code>

executes the given query and expands to the <em>output files</em> of the targets that match.

See the <strong>Query functions</strong> section below for the list of

supported <em>queryfunction</em>s.

</li>

<li>

<code> {literal}$(query_targets_and_outputs [<em>SEPARATOR</em>] "<em>queryfunction</em>(//:foo)"){/literal} </code>

executes the given query and expands to both the target names <em>and</em> the output files of the targets that match.

Targets and paths are separated by <em>SEPARATOR</em> if provided, or a space if it is not.

See the <strong>Query functions</strong> section below for the list of

supported <em>queryfunction</em>s.

</li>

</ul>

<h3>

Query functions

</h3>

<p>

The <code>query_*</code> macros accept a quoted query expression which supports the following query functions.

</p>

<p>

<ul style="line-height:0.5em">

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'attrfilter'/}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'audit' /}{param section: 'classpath'/}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'deps'/}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'set-operations'/}{param rendered_text: 'except (set-difference)' /}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'filter'/}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'set-operations'/}{param rendered_text: 'intersect' /}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'kind'/}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'set'/}{/call}</code></li>

<li><code>{call buck.cmd_link}{param name: 'query' /}{param section: 'union'/}{/call}</code></li>

</ul>

</p>

<p>

All of these except for <code>classpath</code> behave the same as the corresponding operations

in {call buck.cmd_link}{param name: 'query' /}{/call}.

</p>

<p>

The <code>classpath</code> query function is used to query the classpath

of <code>java_library</code> rules. It takes an optional second argument to limit

the depth of the traversal. Its behavior is similar to the corresponding operation

in {call buck.cmd_link}{param name: 'audit' /}{/call}.

</p>

<p>

The items in the preceding list link to the corresponding descriptions in

the <code>buck query</code> and <code>buck audit</code> topics.

</p>

{/param}

{param examples}

<p>

<strong>Example</strong>: Use a string parameter macro in a <code>genrule()</code>{sp}

to copy the output of another rule.

</p>

<p>

<pre>

{literal}

genrule(

name = 'gen',

out = 'out.txt',

cmd = 'cp $(location //some/other:rule) $OUT',

)

{/literal}

</pre>

</p>

<p>

<strong>Example</strong>: Use a backslash to prevent macro expansion.

The rule passes the <code>dirname</code> command to the shell to execute

in a subshell; <code>dirname</code> is a Unix/Linux command-line utility

that returns the directory of a specified file. We need to use an

escape because the syntax for subshells is the same as the syntax for

string parameter macros.

</p>

<p>

<pre class="prettyprint lang-py">

{literal}

genrule(

name = 'gen',

out = 'out.txt',

cmd = 'cp $SRCS \$(dirname $OUT)',

srcs = [

'test1.txt',

'test2.txt',

],

)

{/literal}

</pre>

</p>

<strong>Example</strong>: Queries

<p>

<pre class="prettyprint lang-py">

{literal}

cmd = '$(query_targets "deps(:foo)")'

cmd = '$(query_outputs "filter(name_regex, deps(:bar))")'

cmd = '$(query_targets "attrfilter(annotation_processors, com.foo.Processor, deps(:app))")'

{/literal}

</pre>

</p>

{/param}

{param furtherexp}

<h2>Frequently Asked Questions (FAQ)</h2>

<ul>

<li> <strong>When are macros evaluated?</strong> Macros are evaluated before the command is passed to the shell for execution. You can think of them as simple string replacements. </li>

<li> <strong>Can macros be nested?</strong> Macros cannot be nested. If you need to run an additional macro on the output of a previous macro, create a nested <code>genrule</code> definition and use the <code>$(location)</code> macro to read the output of the previous macro. </li>

<li> <strong>Are parentheses okay inside a macro?</strong> Inside a macro, parentheses must be balanced. Parentheses which are part of a quoted string are ignored. </li>

<li> <strong>Is white space okay inside a macro?</strong> Macro arguments are white space separated, so arguments which contain white space must be quoted.</li>

<li> <strong>Are nested quotes allowed?</strong> A single level of nested quotes is allowed, such

as <code>"My name is 'Buck'."</code> or <code>'My name is "Buck".'</code>).

Note that when you use a macro in a BUCK file, you must ensure that quotes are properly escaped,

so that the shell command that uses the macro forms a proper string. </li>

</ul>

<h2>Extended Backus&mdash;Naur form</h2>

<p>

The Extended Backus&mdash;Naur form (EBNF) grammar for a macro is as follows:

</p>

{literal}<pre>

macro = "$(", macro_name, whitespace, [arg_list], ")";

macro_name = {all_ascii_chars - whitespace - parens};

whitespace = "\t" | "\n" | " " | "\r";

parens = "(" | ")";

arg_list = arg | arg, whitespace, arg_list;

arg = {all_ascii_chars - whitespace - parens}

| "(", arg, ")"

| "\"", [{-"\""}], "\""

| "'", [{-"'"}], "'";

</pre>{/literal}

{/param}

{/call} // buck.function

{/param} // content

{/call}

{/template}