Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the Kotlin docs #959

Merged
merged 2 commits into from
Apr 21, 2023
Merged

Update the Kotlin docs #959

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c53cbb3
Update the Kotlin docs
Bencodes Apr 21, 2023
226d902
Update README
Bencodes Apr 21, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,10 @@ sky.reflow:
deps.regen:
scripts/regen_deps

docs.regen:
bazel build //kotlin:stardoc
cp bazel-bin/kotlin/kotlin.md docs/kotlin.md

proto.regen:
scripts/gen_proto_jars

Expand Down
29 changes: 29 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,6 +264,7 @@ Additionally, you can add options for both tracing and timing of the bazel build
* `bazel build --define=kt_timings=1`

`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.

# Kotlin compiler plugins

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

# KSP Annotation Processing

The `kt_ksp_plugin` rule allows running KSP annotation processors, such as Moshi.

For example, you can add allopen to your project like this:
```python
load("@io_bazel_rules_kotlin//kotlin:core.bzl", "kt_ksp_plugin")
load("@io_bazel_rules_kotlin//kotlin:jvm.bzl", "kt_jvm_library")

kt_ksp_plugin(
name = "moshi-kotlin-codegen",
processor_class = "com.squareup.moshi.kotlin.codegen.ksp.JsonClassSymbolProcessorProvider",
deps = [
"@maven//:com_squareup_moshi_moshi",
"@maven//:com_squareup_moshi_moshi_kotlin",
"@maven//:com_squareup_moshi_moshi_kotlin_codegen",
],
)

kt_jvm_library(
name = "lib",
srcs = glob(["*.kt"]),
plugins = ["//:moshi-kotlin-codegen"],
)
```

Full examples of using compiler plugins can be found [here](examples/plugin).

Full examples of using compiler plugins can be found [here](examples/plugin).

## Examples
Expand Down
77 changes: 72 additions & 5 deletions docs/kotlin.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,10 +392,11 @@ kt_javac_options(<a href="#kt_javac_options-name">name</a>, <a href="#kt_javac_o

## kt_kotlinc_options

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>,
<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>,
<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>,
<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>,
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>,
<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>,
<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>,
<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>,
<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>,
<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>,
<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>)

Expand All @@ -411,9 +412,11 @@ kt_kotlinc_options(<a href="#kt_kotlinc_options-name">name</a>, <a href="#kt_kot
|<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 | |
|<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" |
|<a id="kt_kotlinc_options-java_parameters"></a>java_parameters | Generate metadata for Java 1.8+ reflection on method parameters. | Boolean | optional | False |
|<a id="kt_kotlinc_options-jvm_target"></a>jvm_target | The -jvm_target flag. This is only tested at 1.8. | String | optional | "" |
|<a id="kt_kotlinc_options-warn"></a>warn | Control warning behaviour. | String | optional | "report" |
|<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 |
|<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 |
|<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 |
|<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 |
|<a id="kt_kotlinc_options-x_explicit_api_mode"></a>x_explicit_api_mode | Enable explicit API mode for Kotlin libraries. | String | optional | "off" |
|<a id="kt_kotlinc_options-x_inline_classes"></a>x_inline_classes | Enable experimental inline classes | Boolean | optional | False |
Expand All @@ -432,6 +435,46 @@ kt_kotlinc_options(<a href="#kt_kotlinc_options-name">name</a>, <a href="#kt_kot
|<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 |


<a id="#kt_ksp_plugin"></a>

## kt_ksp_plugin

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>)


Define a KSP plugin for the Kotlin compiler to run. The plugin can then be referenced in the `plugins` attribute
of the `kt_jvm_*` and `kt_android_*` rules.

An example can be found under `//examples/ksp`:

```bzl
kt_ksp_plugin(
name = "moshi-kotlin-codegen",
processor_class = "com.squareup.moshi.kotlin.codegen.ksp.JsonClassSymbolProcessorProvider",
deps = [
"@maven//:com_squareup_moshi_moshi",
"@maven//:com_squareup_moshi_moshi_kotlin",
"@maven//:com_squareup_moshi_moshi_kotlin_codegen",
],
)

kt_jvm_library(
name = "lib",
srcs = glob(["*.kt"]),
plugins = ["//:moshi-kotlin-codegen"],
)


**ATTRIBUTES**


| Name | Description | Type | Mandatory | Default |
| :------------- | :------------- | :------------- | :------------- | :------------- |
|<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 | |
|<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 | [] |
|<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 | |


<a id="define_kt_toolchain"></a>

## define_kt_toolchain
Expand Down Expand Up @@ -485,7 +528,8 @@ This macro registers the kotlin toolchain.
## kotlin_repositories

<pre>
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>)
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>,
<a href="#kotlin_repositories-ksp_compiler_release">ksp_compiler_release</a>, <a href="#kotlin_repositories-configured_repository_name">configured_repository_name</a>)
</pre>

Call this in the WORKSPACE file to setup the Kotlin rules.
Expand All @@ -496,7 +540,30 @@ Call this in the WORKSPACE file to setup the Kotlin rules.
| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="kotlin_repositories-compiler_repository_name"></a>compiler_repository_name | for the kotlinc compiler repository. | <code>"com_github_jetbrains_kotlin"</code> |
| <a id="kotlin_repositories-ksp_repository_name"></a>ksp_repository_name | <p align="center"> - </p> | <code>"com_github_google_ksp"</code> |
| <a id="kotlin_repositories-compiler_release"></a>compiler_release | version provider from versions.bzl. | <code>struct()</code> |
| <a id="kotlin_repositories-ksp_compiler_release"></a>ksp_compiler_release | (internal) version provider from versions.bzl. | <code>struct()</code> |
| <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> |


<a id="versions.use_repository"></a>

## versions.use_repository

<pre>
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>)
</pre>



**PARAMETERS**


| Name | Description | Default Value |
| :------------- | :------------- | :------------- |
| <a id="versions.use_repository-name"></a>name | <p align="center"> - </p> | none |
| <a id="versions.use_repository-version"></a>version | <p align="center"> - </p> | none |
| <a id="versions.use_repository-rule"></a>rule | <p align="center"> - </p> | none |
| <a id="versions.use_repository-kwargs"></a>kwargs | <p align="center"> - </p> | none |