Kotlin/Library Package Maintainer Guide

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

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


 * 
 * The eclass designed for building general Kotlin library packages, 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.


 * 
 * 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 library 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:

Kotlin compiler classes and wrappers
The standalone version of the Kotlin compiler packaged and distributed by the upstream contains the following components for the compiler proper:


 * , the main compiler module
 * Various compiler wrapper executables
 * Other libraries used by the compiler

A compiler wrapper may set the KOTLIN_COMPILER environment variable to the name of the compiler class to be used, and the environment variable will be read by , the main Kotlin compiler wrapper.

Here is a list of classes in that are used when Gradle builds the Kotlin libraries:


 * org.jetbrains.kotlin.cli.jvm.K2JVMCompiler: Takes Kotlin sources as input, and produces Java class files as output. This is the default compiler class if KOTLIN_COMPILER is unset, and it is also the compiler class used in building all the JVM libraries.
 * org.jetbrains.kotlin.cli.js.K2JSCompiler: Takes Kotlin sources as input, and produces JavaScript files as output. This is the compiler class for.
 * org.jetbrains.kotlin.cli.js.internal.JSStdlibLinker: Processes JavaScript sources. Only used in building kotlin-stdlib-js.
 * org.jetbrains.kotlin.serialization.builtins.RunKt: The built-in serializer, which takes Kotlin sources as input and produces files as output.  Only used in building.

Compiler class used in kotlin-libs.eclass
does not have a variable for setting KOTLIN_COMPILER before is invoked, so the default compiler class for, which is org.jetbrains.kotlin.cli.jvm.K2JVMCompiler, will be used. However, ebuilds using can still specify a different compiler class by directly setting the KOTLIN_COMPILER environment variable before the eclass's   is called. For example, the following code changes the Kotlin compiler class used by to org.jetbrains.kotlin.cli.js.K2JSCompiler:

This method only works for compiler classes that comply with the common Kotlin compiler options because the  function of  sets some of the options in the arguments to. Some compiler classes listed above are known to be incompatible with those options, and this method does not work on them:


 * org.jetbrains.kotlin.cli.js.internal.JSStdlibLinker
 * org.jetbrains.kotlin.serialization.builtins.RunKt

When Gradle uses one of these compiler classes, it would run these classes directly with like. More details can be found in the following sections.

To see if a compiler class complies with the common Kotlin compiler options, try to set KOTLIN_COMPILER to that class and run, then see what options the compiler class accepts. If no common compiler option is shown at all in the help message or an exception is even thrown, then the compiler class is likely to not comply with the common compiler options.

{{Cmd|KOTLIN_COMPILER{{=}}org.jetbrains.kotlin.cli.js.K2JSCompiler kotlinc -help|collapse-output=true|output= Usage: kotlinc-js,   and   phase functions work similarly as {{Path|java-pkg-simple.eclass}} too. also has some additional variables for controlling how Kotlin sources are compiled, tested and installed.

Allow pre-built binary JAR to be used
The upstream hosts pre-built binary JAR artifacts for many libraries on Maven Central. To allow the pre-built JAR to be installed for an ebuild, specify the URI to the JAR in KOTLIN_LIBS_BINJAR_SRC_URI before inheriting kotlin-libs, and set JAVA_BINJAR_FILENAME to the base name of the JAR anywhere in the ebuild.

Specifying a non-empty value for KOTLIN_LIBS_BINJAR_SRC_URI has the following effects:


 * A  USE flag will be automatically added for the ebuild.  When this USE flag is enabled, the package will not be compiled and installed from source; the pre-built JAR pointed by KOTLIN_LIBS_BINJAR_SRC_URI will be installed instead.


 * If the  USE flag is disabled, then during , the JAR created by the ebuild will be compared with the pre-built JAR pointed by KOTLIN_LIBS_BINJAR_SRC_URI for non-trivial difference in JAR contents and incompatibility in API.  This is equivalent to specifying   for.


 * Another variable, KOTLIN_LIBS_SRCJAR_SRC_URI, will be recognized by . If KOTLIN_LIBS_SRCJAR_SRC_URI has a non-empty value that is set before kotlin-libs is inherited, then the   USE flag can be set when the   USE flag is enabled.  With  , the ebuild will pull the file pointed by KOTLIN_LIBS_SRCJAR_SRC_URI and install it as the source archive for the package at.
 * If KOTLIN_LIBS_SRCJAR_SRC_URI has a non-empty value, then another variable, KOTLIN_LIBS_SRCJAR_FILENAME, must be set to the base name of the file pointed by KOTLIN_LIBS_SRCJAR_SRC_URI.

Dependencies
A Kotlin package can have both build dependencies and runtime dependencies on other Java or Kotlin packages. Build dependencies are to be added to DEPEND. Runtime dependencies that should present in the classpath when the package is being used should go into both RDEPEND and CP_DEPEND. CP_DEPEND is used by to generate a runtime classpath for the package accordingly.

Checking build dependencies
The list of build dependencies for a Kotlin package can be extracted from the value for the  option in the Kotlin compiler arguments Gradle uses to build the package, which can be obtained by using instructions in the  section.

For example, the following JARs are in the classpath when kotlin-test-junit 1.5.20 is built by Gradle:



Not all JARs in the classpath are really required to build the package: the package can still compile without them. In general, JARs meeting any of the following criteria are not required:


 * JARs that contain only files and no  files.  Generally, all  files have this property.
 * JARs which are a dependency of another JAR in the classpath but are not directly used by the Kotlin package. For instance,  is a dependency of, but it is not used by the package itself, nor is its presence in the classpath required for  to work.

After applying these criteria, the list of JARs from the classpath can be filtered so only the ones that are really necessary are left:



Now, the value of DEPEND in the ebuild can be derived from this list:

If the ebuild supports the  USE flag, then the build dependencies from the classpath are unnecessary when that USE flag is enabled. For such kind of ebuilds, the build dependencies can be pulled conditionally:

Compilation
provides variables that can be used to control the command-line arguments to and. For the simplest case where a package can be compiled with just one normal invocation of (and possibly one additional invocation of, it is possible to write an ebuild for the package which does not define   at all, by inheriting kotlin-libs and setting the relevant eclass variables.

KOTLIN_JAVA_SOURCE_ROOTS
This variable accepts an array whose elements should be added to the value of 's  option. will automatically join those elements to a string with a comma as the separator and pass the string to the  option.

KOTLIN_JAVAC_ARGS
This variable accepts an array of any extra options and arguments to. If any Java sources need to be compiled as a result of having a non-empty value for KOTLIN_LIBS_JAVA_SOURCE_ROOTS, then these arguments will be passed to ; otherwise, they will be unused.

KOTLIN_LIBS_RUNTIME_COMPONENT
This variable manipulates the content of file in the produced JAR. Whether or not this variable should be set and the proper value for it can be determined by inspecting in the JAR pre-built by the upstream. If it contains a Kotlin-Runtime-Component entry, then this eclass variable should be set to the value for that entry (which should be either  or  ); this will cause an equivalent  to be created and copied into the JAR generated by the ebuild. If there is no such entry, or does not exist in the pre-built JAR, or there is even not a pre-built JAR for the package, then this variable needs not be set.