Gradle

Gradle is a build automation tool for JVM projects and many other ecosystems. Build logic is written in the Groovy DSL (.gradle) or Kotlin DSL (.gradle.kts). Gradle itself runs on the JVM.

Project Files #

From a repository root, the important files are:

• settings.gradle[.kts] defines the build and includes subprojects. It is required for a multi-project build and may set the root project name.
• build.gradle[.kts] defines plugins, dependencies, tasks, and conventions for the root project or a subproject.
• gradle.properties holds project properties. User-wide properties may live in ~/.gradle/gradle.properties.
• gradlew, gradlew.bat, and gradle/wrapper/ form the Gradle Wrapper and should be committed.
• .gradle/ is local Gradle state and should be ignored.

Use include("service", "web") in settings.gradle.kts to register subprojects. Each subproject can have its own build script while sharing repository-wide conventions.

Use the Wrapper #

Run ./gradlew build, not a globally installed gradle, in CI and normal development. The wrapper downloads the version specified in gradle/wrapper/gradle-wrapper.properties, making the build reproducible. Review wrapper upgrades and verify the distribution checksum when available.

Useful commands include:

./gradlew tasks
./gradlew test
./gradlew build
./gradlew clean
./gradlew :service:test

Dependencies and Tasks #

Plugins add configurations and tasks. For example, the Java plugin supplies implementation, api (with java-library), compileOnly, runtimeOnly, and test configurations. Prefer the narrowest configuration: an implementation dependency is not automatically part of a consumer’s compile classpath, while an API dependency becomes part of that public contract.

Gradle executes a task graph. A task should declare its inputs and outputs so that incremental builds and the build cache can safely skip work. Avoid performing undeclared file or network work during configuration; use lazy providers and task actions instead.

Keep versions centralized with a version catalog, platform, or dependency constraints. Lock important dependency versions when reproducibility matters, and do not commit credentials in gradle.properties; supply them through environment variables, a secure CI secret store, or an ignored local file.