Gradle Release Notes

In most cases it is more natural and convenient to define dependencies on a component rather than on each if its source sets and it is now possible to do so when defining a Java library in the software model.

Example:

apply plugin: "jvm-component"

model {
  components {
    main(JvmLibrarySpec) {
      dependencies {
        library "core"
      }
    }

    core(JvmLibrarySpec) {
    }
  }
}

Dependencies declared this way will apply to all source sets for the component.

It is now possible to declare dependencies on external modules for a Java library in the software model:

repositories {
    jcenter()
}

model {
    components {
        main(JvmLibrarySpec) {
            dependencies {
                // external module dependency can start with either group or module
                group 'com.acme' module 'artifact' version '1.0'
                module 'artifact' group 'com.acme' version '1.0'

                // shorthand module notation also works, version number is optional
                module 'com.acme:artifact:1.42'
            }
        }
    }
}

Module dependencies declared this way will be resolved against the configured repositories as usual. External dependencies can be declared for a Java library, Java source set or Java library API specification.

The ModelMap creation and configuration DSL syntax now defines nested rules, each with its own inputs. For example, this means that an element of a ModelMap can now be configured using the configuration of a sibling as input:

model {
    components {
        mylib { ... }
        test {
            // Use `mylib` as input. When this code runs, it has been fully configured and will not change any further
            // Previously, this would have been treated as an input of the `components` rule, resulting in a dependency cycle 
            targetPlatform = $.components.mylib.targetPlatform
        }
    }
}

And because tasks is a ModelMap, this means that a task can be configured using another task as input using the same syntax:

model {
    tasks {
        jar { ... }
        dist(Zip) {
            // Use the `jar` task as input. It has been fully configured and will not change any further
            def jar = $.tasks.jar 
            from jar.output
            into someDir
        }
    }
}

This is also available for the various methods of ModelMap, such as all or withType:

model {
    components {
        all {
            // Adds a rule for each component
            ...
        }
        withType(JvmLibrarySpec) {
            // Adds a rule for each JvmLibrarySpec component
            ...
        }
    }
}

The properties of a @Managed type can now be configured using nested configure methods:

model {
    components {
        mylib {
            sources {
                // Adds a rule to configure `mylib.sources`
                ...
            }
            binaries {
                // Adds a rule to configure `mylib.sources`
                ...
            }
        }
    }
}

This is automatically added for any property whose type is @Managed, or a ModelMap<T> or ModelSet<T>. Note that for this release, these nested closures do not define a nested rule, and the closure is executed as soon as it is encountered in the containing closure. This will be improved in the next Gradle release.

See the model DSL user guide section for more details and examples.

The model DSL now supports automatic conversions between various scalar types, making it very easy to use one type for another. In particular, you can use a String wherever a scalar type is expected. For example:

enum FailType {
   FAIL_BUILD,
   WARNING
}

@Managed
interface CoverageConfiguration {
   double getMinClassCoverage()
   void setMinClassCoverage(double minCoverage)

   double getMinPackageCoverage()
   void setMinPackageCoverage(double minCoverage)

   FailType getFailType()
   void setFailType(FailType failType)

   File getReportTemplateDir()
   void setReportTemplateDir(File templateDir)
}

model {
    coverage {
       minClassCoverage = '0.7' // can use a `String` where a `double` was expected
       minPackageCoverage = 1L // can use a `long` where a `double` was expected
       failType = 'WARNING' // can use a `String` instead of an `Enum`
       templateReportDir = 'src/templates/coverage' // creates a `File` which path is relative to the current project directory
    }
}

This release allows source sets (subtypes of LanguageSourceSet) to be added to arbitrary locations in the managed model. A LanguageSourceSet can be attached to any @Managed type as a property, or used for the elements of a ModelSet or ModelMap, or as a top level model element.

The BinarySpec and ComponentSpec types can now be extended via @Managed subtypes, allowing for declaration of @Managed components and binaries without having to provide a default implementation. LibrarySpec and ApplicationSpec can also be extended in this manner.

Example:

@Managed
interface SampleLibrarySpec extends LibrarySpec {
    String getPublicData()
    void setPublicData(String publicData)
}

class RegisterComponentRules extends RuleSource {
    @ComponentType
    void register(ComponentTypeBuilder<SampleLibrarySpec> builder) {
    }
}
apply plugin: RegisterComponentRules

model {
    components {
        sampleLib(SampleLibrarySpec) {
            publicData = "public"
        }
    }
}

Now it is possible to attach a @Managed internal view to any BinarySpec or ComponentSpec type. This allows plugin authors to attach extra properties to already registered binary and component types like JarBinarySpec.

Example:

@Managed
interface MyJarBinarySpecInternal extends JarBinarySpec {
    String getInternal()
    void setInternal(String internal)
}

class CustomPlugin extends RuleSource {
    @BinaryType
    public void register(BinaryTypeBuilder<JarBinarySpec> builder) {
        builder.internalView(MyJarBinarySpecInternal)
    }

    @Mutate
    void mutateInternal(ModelMap<MyJarBinarySpecInternal> binaries) {
        // ...
    }
}

apply plugin: "jvm-component"

model {
    components {
        myComponent(JvmLibrarySpec) {
            binaries.withType(MyJarBinarySpecInternal) { binary ->
                binary.internal = "..."
            }
        }
    }
}

Note: @Managed internal views registered on unmanaged types (like JarBinarySpec) are not yet visible in the top-level binaries container, and thus it's impossible to do things like:

// This won't work:
model {
    binaries.withType(MyJarBinarySpecInternal) {
        // ...
    }
}

This feature is available for subtypes of BinarySpec and ComponentSpec.

It is now possible to declare a default implementation for a base component or a binary type, and extend it via further managed subtypes.

interface MyBaseBinarySpec extends BinarySpec {}

class MyBaseBinarySpecImpl extends BaseBinarySpec implements MyBaseBinarySpec {}

class BasePlugin extends RuleSource {
    @ComponentType
    public void registerMyBaseBinarySpec(ComponentTypeBuilder<MyBaseBinarySpec> builder) {
        builder.defaultImplementation(MyBaseBinarySpecImpl.class);
    }
}

@Managed
interface MyCustomBinarySpec extends BaseBinarySpec {
    // Add some further managed properties
}

class CustomPlugin extends RuleSource {
    @ComponentType
    public void registerMyCustomBinarySpec(ComponentTypeBuilder<MyCustomBinarySpec> builder) {
        // No default implementation required
    }
}

This functionality is available for unmanaged types extending ComponentSpec and BinarySpec.

The goal of the new internal views feature is for plugin authors to be able to draw a clear line between public and internal APIs of their plugins regarding model elements. By declaring some functionality in internal views (as opposed to exposing it on a public type), the plugin author can let users know that the given functionality is intended for the plugin's internal bookkeeping, and should not be considered part of the public API of the plugin.

Internal views must be interfaces, but they don't need to extend the public type they are registered for.

Example: A plugin could introduce a new binary type like this:

/**
 * Documented public type exposed by the plugin
 */
interface MyBinarySpec extends BinarySpec {
    // Functionality exposed to the public
}

// Undocumented internal type used by the plugin itself only
interface MyBinarySpecInternal extends MyBinarySpec {
    String getInternalData();
    void setInternalData(String internalData);
}

class MyBinarySpecImpl implements MyBinarySpecInternal {
    private String internalData;
    String getInternalData() { return internalData; }
    void setInternalData(String internalData) { this.internalData = internalData; }
}

class MyBinarySpecPlugin extends RuleSource {
    @BinaryType
    public void registerMyBinarySpec(BinaryTypeBuilder<MyBinarySpec> builder) {
        builder.defaultImplementation(MyBinarySpecImpl.class);
        builder.internalView(MyBinarySpecInternal.class);
    }
}

With this setup the plugin can expose MyBinarySpec to the user as the public API, while it can attach some additional information to each of those binaries internally.

Internal views registered for an unmanaged public type must be unmanaged themselves, and the default implementation of the public type must implement the internal view (as MyBinarySpecImpl implements MyBinarySpecInternal in the example above).

It is also possible to attach internal views to @Managed types as well:

@Managed
interface MyManagedBinarySpec extends MyBinarySpec {}

@Managed
interface MyManagedBinarySpecInternal extends MyManagedBinarySpec {}

class MyManagedBinarySpecPlugin extends RuleSource {
    @BinaryType
    public void registerMyManagedBinarySpec(BinaryTypeBuilder<MyManagedBinarySpec> builder) {
        builder.internalView(MyManagedBinarySpecInternal.class);
    }
}

Internal views registered for a @Managed public type must themselves be @Managed.

This functionality is available for types extending ComponentSpec and BinarySpec.

Binary names are now scoped to the component they belong to. This means multiple components can have binaries with a given name. For example, several library components might have a jar binary. This allows binaries to have names that reflect their relationship to the component, rather than their absolute location in the software model.