TeamCity
Powerful CI/CD for DevOps-centric teams
Kotlin Configuration Scripts: Creating Configuration Scripts Dynamically
This is part three of the five-part series on working with Kotlin to create Configuration Scripts for TeamCity.
- An Introduction to Configuration Scripts
- Working with Configuration Scripts
- Creating Configuration Scripts dynamically
- Extending the TeamCity DSL
- Testing Configuration Scripts
We saw in the previous post how we could leverage some of Kotlin’s language features to reuse code. In this part, we’re going to take advantage of the fact that we are in fact dealing with a full programming language and not just a limited DSL, to create a dynamic build configuration.
Build Configurations based on parameters
The scenario is the following: we have an HTTP server that we need to test on different platforms with a range of concurrent connections on each one. This generates potentially a lot of different build configurations that we’d need to create and maintain.
Instead of doing this manually, what we can do is write some code to have our Kotlin DSL Configuration Script generate all the different build configurations for us.
Let’s say that we have a list of Operating Systems and a range of concurrent connections for each one. The first thing to do is to create a data class that represents this information
data class BuildParameters(val name: String, val operatingSystem: String, val connections: Int)
which in essence is like a regular class but provides a series of benefits such as a nicer string representation, equality and copy operations amongst other things.
Now let’s imagine we have the different platforms we want to test on represented as a list of `BuildParameters`
val operatingSystems = listOf(
BuildParameters("Windows Build", "windows", 30),
BuildParameters("MacOS Build", "osx", 20),
BuildParameters("Linux Build", "ubuntu", 20)
)
what we’d like to do, is iterate over this list and create a new build type for each combination. In essence, if our standard `Project` is
object Project : Project({
uuid = "9179636a-39a3-4c2c-aa7e-6e2ea7cfbc5b"
extId = "Wasabi"
parentId = "_Root"
name = "Wasabi"
vcsRoot(Wasabi_HomeGitWasabiGitRefsHeadsMaster)
buildType(WasabiBuild)
})
what we want to do is create a new `buildType` for each entry in the list
object Project : Project({
uuid = "9179636a-39a3-4c2c-aa7e-6e2ea7cfbc5b"
extId = "Wasabi"
parentId = "_Root"
name = "Wasabi"
vcsRoot(Wasabi_HomeGitWasabiGitRefsHeadsMaster)
val operatingSystems = listOf(
BuildParameters("Windows Build", "windows", 30),
BuildParameters("MacOS Build", "osx", 20),
BuildParameters("Linux Build", "ubuntu", 20)
)
operatingSystems.forEach {
buildType(OperatingSystemBuildType(it))
}
})
Creating a base Build Type
Any parameter passed into `buildType` needs to be of the type `BuildType`. This means we’d need to inherit from this class and at the same time provide some parameters to it (`BuildParameters`)
class OperatingSystemBuildType(buildParameters: BuildParameters) : BuildType() {
init {
val paramToId = buildParameters.name.toExtId()
uuid = "53f3d94a-20c6-43a2-b056-baa19e55fd40-$paramToId"
extId = "BuildType$paramToId"
name = "Build for ${buildParameters.name}"
vcs {
root(Wasabi.vcsRoots.Wasabi_HomeGitWasabiGitRefsHeadsMaster)
}
steps {
gradle {
tasks = "clean build"
useGradleWrapper = true
gradleWrapperPath = ""
gradleParams = "-Dconnections=${buildParameters.connections}"
}
}
triggers {
vcs {
}
}
requirements {
contains("teamcity.agent.jvm.os.name", buildParameters.operatingSystem)
}
}
}
The code is actually a pretty standard Configuration Script that defines a Gradle build step, has a VCS definition and defines a VCS trigger. What we’ve done is just enhance it somewhat.
To begin with, we’re using the `BuildParameters name` property to suffix it to the `uuid`, `extId` and `name`. This guarantees a unique ID per build configuration as well as provides us a name to identify it easily. To make sure the values are properly formatted, we use the TeamCity DSL defined extension function to String, named `toExtId()` which takes care of removing any forbidden characters.
In the `steps` definition, we pass in certain parameters to `Gradle`, which in our case is the number of concurrent connections we want to test with. Obviously, this is just a sample, and the actual data being passed in can be anything and used anywhere in the script.
Finally, we also use the `BuildParameters operatingSystem` property to define Agent requirements.
Summary
The above is just a sample of what can be done when creating dynamic build scripts. In this case, we created multiple build configurations, but we could just as well have created multiple steps, certain VCS triggers, or whatever else could come in useful. The important thing to understand is that at the end of the day, Kotlin Configuration Script isn’t just merely a DSL but a fully fledged programming language.
In the next part of this series, we’ll see how we can extend the Kotlin Configuration Scripts (hint – it’s going to involve extension functions).
Subscribe to TeamCity Blog updates
