blob: 012c1df4eb085a9aedd398099218609eb31f6d1a [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.android_library}
/***/
{template .soyweb}
{call buck.page}
{param title: 'android_library()' /}
{param navid: 'rule_android_library' /}
{param prettify: true /}
{param description}
A rule that is used to define a set of Java files that can be compiled
together against the Android SDK.
{/param}
{param content}
{call buck.rule}
{param status: 'FROZEN' /}
{param overview}
An <code>android_library()</code> rule is used to define a set of Java files
that can be compiled together against the Android SDK. The main output of an
{sp}<code>android_library()</code> rule is a single JAR file containing all of the
compiled class files and resources.
{/param}
{param args}
{call buck.name_arg /}
{call buck.arg}
{param name: 'srcs' /}
{param default : '[]' /}
{param desc}
The set of <code>.java</code> files to compile for this rule.
{/param}
{/call}
{call buck.arg}
{param name: 'resources' /}
{param default : '[]' /}
{param desc}
Static files to include among the compiled <code>.class</code>
{sp}files. These files can be loaded via <a
href="http://docs.oracle.com/javase/7/docs/api/java/lang/Class.html#getResource(java.lang.String)"
target="_blank">Class.getResource()</a>.
<p>
<strong>Note:</strong> Buck uses the <code>src_roots</code> property in
{sp}<a href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>
{sp}to help determine where resources should be placed within the generated JAR file.
<p>
{/param}
{/call}
{call android_common.manifest_arg}
{param type: 'library' /}
{/call}
{call buck.arg}
{param name: 'final_r_name' /}
{param default : 'None' /}
{param desc}
An optional name for a class like R.java with final values that is generated to be used
for annotation processors. The values will be wrong i.e they will not match the real values
in the final android binary, so they should only be used by carefully crafted annotation processors.
{/param}
{/call}
{call buck.arg}
{param name: 'skip_non_union_r_dot_java' /}
{param default : 'false' /}
{param desc}
When using <code>resource_union_package</code> setting <code>skip_non_union_r_dot_java</code> will
skip generating dummy R.java for other packages which are unnecessary. Reducing the number of
R.java helps in improving the overall compile time especially in libraries with large number of
dependent prebuilt targets.
{/param}
{/call}
{call buck.arg}
{param name: 'deps' /}
{param default : '[]' /}
{param desc}
Rules (usually other <code>android_library</code> rules)
that are used to generate the classpath required to compile this
{sp}<code>android_library</code>.
{/param}
{/call}
{call buck.arg}
{param name: 'source' /}
{param default : '<global value>' /}
{param desc}
Specifies the version of Java (as a string) to interpret source
files as.
Overrides the value in "source_level" in the "java" section
of <a
href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
{/param}
{/call}
{call buck.arg}
{param name: 'target' /}
{param default : '<global value>' /}
{param desc}
Specifies the version of Java (as a string) for which to
generate code.
Overrides the value in "target_level" in the "java" section
of <a
href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
{/param}
{/call}
{call buck.arg}
{param name: 'javac' /}
{param default : '<global value>' /}
{param desc}
Specifies the Java compiler program to use for this rule.
The value is a source path (e.g., //foo/bar:bar).
Only one of "javac" and "javac_jar" may be set for a given rule.
Overrides the value in "javac" in the "tools" section
of <a
href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
{/param}
{/call}
{call buck.arg}
{param name: 'javac_jar' /}
{param default : '<global value>' /}
{param desc}
Specifies the Java compiler program to use for this rule.
The value is a source path (e.g., //foo/bar:bar).
Only one of "javac_jar" and "javac" may be set for a given rule.
Overrides the value in "javac_jar" in the "tools" section
of <a
href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
{/param}
{/call}
{call jvm_common.compiler_class_name_arg /}
{call buck.arg}
{param name: 'extra_arguments' /}
{param default : '[]' /}
{param desc}
List of additional arguments to pass into the Java compiler. These
arguments follow the ones specified in <a
href="{ROOT}concept/buckconfig.html"><code>.buckconfig</code></a>.
{/param}
{/call}
{call buck.arg}
{param name: 'extra_kotlinc_arguments' /}
{param default : '[]' /}
{param desc}
List of additional arguments to pass into the Kotlin compiler.
{/param}
{/call}
{call buck.arg}
{param name: 'annotation_processing_tool' /}
{param default : 'kapt' /}
{param desc}
Specifies the tool to use for annotation processing. Possible values: "kapt" or "javac".
"kapt" allows running Java annotation processors against Kotlin sources while backporting
it for Java sources too.
"javac" works only against Java sources, Kotlin sources won't have access to generated
classes at compile time.
{/param}
{/call}
{call buck.arg}
{param name: 'kapt_ap_options' /}
{param desc}{literal}
Map of annotation processor options to pass into kapt via the apoptions plugin option. Each entry
should be a key value pair of the processor option and its value. Default is an empty map.
E.g.
kapt_ap_options = {
'someAnnotationOption': 'someValue'
}
More information here: https://kotlinlang.org/docs/reference/kapt.html{/literal}
{/param}
{/call}
{call jvm_common.exported_deps}
{param library: 'android_library' /}
{/call}
{call jvm_common.provided_deps}
{param binary: 'android_binary' /}
{/call}
{call jvm_common.exported_provided_deps /}
{call buck.deps_query_arg /}
{call buck.provided_deps_query_arg /}
{call jvm_common.abi_generation_mode /}
{call jvm_common.source_only_abi_deps /}
{call jvm_common.required_for_source_only_abi /}
{call buck.tests_arg /}
{/param} // args
{param examples}
An <code>android_library</code> rule used in concert with an
{sp}{call buck.android_resource /} rule.
This would be a common arrangement for a standard Android Library project
as defined by
{sp}<a href="http://developer.android.com/tools/projects/index.html">
http://developer.android.com/tools/projects/index.html</a>
{literal}<pre class="prettyprint lang-py">
android_resource(
name = 'res',
res = 'res',
package = 'com.example',
)
android_library(
name = 'my_library',
srcs = glob(['src/**/*.java']),
deps = [
':res',
],
)
</pre>{/literal}
{/param} // examples
{/call} // buck.rule
{/param} // content
{/call} // buck.page
{/template}