Gradle Plugin Configuration Design

[sebersole]

At the moment, the Gradle plugin uses a projects's normal compileClasspath Configuration to ascertain the Quarkus extensions used by the project explicitly, implicitly and conditionally by scanning. So the project's compileClasspath Configuration will include:

1. Platforms
2. Extensions
3. "Regular" dependencies

This approach has some drawbacks, 2 main ones:

1. It is tougher to enforce the platform(s) across all Configurations.
2. We have to resolve all dependencies (platforms, extensions and normal dependencies) up front in order to be able to discover extensions. For each dependency defined for the compileClasspath, we need to be able to look at the dependency's jar file to determine whether it is an extension; e.g. a dependency on JUnit is not an extension but we'd still have to resolve that dependency (its resolved as part of the Configuration) to know that.

The important aspect here is to be able to handle the different categorizations specially. In my original poc work, I used DSL to drive this separation. That is definitely a larger usage deviation from the current approach. A smaller move might be to use dedicated Configurations for the 2 we want to handle specially:

// the plugin would handle this creating these, but for demonstration...
configurations {
    quarkusPlatforms {
        description = "Configuration to specify all Quarkus platforms (BOMs) to be applied"
    }
    quarkusExtensions {
        description = "Configuration to specify all Quarkus extensions to be applied"
        extends quarkusPlatforms
    }
    implementation {
        extends quarkusExtensions
        extends quarkusPlatforms
    }
    ...
}

// it is then the responsibility of the the build script to make these categorizations
dependencies {
    quarkusPlatforms enforcedPlatform( "io.quarkus:quarkus-bom:2.9.1" )

    quarkusExtensions "io.quarkus:quarkus-hibernate"
    quarkusExtensions "io.quarkus:quarkus-agroal"

    implementation "org.junit.jupiter:junit-jupiter-api"
}

In terms of compatibility, we can even introduce an option:

quarkus {
    // should we search the project's `compileClasspath` for extensions
    scanForExtensions = true/false
}

This compatibility option could also be used in conjunction with the DSL-approach (like in my poc).

Distinguishing these categorizations allows us to minimize the amount of work needed up front to figure out the extensions to apply because we can limit the number of dependencies we need to resolve to determine the full extension set.

Aside from the DSL aspect, this is also another difference between the quarkusExtensions approach and the "poc approach". The poc creates a Configuration for each extension (it aggregates them via extends into something like quarkusExtensions). Which allows for even more control (e.g. create the Configuration for conditional dependencies, but don't resolve it yet).

[aloubyansky]

That's an interesting idea with great potential. How would it work though for extensions that aren't direct dependencies of the application module. AFAICS, it's not that uncommon to have a module (including an external one), that depends on Quarkus extensions, as a direct (or even a transitive dependency) of the application module. Would then scanForExtensions=true be required?

[sebersole]

I wanted to clarify, as reading back my answer was not really clear. Let's use an example of a dependency for io.github.sebersole:fizzy-widget which in turn has a dependency on the quarkus-agroal Quarkus extension.

Currently, you'd have this in the build file:

dependencies {
    implementation "io.github.sebersole:fizzy-widget:1.0"
}

On configuration, the plugin resolves these dependencies so that it can discover extensions.

We need that process to happen, I'm just suggesting one way (well 2, with the poc dsl approach) to limit how much we resolve.

Assuming this quarkusExtensions Configuration, we'd have:

dependencies {
    quarkusExtensions "io.github.sebersole:fizzy-widget:1.0"
}

or:

quarkus {
    scanForExtensions = true
}
dependencies {
    implementation "io.github.sebersole:fizzy-widget:1.0"
}

maybe even something like:

quarkus {
    scanForExtensions += configurations.implementation
}

dependencies {
    implementation "io.github.sebersole:fizzy-widget:1.0"
}

[aloubyansky]

I see what you are trying to do and it looks interesting to explore. I am just trying to find when it could get complicated. So you would resolve the quarkusExtensions in isolation from the rest of the dependencies? That would be just to locate the extensions?
One point I wanted to remind you of is that conditional dependencies may have any kind of artifact (not necessarily another extension) as a condition to be enabled. So that artifact that is used as a condition might theoretically not be found among the dependency tree of the quarkusExtensions but among the usual dependencies.

[sebersole]

So you would resolve the quarkusExtensions in isolation from the rest of the dependencies? That would be just to locate the extensions?

Conceptually, yes - exactly.

One point I wanted to remind you of is that conditional dependencies may have any kind of artifact (not necessarily another extension) as a condition to be enabled. So that artifact that is used as a condition might theoretically not be found among the dependency tree of the quarkusExtensions but among the usual dependencies.

Yep, I understand that.

Here, I'm just trying to propose some ways to speed up the config phase of projects using this plugin. I would imagine that eagerly resolving the entire compileClasspath can be bad. If that is not the case, then let's just ignore this.

[sebersole]

Another option here, if backwards compatibility is paramount, would be to default to scanning compileClasspath as is done today. People wanting the new behavior can then just do something like:

quarkus {
    // note `=` here... this drops scanning `compileClasspath`
    scanForExtensions = configurations.quarkusExtensions
}

dependencies {
    quarkusExtensions "io.github.sebersole:fizzy-widget:1.0"
}

[aloubyansky]

Right. I am curious how useful this will turn out to be. I get the idea and that it'll depend on the project. I guess we'd need to do it a test it to find out.