Gradle Build Tool

What Gradle Does

Gradle is a build tool. It compiles your Java source code, runs your tests, and manages dependencies — all with a single command. Instead of manually running javac on every file and figuring out classpaths, you run ./gradlew build and Gradle handles everything.

Every assignment in this course includes a build.gradle.kts file that tells Gradle how to build that project. You don’t need to write or edit this file. You just need to run the commands.

You Don’t Install Gradle

Each project comes with the Gradle Wrapper — a script that downloads and uses the correct Gradle version automatically. That’s the gradlew (macOS/Linux) and gradlew.bat (Windows) files in every assignment repo.

This means:

You don’t install Gradle system-wide.
Every project can use a different Gradle version without conflicts.
The first time you run ./gradlew in a new project, it downloads Gradle (~150MB). This is a one-time download per version. Be patient.

Running Gradle Commands

You must be in the project’s root directory (the folder containing build.gradle.kts) for these commands to work.

macOS / Linux

```bash ./gradlew test ``` If you get "Permission denied": ```bash chmod +x gradlew ./gradlew test ```

Windows (PowerShell)

```bash .\gradlew.bat test ``` Or simply: ```bash .\gradlew test ``` PowerShell will find `gradlew.bat` automatically.

Essential Commands

Command	What It Does
`./gradlew test`	Compile and run all tests. This is what you’ll use most.
`./gradlew build`	Compile, run tests, and produce build artifacts
`./gradlew clean`	Delete all build output and start fresh
`./gradlew clean test`	Clean then test — useful when things get weird

For this course, ./gradlew test is your main command. Run it early and often as you work on an assignment.

Reading Test Output

When tests pass, you’ll see something like:

> Task :test

CalculatorTest > testAdd() PASSED
CalculatorTest > testSubtract() PASSED
CalculatorTest > testMultiply() PASSED

BUILD SUCCESSFUL in 3s

When tests fail, you’ll see which ones and why:

> Task :test

CalculatorTest > testAdd() PASSED
CalculatorTest > testDivide() FAILED
    org.opentest4j.AssertionFailedError:
    Expected: 5
    Actual:   0

2 tests completed, 1 failed

BUILD FAILED

The key information is:

Which test failed — testDivide() in this example
What was expected — 5
What your code returned — 0

Use this to figure out what’s wrong with your code. The test names usually tell you what scenario is being tested.

For a detailed HTML report, open:

build/reports/tests/test/index.html

This shows all tests with pass/fail status and full error messages. Just double-click the file to open it in your browser.

Running Tests in VS Code

If the Java extension pack is installed correctly, you can also run tests through VS Code:

Open the Testing panel (beaker icon in the left sidebar, or Ctrl+Shift+P > Test: Focus on Test Explorer View).
You’ll see a tree of all test classes and methods.
Click the play button next to a test to run it, or click the play button at the top to run all tests.
Green check = passed. Red X = failed. Click a failed test to see the error message.

Both ways (terminal and VS Code) run the exact same tests. Use whichever you prefer.

Common Errors

“Permission denied” (macOS/Linux)

The gradlew script isn’t marked as executable. Fix it:

chmod +x gradlew

You only need to do this once per project.

“gradlew is not recognized” or “No such file or directory”

You’re not in the project root directory. The gradlew file lives next to build.gradle.kts. Navigate there first:

cd ~/Documents/cscd210/lab01-yourname
ls gradlew   # should show the file

“JAVA_HOME is set to an invalid directory” or “No matching toolchains found”

Gradle can’t find JDK 25. Possible fixes:

Make sure JDK 25 is installed (run java --version).
Set JAVA_HOME explicitly:

# macOS
export JAVA_HOME=$(/usr/libexec/java_home -v 25)

# Linux
export JAVA_HOME=/usr/lib/jvm/temurin-25-jdk-amd64

# Windows (PowerShell)
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-25.0.1+12"

Add the macOS/Linux line to your ~/.zshrc or ~/.bashrc so it persists.

“Could not resolve dependencies” or network errors on first run

Gradle needs internet access to download dependencies the first time. If you’re offline or behind a restrictive firewall, this will fail. Connect to a network and try again.

Build is extremely slow (> 5 minutes)

The first build in a project is always the slowest (downloading dependencies). Subsequent runs should take seconds. If every run is slow:

Close other heavy applications.
Make sure you’re not running from a network drive or cloud-synced folder (OneDrive, Google Drive, iCloud). Move the project to a local folder.

Tests pass locally but fail on GitHub (or vice versa)

Make sure you’ve pushed all your changes: git status should show nothing to commit.
Your local environment might have something the CI doesn’t (or vice versa). Run ./gradlew clean test locally to simulate a fresh build.

You’re Done

If you’ve completed all six setup guides, your development environment is ready:

JDK 25 compiles and runs Java
Git tracks your changes
VS Code gives you a proper editor with Java support
GitHub hosts your repos and runs automated tests
Cloning gets assignment code onto your machine
Gradle builds and tests your projects

When you get your first assignment link on Canvas, you’ll click it, clone the repo, open it in VS Code, write some Java, run ./gradlew test, and push when you’re done. That’s the whole loop.