Kotlin-dsl-samples: Documentation

[bamboo]

Provide documentation in a suitable format for integration with the Gradle distribution about:

1. Groovy/Kotlin interoperability
2. Resources for the version of Kotlin being used
3. DSL reference guide
4. Current limitations (can I use Kotlin in buildSrc?)
5. Known problems

[aesteve]

Hi, and thanks for the issue, this would definitely be a major feature.

Currently I have absolutely no clue where to find some documentation, and feel completely lost.

1. IntelliJ, even with your plugin installation instructions (in this repo), doesn't open my project as a Gradle project. It has no idea it's a Gradle project since no build.gradle exists (even after restarting IntelliJ twice and even though settings.gradle has rootProject.buildFileName=build.gradle.kts
2. Very trivial DSL use-case : maven { url 'my maven repo' } : what should I write instead ? maven { url("my repo") } displays a huge stacktrace ending with no resolved call

What should I do while waiting for this issue to be resolved ? There must be something I'm missing if Kotlin support is now the "default" for Gradle, there must a documentation somewhere ?

Back to Groovy in the meantime, at least I'm following this issue and will be updated :)

Thanks a lot for your work ! Hope there are simple answers to my questions. Thanks.

[bamboo]

Hi @aesteve.

About your first question, when importing the project into IDEA point it to the settings.gradle file, that should make IDEA recognise it as Gradle project.

After that, with proper IDEA support, code assistance should aid you in answering your second question, inside the maven { } block type this. to see a list of maven specific configuration options. You should end up with something like maven { setUrl("my repo") } (the this qualifier is optional). There are a few differences between how things look in Kotlin and how they look in Groovy. We are working on minimising the differences wherever it makes sense to leverage familiarity and we'll be documenting the ones that remain before our 1.0 release. In the meanwhile please join us in the #gradle Kotlin Slack channel.

For clarification, as mentioned in the Gradle 3.0 Release Announcement:

Groovy is still the primary build language for Gradle scripts and will always be supported, but we are working intensely to make Gradle Script Kotlin fully production ready by the end of the year in order to provide the best possible development experience to Gradle users.

Thanks for your comments!

[aesteve]

Thanks a lot for your answers ! I'll wait for 1.0 release then :)

[flstaats]

I would like to see clear documentation on what the Kotlin specific idioms for writing plugins should be. One of the things that was missing in the early Gradle with Groovy documentation was clear guidance on preferred form, format and structure for plugins. In the early days you couldn't really create useful plugins without using undocumented features and API which were constantly changing. As a result the ecosystem has many wildly varying approaches to writing plugins and existing plugins haves supportability issues.

With Kotlin based plugins and a more mature Gradle infrastructure it would be great to provide templates and examples of the "preferred" plugin architecture and Kotlin coding style. This way people can be guided into a pit of success rather than wandering around in the dark undocumented forest.

[bamboo]

Thanks for the feedback, @flstaats!

[cvmocanu]

Do you have any ETA for documentation on Kotlin DSL?

We need at least a few tips on how to translate from Groovy DSL to Kotlin DSL.

As it stands, it's almost impossible for a noob like me to use KTS (as much as I would like to), since:

• the documentation is in Groovy format EVERYWHERE (gradle website, stack overflow, etc.)
• it's not even close to obvious how to translate from Gradle to Groovy

In my opinion, this should be considered as more important than probably any other feature (except critical bugs), since it prevents early adoption, and thus early feedback.

[JLLeitschuh]

I basically gained all of my knowledge by reading the various samples that exist and pegging questions into the Gradle chat in the Kotlin Slack. Come by! Say hi!

I agree that there needs to be documentation added.

Perhaps @eriwen could provide some insight into the timelines on that?

[eriwen]

I can say that Kotlin DSL 1.0 will not happen without an extensive amount of documentation to help users adopt it. Failing to provide this would be the fastest way to kill such a tremendous launch, and we will delay 1.0 until we have at least:

• An authoritative migration guide from Groovy => Kotlin
• A majority of Gradle docs showing Kotlin DSL configuration

I think the biggest reason this has not happened yet is that we are optimizing for _soonest Kotlin DSL 1.0_, and we want to avoid the overhead of changing documentation in the face of breaking DSL changes. I think I and the @gradle/kotlin-dsl team do owe you folks some kind of timeline soon, and I think we ought to meet about it ASAP.