blob: e3d53c6460c91f48c56c2f9d53d01c4f5a139014 [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.export_file}
/***/
{template .soyweb}
{call buck.page}
{param title: 'export_file()' /}
{param navid: 'rule_export_file' /}
{param prettify: true /}
{param description}
An export_file() rule takes a single file or folder and exposes it so other rules can use it.
{/param}
{param content}
{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
<p><b>Warning:</b> this build rule is deprecated for folders.
Use {call buck.ruleLink}{param name : 'filegroup' /}{/call} instead. It is still supported for individual files.</p>
<p>An <code>export_file()</code> takes a single file or folder and exposes it so other rules can
use it.</p>
{/param}
{param args}
{call buck.arg}
{param name: 'name' /}
{param desc}
The <em>short name</em> for this {call buck.build_target /}. If
this is the only parameter, this must also be the path to the file.
{/param} {/call}
{call buck.arg}
{param name: 'src' /}
{param default: 'None' /}
{param desc}
The path to the file that should be exported.
{/param}
{/call}
{call buck.arg}
{param name: 'out' /}
{param default: 'None' /}
{param desc}
The name which the file will be called if another rule depends on it instead of the name it
already has.
{/param}
{/call}
{call buck.arg}
{param name: 'mode' /}
{param default: 'copy' /}
{param desc}
How files are referenced internally in buck.
If set to 'copy', then a full copy will be made into the new location in buck-out.
If set to 'reference', the original file will be used by internal build rules in-place.
However, this mode does not work across repositories or if the 'out' property is set.
For read-only operations, 'reference' can be more performant.
{/param}
{/call}
{/param} // close args
{param examples}
<p>
The best way to see how the <code>export_file()</code> rule works is with some examples. The
common case is:
</p>
{literal}<pre class="prettyprint lang-py">
export_file(
name = 'example.html',
)
# This is equivalent to
export_file(
name = 'example.html',
src = 'example.html',
out = 'example.html',
)
</pre>
{/literal}
<p>
It is sometimes useful to refer to the file not by its path, but by a more logical name:
</p>
{literal}<pre class="prettyprint lang-py">
export_file(
name = 'example',
src = 'example.html',
)
# This is equivalent to
export_file(
name = 'example',
src = 'example.html',
out = 'example.html',
)
</pre>
{/literal}
<p>
Finally, there are occasions where you want to export a file more than once but want to copy it to
a different name for each output:
</p>
{literal}<pre class="prettyprint lang-py">
export_file(
name = 'runner',
src = 'RemoteRunner.html',
)
export_file(
name = 'runner_hta',
src = 'RemoteRunner.html',
out = 'RemoteRunner.hta',
)
</pre>
{/literal}
<p>
Using the <code>export_file()</code> rule is also simple:
</p>
{literal}<pre class="prettyprint lang-py">
export_file(
name = 'example',
src = 'example.html',
)
genrule(
name = 'demo',
out = 'result.html'
cmd = 'cp $(location :example) $OUT',
)
</pre>
{/literal}
{/param}
{/call} // End of buck.rule
{/param}
{/call}
{/template}