Kotlin/Library Package Maintainer Guide

This page contains useful information for any maintainers of the Kotlin packages' ebuilds.

Kotlin library build process overview
The upstream project uses Gradle as the build system, which handles the building process of the Kotlin libraries automatically. However, as of July 2021, Gradle is not integrated with Portage, and there is not an eclass that can be used to build and package artifacts for a Gradle project easily. Invoking Gradle directly in an ebuild seems to be a feasible solution, but Gradle downloads project dependencies from the Internet on its own, requiring  to be disabled in Portage's FEATURES and preventing any dependencies installed by Portage to be reused, so it is against the best practices.

Instead of relying on Gradle to automatically perform the build steps, the Kotlin library ebuilds directly call the Kotlin compiler and with equivalent compiler options, arguments and list of sources Gradle would use when the upstream project is being built by it. The sequence in which the modules are built and the order of compiler invocations are the same as the upstream project too. Those details about the build process are found through reverse engineering efforts, which will be described in this page below.

A Kotlin library component that is intended to be used with JVM may contain Java sources in addition to Kotlin sources. When such a component is being built, the Kotlin sources will be compiled first, and files will be generated. Then, any Java sources will be compiled by with those  files in the classpath. The files and the class files compiled from Java sources are all the contents in the JAR for the component in most cases. A few components may also have resource files that need to be included in the JAR as well.

Eclasses
The following eclasses are provided to facilitate creation of ebuilds for Kotlin libraries:


 * : The eclass for general Kotlin packages with Kotlin sources to compile, with support for compiling additional Java sources, JAR generation, source archive creation, JUnit 4 tests, installing pre-built binary JAR, and checks based on and .  This eclass is mainly designed for building sources in the main Kotlin programming language project; it might be possible to use it to build other Kotlin projects such as kotlinx libraries and third-party Kotlin libraries, but this has not been tested yet.
 * : An eclass based on for building modules under the directory in the upstream project's source tree.  The directory consists of reflection.jvm, which is the major part of kotlin-reflect, and various other modules which are both required by reflection.jvm during build time and parts of kotlin-reflect.  The modules correspond to the   subprojects in the main Gradle project.  This is a specialized eclass which is not intended to be used by a general Kotlin package's ebuild.

Obtaining compiler options used by Gradle
To build the Kotlin library packages properly and correctly, it is necessary to know how Gradle would compile them. Gradle will print the compiler options it uses to the output when its  option is enabled. As a side effect, this will make the output very verbose, so saving the output to a file might make searching in it easier. For example, the following command runs Gradle task  and copies the output to both standard output and, overwriting any existing contents in the file should it already exist:

Whenever Gradle invokes the Kotlin compiler, it prints the Kotlin compiler class, compiler classpath and compiler arguments to the debug output. These messages can be searched by querying occurrences of string, such as:

Gradle also prints the arguments it uses for. These arguments can be found by searching for occurrences of string, like:

For a few modules, Gradle may also call a command to start an external process directly. For example, it calls the command directly to build the   subproject. Such commands can be captured by searching for string  in the debug log: