Declaring Dependencies & Configurations

The example of the section is tidepool, a small tide prediction toolkit: a model library (tidepool-model), an engine library on top of it (tidepool-engine) and a command line application (tidepool-cli). Its layout, its settings file and how the projects find each other are on Multi Project Builds; the settings file declares Maven Central once, for every project, with repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS, so no build script below has a repositories block. The libraries live in the version catalog, which the Groovy and the Kotlin build share:

The org.gradle.jvmargs line only gives the daemon more room than the 512 MiB heap and 384 MiB metaspace it starts with when nothing is set; the wrapper properties (the checksum and the URL https://services.gradle.org/distributions/gradle-9.8.1-bin.zip) are on Gradle Wrapper.

These files are this page’s own setup for the examples, not an example taken from the manual.

A configuration is a named collection of dependencies, and also of the artifacts a project offers and of the rules by which they are selected. The same word covers three quite different jobs, and since Gradle 8.4 the user manual calls them roles:

The three roles exist so that a build can say what it means. A dependency declared on implementation is a statement about this project; compileClasspath is the answer to "what does javac see?"; apiElements is the answer to "what does the project that depends on me see?". The three questions have different answers, and keeping the three jobs apart is how api can differ from implementation. Before the roles were made explicit, one configuration object could be all three, and the flags canBeResolved, canBeConsumed and canBeDeclared were the only way to tell (all three default to true, which the user manual labels "legacy, don’t use"). The role factory methods dependencyScope, resolvable and consumable arrived in Gradle 8.4 and create configurations whose role cannot be changed afterwards; in Gradle 9.8.1 they are still marked incubating in the Javadoc, and they are the way to create your own (see Your own configurations). Methods called on a configuration in a role they do not suit, such as resolving a declarable one, were a deprecation in the 8.x line and are an error since Gradle 9.0 (both are shown below).

In the tools that came before Gradle the same idea has other names. A Maven scope is an attribute of each dependency (compile, provided, runtime, test) that decides which classpaths the dependency joins and how it is inherited, and it is the thing that is published to consumers; see Maven Dependencies, Scopes & Mediation. An Ivy configuration is a named view of a module, and a dependency maps one configuration of mine to one of the dependency’s (conf="compile->default"); a Gradle configuration is closest to that, and Ivy’s extends is Gradle’s extendsFrom; see Ivy: Module Descriptors & Configurations. The section The same in Maven and in Ant lines the three up.

Source: Gradle: Declarable, Resolvable, and Consumable configurations, Gradle: Configuration flags and roles, Gradle 8.4 release notes: Easier to create role-focused Configurations

Gradle distinguishes module dependencies (a published module found in a repository), project dependencies (another project of the same build) and file dependencies (files with no metadata). All three are written inside dependencies { }, as a configuration name followed by the notation: implementation("org.apache.commons:commons-csv:1.14.1"). In the Kotlin DSL implementation(...) is a generated accessor for the configuration that the Java plugin created; a configuration that your own script creates has none, and is written with a string ("tideTools"("...")) or through add. In the Groovy DSL the configuration name is a dynamic method.

The java plugin creates the configurations for the main source set and for the test source set, and java-library adds api and compileOnlyApi to the main one. The application plugin applies java. All of them were printed from the build that ran on this page, by a task that lists every configuration of tidepool-engine (a java-library project) with its roles and what it extends:

The rows are computed in a provider and stored as a task input, so that the action does not touch the project. The output, the same for both DSLs:

Read together with the user manual’s tables, this is the complete picture:

The diagram draws the main half of it as a graph. An arrow from A to B means that B extendsFrom A, which is why a dependency declared on api ends up in implementation, in compileClasspath, in runtimeClasspath and in both outgoing variants.

A few things in the output are worth reading closely:

What the plugins add is a matter of what is applied, not of the Gradle version. The java plugin has implementation (since Gradle 3.4), compileOnly, runtimeOnly and the test ones, and no api, which is why a library that must tell its consumers what is exposed applies java-library. The War plugin adds providedCompile and providedRuntime, which differ from compileOnly in that the dependencies are on the runtime classpath of the project and the tests but are left out of the WAR. Other plugins create their own: the Android Gradle plugin per build type and flavor (debugImplementation), Kotlin Multiplatform per source set (commonMainImplementation); see Project Structure, Gradle and Build Variants and Dependencies and the Library Ecosystem. The java-test-fixtures plugin (Gradle 5.6) adds testFixturesApi and testFixturesImplementation, and the JVM Test Suite plugin a set per suite (intTestImplementation and intTestRuntimeOnly for a suite called intTest); see Testing JVM Projects.

The history of these names is short enough to list:

Source: Gradle: Understanding dependency configurations, Gradle: Java Library plugin, dependency configurations, Gradle: Configuration inheritance, Gradle 2.12 release notes, Gradle 3.4 release notes, Gradle 4.6 release notes, Gradle 6.7 release notes, Gradle: Removal of compile and runtime configurations

For a library, the most important decision about a dependency is whether the types of that dependency appear in the library’s own interface. If they do, the dependency is part of the API: the consumers need it to compile against the library, so it goes on api and travels to their compile classpath. If it is only used inside, it goes on implementation, and the consumers get it at run time but not to compile against. The user manual’s rule of thumb is to prefer implementation whenever possible, and to reach for api when a type of the dependency is in the library’s binary interface:

A type used only in method bodies, in private members or in internal classes is not part of the API. The compiler cannot tell the difference; Gradle can only be told. Choosing implementation is also the safer error: if an internal type leaks, the consumers fail to compile at once and you notice. Choosing api by habit makes every consumer’s compile classpath larger and every change of the dependency a reason to recompile them, and it lets consumers write code against a library they never declared, which breaks when the library stops exposing it. (The user manual lists faster compilation and less recompilation as the benefits; that is not measured here.)

compileOnly is for what the compiler needs and the running program must not have: annotations that are not used at run time, a servlet API that the container provides, or a dependency that is shaded into the jar. It is what Maven calls provided, with one difference that the Gradle 2.12 release notes state: compileOnly dependencies are not on the test classpath, which a Maven provided dependency is. A test that needs the servlet API declares it again on testImplementation, or on testCompileOnly if the tests only compile against it. The engine proves it: its testCompileClasspath has the model (a project dependency, with the annotations the model exports through compileOnlyApi), Commons CSV and JUnit, and no auto-service-annotations:

annotationProcessor is a separate bucket, since Gradle 4.6, because what the compiler compiles against and what it runs as a processor are different things. Gradle 4.6 deprecated putting processors on the compile classpath and Gradle 5.0 stopped applying them, so a processor declared on the wrong configuration is not an error: it is silently not run. That was tried here, in a scratch copy of the engine with the AutoService processor on compileOnly only. The build succeeded without a warning on JDK 26, and build/classes/java/main has no META-INF directory at all. The engine uses Google’s AutoService, which generates the META-INF/services registration of a class from an annotation. The annotations are compileOnly, because they are not needed at run time, and the processor is annotationProcessor:

The class that uses them is io.tidepool.engine.Warmup (a class with @AutoService(Runnable.class)). After the build, the processor has written build/classes/java/main/META-INF/services/java.lang.Runnable with the line io.tidepool.engine.Warmup. The tree of the configuration is a processor with its own dependencies (Guava, among others), which are not in the compile or the runtime classpath, as the printClasspaths output above shows in its first section:

(The tree is cut after the fifth line, for length; the arrow on its last line is explained in the section "Viewing and debugging dependencies".) The test source set has its own testAnnotationProcessor, empty here.

runtimeOnly is for the opposite case: something the running program needs and the code is not written against, such as a logging backend or a JDBC driver. The command line application declares slf4j-simple on it, and the tree and the classpaths above show that it is in the runtime classpath and not in the compile one. Maven calls this scope runtime.

Source: Gradle: Dependency declaration configurations, Gradle 2.12 release notes: compile-only dependencies, Gradle 4.6 release notes: annotation processors, Gradle: Upgrading from Gradle 4.x to 5.0, annotation processors on the compile classpath

Tests have their own copy of the three Java buckets, each extending the main one (see the table above), so a test sees everything the main code sees and what it adds. Dependencies on a test framework go on testImplementation (the framework’s API, which the test classes compile against) and testRuntimeOnly (the engine that runs them and is not compiled against). The model and the engine declare JUnit Jupiter and its launcher this way, and enable the platform on the task:

The launcher is a classic cause of a failing build. Gradle used to load the test framework’s own dependencies from its distribution when a build did not declare them; that was deprecated in Gradle 8.2 and removed in Gradle 9.0, and a build that relied on it stops with this message. It was produced by removing the testRuntimeOnly line from the model (without the configuration cache; the executor number is Gradle’s):

The Groovy DSL printed the same. The default test task belongs to the default test suite, whose configurations are testImplementation and its siblings; further suites get their own, named from the suite. Builds that use the test suite DSL (useJUnitJupiter(version)) have the framework libraries applied to the suite for them, which is the migration the upgrade guide recommends; the whole subject is on Testing JVM Projects.

Source: Gradle: Testing in Java & JVM projects, troubleshooting, Gradle: Relying on automatic test framework implementation dependencies, Gradle: JVM Test Suite plugin

The Java plugins' configurations cover compiling, running and testing. A build needs its own whenever a set of dependencies has a purpose of its own: the classpath of a code generator, a documentation tool, a set of agents, a smoke test, or the data that one project hands to another. The user manual names three uses: separating API from implementation (which the plugins already do), a resolvable configuration for a classpath, and a consumable configuration to expose something. The tidepool root project, which has no code, has one of each role:

The task listTideTools resolves the classpath at execution time:

and the dependency report of the resolvable configuration, which is the same view as for any other, shows picocli-codegen and its picocli:

The consumable one shows up in outgoingVariants with its capabilities, its attribute and its artifact (both DSLs printed the same; outgoingVariants is described in the next section):

Four reports answer most questions. All of them are tasks of every project (./gradlew :tidepool-cli:dependencies), and with the Java plugins, dependencyInsight has a default configuration of compileClasspath.

dependencies prints the tree of every configuration of the project, or of one with --configuration (the name can be abbreviated by its camel case, tCC for testCompileClasspath, as long as it is unambiguous). The trees above are its output. Its annotations are:

The buildEnvironment task renders the same tree for the classpath of the build scripts themselves (the plugins and what they bring). The tree of the annotation processor above has an instance of the arrow: auto-common asked for guava:31.0.1-jre, and auto-service brought guava:32.0.1-jre; the conflict rules that decide this are on Dependency Resolution, Conflicts & Capabilities.

dependencyInsight explains one dependency in one configuration: why it is there, which version was selected and which paths lead to it. It takes --dependency (a part of group:name is enough), --configuration (default compileClasspath for Java projects), --single-path and --all-variants. The because of the engine’s Commons CSV declaration is a selection reason:

The table lists the attributes the variant provided and those the consumer requested, and how they matched; the bottom tree says the dependency is there because the engine’s implementation put it on the application’s runtimeClasspath. The Groovy DSL printed the same. The possible reasons (By conflict resolution, By constraint, Selected by rule, Forced, Was requested : <because>) are listed in the user manual.

outgoingVariants lists the variants a project offers (its consumable configurations and their secondary variants), with attributes and artifacts. For the engine, the API variant is:

The secondary variant classes is why the application’s compile classpath saw the model as a directory: the consumer asked for libraryelements=classes and got it. resolvableConfigurations is its counterpart for resolvable configurations, with the attributes each requests and the configurations it extends; for the engine it lists annotationProcessor, compileClasspath, runtimeClasspath and the test ones. Since Gradle 9.5 both reports hide variants and configurations that have no attributes unless --all is given (they are marked (n), "not selectable via attributes"); the custom stationData variant above has an attribute and is shown. The reports and the attributes are the subject of Variant-Aware Resolution & Module Metadata.

A Build Scan (--scan) gives a searchable version of the same graph, with the reasons; publishing one needs accepting the terms of use of a service and was not run here. The reports are enough for nearly every question, and their output is text that can be diffed in CI.

Source: Gradle: Viewing and debugging dependencies, the dependencies task, Gradle: Understanding output annotations, Gradle: dependencyInsight, Gradle: The outgoingVariants report, Gradle: The outgoingVariants and resolvableConfigurations reports hide variants without attributes

What the configurations were declared on is, for a published library, what its consumers see. The model and the engine were published with maven-publish to a file:// repository inside the scratch build (publishAllPublicationsToTidepoolRepository; the full publishing page is Publishing), which wrote a POM and a Gradle Module Metadata file (.module) for each. The engine’s POM has the scopes:

api became compile, implementation and runtimeOnly both became runtime, and compileOnly and the test configurations were not written at all. The model’s POM has one dependency, which came from compileOnlyApi:

A POM has no way to say "visible to compilers of consumers, not at run time", so Gradle writes the compileOnlyApi dependency as compile, the closest scope, and a Maven consumer gets the annotations at run time as well. The .module file is richer and keeps the two apart. These are the parts that matter in the engine’s file, cut with ... lines:

and in the model’s, where the API variant has the annotations and the runtime one has no dependencies at all:

The api/implementation distinction therefore survives for Gradle consumers (which read the .module file) and is flattened to compile and runtime for Maven ones. A Maven project that depends on the engine from that repository, resolved with Maven 3.10.0 and the tree goal of maven-dependency-plugin 3.8.1 (the build banner and footer cut):

The model is compile (the engine’s api), Commons CSV is runtime (its implementation), and the annotations are compile, as the POM said. The Groovy DSL build was published as well and wrote a POM with the same dependencies. How the Gradle model compares with Maven’s on this point is on Dependency Management Fundamentals, and how metadata files map to each other (and how to switch Gradle Module Metadata off) on Variant-Aware Resolution & Module Metadata.

The mapping, in the direction of migration, is the one the user manual gives for builds that come from Maven:

Source: Gradle: Migrating from Maven, migrating dependencies, Gradle: Publishing a project as a module, Maven Publish plugin, Maven: Dependency scope

Most of them are in the sections above with their messages. Two more have not been shown yet. The first is what a build from the Gradle 1.x or 2.x era meets when it is upgraded: declaring on compile, a configuration removed in Gradle 7.0:

The Kotlin DSL fails when it compiles the script (the accessor compile no longer exists); the Groovy DSL fails when it runs it (the method does not exist). The same applies to runtime, testCompile and testRuntime. The replacements are implementation or api, runtimeOnly, testImplementation and testRuntimeOnly. A custom configuration that used extendsFrom runtime in the Groovy DSL silently created a new, empty configuration named runtime in Gradle 7, which is a worse symptom (the user manual warns of it).

A version that does not exist, which was run without the configuration cache because with it the build stopped on a serialization error that wraps the same message:

The Groovy DSL printed the same. The message says where Gradle looked (the repository URL from the settings), and which declaration required it; a typo in a version, a repository that does not have the module, or a repository content filter that excludes it all end here.

Gradle 8.14 was not available here, so what follows comes from the official upgrade guides and release notes and was not run here.

Announced for Gradle 10 and not released: the errors for the multi-string notation and for Project as a notation, the change in resolving one’s own module coordinates, and the configuration cache on by default (which rejects the pattern shown in "Resolving at execution time, and the configuration cache").

Source: Gradle 8.4 release notes, Gradle: Using configurations incorrectly, Gradle: Deprecation of using Project objects as dependency notation

Gradle in Action (Muschko, Manning 2014) was written for Gradle 1.7, and its chapters 5 and 6 are about dependencies. The model it teaches (configurations, module, file and project dependencies, exclusions, repositories) is still right. What changed around it:

Dynamic versions, repositories and the dependency cache, which the book also covers, are on Platforms, Constraints & Rich Versions, Repositories & Content Filtering and Dependency Locking, Verification & Caching.

For the Maven side see Maven Dependencies, Scopes & Mediation and Maven Dependency Management & BOMs; for Ivy see Ivy: Module Descriptors & Configurations and Maven Resolver Ant Tasks; the three side by side on Comparing Ant, Maven & Gradle and the move from one to another on Migrating Between Tools.