Skip to content

Getting started with the DMLA3.1 project

This guide summarizes the process of importing and building the DMLA Kotlin project.

The guide assumes the use of IntelliJ IDEA, but the project may be developed/built with a different IDE as well.

Prerequisites and import

  • GraalVM JDK 24 is required - this can also be installed within IntelliJ IDEA (when choosing Gradle JVM: Download JDK... -> graalvm-jdk-24), and for the most part things work even if JAVA_HOME is not set to GraalVM.
  • Use the setting shown in Fig. 1 (in IntelliJ IDEA: Settings... -> Build, Execution, Deployment -> Gradle) or ensure that Gradle 9.0.0 is installed within IntelliJ or globally with a compatible JDK version in PATH.

Recommended Gradle Settings

Fig 1: Recommended Gradle Settings (when a local Gradle 9 installation is not available)

On Unable to delete... errors

Gradle sometimes fails due to not being able to delete certain jar files. If you are using the wrapper task, installing Gradle natively resolved this problem in multiple times. Issuing the command gradle --stop may also fix the issue when a dead Gradle daemon keeps the file locked/open.

The project was last refactored using IntelliJ IDEA 2025.2, earlier versions may have (even more) issues with Kotlin KSP. The JetBrains Toolbox App is recommended for updating IDEA to the latest version without a hassle.

The Gradle project should take care of any additional requirements (including building the Dokka plugin). The first import of the Gradle project takes a tremendous amount of time, taking up to 4 minutes even on a system with an Intel i7 13700K (16c/24t) and 64 GBs of RAM.

When the import completes, build the project with the IntelliJ build button (or by invoking the DMLA3.1:build Gradle task). As a side effect, the first build runs the KAPT and KSP generators, therefore all generated symbols will become availble in code completions and analyzers.

Once the build completes, you can use the provided launch configurations (e.g. LSP).

Dependency management

In an effort to unify and simplify the management of our Gradle dependencies, the project has been refactored to use Gradle version catalogs.

I found the Android Studio migration guide to be one of the most straightforward introductions to Gradle version catalogs.

In further releases we should avoid version specification in *.kts files even as variables, as the libs object makes all items set in the libs.versions.toml file available in all sub-project configurations.

Additional remarks

org.dmla package prefixes will be added using Gradle later on, it is safe to ignore all related warnings. The JVM target was set to 24, but further testing is required to validate that this did not break anything.

The ANTLR runtime dependency is required due to an error in Truffle DSL that selects a wrong ANTLR version as its dependency, and fails to process the KAPT-generated code. DO NOT REMOVE IT.

Troubleshooting

Gradle import errors

Plugin ... not found

Plugin [id: 'org.gradle.toolchains.foojay-resolver-convention', version: '0.8.0'] was not found in any of the following sources:

  • Try: Run with --info or --debug option to get more log output. Run with --scan to generate a Build Scan (powered by Develocity). Get more help at https://help.gradle.org.

  • Exception is: org.gradle.api.plugins.UnknownPluginException: Plugin [id: 'org.gradle.toolchains.foojay-resolver-convention', version: '0.8.0'] was not found in any othe following sources:

  • Gradle Core Plugins (plugin is not in 'org.gradle' namespace)

  • Included Builds (No included builds contain this plugin)
  • Plugin Repositories (could not resolve plugin artifact 'org.gradle.toolchains.foojay-resolver-convention:org.gradle.toolchainfoojay-resolver-convention. gradle.plugin:0.8.0') Searched in the following repositories: Gradle Central Plugin Repositor
  • There might be network connection issues - even if the error message is not detailed enough.
  • If you are behind a proxy, you can try pointing Gradle to the certificate store that has the proxy's certificate in it, e.g. to Windows root.
  • Add -Djavax.net.ssl.trustStoreType=WINDOWS-ROOT to org.gradle.jvmargs in the gradle.properties file as per this relevant stackowerflow thread.
  • This resolved the issue in one case behind a company proxy firewall.