Registering Gradle plugins in Arciphant components

Combine Arciphant with convention plugins for components and included builds.

Component plugins

The real power of Arciphant comes into play when you use it in combination with convention plugins that configure your components’ characteristics and external dependencies. Convention plugins define what a component type looks like; Arciphant defines which components exist and how they relate — see Beyond convention plugins for how the two complement each other.

Convention plugins are pre-compiled script plugins that contain build logic. See the official Gradle documentation for detailed information. They can be located either in the buildSrc folder or in a separate Gradle project that is included with includeBuild in pluginManagement.

Assume that each of the components in your modules has some specific Gradle setup, such as external dependencies and the configuration around them. For example, the web component might depend on a web framework, and the db component on a library that manages database access.

So assume you have the following convention plugins in your buildSrc folder specifying the dependencies/configurations for the respective component types:

spring-web-component.gradle.kts
jooq-component.gradle.kts

Such a convention plugin is a plain precompiled script plugin — it applies the JVM plugin and declares whatever the component type needs, for example:

plugins {
    kotlin("jvm")
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
}

You can register these plugins for the components in Arciphant and they will be applied to every component project created from the template — the architecture-specific Gradle setup is written once per component type, not once per component:

template()
    .createComponent(name = "web", plugin = "spring-web-component")
    .createComponent(name = "db", plugin = "jooq-component")

For complete, working convention plugins (Spring, jOOQ, MinIO, a Spring Boot bundle) see the build-logic of the demo project.

Bundle plugins

A plugin can also be registered for a bundle module. This is the natural place for packaging concerns — e.g. a convention plugin that applies Spring Boot and configures the executable jar:

bundle(name = "online-learning-platform", plugin = "spring-boot-bundle-module")

Use `includeBuild` instead of `buildSrc`

It is good practice to use a dedicated project for convention plugins instead of the buildSrc folder and to include it with includeBuild:

Create the build-logic project

Move the convention plugins into a separate Gradle build, e.g. build-logic/src/main/kotlin/spring-web-component.gradle.kts, with the kotlin-dsl plugin applied in its build.gradle.kts. Plugins that the convention plugins apply (e.g. kotlin("jvm")) must be on its classpath:

plugins {
    `kotlin-dsl`
}

repositories {
    gradlePluginPortal()
}

dependencies {
    // required since the convention plugins apply the Kotlin JVM plugin
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.2.0")
}

Include it in the plugin management

pluginManagement {
  // …
  includeBuild("./build-logic")
}

Reference one plugin with apply false

Reference one of the convention plugins in the plugins block of your settings.gradle.kts with apply false:

plugins {
  // …
  id("my-plugin") apply false // makes Gradle resolve plugins from the included build; the plugin is not applied here
}

Referencing a single plugin is enough: it triggers Gradle’s plugin resolution for the included build, and Arciphant can then apply all plugins it provides.

template()
    .createComponent(name = "web", plugin = "spring-web-component")