blob: a8bf5daf21573521cbb5e16ad3d476dcab4a7cad [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 buck.command_alias}
/***/
{template .soyweb}
{call buck.page}
{param title: 'command_alias()' /}
{param navid: 'rule_command_alias' /}
{param prettify: true /}
{param description}
A rule for wrapping binary rules, and add fixed arguments or
environment variables.
{/param}
{param content}
{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
<p>
The <code>command_alias</code> rule enables you to wrap build
rules that create binaries and to pre-apply command-line
arguments and environment variables.
</p>
<p>
Example uses include running a command written in a scripting
language with a specific interpreter, and transparently wrapping
sub-commands of a binary.
</p>
<p>
You can reference a <code>command_alias</code> target in
the <code>cmd</code> parameter of a {call buck.genrule /} by
using the <code>exe</code> macro:
</p>
<p>
<pre>
{literal}
$(exe //path/to:target)
{/literal}
</pre>
</p>
{/param}
{param args}
{call buck.name_arg /}
{call buck.arg}
{param name: 'exe'/}
{param default: 'None'/}
{param desc}
A {call buck.build_target /} for a rule that outputs
an executable, such as an {call buck.sh_binary /}.
{/param}
{/call}
{call buck.arg}
{param name: 'platform_exe' /}
{{param default: '{}' /}}
{param desc}
<p>A mapping from platforms to {call buck.build_target /}.
enables you to override <code>exe</code> per host platform.</p>
<p>If present, <code>exe</code> will be used as a fallback on host platforms that are not
specified in <code>platform_exe</code>.</p>
<p>It is possible to omit <code>exe</code> when providing <code>platform_exe</code>.
In that case, the build will fail if the command is invoked on a platform not specified in
the mapping.</p>
<p>Valid platforms are all values of the{sp}
<a href="https://buck.build/javadoc/com/facebook/buck/util/environment/Platform.html">
<code>Platform</code> enum
</a>:
</p>
<ul>
<li><code>FREEBSD</code></li>
<li><code>LINUX</code></li>
<li><code>MACOS</code></li>
<li><code>WINDOWS</code></li>
</ul>
{/param}
{/call}
{call buck.arg}
{param name: 'args' /}
{param default: 'None' /}
{param desc}
A string of arguments that is passed to the executable specified by
{sp}<code>exe</code> at startup. These arguments support a subset of
Buck's {call buck.string_parameter_macros /}. Only the
{sp}<code>$(location ...)</code> and <code>$(exe ...)</code>{sp}
macros are supported currently.
{/param}
{/call}
{call buck.arg}
{param name: 'env' /}
{param default: 'None' /}
{param desc}
A map of environment variables that will be passed to the executable represented
by <code>exe</code> on startup. Environment variables support the same macros as arguments.
{/param}
{/call}
{/param}
{param examples}
{literal}<pre class="prettyprint lang-py">
# Combining an interpreter and a script
cxx_binary(
name = "node-js",
srcs = [
# ...
],
headers = [
# ...
],
)
export_file(
name = "scripts"
)
command_alias(
name = "server",
exe = ":node-js",
args = [
"$(location :scripts)/start-server.js",
],
)
</pre>{/literal}
{literal}<pre class="prettyprint lang-py">
# Exposing sub commands
export_file(
name = "yarn",
src = "yarn.sh",
)
command_alias(
name = "add",
exe = ":yarn",
args = ["add"],
)
command_alias(
name = "install",
exe = ":yarn",
args = ["install"],
)
command_alias(
name = "run",
exe = ":yarn",
args = ["run"],
)
</pre>{/literal}
{literal}<pre class="prettyprint lang-py">
# Platform specific commands
export_file(
name = "node-windows",
src = "windows/node.exe",
)
export_file(
name = "node-linux",
src = "linux/node",
)
export_file(
name = "node-macos",
src = "macos/node",
)
command_alias(
name = "node",
platform_exe = {
"windows": ":node-windows",
"linux": ":node-linux",
"macos": ":node-macos",
},
)
</pre>{/literal}
{/param}
{/call}
{/param}
{/call}
{/template}