jjohannes/idiomatic-gradle

How do I idiomatically structure a large build with Gradle 7.2+?

Jendrik Johannes | onepiece.Software

Gradle Training and Consulting

• 🚀 Online course - Modern Gradle Fundamentals Buy on Udemy
• 🏎️ Training on your Gradle topics onepiece.Software/#training
• ✨ Support with your Gradle project onepiece.Software/#consulting

Most of my online content is free. If you want to support my work...

• 🗣️ Tell others about my work, subscribe to my YouTube channel, Star my GitHub repositories, follow me on Mastodon
• 💬 Give feedback and ask questions: Use the YouTube comment sections or open an issue in one of my GitHub repositories
• 💚 If my work helps you, you can support me in doing more: paypal.me/onepiecesw

Gradle How-To GitHub repositories

• 🔌 gradle-plugins-howto How to write Gradle plugins - answers to questions and alternative implementation solutions
• 🗂️ gradle-project-setup-howto How to structure a growing Gradle project with smart dependency management?
• 🧶 idiomatic-gradle How to idiomatically structure a large build
• 📚 gradle-demos A collection of samples demonstrating how to do different things in Gradles

Gradle Plugins maintained by me in the GradleX project

• ⚙️ build-parameters Compile-safe access to parameters supplied to a Gradle build
• 📖 jvm-dependency-conflict-resolution Adds Capabilities to well-known Components hosted on Maven Central
• 🍯 extra-java-module-info Add Java Module information to legacy Java libraries
• 🔄 java-module-dependencies Makes Gradle respect the dependencies defined in 'module-info.java' files
• 🔍 java-module-testing Test Java Modules (whitebox and blackbox) without the hassle

Understanding Gradle video series

idiomatic-gradle's Issues

Share common logic between subproject subsets

Hi Jendrik,

Thank you for sharing your idiomatic gradle project example - it seems really promising!

I have one question though regarding sharing of common logic (dependencies, plugins, etc.) between various disparate subsets of subprojects.

To give you a better perspective - we are trying to incorporate this structure and way of organising gradle builds on a company wide scale where we have a root project that includes different sets of subprojects. Some of those subproject subsets have their own common logic etc. that is not quite appropriate for build-src or living in some included build that's somehow distant from them.

For example:

root
-- subprojects/product/A
-- subprojects/product/B
-- subprojects/product/C
-- subprojects/product/C/C1
-- subprojects/product/C/C2

C1 and C2 are kind of subprojects to C and they need to share common specific to them only logic that has nothing to do with A or B.

How would you share such logic?

Build-logic project clean uses different Gradle version

Hello, we are using patterns based on this repository and we have met weird issue when cleaning through Android studio.

It runs cleans for both projects and the build-logic project clean fail with error resulting from the fact it uses some older Gradle version.

Currently, it is a Using dependency catalogs requires the activation of the matching feature preview. error. Otherwise, building the app normally works.

Do you have any idea why a different Gradle version is used? Thank you.

Alternate name for `gradle/settings` ?

Thoughts on these alternative locations for gradle/settings ?

• gradle/settings-plugins
• gradle/settings/plugins
• gradle/plugins/settings

These all contain plugins which and not just settings which seems clearer to me.

Also, maybe consider turning on the Github Discussions feature on this repo, for items like this. :)

`build-logic` fails to build as a stand-alone build

do:

cd build-logic
../gradlew build

it fails with:

> Task :java-convention:generateExternalPluginSpecBuilders FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':java-convention:generateExternalPluginSpecBuilders'.
> Could not resolve all files for configuration ':java-convention:compileClasspath'.
   > Could not find com.example.buildlogic:libraries:.
     Required by:
         project :java-convention
   > Could not find com.example.idiomatic.gradle:platform:.
     Required by:
         project :java-convention
   > Could not find com.google.guava:guava:.
     Required by:
         project :java-convention

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 687ms
20 actionable tasks: 3 executed, 17 up-to-date

if you add this into dependencyResolutionManagement :

    includeBuild("../platform")
    includeBuild("../libraries")

here:

idiomatic-gradle/build-logic/settings.gradle.kts

Line 4 in ffb5515

dependencyResolutionManagement {

It will fix the build failure.

Better Name for lib.versions.toml

The file lib.versions.toml contains no version information. It only contains coordinates.

A better name would be lib.coordinates.toml

An even better name would be library.coordinates.toml as abbreviations in such contexts reduce readability and offer no value.

Using JVM packages for precompiled script plugins, rather that `.` in the file name.

Currently this repo uses . in the file name of precompiled script plugins.

i.e. a file at src/main/kotlin/com.example.repositories.settings.gradle.kts

can applied with:

plugins {
    id("com.example.repositories")
}

Like this:

But this alternative using JVM packages accomplishes the same thing:
The below can also be applied with:

plugins {
    id("com.example.repositories")
}

I tend to prefer the second one because it matches the pattern of normal kotlin source code.

Is there a reason that using . in the file name rather than JVM packages is seen a more idiomatic?

Also, maybe consider turning on the Github Discussions feature on this repo, for items like this. :)

How to use an external plugin in a local plugin and where to put its version

Hi! I have started to study this repository and it seems to be a solution to many of my problems. However, when trying to apply it to my projects, I'm stuck on something.

I am using gradle-git-version to generate Gradle's version from Git, and RefreshVersions to store the version numbers in a .properties file.

Previously, the setup looked like this:

// root build.gradle.kts

plugins {
    id("com.palantir.git-version")
}

fun calculateVersion(): String = // …

version = calculateVersion()

subprojects {
    version = rootProject.version
}

My understanding is that I should make this entire thing its own included build in gradle/plugins/versioning and use it as a plugin in all projects of the main build to avoid using subprojects.

For this, I have:

// gradle/plugins/settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
}

include("versioning")

// gradle/plugins/versioning/build.gradle.kts

plugins {
    `kotlin-dsl`
}

// gradle/plugins/versioning/src/main/kotlin

plugins {
    id("com.palantir.git-version")
}

fun calculateVersion() = // …

version = calculateVersion()

However, I get:

Failed to generate type-safe Gradle model accessors for the following precompiled script plugins:
 - src/main/kotlin/versioning.gradle.kts

org.gradle.internal.exceptions.LocationAwareException: Precompiled script plugin
Plugin [id: 'com.palantir.git-version'] was not found in any of the following sources:

- Gradle Core Plugins (plugin is not in 'org.gradle' namespace)
- Plugin Repositories (plugin dependency must include a version number for this source)

I understand that it cannot find the version (since it's provided by RefreshVersion, which is only applied to the main build), but I don't understand what is the proper way to do this:

• add RefreshVersions to each included plugin individually? That doesn't sound like the modularity this project aimed for
• hardcode the plugin versions in each dependent plugin? That sounds a bit counter-intuitive when there's a platform module that's supposed to encapsulate all version information
• some other solution?

It would be nice to add an example to this repository of a gradle/plugins plugin which applies a third-party plugin to demonstrate what the idiomatic way to manage its version is.

Can you elaborate on buildSrc vs. Composite Build for convention plugins?

I have always used buildSrc for my convention plugins, but I have not see you use it any of your demos / videos. What are the pros and cons of buildSrc as the place for convention plugins.

Add a license on the repo.

It would help to have a license on this repo, thanks. :)

Looks like gradle is defaulting to `build-logic` instead of `gradle/plugins`

Looks like gradle is defaulting to build-logic instead of gradle/plugins, maybe this repo should follow suit?

See https://github.com/gradle/gradle/pull/22141/files

Toml dependencies

Hello,

Just wanted to ask what is your stance on toml dependencies and if you have considered using them in your project as an idiomatic way of describing them?

Kind regards,
Hristo

Only one Gradle Wrapper in repository root

I noticed there is no Gradle Wrapper in this project. I want to confirm this is intentional.

Personally, I have spent weeks in Gradle Wrapper Version Upgrade Hell because our Big Ball Of Mud Monorepo is riddled with Gradle Wrapper leading to insanity.

My goal is to refactor our Monorepo based on idiomatic-gradle and remove all Gradle Wrapper along the way. Am I on the right path?

Can't build project

First, thanks for this very interesting example! I decided to clone it so I could take a look more easily than on Github, and the project won't sync in IDEA, and can't be built as-is from the command line. I simply ran ./gradlew help and got this error:

> Task :buildlogic-packaging:compileKotlin FAILED
The `kotlin-dsl` plugin applied to project ':buildlogic-packaging' enables experimental Kotlin compiler features. For more information see https://docs.gradle.org/6.7-20200723220251+0000/userguide/kotlin_dsl.html#sec:kotlin-dsl_plugin
e: /Users/trobalik/workspace/personal/idiomatic-gradle/buildlogic/buildlogic-packaging/src/main/kotlin/buildlogic/packaging.gradle.kts: (47, 31): Unresolved reference: asIterator
e: /Users/trobalik/workspace/personal/idiomatic-gradle/buildlogic/buildlogic-packaging/src/main/kotlin/buildlogic/packaging.gradle.kts: (47, 44): Overload resolution ambiguity:
public inline fun <T> Iterable<TypeVariable(T)>.forEach(action: (TypeVariable(T)) -> Unit): Unit defined in kotlin.collections
public inline fun <K, V> Map<out TypeVariable(K), TypeVariable(V)>.forEach(action: (Map.Entry<TypeVariable(K), TypeVariable(V)>) -> Unit): Unit defined in kotlin.collections
e: /Users/trobalik/workspace/personal/idiomatic-gradle/buildlogic/buildlogic-packaging/src/main/kotlin/buildlogic/packaging.gradle.kts: (49, 35): Unresolved reference: isDirectory
e: /Users/trobalik/workspace/personal/idiomatic-gradle/buildlogic/buildlogic-packaging/src/main/kotlin/buildlogic/packaging.gradle.kts: (50, 69): Unresolved reference: name