Skip to content

assumed-gradle-knowledge.md

Latest commit

 

History

History
323 lines (232 loc) · 6.1 KB

assumed-gradle-knowledge.md

File metadata and controls

323 lines (232 loc) · 6.1 KB

Gradle Mental Model for New Users

A practical, industry-aligned explanation

1. What Gradle Is (in one paragraph)

Gradle is a build automation tool. It describes:

  • how source code is compiled,
  • how dependencies are resolved,
  • how artifacts are produced,
  • and how tasks are wired together.

It is declarative by default, lazy by design, and convention‑driven, much like Maven — but more flexible.

2. The Gradle Build Lifecycle (Core Concept)

Every Gradle build runs in three phases, always.

① Initialization phase

Purpose: decide what is being built.

What happens:

  • Reads settings.gradle(.kts)
  • Determines which projects participate
  • Builds the project graph

What does not happen:

  • No tasks
  • No build scripts executed

Mental model:

"Which projects exist?"

② Configuration phase (critical to understand)

Purpose: decide how the build could run.

What happens:

  • All build.gradle(.kts) files execute
  • Plugins are applied
  • Tasks are registered and configured
  • Task dependencies are wired

Important rule:

All build scripts run, even if you execute one task.

This is why Gradle emphasizes:

  • lazy configuration
  • avoiding heavy logic at top level

Mental model:

"What could run, and how is it connected?"

③ Execution phase

Purpose: actually do the work.

What happens:

  • Only requested tasks (and dependencies) execute
  • Tasks run in dependency order
  • Up‑to‑date tasks are skipped

Mental model:

"Now do it."

3. Industry Conventions (Why Gradle Feels Familiar)

Gradle intentionally follows industry conventions, mostly inherited from Maven.

Standard directory layout (Java projects)

src/main/java
src/main/resources

src/test/java
src/test/resources

Why this matters:

  • Tools understand your project without configuration
  • IDEs auto-detect sources
  • CI systems work out-of-the-box

If you follow conventions:

  • Gradle does less work
  • Builds are faster
  • Less configuration is required

Convention over configuration is a feature, not a limitation.

4. The Base Plugin (Minimal Build Lifecycle)

The base plugin provides intent, not behavior.

Lifecycle tasks it defines

  • clean
  • assemble
  • check
  • build

Default wiring:

build
 ├─ assemble
 └─ check

By default:

  • assemble does nothing
  • check does nothing

Expectation:

You attach real work to these lifecycle tasks.

Mental model:

"These tasks describe what should exist, not how."

5. The Java Plugin (Strong Conventions)

The java plugin builds on base and adds opinionated behavior.

It assumes:

  • You are building JVM bytecode
  • You want JARs
  • You want tests
  • You follow Maven layout

Tasks it creates (simplified)

compileJava
processResources
classes

compileTestJava
processTestResources
testClasses

jar
test
check
assemble
build

Core dependency graph

build
 ├─ assemble
 │   └─ jar
 │       └─ classes
 │           ├─ compileJava
 │           └─ processResources
 └─ check
     └─ test
         └─ testClasses
             ├─ compileTestJava
             └─ processTestResources

Expectation:

  • build produces a JAR
  • check runs tests
  • clean deletes build/

If you fight these assumptions, you must rewire tasks manually.

6. Source Sets (Foundational Concept)

A SourceSet is a logical build unit:

  • source files
  • resources
  • compile classpath
  • runtime classpath
  • generated tasks

It is not just a folder.

Default source sets

SourceSet Purpose
main Production code
test Test code

Each source set automatically creates tasks and outputs.

Classpath rules

  • main sees its own dependencies
  • test sees main + test dependencies

Mental model:

A SourceSet is a mini build pipeline.

7. Artifacts: group:name:version

Gradle and Maven share the same artifact model.

An artifact is identified by:

group:name:version

Example:

org.slf4j:slf4j-api:2.0.9

Meaning:

  • group → organization or namespace
  • name → library or module
  • version → immutable release

This is exactly how Maven works.

8. Artifact Repositories

Artifacts live in repositories.

Common ones:

  • Maven Central
  • Google Maven
  • Company internal repositories

Repositories store:

  • compiled JARs
  • metadata
  • dependency graphs

Gradle:

  • downloads artifacts once
  • caches them locally
  • reuses them across projects

Mental model:

"A repository is a global package warehouse."

9. The Gradle Wrapper (Extremely Important)

The Gradle Wrapper (gradlew) is not optional.

What it does

  • Downloads the correct Gradle version
  • Ensures build reproducibility
  • Avoids system Gradle mismatches

Files involved:

gradlew
gradlew.bat
gradle/wrapper/gradle-wrapper.properties

Why industry requires it

  • CI systems rely on it
  • Developers don't install Gradle manually
  • Builds are deterministic

Rule:

Always run ./gradlew, never gradle.

10. How This Maps to Maven

Concept Maven Gradle
Lifecycle Fixed Extensible
Artifacts group:artifact:version group:name:version
Repos Maven repos Same
Convention Strong Strong
Flexibility Low High

Gradle is not "different" — it is Maven's model plus programmability.

11. Common Beginner Pitfalls

  • Doing work during configuration phase
  • Ignoring the wrapper
  • Fighting conventions
  • Replacing lifecycle tasks instead of extending them
  • Treating Gradle as a script instead of a model

Final Mental Model

Layer Responsibility
Gradle core Lifecycle
Wrapper Reproducibility
Base plugin Build intent
Java plugin JVM conventions
Source sets Code topology
Artifacts Binary identity
Repositories Distribution

One sentence summary

Gradle describes what can happen during configuration, then executes only what must happen, using industry‑standard artifact conventions and reproducible tooling.