Easy to use. This is one of a main tasks to solve then new tool is created. For the world of DSL this mostly mean it should be easy to a end-user to use the tool and to be able to run the tool within a continuous integration build easily.
I found an elegant way to fiddle a DSL tasks into Gradle to make it easy to use. Next I’ll cover an example of TeamCity2DSL where I implemented this approach.
I will not cover the domain where TeamCity2DSL is applied. This deserves a dedicated post(s) (link will be included here). All we need to know about TeamCity2DSL here are
- it provides a way to describe build settings with Kotlin DSL
- the DSL is executed to generate XML settings that TeamCity understands
- it also generates DSL from existing XML settings from TeamCity
Here goes tricks one need to handle to use the TeamCity2DSL
- download TeamCity2DSL classes
- have Kotlin sources with DSL complied
- allow an IDE to be used to author/edit DSL code
This is vital to provide as easy as possible way to run those tasks. This is where our Gradle plugin is used.
TeamCity2DSL Gradle Plugin
The plugin does the following set of tricks
- it setups project repositories and dependencies
- setups dependency on Kotlin runtime and compiler
- adds DSL generation output folder as Kotlin sources
- introduces a dependency on compilation from
A Gradle Plugin Usage Example
build.gradle script that is only required to have both TeamCity2DSL tasks (
The project opens in IntelliJ IDEA. It detects all dependencies, Kotlin, source roots, library sources, etc. No specific requirements here. It Just Works. And again an easy-to-use pattern is implemented.
The first trick is the plugin itself declares a dependency on Kotlin Gradle plugin. The version of Kotlin is selected from plugin dependency. This allows to avoid explicit configuration for Kotlin.
The plugin includes DSL dependencies to itself into
compile configuration. Those jars are predefined and
we make Gradle download them from Maven repository.
Next, we include all
buildScript block repositories into code repositories. This helps to avoid
duplicates in repositories declaration.
To add extra source directory we use the following code (that depends on Gradle’s Java plugin)
We know Kotlin plugin checks Java output path for kotlin sources too. So we depend here only on Java plugin, not on a private API of the Kotlin plugin.
The task implementation uses a custom classloader (with
null parent) to avoid bothering Gradle’s tasks
execution classpath. This is too complicated, from the other hand, to synchronize dependencies
of TeamCity2DSL and Gradle. In the future we may consider running an external processes for better stability.
We created a Gradle plugin that helps to use a Kotlin DSL.
Everything that is related to the setup and execution of tasks is now packed as a Gradle Plugin leading to easy-to-use and easy-to-adopt solution.
This pattern could be re-used for other applications.
Feel free to try TeamCity2DSL for TeamCity project settings domain.comments powered by Disqus