Gradle: compileOnly and runtimeOnly

Question

I'd read the documentation but I'm not able to understand how to create a working example to understand better their differences.

And ofc I've created a playground project to check what happens when I use one or another.

app.gradle

dependencies {
    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8:$rootProject.kotlin_version"
    implementation 'androidx.appcompat:appcompat:1.1.0'
    implementation 'androidx.core:core-ktx:1.2.0'
    compileOnly project(":compileonlylibrary")
    runtimeOnly project(":runtimeonlylibrary")
}

MainActivity.kt

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        FooCompile() // this crash in runtime
        BarRuntime() // this doesn't compiles obviously
    }
}
// FooCompile belongs to compileonlylibrary
// BarRuntime belongs to runtimeonlylibrary

And that's it, I'm stuck here, I'm not able to create a proper example in order to improve my knowledge of Gradle configurations.

Could someone give me a hand? I can provide more details if needed.

Answer 1

• implementation: mostly we use implementation configuration. It hides the internal dependency of the module to its consumer to avoid accidental use of any transitive dependency, hence faster compilation and less recompilation.

• api: must be used very carefully, since it leaks the to consumer’s compile classpath, hence misusing of api could lead to dependency pollution.

• compileOnly: when we don’t need any dependency at runtime, since compileOnly dependency won’t become the part of the final build. we will get a smaller build size.

• runtimeOnly: when we want to change or swap the behaviour of the library at runtime (in final build).

I have created a post with an in-depth understanding of each one with Working Example: source code

https://medium.com/@gauraw.negi/how-gradle-dependency-configurations-work-underhood-e934906752e5

Answer 2

compileOnly dependencies are available while compiling but not when running them.

This is equivalent to the provided scope in maven.

It means that everyone who wants to execute it needs to supply a library with all classes of the CompileOnly library.

For example, you could create a library that uses the SLF4J API and you could set it to CompileOnly.

Anyone using the library needs to (explicitely) import some version of the SLF4J API in order to use it.

runtimeOnly libraries are the opposite, they are available at runtime but not at compile-time.

For example, you don't need the concrete SLF4J logger(e.g. logback) at compile time (as you use the SLF4J classes in order to access it) but you need it at runtime as you want to use it.

Let's look at the following example:

You have a library that uses the SLF4J:

compileOnly org.slf4j:slf4j-api:1.7.30

and you could have a project using the library:

implementation project(":yourlibrary")
implementation org.slf4j:slf4j-api:2.0.0-alpha1
runtimeOnly ch.qos.logback:logback:0.5

SLF4J detects the concrete logger at runtime, it does not need to know the logging library (like logback) at compile-time. This is why you can use runtimeOnly for the concrete logger.

---

Note that compileOnly is broadly used with Jakarta EE as lots of dependencies are provided by the JEE container/application server as shown in the blog the OP found.

Answer 3

From this article, looks like

• Maven's compile scope is equivalent to gradle's api scope
• Maven's provided scope is equivalent to gradle's compileOnly scope

https://reflectoring.io/maven-scopes-gradle-configurations/