Gradle Installation, Wrapper, CLI, Settings, Build Scripts, and Project Bootstrap: Configuration, Design Choices, and Tradeoffs

1. Configuration choices are contracts, not aesthetic preferences

Chapter 15 has only a few files, but each choice affects who controls the build. A wrapper-only rule controls tool identity. A DSL choice affects build-authoring ergonomics and plugin compatibility. A user-home policy controls state sharing. Generated defaults can accelerate bootstrap yet still need ownership.

A good design question is therefore: which state may vary by machine, and which state must be reviewed with the repository?

2. System Gradle versus Wrapper

3. Kotlin DSL versus Groovy DSL

Gradle accepts *.gradle.kts (Kotlin DSL) and *.gradle (Groovy DSL). Both configure Gradle’s same core model; the DSL changes syntax, type assistance, IDE experience, and sometimes plugin examples—not the conceptual meaning of tasks, configurations, or providers.

Do not convert a mature build merely to follow a fashion. Choose a DSL, automate formatting/review conventions, and keep custom build logic tested.

4. Shared developer User Home versus isolated CI User Home

5. Build Init is scaffolding, not governance

gradle init can create Wrapper files, source layout, build scripts, a version catalog, test dependencies, and samples. That is a bootstrap convenience. A repository team still owns every generated dependency version, plugin, repository declaration, source layout, and convention.

Keep generated comments/examples if they teach the team. Remove sample dependencies that are not required. Pin/verify the Wrapper explicitly. Decide whether version catalogs and subproject layout fit the repository rather than accepting them because Init produced them.

6. Put structure in settings; put project behavior in build scripts

Build-wide structure and plugin/dependency-resolution policy often belong in settings, while a project’s compile/test/package configuration belongs in its build script. This boundary becomes more valuable as a repository grows.

// settings.gradle.kts
rootProject.name = "service"

// build.gradle.kts
plugins {
    java
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(17)
    }
}

Avoid turning settings.gradle.kts into an arbitrary dumping ground. Its main role is the build and project structure; later chapters will add plugin management, dependency resolution, and multi-project structure deliberately.

7. Runtime JVM policy is separate from project toolchain policy

Gradle 9.7.1 can run on JVM 17–26. A team might standardize the Gradle runtime on JDK 21 while compiling services for Java 17. That is legitimate if both identities are pinned/observable. Conversely, relying on every developer’s JAVA_HOME without recording the daemon runtime can create “works in IDE, fails in CI” drift.

Current Gradle also supports daemon JVM criteria via gradle/gradle-daemon-jvm.properties. This chapter introduces the concept but does not require auto-provisioning because that adds toolchain repository policy and network behavior. Use it only when the team is ready to govern those inputs.

8. Worked decision: a 30-repository JVM estate

Suppose 30 repositories run on developer laptops and ephemeral CI. Runner images carry arbitrary system Gradle versions, and developers use JDK 21. The recommended baseline is:

• commit and verify a Wrapper per repository;
• invoke the Wrapper in CI and developer documentation;
• standardize a supported Gradle runtime JDK (JDK 21 here) independently of Java toolchains;
• use shared developer User Homes for speed, but job-scoped or tightly controlled cached User Homes in CI;
• choose one DSL convention for new repositories without forcing a bulk rewrite of mature builds;
• treat Build Init output as a reviewed starting point, not a corporate standard by accident.

9. Security and interoperability consequences

The Wrapper can download executable tooling; global init scripts can inject code into builds; build scripts and plugins execute code. Do not run an untrusted repository’s Wrapper with credentials simply because the distribution checksum is valid. Distribution authenticity and project trust are separate questions.

IDE integrations also use Gradle tooling/daemons. An IDE selecting a different Gradle JVM or bypassing the Wrapper can diverge from CI. Treat IDE settings as a client of the repository contract, not as the contract itself.

10. Performance belongs after correctness

A warm shared User Home is normally faster than a fresh one because distributions, dependencies, and compiled script state can be reused. That does not justify making a warm cache a correctness dependency. First prove a clean build can resolve and execute from controlled inputs; then optimize cache reuse and daemon behavior with measurements.

Knowledge check

11. Bridge to diagnostics

Lesson 4 now breaks these boundaries deliberately: system/wrapper version drift, a bad distribution checksum, unsupported runtime assumptions, a global init script, and stale isolated cache state. The repair method begins with evidence, not cache deletion.

Official references and version notes

• Gradle 9.7.1 Release Notes — 9.7.1 is the August 19, 2026 patch release recommended over 9.7.0.
• Gradle Wrapper — Wrapper files, generation, distribution URL, checksum verification, and upgrade behavior.
• Gradle distribution and Wrapper JAR checksums — official SHA-256 reference.
• Compatibility Matrix — Gradle 9.7.1 runtime JVM support.
• Build Init Plugin — supported project types and non-interactive init options.
• Gradle-managed Directories and Caches — Gradle User Home, project .gradle, build outputs, daemon logs, and dependency caches.
• Gradle Daemon — client JVM, daemon JVM, status, logs, and daemon JVM criteria.
• Settings File Basics and Build File Basics.

Version snapshot: These lessons were generated for August 24, 2026 with Gradle 9.7.1 as the pinned lab release. Re-check the official release and compatibility pages before copying version-specific pins into a future production repository.