blob: 320df7799a717e1e84e834276a86a8a6c50d1312 [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 remote_file}
/***/
{template .soyweb}
{call buck.page}
{param title: 'remote_file()' /}
{param navid: 'rule_remote_file' /}
{param prettify: true /}
{param description}
A rule that is used to download files from the Internet to be used as dependencies of other
rules.
{/param}
{param content}
{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
A <code>remote_file()</code> rule is used to download files from the Internet to be used as
dependencies for other rules. These rules are downloaded by running {call buck.cmd_fetch /}, or can
be downloaded as part of {call buck.cmd_build /}. See the note there about the
{sp}<code>.buckconfig</code> setting to configure that.
{/param}
{param args}
{call buck.name_arg /}
{call buck.arg}
{param name: 'url' /}
{param desc}
You can specify an <code>http</code>, <code>https</code>, or a <code>mvn</code> URL. If you
specify a <code>mvn</code> URL, it will be decoded as described in the
{sp}<a href="{ROOT}javadoc/com/facebook/buck/file/MavenUrlDecoder.html">javadocs for
MavenUrlDecoder</a>. See the example section below.
{/param}
{/call}
{call buck.arg}
{param name: 'sha1' /}
{param desc}
The <a href="//wikipedia.org/wiki/SHA-1"><code>SHA-1</code></a> hash of the downloaded artifact.
Buck verifies this is correct and fails the fetch command if it doesn't match in order to
guarantee repeatable builds.
{/param}
{/call}
{call buck.arg}
{param name: 'out' /}
{param default: 'None' /}
{param desc}
An optional name to call the downloaded artifact. Buck will generate a default name if one is not
provided that uses the <code>name</code> of the rule.
{/param}
{/call}
{call buck.arg}
{param name: 'type' /}
{param default: 'data' /}
{param desc}
An optional type of the downloaded file.
<dl>
<dt><code>data</code></dt>
<dd>Regular data file.</dd>
<dt><code>executable</code></dt>
<dd>
Executable file. Buck will ensure that output has appropriate permissions if applicable.
</dd>
<dt><code>exploded_zip</code></dt>
<dd>
Zip archive which will be automatically unzipped into an output directory.
</dd>
</dl>
{/param}
{/call}
{/param} // close args
{param examples}
<p>
Here's an example of a <code>remote_file()</code> using an <code>https</code> URL.
</p>
{literal}<pre class="prettyprint lang-py">
remote_file(
name = 'android-ndk-r10e-darwin-x86_64',
url = 'https://dl.google.com/android/ndk/android-ndk-r10e-darwin-x86_64.bin',
sha1 = 'b57c2b9213251180dcab794352bfc9a241bf2557',
)
</pre>{/literal}
<p>
Here's an example of a <code>remote_file()</code> using a <code>mvn</code> URL being referenced
by a {call buck.prebuilt_jar /}.
</p>
{literal}<pre class="prettyprint lang-py">
prebuilt_jar(
name = 'jetty-all',
binary_jar = 'jetty-all-9.2.10.v20150310.jar',
source_jar = ':jetty-source',
)
remote_file(
name = 'jetty-source',
out = 'jetty-all-9.2.10.v20150310-sources.jar',
url = 'mvn:org.eclipse.jetty.aggregate:jetty-all:src:9.2.10.v20150310',
sha1 = '311da310416d2feb3de227081d7c3f48742d7075',
)
</pre>{/literal}
<p>
Here's an example of a <code>remote_file()</code> using a <code>mvn</code> URI which uses a
non-default maven repository host.
</p>
{literal}<pre class="prettyprint lang-py">
remote_file(
name = 'jetty-source',
out = 'jetty-all-9.2.10.v20150310-sources.jar',
url = 'mvn:https://maven-repo.com:org.eclipse.jetty.aggregate:jetty-all:src:9.2.10.v20150310',
sha1 = '311da310416d2feb3de227081d7c3f48742d7075',
)
</pre>{/literal}
<p>
Here's an example of a <code>remote_file()</code> using a <code>mvn</code> URI which uses a
Maven classifier.
</p>
{literal}<pre class="prettyprint lang-py">
remote_file(
name = 'groovy-groovysh-indy',
out = 'jetty-all-9.2.10.v20150310-sources.jar',
url = 'mvn:org.codehaus.groovy:groovy-groovysh:jar:indy:2.4.1',
sha1 = '1600fde728c885cc9506cb102deb1b494bd7c130',
)
</pre>{/literal}
{/param}
{/call} // close buck.rule
{/param}
{/call}
{/template}