Gradle apply plugin vs plugins

Question

I have a simple plugin with greet task doing some 'Hello World' print.

plugins {
    id 'java-gradle-plugin'
    id 'groovy'
    id 'maven-publish'
}

group = 'standalone.plugin2.greeting'
version = '1.0'

gradlePlugin {
    plugins {
        greeting {
            id = 'standalone.plugin2.greeting'
            implementationClass = 'standalone.plugin2.StandalonePlugin2Plugin'    
        }
    }
}

publishing {
    publications {
        maven(MavenPublication) {
            groupId = 'standalone.plugin2.greeting'
            version = '1.0'
            from components.java
        }
    }
}

Now, I have runner application to just run the greet task

buildscript {
    repositories {
        mavenLocal()
    }
    dependencies {
        classpath 'standalone.plugin2.greeting:standalone-plugin2:1.0'
    }
}

apply plugin: 'standalone.plugin2.greeting'

With apply plugin notation it works OK, but when I use plugins notation instead like this:

plugins {
    id 'standalone.plugin2.greeting' version '1.0'
}

it doesn't work.

The error message is:

* What went wrong:
Plugin [id: 'standalone.plugin2.greeting', version: '1.0'] was not found in any of the following sources:

- Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
- Plugin Repositories (could not resolve plugin artifact 'standalone.plugin2.greeting:standalone.plugin2.greeting.gradle.plugin:1.0')
  Searched in the following repositories:
    Gradle Central Plugin Repository

What is the difference? According to documentation apply plugin is old and should not be used.

Answer 1

Before the introduction of the plugins block, plugin dependencies had to be resolved in the same way as regular project dependencies using a combination of repositories and dependencies. Since they need to be resolved before running the actual build script, they need to be defined in the special buildscript block:

buildscript {
    repositories {
        // define repositories for build script dependencies
    }
    dependencies {
        // define build script dependencies (a.k.a. plugins)
    }
}

repositories {
    // define repositories for regular project dependencies
}

dependencies {
    // define regular project dependencies
}

Once the dependencies were resolved, they could be applied using apply plugin:.

By default, the new plugins block just resolves the plugins from the Gradle Plugin Repository. This is a regular Maven repository, so it can be used using the old way, too:

buildscript {
    repositories {
        maven {
            url "https://plugins.gradle.org/m2/"
        }
    }
}

In your case, the plugin only exists in mavenLocal, so the plugins block cannot resolve it, as it only looks into the Gradle Central Plugin Repository. You may use the pluginManagement block to resolve plugins from custom repositories.

As described in the article linked above, it is necessary to create a link between the plugin identifier (used inside the plugins block) and the Maven coordinates that provide the respective plugin. To create this link a marker artifact following a specific convention must be published. The Gradle Plugin Development Plugin automatically publishes this marker artifact if used in combination with the Maven Publish Plugin.