To start working with Kotlin DSL, go to the project settings page, click the Actions menu and select Download settings in kotlin format, the option available since TeamCity 10.0.3. This will generate a
.zip archive with project settings which can be used in your sandbox project.
- Enable versioned settings for your project.
- Select kotlin as the format.
Commit the settings to your version control.
Prior to TeamCity 2017.2, as soon as a project is switched to Kotlin, editing of its settings is disabled in the UI (except a few pages: Versioned settings, Maven Settings, SSH keys and Meta-runners). If you need to enable editing, switch versioned settings to XML format or disable versioned settings.
Once you apply the versioned settings to your project, TeamCity will generate necessary Kotlin files for this project and check them in to the specified repository under the
.teamcitydirectory. If this repository already contains project settings in the XML format, they will be preserved, but TeamCity will no longer use them: once you get familiar with Kotlin files, these xml files can be removed.
The easiest way to experiment with DSL in TeamCity 2017.2+ is to edit settings in UI and check the UI diff script generated by TeamCity.
Since TeamCity 2017.2 after Kotlin DSL is enabled for a project, the TeamCity server provides html documentation for the core DSL API as well as the API provided by installed TeamCity plugins. The online documentation is available on your local server, accessible via the link on the Versioned Settings project tab in the UI or by running the
mvn -U dependency:sources command in the IDE. See an example.
If the server url is correct and your TeamCity is up and running, all necessary dependencies will be resolved automatically and you can start working with Kotlin DSL right away.
The Since 2017.2 the TeamCity server does not use uses the pom.xml file ; it is to fetch required dependencies from the Maven repository; the file is also used by the IDE to download required dependencies and to provide code completion as well as detect compilation errors, so any changes you will make to this POM file won’t have any effect during the DSL settings application to the server. You can also delete this file.
Debugging Maven ‘generate’ Task
The pom.xml file provided for a Kotlin project has the 'generate' task, which can be used to generate TeamCity XML files locally from the Kotlin DSL files. Since TeamCity 2017.2 this task supports debugging. If you’re using IntelliJ IDEA, you can easily start debugging of a Maven task, see screenshot:
Ability to Use External Libraries
.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.
You can create a new project via DSL inside a parent project which already has uses settings in the Kotlin format. A new project can be added either in its own directory with
settings.kts or using the
subProject() method in the parent project.
Prior to TeamCity 2017.2, no external resources are supported and since
TeamCity will apply the changes to configuration as follows: