Plugin Documenatation Conflicting info

Help/Discuss
1

I’m trying to write a plugin, which I want to be a stand alone plugin, and probably publish in the plugins repo, but I’m finding the docs very inconsistent…

It seemed logical to click on the sidebar item in the manual that had a title for what I wanted to do start here:

https://docs.gradle.org/current/userguide/custom_plugins.html

That page shows a lot of stuff in groovy, creates an extension, and talks about creating a properties file to enumerate the implementation class (a groovy class it seems from this page). It recommends configuration for use in other projects either of these two ways:

buildscript {
    repositories {
        maven {
            url = uri(repoLocation)
        }
    }
    dependencies {
        classpath 'org.gradle:customPlugin:1.0-SNAPSHOT'
    }
}
apply plugin: 'org.samples.greeting'

or

plugins {
    id 'com.jfrog.bintray' version '0.4.1'
}

This all seemed fine until I found mys elf having difficulty accessing extensions from inside my doLast (turned out to be a silly error)… So I googled around for examples…

I found this:
https://docs.gradle.org/4.10.3/userguide/custom_tasks.html

Started on that and then noticed the version, and edited the url to find this:
https://docs.gradle.org/6.0.1/userguide/custom_tasks.html

That has a section for Stand alone, and talks about publishing it for others to used but has no notion of a properties file, and only recommends configuration like this (note the lack of an apply plugin):

buildscript {
    repositories {
        maven {
            url = uri(repoLocation)
        }
    }
    dependencies {
        classpath 'org.gradle:customPlugin:1.0-SNAPSHOT'
    }
}

task greeting(type: org.gradle.GreetingTask) {
    greeting = 'howdy!'
}

unfortunately after that point it goes into a lot of detail about incremental/worker/timeout and says nothing about extensions, or how to configure this task independently from creating an instance of it’s type… So back to google… ok maybe I need to try a tutorial

Gradle | Gradle Guides →
https://guides.gradle.org/writing-gradle-plugins/

And here I land in a world of Java (I’ve got nearly 20 years of java experience so this does not bother me in and of itself) but it’s now monumentally unclear what the recommended way to develop a plugin is… on that tutorial the properties file makes a return but now there’s no mention of extension classes… it seems as if the extension isn’t necessary if you use java? That page also has a link directly to 4.10.3 docs

You can learn more about creating your own task types in the user manual.

So that makes me wonder how up to date that tutorial is… back to the tutorial search page… and next I try:

https://guides.gradle.org/implementing-gradle-plugins/

On this page we now see mention of a plugin-development-plugin, and all the examples are again in Java… And I find an entirely new way of configuring the tasks!!

tasks.register("latestVersionMavenCentral", LatestArtifactVersion) {
    coordinates = 'commons-lang:commons-lang:1.5'
    serverUrl = 'http://repo1.maven.org/maven2/'
}

tasks.register("latestVersionInhouseRepo", LatestArtifactVersion) {
    coordinates = 'commons-lang:commons-lang:2.6'
    serverUrl = 'http://my.company.com/maven2'
}

Then there’s a section where Extensions are lauded, and some classes are shown, and how to connect those two classes to each other but there doesn’t’ seem to be any advice on how to register or otherwise make the extension available? Then it goes on to discuss conventions… And then circles back to how to install the extension… I didn’t find this initially because I stopped reading with the apparent end of discussion of extensions, and then eventually after foundering some more read further and discovered that the topic returned to extensions under a title totally lacking the word extension (" Capturing user input to configure plugin runtime behavior")

At this point I realized my initial error that lead to this search was blindingly dumb, I had somehow deleted the def extension = in front of my extension registration. But In the interim, I’ve now been saddled with a great deal of confusion over what the preferred/best way of developing an extension is:

Should it be done in java or in groovy? what are the pros/cons. What should I be doing to ensure compatibility with the future direction (as it’s seen now of course). What of the above should I be avoiding?

Also I’d like to suggest that the four similarly titled documents:

  1. custom_plugins.html
  2. custom_tasks.html
  3. writing-gradle-plugins/
  4. implementing-gradle-plugins/

be coalesced into a single, or maybe 2 documents that show the current best practice… possibly with sidebar/inline-boxes or whatever to note legacy syntax where applicable…