Precompiled script plugin on Groovy with a package declaration

[nbir94]

Issue type

Wrong or misleading information

Problem description

According to the documentation for Precompiled script plugins, there is an opportunity to add a package declaration for a plugin implemented either on Groovy or Kotlin:

For example, the script src/main/*/java-library.gradle(.kts) has a plugin ID of java-library (assuming it has no package declaration).
Likewise, src/main/*/my/java-library.gradle(.kts) has a plugin ID of my.java-library as long as it has a package declaration of my.

By the way, it's impossible to create a plugin named java-library because it conflicts with a core plugin with the same name. But here I want to describe another problem.

When I implement a plugin with a package statement on Kotlin, it works according to the documentation. I could not succeed in doing the same on Groovy. If I add a package statement in the plugin having a .gradle extension like below:

// buildSrc/src/main/groovy/com/example/my-plugin.gradle
package com.example

I see an error from Gradle:

Execution failed for task ':buildSrc:extractPluginRequests'.
Script '/Users/enbirr/IdeaProjects/precompiled-plugins/buildSrc/src/main/groovy/com/example/my-plugin.gradle' should not contain a package statement.

Without specifying the package in the plugin, I cannot use the plugin ID containing the package as suggested in the documentation - com.example.my-plugin. I assume that in this case, com and example are treated as directories rather than packages. Thus, I can only use my-plugin as the plugin identifier in the build script.

Is there a misleading in the documentation, or do I need to do something differently?

Gradle version: 8.7
Mac OS

Context (optional)

I am implementing navigation to the plugin source from its ID in IntelliJ IDEA for statements like

// build.gradle
plugins {
    id 'my-plugin'
}

I found this issue while learning the documentation to find possible approaches for plugin implementation. I am looking for conditions that would allow me to verify that a file found for navigation is a Gradle plugin and not something else.

Page with the problem

https://docs.gradle.org/current/userguide/custom_plugins.html#sec:precompile_script_plugin

[ov7a]

By the way, it's impossible to create a plugin named java-library because it conflicts with a core plugin with the same name. But here I want to describe another problem.

Indeed, the example should use a different name.

Is there a misleading in the documentation, or do I need to do something differently?

The docs are misleading.

The changes were made in

• Weekly Documentation cleanup #28707
• Rewrite of developing plugins section in Gradle User Manual -> Authoring Gradle Builds #28167

Additional note:
It should be explicitly said that id("kotlin-dsl") / id("groovy-gradle-plugin") should be put into buildSrc/build.gradle

Another related docs page:
https://docs.gradle.org/current/userguide/implementing_gradle_plugins_precompiled.html#sec:the_plugin_id