// Copyright (C) 2023 Gradle, Inc.
//
// Licensed under the Creative Commons Attribution-Noncommercial-ShareAlike 4.0 International License.;
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      https://creativecommons.org/licenses/by-nc-sa/4.0/
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

:maven-optional-deps: https://maven.apache.org/guides/introduction/introduction-to-optional-and-excludes-dependencies.html[Maven optional dependencies]
:metadata-file-spec: https://github.com/gradle/gradle/blob/master/subprojects/docs/src/docs/design/gradle-module-metadata-latest-specification.md

[[feature_variants]]
= Modeling library features

Gradle supports the concept of _features_: it's often the case that a single library can be split up into multiple related yet distinct libraries, where each _feature_ can be used alongside the _main_ library.

Features allow a component to expose multiple related libraries, each of which can declare its own dependencies.
These libraries are exposed as variants, similar to how the _main_ library exposes variants for its API and runtime.

This allows for a number of different scenarios (list is non-exhaustive):

- a (better) substitute for {maven-optional-deps}
- a _main_ library is built with support for different mutually-exclusive implementations of runtime features; the <<sec::incompatible_variants,user must choose one, and only one, implementation of each such feature>>
- a _main_ library is built with support for optional runtime features, each of which requires a different set of dependencies
- a _main_ library comes with supplementary features like _test fixtures_
- a _main_ library comes with a main artifact, and enabling an additional feature requires additional artifacts

[[sec::feature_variant_selection]]
== Selection of features via capabilities

Declaring a dependency on a component is usually done by providing a set of coordinates (group, artifact, version also known as GAV coordinates).
This allows the engine to determine the _component_ we're looking for, but such a component may provide different _variants_.
A _variant_ is typically chosen based on the usage. For example, we might choose a different variant for compiling against a component (in which case we need the API of the component) or when executing code (in which case we need the runtime of the component).
All variants of a component provide a number of <<dependency_capability_conflict.adoc#sub:capabilities, capabilities>>, which are denoted similarly using GAV coordinates.

--
A capability is denoted by GAV coordinates, but you must think of it as feature description:

- "I provide an SLF4J binding"
- "I provide runtime support for MySQL"
- "I provide a Groovy runtime"

And in general, having two components that provide the _same thing_ in the graph is a problem (they conflict).
--

This is an important concept because:

- By default, a variant provides a capability corresponding to the GAV coordinates of its component
- No two variants in a dependency graph can provide the same capability
- Multiple variants of a single component may be selected as long as they provide _different capabilities_

A typical component will *only* provide variants with the default capability.
A Java library, for example, exposes two variants (API and runtime) which provide the _same capability_.
As a consequence, it is an error to have both the _API_ and _runtime_ of a single component in a dependency graph.

However, imagine that you need the _runtime_ and the _test fixtures runtime_ of a component.
Then it is allowed as long as the _runtime_ and _test fixtures runtime_ variant of the library declare different capabilities.

If we do so, a consumer would then have to declare two dependencies:

- one on the "main" feature, the library
- one on the "test fixtures" feature, by _requiring its capability_

NOTE: While the resolution engine supports multi-variant components independently of the ecosystem, _features_ are currently only available using the Java plugins.

[[sec::declare_feature_variants]]
== Registering features

Features can be declared by applying the `java-library` plugin.
The following code illustrates how to declare a feature named `mongodbSupport`:

.Registering a feature
====
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/kotlin",files="build.gradle.kts[tags=register_variant,register_variant2]"]
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/groovy",files="build.gradle[tags=register_variant,register_variant2]"]
====

Gradle will automatically set up a number of things for you, in a very similar way to how the <<java_library_plugin#java_library_plugin,Java Library Plugin>> sets up configurations.

Dependency scope configurations are created in the same manner as for the main feature:

- the configuration `mongodbSupportApi`, used to _declare API dependencies_ for this feature
- the configuration `mongodbSupportImplementation`, used to _declare implementation dependencies_ for this feature
- the configuration `mongodbSupportRuntimeOnly`, used to _declare runtime-only dependencies_ for this feature
- the configuration `mongodbSupportCompileOnly`, used to _declare compile-only dependencies_ for this feature
- the configuration `mongodbSupportCompileOnlyApi`, used to _declare compile-only API dependencies_ for this feature

Furthermore, consumable configurations are created in the same manner as for the main feature:

- the configuration `mongodbSupportApiElements`, used by consumers to fetch the artifacts and API dependencies of this feature
- the configuration `mongodbSupportRuntimeElements`, used by consumers to fetch the artifacts and runtime dependencies of this feature

A feature should have a _source set_ with the same name.
Gradle will create a `Jar` task to bundle the classes built from the feature source set, using a classifier corresponding to the kebab-case name of the feature.

WARNING: Do not use the _main_ source set when registering a feature. This behavior will be deprecated in a future version of Gradle.

Most users will only need to care about the dependency scope configurations, to declare the specific dependencies of this feature:

.Declaring dependencies of a feature
====
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/kotlin",files="build.gradle.kts[tags=variant_dependencies]"]
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/groovy",files="build.gradle[tags=variant_dependencies]"]
====

--
By convention, Gradle maps the feature name to a capability whose group and version are the same as the group and version of the main component, respectively, but whose name is the main component name followed by a `-` followed by the kebab-cased feature name.

For example, if the component's group is `org.gradle.demo`, its name is `provider`, its version is `1.0`, and the feature is named `mongodbSupport`, the feature's variants will have the `org.gradle.demo:provider-mongodb-support:1.0` capability.

If you choose the capability name yourself or add more capabilities to a variant, it is recommended to follow the same convention.
--

[[sec::publishing_feature_variants]]
== Publishing features

--
Depending on the metadata file format, publishing features may be lossy:

- using {metadata-file-spec}[Gradle Module Metadata], everything is published and consumers will get the full benefit of features
- using POM metadata (Maven), features are published as **optional dependencies** and artifacts of features are published with different _classifiers_
- using Ivy metadata, features are published as extra configurations, which are _not_ extended by the `default` configuration
--

Publishing features is supported using the `maven-publish` and `ivy-publish` plugins only.
The Java Library Plugin will take care of registering the additional variants for you, so there's no additional configuration required, only the regular publications:

.Publishing a component with features
====
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/kotlin",files="build.gradle.kts[tags=plugins,publishing]"]
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/groovy",files="build.gradle[tags=plugins,publishing]"]
====

[[sub:javadoc_sources_features_variants]]
=== Adding javadoc and sources JARs

Similar to the <<building_java_projects.adoc#sec:java_packaging,main Javadoc and sources JARs>>, you can configure the added feature so that it produces JARs for the Javadoc and sources.

.Producing javadoc and sources JARs for features
====
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/kotlin",files="build.gradle.kts[tags=register_variant_extra_jars]"]
include::sample[dir="snippets/java-feature-variant/producer-separate-sourceset/groovy",files="build.gradle[tags=register_variant_extra_jars]"]
====

[[sec::consuming_feature_variants]]
== Dependencies on features

--
As mentioned earlier, features can be lossy when published.
As a consequence, a consumer can depend on a feature only in these cases:

- with a project dependency (in a multi-project build)
- with Gradle Module Metadata available, that is the publisher MUST have published it
- within the Ivy world, by declaring a dependency on the configuration matching the feature
--

A consumer can specify that it needs a specific feature of a producer by declaring required capabilities.
For example, if a producer declares a "MySQL support" feature like this:

.A library declaring a feature to support MySQL
====
include::sample[dir="snippets/java-feature-variant/requiring-features/kotlin/producer",files="build.gradle.kts[tags=producer]"]
include::sample[dir="snippets/java-feature-variant/requiring-features/groovy/producer",files="build.gradle[tags=producer]"]
====

Then the consumer can declare a dependency on the MySQL support feature by doing this:

.Consuming specific features in a multi-project build
====
include::sample[dir="snippets/java-feature-variant/requiring-features/kotlin/consumer",files="build.gradle.kts[tags=consumer]"]
include::sample[dir="snippets/java-feature-variant/requiring-features/groovy/consumer",files="build.gradle[tags=consumer]"]
====

This will automatically bring the `mysql-connector-java` dependency on the runtime classpath.
If there were more than one dependency, all of them would be brought, meaning that a feature can be used to group dependencies which contribute to a feature together.

Similarly, if an external library with features was published with {metadata-file-spec}[Gradle Module Metadata], it is possible to depend on a feature provided by that library:

.Consuming specific features from an external repository
====
include::sample[dir="snippets/java-feature-variant/requiring-features-external/kotlin/project",files="build.gradle.kts[tags=consumer]"]
include::sample[dir="snippets/java-feature-variant/requiring-features-external/groovy/project",files="build.gradle[tags=consumer]"]
====

[[sec::incompatible_variants]]
== Handling mutually exclusive variants

The main advantage of using _capabilities_ as a way to handle features is that you can precisely handle compatibility of variants.
The rule is simple:

> No two variants in a dependency graph can provide the same capability

We can leverage this to ensure that Gradle fails whenever the user mis-configures dependencies.
Consider a situation where your library supports MySQL, Postgres and MongoDB, but that it's only allowed to choose _one_ of those at the same time.
We can model this restriction by ensuring each feature also provides the same capability, thus making it impossible for these features to be used together in the same graph.

.A producer of multiple features that are mutually exclusive
====
include::sample[dir="snippets/java-feature-variant/incompatible-variants/kotlin/producer",files="build.gradle.kts[tags=producer]"]
include::sample[dir="snippets/java-feature-variant/incompatible-variants/groovy/producer",files="build.gradle[tags=producer]"]
====

Here, the producer declares 3 features, one for each database runtime support:

- `mysql-support` provides both the `db-support` and `mysql-support` capabilities
- `postgres-support` provides both the `db-support` and `postgres-support` capabilities
- `mongo-support` provides both the `db-support` and `mongo-support` capabilities

Then if the consumer tries to get both the `postgres-support` and `mysql-support` features (this also works transitively):

.A consumer trying to use 2 incompatible variants at the same time
====
include::sample[dir="snippets/java-feature-variant/incompatible-variants/kotlin/consumer",files="build.gradle.kts[tags=consumer]"]
include::sample[dir="snippets/java-feature-variant/incompatible-variants/groovy/consumer",files="build.gradle[tags=consumer]"]
====

Dependency resolution would fail with the following error:

----
Cannot choose between
   org.gradle.demo:producer:1.0 variant mysqlSupportRuntimeElements and
   org.gradle.demo:producer:1.0 variant postgresSupportRuntimeElements
   because they provide the same capability: org.gradle.demo:producer-db-support:1.0
----
