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. 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...
 * 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.4.30, 1.4.31, 1.4.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 Leo3418's fork of the Spark overlay originally created during GSoC 2020. It is configured as:

Instead of editing the file directly, the repository can be set up with :

Since this is a Git-based ebuild repository, please ensure is installed on the system before syncing it:

Then, the repository's contents can be synchronized to the system:

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

Kotlin compiler packages
The packages for Kotlin compiler, including dev-lang/kotlin-bin and virtual/kotlin, have a USE flag for installing with optional Kotlin/JS support.

Emerge
To compile the Kotlin libraries from source, the Kotlin compiler, which is provided by dev-lang/kotlin-bin, must be installed first. However, the compiler depends on two components from the Kotlin libraries, namely kotlin-stdlib and kotlin-reflect, so the two components must be bootstrapped before the remaining packages for Kotlin are installed.

dev-java/kotlin-stdlib and dev-java/kotlin-reflect both recognize the  USE flag, which should be enabled when they are to be installed before dev-lang/kotlin-bin has been merged. The USE flag can be temporarily enabled via the USE environment variable.

Then, the Kotlin compiler can be merged:

Finally, dev-java/kotlin-stdlib and dev-java/kotlin-reflect can be rebuilt from source with the compiler installed just now:

The compiler can now be used to build all other Kotlin library packages for Java and JVM from source as well.

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 permanently 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
To install Kotlin with Kotlin/JS support, please enable the  USE flag for dev-lang/kotlin-bin. This makes dev-lang/kotlin-bin depend on dev-java/kotlin-stdlib-js, but the latter package also requires the Kotlin compiler if it is to be built from source. Thus, dev-java/kotlin-stdlib-js needs to be bootstrapped with dev-java/kotlin-stdlib and dev-java/kotlin-reflect together in this case:

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

Installing an old version of both the compiler and the libraries
When bootstrapping kotlin-stdlib and kotlin-reflect (and kotlin-stdlib-js if the  USE flag is enabled for dev-lang/kotlin-bin), specify the feature release's version with the slot name. For example, to install libraries for Kotlin 1.4:

Now, the Kotlin compiler for the feature release can be merged. Please specify the same slot for dev-lang/kotlin-bin too:

Finally, the libraries can be rebuilt from source. The slots for the library packages need to be specified here as well:

Installing an old version of the libraries only
As long as a version of dev-lang/kotlin-bin has been merged, the Kotlin compiler should be able to be used for building library packages for older Kotlin feature releases still supported by the compiler. As a rule of thumb, the last version each recent Kotlin feature release supports is the one that is two feature releases behind it:

Assuming a compiler that supports the desired feature release version of the libraries has already been installed, the libraries can be merged directly. Remember to specify the libraries' version via the slot name. For example, to install kotlin-stdlib-jdk8 and kotlin-test-junit for Kotlin 1.4:

Installing an old version of the compiler only
It is not possible to have only the compiler for a feature release installed because dev-lang/kotlin-bin depends on dev-java/kotlin-stdlib and dev-java/kotlin-reflect for the same version. For example, dev-lang/kotlin-bin-1.4.32 requires strictly ~dev-java/kotlin-stdlib-1.4.32 and ~dev-java/kotlin-reflect-1.4.32. Thus, installing dev-lang/kotlin-bin means that some Kotlin library components for the same Kotlin version would always be installed alongside.

Nevertheless, users can eliminate newer Kotlin library packages' dependency on the compiler by enabling the  USE flag to use the upstream's pre-built binaries for them. In case both Kotlin compiler 1.4 and some Kotlin 1.5 libraries are needed, the  USE flag can be enabled for the library packages with SLOT 1.5, like in the following example. dev-java/kotlin-stdlib:1.4 will still be pulled for Kotlin compiler 1.4, but dev-java/kotlin-stdlib:1.5 is cleared for installation without Kotlin compiler 1.5.

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 either of these commands can be used to 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:

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 versioned executable for an absent tool will result in an error message. For example, if dev-lang/kotlin-bin:1.5 was built with the  USE flag disabled and it is selected as the default compiler package, then  will emit the following message:

In this case, users who really need to use can either rebuild dev-lang/kotlin-bin:1.5 with the   USE flag enabled or 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.

Likewise, kotlin-stdlib-js needs to be re-bootstrapped too if the  USE flag is enabled for dev-lang/kotlin-bin:

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