Kotlin

Kotlin is [[Article description::a programming language developed by JetBrains]]. Originally shaped as a programming language based on the Java platform and JVM, Kotlin was designed with Java interoperability in mind, meaning that a Kotlin program can use not just the Kotlin Standard Library but the Java SE API and all Java libraries too, and Java programs can call useful helpers in the Kotlin Standard Library and all sorts of other Kotlin code as well. Later, Kotlin has been expanded with Android support, JavaScript support through Kotlin/JS, and support for native machine code as compiler target via Kotlin/Native.

Like virtually all other GNU/Linux distributions, Gentoo does not provide Kotlin in its official ebuild repository yet. A few users' personal ebuild repositories may contain an ebuild for Kotlin that unpacks the compiler Zip archive made by the upstream to the file system. During Google Summer of Code 2021, ebuilds that can build the Kotlin core libraries were created, so Gentoo users can install the Kotlin libraries from source instead of binaries pre-compiled by the upstream. A blog post documenting how the ebuilds were created is available.

Available packages
The following packages for Kotlin are available:

Versioning and package slotting
The Kotlin packages strive to stay consistent with the upstream's versioning scheme. Here is the glossary of terms the upstream uses to define the versioning scheme and describe different kinds of Kotlin releases:


 * Feature releases
 * e.g. 1.3, 1.4, 1.5...
 * Incompatible API changes are expected. For example, several compiler warnings have been promoted to compiler errors in Kotlin 1.5.


 * Incremental releases
 * e.g. 1.5.0, 1.5.10, 1.5.20, 1.5.30...
 * Small but non-trivial changes are expected; however, they should be API compatible with prior versions in the same feature release series. For example, in the upstream's Kotlin compiler Zip archive for Kotlin 1.5.20, a new Lombok compiler plugin JAR was added.


 * Bug fix releases
 * e.g. 1.5.30, 1.5.31, 1.5.32...
 * As the name suggests, this kind of releases usually contains minor fixes only.

All Kotlin packages are slotted based on the feature releases, so users can specify to install Kotlin 1.4.x, 1.5.x, etc. to use multiple feature releases in parallel.

Ebuild repository
The Kotlin ebuilds are currently located in the Spark overlay. Before installing the Kotlin ebuilds, please add the Spark overlay to the system using the instructions in the overlay's README.

dev-java/kotlin-* packages
Each of the Kotlin library packages provides some or all of the USE flags listed below:


 * : Use the binary JAR pre-built by the upstream instead of compile the package from source
 * : Install an archive of the source files under, so the package's source files can be viewed from some IDEs
 * : Enable dependencies to run the package's tests, which are controlled by

Emerge
The first step to install any Kotlin packages - both the Kotlin library packages and third-party Kotlin packages - is to install the Kotlin compiler, which is provided by dev-lang/kotlin-bin.

If this is the first time dev-lang/kotlin-bin is being installed, bootstrap packages for Kotlin libraries required by the Kotlin compiler will be pulled as dependencies. After the Kotlin compiler is installed, these libraries can be rebuilt from source using it, and the bootstrap packages will be replaced:

Using the upstream's pre-built binaries
If use of the upstream's pre-built binaries is acceptable for some or all of the Kotlin library packages, the  USE flag can be enabled for them so they will not be built from source. The following example demonstrates how to enable the USE flag for select Kotlin packages:

Kotlin/JS
For Kotlin/JS support, please install dev-java/kotlin-stdlib-js.

Installing an old feature release
The steps listed above install the latest version of Kotlin available in the Spark overlay. The overlay might provide packages for multiple feature releases of Kotlin, and an older release can be installed using instructions in this section.

If no versions of dev-java/kotlin-stdlib and dev-java/kotlin-reflect are installed on the system, an older release of the Kotlin compiler can be installed directly by specifying the feature release's version as the slot of dev-lang/kotlin-bin. Bootstrap packages for kotlin-stdlib and kotlin-reflect for the same release will be pulled together, and they can be rebuilt after the Kotlin compiler is installed:

If any version of dev-java/kotlin-stdlib or dev-java/kotlin-reflect is already installed on the system, the above commands would not work. Portage would attempt to install dev-java/kotlin-stdlib and dev-java/kotlin-reflect for the older feature release directly, but these Kotlin libraries must be re-bootstrapped for the release using the same version of the Kotlin compiler.

In this case, please explicitly request the bootstrap packages for kotlin-stdlib and kotlin-reflect for the older release to be installed before running the commands above:

Managing multiple versions of Kotlin
The slotting of Kotlin packages makes it possible to install and use more than one version of Kotlin on a single system without conflicts. To facilitate use of multiple Kotlin versions, an eselect module for Kotlin, app-eselect/eselect-kotlin, is provided with the Kotlin packages for selecting the default Kotlin version backing the, and  tools. For each of those Kotlin tools, versioned executables like, , etc. are provided too for users who want to use a different Kotlin version without changing the default settings.

Finding the Kotlin tools' version
The option recognized by various Kotlin tools for querying their version is.

Eselect
Similar to the java-vm eselect module, the Kotlin eselect module supports independent Kotlin compiler version selection for both the user and the system. Additionally, if multiple packages of the Kotlin compiler are installed for the same Kotlin feature release, then the Kotlin eselect module provides the functionality to choose the package to use for the feature release.

Getting information for installed Kotlin compiler packages
Like common eselect modules, the  action is used for printing a list of installed Kotlin compilers:

Next to each compiler package's name are indicators showing if the package has been chosen as the default compiler for the user, the system, or a Kotlin feature release. The default version selections can be obtained with the  action as well:

Setting a default Kotlin compiler for the user or the system
The  action of the Kotlin eselect module changes the Kotlin compiler preferences. Like most other eselect modules, the target Kotlin compiler can be specified using either its full name or its ordinal in the list returned by.

For example, if  prints the list shown in the previous section, then both of these commands can set the default Kotlin compiler for the user to  :

The default Kotlin compiler for the system can be set similarly:

Setting a default Kotlin compiler for a feature release
A default Kotlin compiler package can also be set for each Kotlin feature release. This will link the versioned Kotlin tool executables like and  to the executables for that package and cause any ebuilds depending on that feature release to use that package for compilation.

To find all Kotlin compiler packages for a specific feature release, specify the feature release number as an argument to :

The default compiler preference for a feature release can be changed with  too, but please note that if an ordinal is being used to specify the compiler package, then the ordinal needs to come from the list of compilers for the feature release. For example, the same  package's ordinal should be 2 instead of 3:

Selecting Kotlin feature release used to build a Kotlin package
Every Kotlin package has a set of KOTLIN_SINGLE_TARGET USE_EXPAND  flags that can be used to select the Kotlin feature release used to build it. The format of values in KOTLIN_SINGLE_TARGET is  for Kotlin 1. x.

A global default value of KOTLIN_SINGLE_TARGET is set for all Kotlin packages that support more than one Kotlin feature release. It can be overridden both globally and on a per-package basis in.

Versioned Kotlin tool executables
To run a Kotlin tool for a specific feature release without changing the preferences via the Kotlin eselect module, the versioned Kotlin tool executables can be used.

Tools that are not available
If the default Kotlin compiler package does not provide all Kotlin tools, then calling the executable for an absent tool will result in an error message like the following:

In this case, users may either temporarily use the versioned Kotlin tool executable for a Kotlin feature release that provides the tool (e.g. ) or permanently change the default package to another one that provides.

Compile and run the most simple "hello, world" program
A simple Kotlin "hello, world" program can be written as follows:

Assuming this program's source file is saved to, it can be compiled with , the main executable for the Kotlin compiler:

In this case, the compiled Java class file's name will be, which can be launched with :

If the Kotlin program does not use any class or method from the Kotlin Standard Library, which is true for this version of "hello, world" for Kotlin, it can also be run with :

Compile and run a "hello, world" program which uses the Kotlin Standard Library
Consider a fancy version of the Kotlin "hello, world" program, which creates a list for all the words in the phrase with the method and generates the phrase from the list with the  method, both of which are members of the Kotlin Standard Library:

This program can be compiled with and run with  as normal. However, it cannot be run directly with :

This is because adds the Kotlin Standard Library to the classpath automatically, whereas  does not. The program can still be run with if the classpath is manually set. The Kotlin Standard Library's classpath can be obtained through the tool. For example, the following command can be used to run the program with and Kotlin Standard Library 1.5:

Compile and run a "hello, world" program which uses additional libraries
Consider an even fancier version of the Kotlin "hello, world" program, which first creates a stream of words using the method from Java, then converts the stream to a list with the  method in kotlin-stdlib-jdk8, and finally joins the elements in the list into a string.

If this program is compiled directly using, there will be errors suggesting that the  method cannot be found:

This is caused by not automatically including  in the classpath. Again, it can be added manually:

Compile and run a Java program which uses the Kotlin Standard Library
Kotlin code can be called from Java programs, so it is possible to use Kotlin libraries within Java. For example, the following program is the Java equivalent for the Kotlin "hello, world" program which uses the Kotlin Standard Library shown in a previous section.

This program can be compiled with and run with, provided that the Kotlin Standard Library is in the classpath:

Compile and run programs with libraries for a newer feature release
The Kotlin compiler will emit a warning if the classpath contains a library for a newer feature release. For example, the following messages would given by Kotlin compiler 1.4 when Kotlin Standard Library 1.5 is used:

The warning can be eliminated by not letting include  and  it depends on in the classpath for compilation. This is controlled by the  option.

Compile and run programs with libraries for an older feature release
If libraries for a feature release older than the compiler's version is used, then will emit an additional warning even if the   option is enabled. The following warning would appear when Kotlin compiler 1.5 is used with Kotlin Standard Library 1.4:

Specifying the library's version with the  option, as instructed by the warning, is sufficient to eliminate it.

New incremental or bug fix release
All small updates that do not involve migration to a new feature release should be installable with the normal system update method without any issues.

New feature release
To upgrade to a newer Kotlin feature release, kotlin-stdlib and kotlin-reflect must be re-bootstrapped before the remaining components for the new release can be updated. This is necessary because the upstream bootstraps each new feature release with an RC version of that release instead of the latest version in the previous feature release series. For example, Kotlin 1.5.0 is bootstrapped with version 1.5.0-RC-556 instead of 1.4.32.

Staying on a feature release
Users who installed the Kotlin packages without specifying the slot but would like to stay on the installed feature release of Kotlin can re-add dev-lang/kotlin-bin with a slot to the "world" favorites file. If the current installed feature release is 1.4, then please run the following commands:

External resources

 * Kotlin compiler options﻿ reference
 * Kotlin Standard Library API reference
 * kotlin.test API reference