Skip to content

Commit cbf5679

Browse files
BencodesBencodes
authored
Update the Kotlin docs (bazelbuild#959)
1 parent f92d4b7 commit cbf5679

File tree

3 files changed

+105
-5
lines changed

3 files changed

+105
-5
lines changed

‎Makefile

+4
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ sky.reflow:
2929
deps.regen:
3030
scripts/regen_deps
3131

32+
docs.regen:
33+
bazel build //kotlin:stardoc
34+
cp bazel-bin/kotlin/kotlin.md docs/kotlin.md
35+
3236
proto.regen:
3337
scripts/gen_proto_jars
3438

‎README.md

+29
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,7 @@ Additionally, you can add options for both tracing and timing of the bazel build
264264
* `bazel build --define=kt_timings=1`
265265

266266
`kt_trace=1` will allow you to inspect the full kotlinc commandline invocation, while `kt_timings=1` will report the high level time taken for each step.
267+
267268
# Kotlin compiler plugins
268269

269270
The `kt_compiler_plugin` rule allows running Kotlin compiler plugins, such as no-arg, sam-with-receiver and allopen.
@@ -296,6 +297,34 @@ kt_jvm_library(
296297
)
297298
```
298299

300+
# KSP Annotation Processing
301+
302+
The `kt_ksp_plugin` rule allows running KSP annotation processors, such as Moshi.
303+
304+
For example, you can add allopen to your project like this:
305+
```python
306+
load("@io_bazel_rules_kotlin//kotlin:core.bzl", "kt_ksp_plugin")
307+
load("@io_bazel_rules_kotlin//kotlin:jvm.bzl", "kt_jvm_library")
308+
309+
kt_ksp_plugin(
310+
name = "moshi-kotlin-codegen",
311+
processor_class = "com.squareup.moshi.kotlin.codegen.ksp.JsonClassSymbolProcessorProvider",
312+
deps = [
313+
"@maven//:com_squareup_moshi_moshi",
314+
"@maven//:com_squareup_moshi_moshi_kotlin",
315+
"@maven//:com_squareup_moshi_moshi_kotlin_codegen",
316+
],
317+
)
318+
319+
kt_jvm_library(
320+
name = "lib",
321+
srcs = glob(["*.kt"]),
322+
plugins = ["//:moshi-kotlin-codegen"],
323+
)
324+
```
325+
326+
Full examples of using compiler plugins can be found [here](examples/plugin).
327+
299328
Full examples of using compiler plugins can be found [here](examples/plugin).
300329

301330
## Examples

‎docs/kotlin.md

+72-5
Original file line numberDiff line numberDiff line change
@@ -392,10 +392,11 @@ kt_javac_options(<a href="#kt_javac_options-name">name</a>, <a href="#kt_javac_o
392392

393393
## kt_kotlinc_options
394394

395-
kt_kotlinc_options(<a href="#kt_kotlinc_options-name">name</a>, <a href="#kt_kotlinc_options-include_stdlibs">include_stdlibs</a>, <a href="#kt_kotlinc_options-java_parameters">java_parameters</a>, <a href="#kt_kotlinc_options-warn">warn</a>, <a href="#kt_kotlinc_options-x_allow_result_return_type">x_allow_result_return_type</a>,
396-
<a href="#kt_kotlinc_options-x_backend_threads">x_backend_threads</a>, <a href="#kt_kotlinc_options-x_emit_jvm_type_annotations">x_emit_jvm_type_annotations</a>, <a href="#kt_kotlinc_options-x_explicit_api_mode">x_explicit_api_mode</a>,
397-
<a href="#kt_kotlinc_options-x_inline_classes">x_inline_classes</a>, <a href="#kt_kotlinc_options-x_jvm_default">x_jvm_default</a>, <a href="#kt_kotlinc_options-x_lambdas">x_lambdas</a>, <a href="#kt_kotlinc_options-x_multi_platform">x_multi_platform</a>, <a href="#kt_kotlinc_options-x_no_call_assertions">x_no_call_assertions</a>,
398-
<a href="#kt_kotlinc_options-x_no_optimize">x_no_optimize</a>, <a href="#kt_kotlinc_options-x_no_optimized_callable_references">x_no_optimized_callable_references</a>, <a href="#kt_kotlinc_options-x_no_param_assertions">x_no_param_assertions</a>,
395+
kt_kotlinc_options(<a href="#kt_kotlinc_options-name">name</a>, <a href="#kt_kotlinc_options-include_stdlibs">include_stdlibs</a>, <a href="#kt_kotlinc_options-java_parameters">java_parameters</a>, <a href="#kt_kotlinc_options-jvm_target">jvm_target</a>, <a href="#kt_kotlinc_options-warn">warn</a>,
396+
<a href="#kt_kotlinc_options-x_allow_result_return_type">x_allow_result_return_type</a>, <a href="#kt_kotlinc_options-x_backend_threads">x_backend_threads</a>, <a href="#kt_kotlinc_options-x_debug">x_debug</a>,
397+
<a href="#kt_kotlinc_options-x_emit_jvm_type_annotations">x_emit_jvm_type_annotations</a>, <a href="#kt_kotlinc_options-x_explicit_api_mode">x_explicit_api_mode</a>, <a href="#kt_kotlinc_options-x_inline_classes">x_inline_classes</a>, <a href="#kt_kotlinc_options-x_jvm_default">x_jvm_default</a>,
398+
<a href="#kt_kotlinc_options-x_lambdas">x_lambdas</a>, <a href="#kt_kotlinc_options-x_multi_platform">x_multi_platform</a>, <a href="#kt_kotlinc_options-x_no_call_assertions">x_no_call_assertions</a>, <a href="#kt_kotlinc_options-x_no_optimize">x_no_optimize</a>,
399+
<a href="#kt_kotlinc_options-x_no_optimized_callable_references">x_no_optimized_callable_references</a>, <a href="#kt_kotlinc_options-x_no_param_assertions">x_no_param_assertions</a>,
399400
<a href="#kt_kotlinc_options-x_no_receiver_assertions">x_no_receiver_assertions</a>, <a href="#kt_kotlinc_options-x_optin">x_optin</a>, <a href="#kt_kotlinc_options-x_report_perf">x_report_perf</a>, <a href="#kt_kotlinc_options-x_sam_conversions">x_sam_conversions</a>,
400401
<a href="#kt_kotlinc_options-x_skip_prerelease_check">x_skip_prerelease_check</a>, <a href="#kt_kotlinc_options-x_use_k2">x_use_k2</a>)
401402

@@ -411,9 +412,11 @@ kt_kotlinc_options(<a href="#kt_kotlinc_options-name">name</a>, <a href="#kt_kot
411412
|<a id="kt_kotlinc_options-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
412413
|<a id="kt_kotlinc_options-include_stdlibs"></a>include_stdlibs | Don't automatically include the Kotlin standard libraries into the classpath (stdlib and reflect). | String | optional | "all" |
413414
|<a id="kt_kotlinc_options-java_parameters"></a>java_parameters | Generate metadata for Java 1.8+ reflection on method parameters. | Boolean | optional | False |
415+
|<a id="kt_kotlinc_options-jvm_target"></a>jvm_target | The -jvm_target flag. This is only tested at 1.8. | String | optional | "" |
414416
|<a id="kt_kotlinc_options-warn"></a>warn | Control warning behaviour. | String | optional | "report" |
415417
|<a id="kt_kotlinc_options-x_allow_result_return_type"></a>x_allow_result_return_type | Enable kotlin.Result as a return type | Boolean | optional | False |
416418
|<a id="kt_kotlinc_options-x_backend_threads"></a>x_backend_threads | When using the IR backend, run lowerings by file in N parallel threads. 0 means use a thread per processor core. Default value is 1. | Integer | optional | 1 |
419+
|<a id="kt_kotlinc_options-x_debug"></a>x_debug | Enable debugging, this option allows for a better debugging experience, especially when using coroutines, but should not be used in production | Boolean | optional | False |
417420
|<a id="kt_kotlinc_options-x_emit_jvm_type_annotations"></a>x_emit_jvm_type_annotations | Basic support for type annotations in JVM bytecode. | Boolean | optional | False |
418421
|<a id="kt_kotlinc_options-x_explicit_api_mode"></a>x_explicit_api_mode | Enable explicit API mode for Kotlin libraries. | String | optional | "off" |
419422
|<a id="kt_kotlinc_options-x_inline_classes"></a>x_inline_classes | Enable experimental inline classes | Boolean | optional | False |
@@ -432,6 +435,46 @@ kt_kotlinc_options(<a href="#kt_kotlinc_options-name">name</a>, <a href="#kt_kot
432435
|<a id="kt_kotlinc_options-x_use_k2"></a>x_use_k2 | Compile using experimental K2. K2 is a new compiler pipeline, no compatibility guarantees are yet provided | Boolean | optional | False |
433436

434437

438+
<a id="#kt_ksp_plugin"></a>
439+
440+
## kt_ksp_plugin
441+
442+
kt_ksp_plugin(<a href="#kt_ksp_plugin-name">name</a>, <a href="#kt_ksp_plugin-deps">deps</a>, <a href="#kt_ksp_plugin-processor_class">processor_class</a>)
443+
444+
445+
Define a KSP plugin for the Kotlin compiler to run. The plugin can then be referenced in the `plugins` attribute
446+
of the `kt_jvm_*` and `kt_android_*` rules.
447+
448+
An example can be found under `//examples/ksp`:
449+
450+
```bzl
451+
kt_ksp_plugin(
452+
name = "moshi-kotlin-codegen",
453+
processor_class = "com.squareup.moshi.kotlin.codegen.ksp.JsonClassSymbolProcessorProvider",
454+
deps = [
455+
"@maven//:com_squareup_moshi_moshi",
456+
"@maven//:com_squareup_moshi_moshi_kotlin",
457+
"@maven//:com_squareup_moshi_moshi_kotlin_codegen",
458+
],
459+
)
460+
461+
kt_jvm_library(
462+
name = "lib",
463+
srcs = glob(["*.kt"]),
464+
plugins = ["//:moshi-kotlin-codegen"],
465+
)
466+
467+
468+
**ATTRIBUTES**
469+
470+
471+
| Name | Description | Type | Mandatory | Default |
472+
| :------------- | :------------- | :------------- | :------------- | :------------- |
473+
|<a id="kt_ksp_plugin-name"></a>name | A unique name for this target. | <a href="https://bazel.build/docs/build-ref.html#name">Name</a> | required | |
474+
|<a id="kt_ksp_plugin-deps"></a>deps | The list of libraries to be added to the compiler's plugin classpath | <a href="https://bazel.build/docs/build-ref.html#labels">List of labels</a> | optional | [] |
475+
|<a id="kt_ksp_plugin-processor_class"></a>processor_class | The fully qualified class name that the Java compiler uses as an entry point to the annotation processor. | String | required | |
476+
477+
435478
<a id="define_kt_toolchain"></a>
436479

437480
## define_kt_toolchain
@@ -485,7 +528,8 @@ This macro registers the kotlin toolchain.
485528
## kotlin_repositories
486529

487530
<pre>
488-
kotlin_repositories(<a href="#kotlin_repositories-compiler_repository_name">compiler_repository_name</a>, <a href="#kotlin_repositories-compiler_release">compiler_release</a>, <a href="#kotlin_repositories-configured_repository_name">configured_repository_name</a>)
531+
kotlin_repositories(<a href="#kotlin_repositories-compiler_repository_name">compiler_repository_name</a>, <a href="#kotlin_repositories-ksp_repository_name">ksp_repository_name</a>, <a href="#kotlin_repositories-compiler_release">compiler_release</a>,
532+
<a href="#kotlin_repositories-ksp_compiler_release">ksp_compiler_release</a>, <a href="#kotlin_repositories-configured_repository_name">configured_repository_name</a>)
489533
</pre>
490534

491535
Call this in the WORKSPACE file to setup the Kotlin rules.
@@ -496,7 +540,30 @@ Call this in the WORKSPACE file to setup the Kotlin rules.
496540
| Name | Description | Default Value |
497541
| :------------- | :------------- | :------------- |
498542
| <a id="kotlin_repositories-compiler_repository_name"></a>compiler_repository_name | for the kotlinc compiler repository. | <code>"com_github_jetbrains_kotlin"</code> |
543+
| <a id="kotlin_repositories-ksp_repository_name"></a>ksp_repository_name | <p align="center"> - </p> | <code>"com_github_google_ksp"</code> |
499544
| <a id="kotlin_repositories-compiler_release"></a>compiler_release | version provider from versions.bzl. | <code>struct()</code> |
545+
| <a id="kotlin_repositories-ksp_compiler_release"></a>ksp_compiler_release | (internal) version provider from versions.bzl. | <code>struct()</code> |
500546
| <a id="kotlin_repositories-configured_repository_name"></a>configured_repository_name | for the default versioned kt_* rules repository. If None, no versioned repository is created. | <code>"io_bazel_rules_kotlin_configured"</code> |
501547

502548

549+
<a id="versions.use_repository"></a>
550+
551+
## versions.use_repository
552+
553+
<pre>
554+
versions.use_repository(<a href="#versions.use_repository-name">name</a>, <a href="#versions.use_repository-version">version</a>, <a href="#versions.use_repository-rule">rule</a>, <a href="#versions.use_repository-kwargs">kwargs</a>)
555+
</pre>
556+
557+
558+
559+
**PARAMETERS**
560+
561+
562+
| Name | Description | Default Value |
563+
| :------------- | :------------- | :------------- |
564+
| <a id="versions.use_repository-name"></a>name | <p align="center"> - </p> | none |
565+
| <a id="versions.use_repository-version"></a>version | <p align="center"> - </p> | none |
566+
| <a id="versions.use_repository-rule"></a>rule | <p align="center"> - </p> | none |
567+
| <a id="versions.use_repository-kwargs"></a>kwargs | <p align="center"> - </p> | none |
568+
569+

0 commit comments

Comments
 (0)