Article 1: Creating a Gradle Plugin from A to Z with the gradle init command
Published on 23 September 2025
Introduction
Starting a new Gradle plugin project can seem intimidating. Fortunately, Gradle provides a powerful interactive assistant, the`init`task, which generates a complete, clean, and ready-to-use project structure. This guide will show you how to use this tool to create a healthy plugin base, explain its structure, and show you how to run the first build tasks.
Step 1: Launch the project assistant
The`gradle init`command is the starting point. It launches a command-line assistant that asks you a series of questions to configure the project.
Open your terminal in an empty folder and run:
gradle initThe assistant will guide you. Here are the choices to make for a Gradle plugin written in Kotlin:
-
Select type of project to generate:Choose`Gradle plugin`.
-
Select implementation language:Choose`Kotlin`.
-
Select build script DSL:Choose`Kotlin`.
-
Project name:Enter a name for your project (e.g.,
site-baker). -
Plugin id:Give a unique identifier to your plugin (e.g.,
com.cheroliv.site-baker). -
Plugin class:Specify the name of the implementation class (e.g.,
com.cheroliv.SiteBakerPlugin).
Once finished, Gradle generates a complete file tree.
Step 2: Understanding the generated structure
The assistant creates a multi-module project structure, separating the root project from the plugin source code itself.
.
├── gradle/
│ └── wrapper/
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── plugin/
│ ├── build.gradle.kts
│ └── src/
│ ├── main/
│ │ └── kotlin/
│ │ └── com/cheroliv/SiteBakerPlugin.kt
│ ├── test/
│ │ └── kotlin/
│ │ └── com/cheroliv/SiteBakerPluginTest.kt
│ └── functionalTest/
│ └── kotlin/
│ └── com/cheroliv/SiteBakerPluginFunctionalTest.kt
└── settings.gradle.ktsKey files and folders
-
settings.gradle.kts: This file at the root defines the modules included in the build. Here, it includes the`plugin`sub-project.
[source,kotlin] ---- rootProject.name = "site-baker" include("plugin") ----
-
plugin/build.gradle.kts: This is the heart of your plugin configuration. It applies the`java-gradle-plugin`plugin, declares dependencies, and configures the plugin metadata.
[source,kotlin] ---- plugins { java-gradle-plugin alias(libs.plugins.kotlin.jvm) }
gradlePlugin { val siteBaker by plugins.creating { id = "com.cheroliv.site-baker" implementationClass = "com.cheroliv.SiteBakerPlugin" } } ----
-
src/main/: Contains the source code of your plugin. -
src/test/: Contains unit tests. They run quickly and in isolation. -
src/functionalTest/: Contains functional tests. These tests use`GradleRunner`to execute a full version of Gradle on a test project, thus simulating real-world usage of your plugin.
Step 3: Building and testing the plugin
The generated project includes theGradle Wrapper(gradlew). This is the recommended way to run Gradle, as it ensures that all developers use the same version, ensuring reproducible builds.
Basic tasks
-
Build the project:
This command compiles your code, runs all tests (unit and functional), and assembles your plugin’s JAR. [source,bash] ---- ./gradlew build ----
-
Run all checks:
The`check`task is an alias that runs all verification tasks, including`test` et functionalTest. [source,bash] ---- ./gradlew check ----
-
Run only unit tests:
For quick feedback during development. [source,bash] ---- ./gradlew test ----
|
The`./gradlew :test`command, which explicitly targets the root project, will fail because the latter contains no tests. On the other hand: * `./gradlew test`works because Gradle runs the`test`task on all sub-projects that possess it (here, the`plugin`module). * `./gradlew :plugin:test`is the most explicit command to run the tests of the`plugin`module only. |
-
Run only functional tests:
Slower, they are useful for validating overall behavior. [source,bash] ---- ./gradlew functionalTest ----
The test results are generated in the`plugin/build/reports/tests/`folder. You can open the`index.html`file in your browser for a detailed report.
Conclusion
In a few minutes,`gradle init`has provided you with a solid, modern, and complete project base for your plugin development. You have a clear structure, preconfigured unit and functional tests, and a reproducible build system thanks to the Gradle Wrapper.
You are now ready to open the`SiteBakerPlugin.kt`file and start adding your plugin’s business logic!