User Manual #106

Open
bamboo opened this Issue Jul 28, 2016 · 5 comments

Projects

None yet

3 participants

@bamboo
Member
bamboo commented Jul 28, 2016

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
@bamboo bamboo added this to the 1.0.0 milestone Jul 28, 2016
@bamboo bamboo added the epic label Jul 28, 2016
@aesteve
aesteve commented Aug 16, 2016 edited

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
Member
bamboo commented Aug 16, 2016

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
aesteve commented Aug 16, 2016

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
Member
bamboo commented Oct 28, 2016

Thanks for the feedback, @flstaats!

@bamboo bamboo changed the title from Improve documentation to User Manual Jan 5, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment