blob: 77dd676af16cdffdca5a8a471659a7174e1af3b3 [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 sh_binary}
/***/
{template .soyweb}
{call buck.page}
{param title: 'sh_binary()' /}
{param navid: 'rule_sh_binary' /}
{param prettify: true /}
{param description}
A rule that is used to invoke a shell script.
{/param}
{param content}
{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
A <code>sh_binary()</code> is used to execute a shell script.
{/param}
{param args}
{call buck.name_arg /}
{call buck.arg}
{param name: 'main' /}
{param desc}
Either the path to the script (relative to the build file), or a {call buck.build_target /}.
This file must be executable in order to be run.
{/param}
{/call}
{call buck.arg}
{param name: 'resources' /}
{param default: '[]' /}
{param desc}
A list of files or build rules that this rule requires in order to run. These could be things such as
random data files.
<p>
When the script runs, the <code>$BUCK_DEFAULT_RUNTIME_RESOURCES</code>
environment variable specifies the directory that contains these resources.
This directory's location is determined entirely by Buck; the script should
not assume the directory's location.
</p>
<p>
The <code>$BUCK_EXTERNAL_RUNTIME_RESOURCES</code> variable is also defined.
Resources that are targets from external cells are placed in this
directory.
</p>
<p>
The resources are also made available in a tree structure that mirrors
their locations in the source and <code>buck-out</code> trees. The
environment variable <code>$BUCK_PROJECT_ROOT</code> specifies a directory
that contains all the resources, laid out in their locations relative to
the original buck project root.
</p>
{/param}
{/call}
{/param} // args
{param examples}
<p>This sh_binary() just cats a sample data file back at the user.</p>
{literal}
<pre class="prettyprint lang-py">
# $REPO/BUCK
sh_binary(
name = "script",
main = "script.sh",
resources = [
"data.dat",
],
)
</pre>{/literal}
{literal}
<pre class="prettyprint lang-sh">
# Sample data file with data we need at runtime
$ echo "I'm a datafile" > data.dat
# Create a simple script that prints out the resource
$ cat > script.sh
#!/bin/sh
cat $BUCK_DEFAULT_RUNTIME_RESOURCES/data.dat
# Make sure the script is executable
$ chmod u+x script.sh
# Run the script, and see that it prints out the resource we provided
$ buck run //:script
Building: finished in 1.9 sec (100%) 1/1 jobs, 1 updated
Total time: 2.1 sec
I'm a datafile
</pre>
{/literal}
{/param} // examples
{/call} // buck.rule
{/param}
{/call}
{/template}