Other JVM languages

Jenesis is not a Java-only build tool. Drop .kt, .scala, .groovy or .clj sources into a module, and the build resolves the matching compiler and builds them, mixed freely with Java, into one jar and its generated POM, with no build script to write and no file to switch a language on.

Kotlin, Scala, Groovy and Clojure are official plugins: the build resolves each by itself, as build.jenesis.plugin.kotlin, build.jenesis.plugin.scala, build.jenesis.plugin.groovy or build.jenesis.plugin.clojure, in every module that holds a source of its extension, and wires its compiler into the same step graph Core concepts described. No line of jenesis.plugins.properties names them.

Language Extension Switched off by
Kotlin .kt jenesis.language.kotlin=false
Scala .scala jenesis.language.scala=false
Groovy .groovy jenesis.language.groovy=false
Clojure .clj jenesis.language.clojure=false

Each of these compilers comes from its plugin alone, so a module holding a source of a language switched off fails the build, naming the extension and the setting. A pom.xml project reads a folder beside its source directories, such as src/main/kotlin and src/test/kotlin, only where jenesis.maven.sources names it - jenesis.maven.sources=kotlin,groovy in jenesis.properties reads the folders the Kotlin and GMavenPlus plugins read by default, and jenesis.maven.sources=clojure reads src/main/clojure.

This chapter covers what changes when a module holds more than Java: how two compilers share one module, the one rule that decides which packages you can export, the standard-library dependency each language needs, and how to run a compiler plugin.

One module, two compilers

A mixed module is compiled by two compilers in sequence. The build runs the language's compiler and javac in a fixed order over the same sources, each producing its own classes into the module. Because both write into one module, the exported jar looks exactly like a single-language one - a consumer never sees the seam.

The order is not arbitrary, and it differs by language:

Language Order Why
Kotlin kotlinc, then javac kotlinc reads .java as source for symbol resolution but emits only Kotlin classes
Scala scalac, then javac scalac reads .java as source for symbol resolution but emits only Scala classes
Groovy javac, then groovyc groovyc cannot read .java as source; it resolves Java from the compiled class path
Clojure javac, then Clojure's compiler a namespace reaches Java types as classes, from the compiled class path

For Kotlin and Scala, the language compiler runs first: it reads your .java files only to resolve symbols (so Sample.kt can call a Java Greeter) but leaves the Java output to javac, which compiles the .java sources and module-info.java afterwards. For Groovy it is the mirror image: javac runs first and owns all Java output, then groovyc compiles the .groovy sources, reaching Java types through the classes javac already produced. Clojure follows Groovy's order.

Who owns module-info.java. Neither kotlinc nor scalac is handed the module declaration; javac always owns it. For scalac that is a necessity, since its Java parser trips over the dotted module name. Both compilers still receive your other .java sources for resolution.

Which packages you can export

That order decides one thing you need to know: whether a package holding only non-Java code can be exported.

When javac validates an exports <package> directive, it checks that the package is populated in the module's output. For Kotlin and Scala this just works: their compiler already ran, so javac sees the Kotlin or Scala classes through --patch-module and accepts the export. You can export a package that contains a single Kotlin (or Scala) class and no Java type at all.

For Groovy you cannot. groovyc runs after javac, so at export-check time the package's Groovy classes do not exist yet and only Java types count. The rule is:

A package named in an exports directive must contain at least one Java type when the module also uses Groovy. Add a Java type to a Groovy package you want to export, or keep the package internal (a requires with no exports). This is a permanent Groovy restriction, not a Jenesis one - it follows from groovyc resolving Java only from the compiled class path.

Clojure

The Clojure plugin copies every .clj and .cljc source of a module into its jar, as a Clojure library ships them, and compiles each namespace ahead of time. A namespace with (:gen-class) thereby becomes a class with a main method, which java build/jenesis/Execute.java runs where the pom.xml names it as its mainClass.

Classes compiled ahead of time are tied to the Clojure that compiled them, so the plugin compiles with the org.clojure:clojure the module depends on rather than with one of its own. A module that holds a Clojure source but does not depend on org.clojure:clojure fails the build, naming it. Compiling a namespace also compiles every namespace it requires; the plugin keeps the classes of a dependency's namespaces out of the module's jar, as they ship in the dependency's own.

Clojure's jar declares no module name, so the demo declares it as a dependency of a pom.xml project:

<dependency>
    <groupId>org.clojure</groupId>
    <artifactId>clojure</artifactId>
    <version>1.12.6</version>
</dependency>

The standard-library dependency

Each language needs its standard library on the module path. You declare it as a normal requires in module-info.java, and Jenesis resolves it through Maven like any other dependency:

Language requires Resolves to
Kotlin requires kotlin.stdlib; org.jetbrains.kotlin:kotlin-stdlib (plus its transitives)
Scala requires scala.library; org.scala-lang:scala-library
Groovy requires org.apache.groovy; org.apache.groovy:groovy

The code compiles against what the module declares and nothing else - not against the libraries the compiler itself runs on. Gradle's Kotlin plugin adds kotlin-stdlib to a project on its own, so a build moved from Gradle declares it, as a pom.xml dependency or a requires, or kotlinc reports that it cannot access kotlin.Any.

Groovy's jar carries an Automatic-Module-Name, so org.apache.groovy resolves as an automatic module. The Scala standard library lives entirely in one module - scala-library - with scala3-library_3 being an empty aggregator, so nothing splits package scala across two modules and the Java Module System accepts it on the module path with no hand-written wiring.

Pinning the compiler

Every language compiler but Clojure's resolves in the tool group of its plugin - kotlin:tool, scala:tool or groovy:tool - kept completely apart from your module's own main-group dependencies. That separation matters: the running compiler is locked independently of the standard library your module ships against, so pinning a different kotlin-stdlib for your code can never downgrade the kotlinc that compiles it. The documentation tools and Zinc resolve beside them, in kotlin:dokka, scala:scaladoc and scala:zinc; Groovydoc shares the groovy:tool group. Clojure compiles with the org.clojure:clojure of your module, which is pinned as any other dependency of it is.

The compilers float a latest version by default. Run the pin step to record each resolved compiler jar with its version and SHA-256, exactly as it pins your Java compilers and dependencies (see Pinning & bills of materials):

java build/jenesis/Make.java pin
For Scala and Groovy this is more than reproducibility. Their latest releases on Maven Central are often pre-release builds - a Scala -RC or a Groovy -alpha. An unpinned build skips a version with a pre-release qualifier while a version without one is published, and so takes the newest stable compiler of the day; pinning keeps the module on one compiler while you upgrade deliberately.

Compiler arguments

A process-kotlinc.properties in a configuration folder hands kotlinc arguments of its own, written as process-javac.properties writes them for javac (see Building & running):

# build.jenesis/process-kotlinc.properties
-api-version=2.0
-java-parameters=
-J-Xss4m=

Each line is an argument of the compiler. A -J<option> line or a -D line goes to the JVM that runs it instead, as the kotlinc command passes them, so the last line gives that JVM -Xss4m. For Scala and Groovy, process-scalac.properties and process-groovyc.properties configure the JVM each compiler runs in.

Compiling incrementally

-Djenesis.kotlin.incremental=true compiles Kotlin incrementally, as Gradle does by default: after an edit, only the sources the change reaches are compiled again. The compiler runs through the Kotlin Build Tools API, which needs Kotlin 2.3 or newer, in the JVM every compilation of the build shares, rather than in Kotlin's own daemon. That JVM ends with the build, unless jenesis.process.mode=daemon keeps it for the next one. -Djenesis.scala.incremental=true compiles Scala with Zinc, the incremental compiler sbt is built on, in the same way.

Tests and internal declarations

Kotlin's internal visibility ends at the module, and a module's tests reach into it all the same: the build hands kotlinc the tested module's jar as a friend path when it compiles the tests, as Gradle and the Kotlin Maven plugin do. A test that calls an internal function compiles without an argument of its own, in a pom.xml build's test sources and in a module that names its tested module with @jenesis.test.

The build names a module for kotlinc after its artifact ID, as the Kotlin Maven plugin does, or after its module name where it publishes no artifact, and its tests after that name with _test appended. It is the name of the META-INF/<name>.kotlin_module file and the suffix of the binary name of an internal member. A -module-name line in process-kotlinc.properties names the module otherwise.

A compiler plugin

A Kotlin or Scala compiler plugin is declared exactly like a Java annotation processor (Building & running), with one addition: lead with the tool group of the language, as kotlin:tool, so the compiler plugin resolves beside that compiler rather than on javac's processor path.

/**
 * @jenesis.plugin kotlin:tool maven/org.jetbrains.kotlin/kotlin-serialization-compiler-plugin
 */
module demo.serialize {
    requires kotlinx.serialization.core;
}

Jenesis resolves the compiler plugin under the kotlin:tool group, and the Kotlin compiler picks up the jar and loads it itself - you never name an entry point. Above, the kotlinx.serialization plugin generates a @Serializable class's serializer(), and the requires provides the annotation and the runtime types the generated code references. The Scala path is identical: @jenesis.plugin scala:tool <coordinate> resolves in the scala:tool group, and scalac loads the plugin the same way.

A plugin runs only because it is declared. Without the @jenesis.plugin line the plugin is not handed to the compiler - the generated code is never produced and the build fails to compile whatever referenced it. Nothing on the class or module path is scanned for plugins implicitly.

The plugin's version is pinned the usual way, coordinated to the compiler - the pin step writes back its @jenesis.pin line for you.

API documentation

When you build documentation jars (jenesis.project.documentation, Building & running), each language documents its own sources: Dokka for Kotlin, scaladoc for Scala, groovydoc for Groovy, beside javadoc for Java; the Clojure plugin documents nothing. A module with one language and no Java is documented by that language's tool at the root of the archive. Where a module mixes languages, javadoc renders the Java at the root and each other language renders in a folder named after its language - kotlin/, scala/ or groovy/. Where a module holds Java beside Groovy, groovydoc documents the Java sources as well, so its folder covers the whole module. Either way the produced -javadoc.jar always has a root index.html, so it satisfies a repository like Maven Central.

Configuring Dokka

A dokka.properties in a configuration folder takes the options the Dokka Gradle plugin and the dokka-maven-plugin take, one per line. Every value is optional, and an unknown one fails the build:

Value Meaning
module-name the name the pages give the module, documentation unless set
format html, the default, or javadoc for javadoc-styled pages
documented-visibilities any of public, protected, internal, private and package
suppress-obvious-functions, skip-empty-packages true unless set to false
suppress-inherited-members, skip-deprecated, report-undocumented false unless set to true
suppressed-packages regular expressions of packages to leave out, comma-separated
fail-on-warning true fails the build on a warning of Dokka's
jdk-version the Java feature release the JDK links point at
source-link, source-link-suffix the URL of the module's sources, and the line suffix, #L unless set
external-link.<name>, external-link.<name>.package-list documentation to link to, and its package list
footer-message the footer of every page
# sources/META-INF/build.jenesis/dokka.properties
module-name=Kotlin demo
footer-message=Documented by Dokka, built by Jenesis

Dokka failing, including on a warning under fail-on-warning=true, fails the build.