blob: bf5ceb83609f96b09817add7726813980ab9cca5 [file] [log] [blame]
/*
* Copyright (c) Facebook, Inc. and its affiliates.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
{namespace cxx_genrule}
/***/
{template .soyweb}
{call buck.page}
{param title: 'cxx_genrule()' /}
{param navid: 'rule_cxx_genrule' /}
{param prettify: true /}
{param description}
A rule that is used to post-process a C or C++ executable or library.
{/param}
{param content}
{call buck.rule}
{param status: 'FROZEN' /}
{param overview}
<p>
A <code>cxx_genrule()</code> enables you to run shell commands as part
of the Buck build process. A <code>cxx_genrule()</code> exposes&mdash;through
a set of string parameter macros and variables&mdash;information about the
tools and configuration options used by the
Buck environment, specifically those related to the C/C++ toolchain.
</p>
<p>
The information exposed through these tools and configuration options is a reflection of:
Buck's built-in settings,
the settings in {call buck.buckconfig_link /} and <code>.buckconfig.local</code>,
and the result of various command-line overrides specified through
the {sp}{call buck.cmd_link}{param name: 'common_parameters' /}{param rendered_text: '<code>--config</code>' /}{/call} command-line option.
</p>
<p>
This information is available only
to the shell commands specified in the <code>cxx_genrule</code>.
The information is not available to other arguments of the rule.
</p>
<p>
A {sp}<code>cxx_genrule()</code> can be an input to
another {sp}<code>cxx_genrule()</code>.
</p>
<p>
Note that if you specify the <code>cxx_genrule</code> as a command-line
target to <code>buck build</code>, you must include a platform flavor.
For example:
</p>
<p>
<pre>
{literal}
buck build :cxx_gr_name#iphonesimulator-x86_64
{/literal}
</pre>
</p>
<p>
You could also just specify the default platform flavor explicitly:
</p>
<p>
<pre>
{literal}
buck build :cxx_gr_name#default
{/literal}
</pre>
</p>
{/param}
{param args}
{call buck.name_arg /}
{call genrule_common.srcs_arg /}
{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>. The shell command can access information
about the buck build environment through a set
of <em>macros</em>, <em>parameterized macros</em>, and <em>variables</em>.
<h4>Macros</h4>
<p>
The following macros are available to the shell command and are
accessed using the following syntax.
</p>
<pre>$(&lt;macro&gt;)</pre>
<p>
Example:
</p>
<pre>$(cc)</pre>
<dl>
<dt><code>$(cc)</code></dt>
<dd>Path to the C compiler.</dd>
<br/>
<dt><code>$(cxx)</code></dt>
<dd>Path to the C++ compiler.</dd>
<br/>
<dt><code>$(cflags)</code></dt>
<dd>Flags passed to the C compiler.</dd>
<br/>
<dt><code>$(cppflags)</code></dt>
<dd>Flags passed to the C preprocessor.</dd>
<br/>
<dt><code>$(cxxflags)</code></dt>
<dd>Flags passed to the C++ compiler.</dd>
<br/>
<dt><code>$(ld)</code></dt>
<dd>Path to the linker.</dd>
<br/>
<dt><code>$(ldflags-pic)</code></dt>
<dd>Flags passed to the linker for binaries that use
position-independent code (PIC).</dd>
<br/>
<dt><code>$(ldflags-pic-filter &lt;pattern&gt;)</code></dt>
<dd>Flags passed to the linker for binaries that use position-independent code (PIC).
Use the <em>pattern</em> parameter to specify a regular expression that matches the build targets that use these flags.
</dd>
<br/>
<dt><code>$(ldflags-shared)</code></dt>
<dd>Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs).</dd>
<br/>
<dt><code>$(ldflags-shared-filter &lt;pattern&gt;)</code></dt>
<dd>Flags passed to the linker for shared libraries, such as dynamic-link libraries (DLLs).
Use the <em>pattern</em> parameter to specify a regular expression that matches the build targets that use these flags.
</dd>
<br/>
<dt><code>$(ldflags-static)</code></dt>
<dd>Flags passed to the linker for statically-linked libraries.</dd>
<br/>
<dt><code>$(ldflags-static-filter &lt;pattern&gt;)</code></dt>
<dd>Flags passed to the linker for statically-linked libraries.
Use the <em>pattern</em> parameter to specify a regular expression that matches the build targets that use these flags.
</dd>
<br/>
<dt><code>$(platform-name)</code></dt>
<dd>The platform flavor with which this <code>cxx_genrule</code> was specified.
</dd>
</dl>
<h4>Parameterized Macros</h4>
<p>
It is also possible to expand references to other rules within the
shell command, using the following subset of the
builtin {call buck.string_parameter_macros /}.
Note that all build rules expanded in the command are automatically
considered to be dependencies of the <code>genrule()</code>.
</p>
{call genrule_common.abs_path_note /}
<dl>
<dt><code>$(exe /&#x2F;path/to:target)</code></dt>
<dd>Expands to the commands necessary to run the executable
generated by the specified build rule. For a C++ executable, this
will typically just be the name of the output executable itself,
such as <code>main</code>. If the specified build rule does not generate an
executable output, an exception will be thrown and the build will
fail.</dd>
<br/>
<dt><code>$(location /&#x2F;path/to:target)</code></dt>
<dd>Expands to the path 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>
<h4>Variables</h4>
<p>
Finally, Buck adds the following variables to the environment in
which the shell command runs. They are accessed using the following syntax.
Note the use of braces rather than parentheses.
</p>
<pre>$&#x7B;&lt;variable&gt;&#x7D;</pre>
<p>
Example:
</p>
<pre>$&#x7B;SRCS&#x7D;</pre>
<dl>
<dt><code>$&#x7B;SRCS&#x7D;</code><dt>
<dd>A string expansion of the <code>srcs</code> argument delimited by
the <code>environment_expansion_separator</code> argument where each element
of <code>srcs</code> will be translated into an absolute path.</dd>
<br/>
<dt><code>$&#x7B;SRCDIR&#x7D;</code><dt>
<dd>The absolute path to the to which sources are copied
prior to running the command.</dd>
<br/>
<dt><code>$&#x7B;OUT&#x7D;</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>
<br/>
<dt><code>$&#x7B;TMP&#x7D;</code></dt>
<dd>A temporary directory which can be used for intermediate results and will not be
bundled into the output.</dd>
</dl>
{/param}
{/call}
{call genrule_common.bash_arg /}
{call genrule_common.cmd_exe_arg /}
{call genrule_common.type_arg /}
{call genrule_common.out_arg /}
{call genrule_common.environment_expansion_separator /}
{call buck.arg}
{param name: 'enable_sandbox' /}
{param default : 'False' /}
{param desc}
Whether this target should be executed in a sandbox or not.
{/param}
{/call}
{call buck.arg}
{param name: 'executable' /}
{param default : 'False' /}
{param desc}
Whether the output of the genrule is itself executable. Marking an output as
executable makes <code>buck run</code> and <code>$(exe ...)</code> macro
expansion work with this target.
{/param}
{/call}
{call buck.tests_arg /}
{/param} // close args
{/call} // close buck.rule
{/param}
{/call}
{/template}