blob: 674da84802f67e7eb26bbe64aee1474dc4902a0a [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 kotlin_library}
/***/
{template .soyweb}
{call buck.page}
{param title: 'kotlin_library()' /}
{param navid: 'rule_kotlin_library' /}
{param prettify: true /}
{param description}
A rule that is used to define a set of Kotlin files that can be compiled
together.
{/param}
{param content}
{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
A <code>kotlin_library()</code> rule is used to define a set of Kotlin
files that can be compiled together. The main output of a
{sp}<code>kotlin_library()</code> rule is a single JAR file containing all
of the compiled class files, as well as the static files specified in
the <code>resources</code> argument.
{/param}
{param args}
{call buck.name_arg /}
{call buck.arg}
{param name: 'srcs' /}
{param default: '[]' /}
{param desc}
The set of <code>.kt</code>, <code>.java</code> or <code>.kts</code> files to compile for this rule.
If any of the files in this list end in <code>.src.zip</code>,
then the entries in the ZIP file that end in <code>.java</code> or <code>.kt</code> will be
included as ordinary inputs to compilation.
{/param}
{/call}
{call jvm_common.resources_arg /}
{call buck.arg}
{param name: 'deps' /}
{param default: '[]' /}
{param desc}
Rules (usually other <code>kotlin_library</code> rules) that are used to
generate the classpath required to compile this <code>kotlin_library</code>.
{/param}
{/call}
{call buck.arg}
{param name: 'kotlinc_plugins' /}
{param default: '[]' /}
{param desc}
Use this to specify <a href="https://kotlinlang.org/docs/reference/compiler-plugins.html">
Kotlin compiler plugins</a> to use when compiling this library.
This takes a list of source paths, each of which will be prefixed
with <code>-Xplugin=</code> and passed as extra arguments to the compiler.
Unlike <code>extra_kotlinc_arguments</code>, these can be <em>source paths</em>,
not just strings (though <code>extra_kotlinc_arguments</code> should be used
to specify plugin compiler options with <code>-P</code>).
<p>
For example, if you want to use{sp}
<a href="https://github.com/Kotlin/kotlinx.serialization">kotlinx.serialization</a>
{sp}with <code>kotlin_library()</code>, you need to specify{sp}
<code>kotlinx-serialization-compiler-plugin.jar</code> under{sp}
<code>kotlinc_plugins</code> and <code>kotlinx-serialization-runtime.jar</code>{sp}
(which you may have to fetch from Maven) in your <code>deps</code>:
{literal}<pre class="prettyprint lang-py">
kotlin_library(
name = "example",
srcs = glob(["*.kt"]),
deps = [
":kotlinx-serialization-runtime",
],
kotlinc_plugins = [
# Likely copied from your $KOTLIN_HOME directory.
"kotlinx-serialization-compiler-plugin.jar",
],
)
prebuilt_jar(
name = "kotlinx-serialization-runtime",
binary_jar = ":kotlinx-serialization-runtime-0.10.0",
)
# Note you probably want to set
# maven_repo=http://jcenter.bintray.com/ in your .buckconfig until
# https://github.com/Kotlin/kotlinx.serialization/issues/64
# is closed.
remote_file(
name = "kotlinx-serialization-runtime-0.10.0",
out = "kotlinx-serialization-runtime-0.10.0.jar",
url = "mvn:org.jetbrains.kotlinx:kotlinx-serialization-runtime:jar:0.10.0",
sha1 = "23d777a5282c1957c7ce35946374fff0adab114c"
)
</pre>{/literal}
{/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: 'friend_paths' /}
{param default: '[]' /}
{param desc}
List of source paths to pass into the Kotlin compiler as friend-paths, that is, modules
you can have access to internal methods.
{/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.remove_classes_arg /}
{call jvm_common.exported_deps}
{param library: 'kotlin_library' /}
{/call}
{call jvm_common.provided_deps}
{param binary: 'kotlin_library' /}
{/call}
{call jvm_common.exported_provided_deps /}
{call buck.labels_arg /}
{call buck.tests_arg /}
{/param} // close args
{param examples}
{literal}<pre class="prettyprint lang-py">
# A rule that compiles a single .kt file.
kotlin_library(
name = 'JsonUtil',
srcs = ['JsonUtil.kt'],
deps = [
'//third_party/guava:guava',
'//third_party/jackson:jackson',
],
)
# A rule that compiles all of the .kt files under the directory in
# which the rule is defined using glob(). It also excludes an
# individual file that may have additional dependencies, so it is
# compiled by a separate rule.
kotlin_library(
name = 'messenger',
srcs = glob(['**/*.kt'], excludes = ['MessengerModule.kt']),
deps = [
'//src/com/facebook/base:base',
'//third_party/guava:guava',
],
)
kotlin_library(
name = 'MessengerModule',
srcs = ['MessengerModule.kt'],
deps = [
'//src/com/facebook/base:base',
'//src/com/google/inject:inject',
'//third_party/guava:guava',
'//third_party/jsr-330:jsr-330',
],
)
# A rule that builds a library with both relative and
# fully-qualified deps.
kotlin_library(
name = 'testutil',
srcs = glob(['tests/**/*.kt'], excludes = 'tests/**/*Test.kt'),
deps = [
':lib-fb4a',
'//java/com/facebook/base:base',
],
)
</pre>{/literal}
{/param}
{/call} // close buck.rule
{/param}
{/call}
{/template}