Skip to content

Commit

Permalink
docs: reformat the kotlin docs to have better line breaks on readme.c…
Browse files Browse the repository at this point in the history 
…om (pantsbuild#17929)

Readme.com does not like arbitrary line breaks in the markdown. Join lines together to satisfy readme.com and get better rendering on readme.com.
  • Loading branch information
@tdyas
tdyas authored Jan 6, 2023
1 parent 2c65434 commit 9d5840b
Showing 1 changed file with 24 additions and 67 deletions.
91 changes: 24 additions & 67 deletions docs/markdown/Java and Scala/kotlin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,31 +9,21 @@ updatedAt: "2022-07-26T02:02:59.962Z"

> 🚧 Kotlin support is alpha stage
>
> Kotlin support in Pants is still under active development, but currently supports compilation and testing. It has
> been tested with Kotlin v1.6.20.
> Kotlin support in Pants is still under active development, but currently supports compilation and testing. It has been tested with Kotlin v1.6.20.
>
> Please share feedback for what you need to use Pants with your Kotlin project by either
> [opening a GitHub issue](https://github.com/pantsbuild/pants/issues/new/choose)
> or [joining our Slack](doc:community)!
> Please share feedback for what you need to use Pants with your Kotlin project by either [opening a GitHub issue](https://github.com/pantsbuild/pants/issues/new/choose) or [joining our Slack](doc:community)!
> 📘 Example Kotlin repository
>
> Check out [github.com/pantsbuild/example-kotlin](https://github.com/pantsbuild/example-kotlin) to try a
> sample Pants project with Kotlin support.
> Check out [github.com/pantsbuild/example-kotlin](https://github.com/pantsbuild/example-kotlin) to try a sample Pants project with Kotlin support.
# Overview

[Kotlin](https://kotlinlang.org/) is a programming language from Jetbrains that runs on the JVM and certain other
platforms. The Kotlin backend in Pants supports compilation, testing, and linting of
[Kotlin code for the JVM](https://kotlinlang.org/docs/server-overview.html). (The other Kotlin platforms including
[Kotlin Multiplatform Mobile](https://kotlinlang.org/docs/multiplatform.html) and
[Kotlin/JS](https://kotlinlang.org/docs/js-overview.html) are not currently supported, nor are there currently
any plans to do so.)
[Kotlin](https://kotlinlang.org/) is a programming language from Jetbrains that runs on the JVM and certain other platforms. The Kotlin backend in Pants supports compilation, testing, and linting of [Kotlin code for the JVM](https://kotlinlang.org/docs/server-overview.html). (The other Kotlin platforms including [Kotlin Multiplatform Mobile](https://kotlinlang.org/docs/multiplatform.html) and [Kotlin/JS](https://kotlinlang.org/docs/js-overview.html) are not currently supported, nor are there currently any plans to do so.)

# Initial Setup

First, activate the Kotlin backend in `pants.toml` plus the `ktlint` backend if you would like to use
[`ktlint`](https://ktlint.github.io/) for code formatting and linting:
First, activate the Kotlin backend in `pants.toml` plus the `ktlint` backend if you would like to use [`ktlint`](https://ktlint.github.io/) for code formatting and linting:

```toml pants.toml
[GLOBAL]
Expand All @@ -47,9 +37,7 @@ backend_packages = [

## Setting up targets

Run [`./pants tailor ::`](doc:initial-configuration#5-generate-build-files) to generate BUILD files. This will
create `kotlin_sources` targets in every directory containing library code, as well as `kotlin_junit_tests` targets
for filenames that look like tests.
Run [`./pants tailor ::`](doc:initial-configuration#5-generate-build-files) to generate BUILD files. This will create `kotlin_sources` targets in every directory containing library code, as well as `kotlin_junit_tests` targets for filenames that look like tests.

```
❯ ./pants tailor ::
Expand All @@ -76,61 +64,41 @@ src/jvm/org/pantsbuild/example/lib/ExampleLib.java

## Choosing JDK and Kotlin versions

Pants supports choosing the JDK and Kotlin versions per target in your repository. To reduce the amount of
boilerplate required, however, most users set repository-wide defaults in `pants.toml`, and then only override
them when necessary for particular targets.
Pants supports choosing the JDK and Kotlin versions per target in your repository. To reduce the amount of boilerplate required, however, most users set repository-wide defaults in `pants.toml`, and then only override them when necessary for particular targets.

### JDK

JDKs used by Pants are automatically fetched using [Coursier](https://get-coursier.io/), and are chosen using
the [`[jvm].jdk` option](doc:reference-jvm#section-jdk) to set a repository-wide default.
JDKs used by Pants are automatically fetched using [Coursier](https://get-coursier.io/), and are chosen using the [`[jvm].jdk` option](doc:reference-jvm#section-jdk) to set a repository-wide default.

To override the default on a particular target, you can use the [`jdk=` field](doc:reference-kotlin_source#codejdkcode).
It can be useful to use the [`parametrize` builtin](doc:targets#parametrizing-targets) with the `jdk=` field,
particularly to run test targets under multiple JDKs.
To override the default on a particular target, you can use the [`jdk=` field](doc:reference-kotlin_source#codejdkcode). It can be useful to use the [`parametrize` builtin](doc:targets#parametrizing-targets) with the `jdk=` field, particularly to run test targets under multiple JDKs.

### Kotlin version

The Kotlin version to use is configured on a resolve-by-resolve basis (see the "Third-party dependencies" section
below) using the [`[kotlin].version_for_resolve` option](doc:reference-kotlin#section-version_for_resolve). The
default Kotlin version for your repository will thus be whichever Kotlin version is configured for the "default"
resolve, which is configured by the [`[jvm].default_resolve` option](reference-jvm#section-default-resolve).
The Kotlin version to use is configured on a resolve-by-resolve basis (see the "Third-party dependencies" section below) using the [`[kotlin].version_for_resolve` option](doc:reference-kotlin#section-version_for_resolve). The default Kotlin version for your repository will thus be whichever Kotlin version is configured for the "default" resolve, which is configured by the [`[jvm].default_resolve` option](reference-jvm#section-default-resolve).

Each resolve must contain the following jars for the Kotlin runtime with the version matching the version specified
for the resolve in the `[kotlin].version_for_resolve` option:
Each resolve must contain the following jars for the Kotlin runtime with the version matching the version specified for the resolve in the `[kotlin].version_for_resolve` option:

- `org.jetbrains.kotlin:kotlin-stdlib`
- `org.jetbrains.kotlin:kotlin-reflect`
- `org.jetbrains.kotlin:kotlin-script-runtime`

To use multiple Kotlin versions in a repository, you would define multiple resolves, and then adjust
the [`resolve` field](doc:reference-kotlin_junit_test#coderesolvecode) of any targets which should be used with the
non-`default_resolve` resolve.
To use multiple Kotlin versions in a repository, you would define multiple resolves, and then adjust the [`resolve` field](doc:reference-kotlin_junit_test#coderesolvecode) of any targets which should be used with the non-`default_resolve` resolve.

To cross-build a set of Kotlin targets for multiple Kotlin versions, you can use the
[`parametrize` builtin](doc:targets#parametrizing-targets) with the `resolve=` field of the target and its dependencies.
To cross-build a set of Kotlin targets for multiple Kotlin versions, you can use the [`parametrize` builtin](doc:targets#parametrizing-targets) with the `resolve=` field of the target and its dependencies.

> 🚧 `jvm_artifact` targets for the Kotlin runtime must be explicitly defined.
>
> The Kotlin backend currently requires that a `jvm_artifact` target for each Kotlin runtime jars be present in any
> resolve used for Kotlin. If any of the required `jvm_artifact` targets are missing, Pants will error. Pants will
> automatically inject a dependency on the runtime into Kotlin targets. (These targets may be automatically supplied by
> Pants in a future version, but that is not currently implemented.)
> The Kotlin backend currently requires that a `jvm_artifact` target for each Kotlin runtime jars be present in any resolve used for Kotlin. If any of the required `jvm_artifact` targets are missing, Pants will error. Pants will automatically inject a dependency on the runtime into Kotlin targets. (These targets may be automatically supplied by Pants in a future version, but that is not currently implemented.)
## Dependencies

### First-party dependencies

In many cases, the dependencies of your first-party code are automatically inferred via
[dependency inference](https://blog.pantsbuild.org/automatically-unlocking-concurrent-builds-and-fine-grained-caching-on-the-jvm-with-dependency-inference/)
based on `import` statements in the code. If you do need to declare additional dependencies for any reason, you can do
so using Pants' [syntax for declaring dependencies for targets](doc:targets).
In many cases, the dependencies of your first-party code are automatically inferred via [dependency inference](https://blog.pantsbuild.org/automatically-unlocking-concurrent-builds-and-fine-grained-caching-on-the-jvm-with-dependency-inference/) based on `import` statements in the code. If you do need to declare additional dependencies for any reason, you can do so using Pants' [syntax for declaring dependencies for targets](doc:targets).

### Third-party dependencies and lockfiles

Third-party dependencies (i.e. those from repositories like [Maven central](https://search.maven.org/)) are also
automatically inferred via dependency inference, but must first be declared once per repository as
[`jvm_artifact` targets](doc:reference-jvm_artifact):
Third-party dependencies (i.e. those from repositories like [Maven central](https://search.maven.org/)) are also automatically inferred via dependency inference, but must first be declared once per repository as [`jvm_artifact` targets](doc:reference-jvm_artifact):

```python BUILD
jvm_artifact(
Expand All @@ -142,29 +110,21 @@ jvm_artifact(
)
```

Pants requires use of a lockfile for third-party dependencies. After adding or editing `jvm_artifact` targets, you
will need to update affected lockfiles by running `./pants generate-lockfiles`. The default lockfile is located at
`3rdparty/jvm/default.lock`, but it can be relocated (as well as additional resolves declared) via the
[`[jvm].resolves` option](doc:reference-jvm#section-resolves).
Pants requires use of a lockfile for third-party dependencies. After adding or editing `jvm_artifact` targets, you will need to update affected lockfiles by running `./pants generate-lockfiles`. The default lockfile is located at `3rdparty/jvm/default.lock`, but it can be relocated (as well as additional resolves declared) via the [`[jvm].resolves` option](doc:reference-jvm#section-resolves).

> 📘 Thirdparty symbols and the `packages` argument
>
> To efficiently determine which symbols are provided by third-party code (i.e., without hitting the network in order
> to compute dependencies in the common case), Pants relies on a static mapping of which artifacts provide which
> symbols, and defaults to treating each `jvm_artifact` as providing symbols within its `group`.
> To efficiently determine which symbols are provided by third-party code (i.e., without hitting the network in order to compute dependencies in the common case), Pants relies on a static mapping of which artifacts provide which symbols, and defaults to treating each `jvm_artifact` as providing symbols within its `group`.
>
> The `packages` argument allows you to override which symbols a `jvm_artifact` provides. See the
> [`jvm_artifact` docs](doc:reference-jvm_artifact#codepackagescode) for more information.
> The `packages` argument allows you to override which symbols a `jvm_artifact` provides. See the [`jvm_artifact` docs](doc:reference-jvm_artifact#codepackagescode) for more information.
### `resource` targets

To have your code [load files as "resources"](https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html):

1. Add a `resource` or `resources` target with the relevant files in the `source` / `sources` field, respectively.
2. Ensure that [an appropriate `source_root`](doc:source-roots) is detected for the `resources` target, in order to
trim the relevant prefix from the filename to align with the layout of your JVM packages.
3. Add that target to the `dependencies` field of the relevant JVM target (usually the one that uses the JVM APIs to
load the resource).
2. Ensure that [an appropriate `source_root`](doc:source-roots) is detected for the `resources` target, in order to trim the relevant prefix from the filename to align with the layout of your JVM packages.
3. Add that target to the `dependencies` field of the relevant JVM target (usually the one that uses the JVM APIs to load the resource).

For example:

Expand Down Expand Up @@ -254,8 +214,7 @@ kotlin_junit_tests(

## Lint and Format

[`ktlint`](https://ktlint.github.io/) can be enabled by adding the `pants.backend.experimental.kotlin.lint.ktlint`
backend to `backend_packages` in the `[GLOBAL]` section of `pants.toml`.
[`ktlint`](https://ktlint.github.io/) can be enabled by adding the `pants.backend.experimental.kotlin.lint.ktlint` backend to `backend_packages` in the `[GLOBAL]` section of `pants.toml`.

Once enabled, `lint` and `fmt` will check and automatically reformat your code:

Expand All @@ -274,7 +233,5 @@ Once enabled, `lint` and `fmt` will check and automatically reformat your code:

The Kotlin backend is currently experimental since many features are not implemented including:

- Kotlin modules. We would love to hear from Kotlin developers for advice on how modules are used and could
be potentially supported by Pants.
- Non-JVM backends including [Kotlin Multiplatform Mobile](https://kotlinlang.org/docs/multiplatform.html) and
[Kotlin/JS](https://kotlinlang.org/docs/js-overview.html)
- Kotlin modules. We would love to hear from Kotlin developers for advice on how modules are used and could be potentially supported by Pants.
- Non-JVM backends including [Kotlin Multiplatform Mobile](https://kotlinlang.org/docs/multiplatform.html) and [Kotlin/JS](https://kotlinlang.org/docs/js-overview.html)

0 comments on commit 9d5840b

Please sign in to comment.