Getting Started with Kotlin DSL
The Kotlin tutorial helps The Kotlin tutorial helps you learn most Kotlin features in a few hours.
To open the Kotlin DSL project in IntelliJ IDEA, open the .teamcity/pom.xml file as a project. All necessary dependencies will be resolved automatically right away. If all dependencies have been resolved, no errors in red will be visible in the settings.kts.
If you already have an IntelliJ IDEA project and want to add Kotlin DSL module to it, see this section.
Editing Kotlin DSL
If you created an empty project, that’s what you’ll see in your IDE when you open settings.kts:
To get familiar with Kotlin API, see the online documentation on your local server, accessible via the link on the the Versioned Settings project project tab in the UI or by running the the
The documentation is generated in a separate Java process and might take several minutes to build after the server restart.
You can also use the the Download settings in Kotlin format option option from the project project Actions menu menu. For instance, you can find a project that defines some settings that you want to use in your Kotlin DSL project and use this "download" action to see what the DSL generated by TeamCity looks like.
It is implied that you move the changes from the patch file to you settings.kts and delete the patch file. Patches generation allows smooth transition from editing settings via UI to Kotlin DSL.
Sharing Kotlin DSL Scripts
To use an external library in your Kotlin DSL code, add a dependency on this library to the .teamcity/pom.xml file in the settings repository and commit this change so that TeamCity detects it. Then, before starting the generation process, the TeamCity server will fetch the necessary dependencies from the Maven repository, compile code with them, and then start the settings generator.
View DSL in UI
There is an option in the UI to help those using Kotlin-based DSL. When viewing your build configuration settings in the UI, you can click View DSL in the sidebar: the DSL representation of the current configuration will be displayed and the setting being viewed (e.g. a build step, a trigger, dependencies) will be highlighted. To go back, click Edit in UI.
FAQ and Common Problems
Why portable DSL requires the same prefix for all
In TeamCity projects, templates, build configurations and VCS roots all have unique IDs. These IDs usually look like:
Solution: TeamCity executes DSL with the .teamcity as the current directory, so files can be read using the paths relative to the .teamcity directory e.g. File("data/setup.xml"). Files outside the .teamcity directory are not accessible to Kotlin DSL.
Kotlin DSL API documentation is not initialized yet
- app/dsl-documentation/index.html on our Teamcity server displays "Kotlin DSL API documentation is not initialized yet"
- OutOfMemoryError during TeamCity startup with `org.jetbrains.dokka` in stack trace
Solution: set the internal property
Administrator's Guide: Storing Project Settings in Version Control