API and Implementation Separation

Java/JVM Gradle Core Plugins

Separating runtime/compile time dependencies

Dependency Constraints and Platforms

Share dependency versions with platforms

Use dependency constraints and rich versions

dependencies {
  constraints {
    api("com.google.guava:guava:24.1.1-jre!!")
    api("com.google.inject:guice") {
      version {
        strictly("[4.0, 5.0[")
        // require("[4.0, 5.0[")
        prefer("4.2.0")
        reject("4.2.1")
        // rejectAll()
      }
      because("Only version 4 of Guice has all DI features we need.")
    }
  }
}

Use Platform in all Projects

dependencies {
  api(platform(project(":my-platform")))
}

dependencies {
  api(platform("com.fasterxml.jackson:jackson-bom:2.9.8"))
}

Publishing with Gradle Module Metadata

Today’s Demo Project

Gradle Module Metadata

Javadoc and sources packaging and publishing

java {
    withJavadocJar()
    withSourcesJar()
}

Gradle Module Metadata

data/0.1/
├── data-0.1.pom
      <!-- do_not_remove: published-with-gradle-metadata -->
├── data-0.1.module
      variants [
        { "name": "apiElements",     "files": [...], ... }
        { "name": "runtimeElements", "files": [...], ... }
        { "name": "javadocElements", "files": [...], ... }
        { "name": "sourcesElements", "files": [...], ... }
      ]
├── data-0.1.jar
├── data-0.1-javadoc.jar
├── data-0.1-sources.jar

Gradle Module Metadata

platform/0.1/
├── platform-0.1.pom
      <!-- do_not_remove: published-with-gradle-metadata -->
├── platform-0.1.module
      variants [
      {
        "dependencyConstraints": [
          { "group": "com.google.guava", "module": "guava",
            "version": { "strictly": "24.1.1-jre" }
          },
          { "group": "com.google.inject", "module": "guice",
            "version": { "requires": "4.2.2" }
          },
          ...

Better project structures and reuse with test fixtures and feature variants

Write test fixtures to share code for testing

Use test fixtures of other project/component

dependencies {
  // Use test fixtures of local project
  testImplementation(testFixtures(project(":data")))

  // Use test fixture of Guava (if it would publish test fixtures)
  testImplementation(testFixtures("com.google.guava:guava")))
}

Split modules by using feature variants

val loud: SourceSet by sourceSets.creating

java {
  registerFeature("loud") {
    // code isolated: separate implementation and dependencies
    usingSourceSet(loud)

    // code not isolated: use for "optional dependencies"
    usingSourceSet(sourceSets.main)
  }
}

dependencies {
  "loudApi"(project(":data"))
  "loudImplementation"("org.apache.commons:commons-lang3")
}

Use feature variants of other project/component

dependencies {
  implementation(project(":hello-java-service")) {
    capabilities {
      // Use feature variant by requesting the corresponding capability
      requireCapability("org.gradle.hello6:hello-java-service-loud")
    }
  }

  implementation("com.google.inject:guice") {
    capabilities {
      // Select no_aop feature of Guice (not published, added by rule)
      requireCapability("com.google.inject:guice-no_aop")
    }
  }
}

Enrich existing Metadata with Component Metadata Rules

Component Metadata Rules

Guava Component Metadata Rule

subprojects {
  dependencies {
    components {
      withModule<GuavaRule>("com.google.guava:guava")
    }
  }
}

Java, Groovy, and Scala toolchain improvements

Combine Core JVM Plugins

Support for JDK 13

java {
    sourceCompatibility = JavaVersion.VERSION_13
    targetCompatibility = JavaVersion.VERSION_13
}

subprojects {
    plugins.withType<JavaPlugin> {
        extensions.configure<JavaPluginExtension> {
            sourceCompatibility = JavaVersion.VERSION_13
            targetCompatibility = JavaVersion.VERSION_13
        }
    }
}

Support for JDK 13

// for compilation
tasks.withType<JavaCompile> {
    options.compilerArgs.add("--enable-preview")
}

// to run tests
tasks.withType<Test>  {
    jvmArgs = listOf("--enable-preview")
}

// to run an application
application {
    applicationDefaultJvmArgs = listOf("--enable-preview")
}

// to generate Javadoc
tasks.withType<Javadoc>  {
    val javadocOptions = options as CoreJavadocOptions
    javadocOptions.addStringOption("source", "13")
    javadocOptions.addBooleanOption("-enable-preview", true)
}

Incremental Groovy compilation

Scala Zinc compiler update

New features for plugin authors

Generate plugin projects with Gradle init task

$ gradle init

Generate plugin projects with Gradle init task

Select type of project to generate:
  1: basic
  2: application
  3: library
  4: Gradle plugin
Enter selection (default: basic) [1..4]

Generate plugin projects with Gradle init task

Select implementation language:
  1: Groovy
  2: Java
  3: Kotlin
Enter selection (default: Java) [1..3]

Generate plugin projects with Gradle init task

Select build script DSL:
  1: Groovy
  2: Kotlin
Enter selection (default: Groovy) [1..2]

├── build.gradle.kts
├── gradle
│   └── wrapper
│       ├── gradle-wrapper.jar
│       └── gradle-wrapper.properties
├── gradlew
├── gradlew.bat
├── settings.gradle.kts
└── src
    ├── functionalTest
    │   └── java
    │       └── my
    │           └── MyPluginFunctionalTest.java
    ├── main
    │   ├── java
    │   │   └── my
    │   │       └── MyPlugin.java
    │   └── resources
    └── test
        ├── java
        │   └── my
        │       └── MyPluginTest.java
        └── resources

Managed properties improvements

abstract class ATask extends DefaultTask {
    abstract Property<String> getInput();

    @TaskAction
    void doAction() {
        System.out.println(input.get());
    }
}

tasks.create<ATask>("a") {
    input.set("something")
    // input.set(provider { ... })
}

Worker API enhancements

private final FileSystemOperations fileSystemOperations

@Inject
public ReverseFile(FileSystemOperations fileSystemOperations) {
    this.fileSystemOperations = fileSystemOperations
}

@Override
public void execute() {
    fileSystemOperations.copy {
        from parameters.fileToReverse
        into parameters.destinationDir
        filter { String line -> line.reverse() }
    }
}

Variant-aware plugins

Variant-aware plugins

Bonus: Where are the variants?

Variants of Components

Variants of Components

Test fixture variant selection

Feature variant selection

Published variants with artifacts

"variants": [
  { "name": "apiElements" ... },
  { "name": "runtimeElements" ... },
  { "name": "javadocElements",
    "attributes": {
      "org.gradle.category": "documentation",
      "org.gradle.docstype": "javadoc",
    },
    "files": [
      { "url": "junit-jupiter-api-5.6.0-javadoc.jar" ... }
    ]},
  { "name": "sourcesElements" ... },

val javadoc by configurations.creating {
    attributes.attribute(CATEGORY_ATTRIBUTE, objects.named(DOCUMENTATION))
    attributes.attribute(DOCS_TYPE_ATTRIBUTE, objects.named(JAVADOC))
}
dependencies { javadoc("org.junit.jupiter:junit-jupiter-api:5.6.0") }
tasks.create("doSomethingWithJavadocs") { doLast { javadoc.files } }

Published platform dependency

"variants": [
  {
    "name": "apiElements",
    "attributes": { "org.gradle.category": "library", ... },
    "dependencies": [
      {
        "group": "org.junit",
        "module": "junit-bom",
        "version": { "requires": "5.6.0" },
        "attributes": { "org.gradle.category": "platform" },
      }
    ]
  },

Published platform (BOM)

"variants": [
  {
    "name": "apiElements",
    "attributes": { "org.gradle.category": "platform", ... },
    "dependencyConstraints": [
      {
        "group": "org.junit.jupiter",
        "module": "junit-jupiter-api",
        "version": { "requires": "5.6.0" }
      },
      {
        "group": "org.junit.jupiter",
        "module": "junit-jupiter-engine",
        "version": { "requires": "5.6.0" }
      }
      ...

Published variants and platform dependencies

Guava Component Metadata Rule

val variantVersion = ctx.details.id.version
val version = variantVersion.substring(0, variantVersion.indexOf("-"))

val artifactName = variantVersion.substring(variantVersion.indexOf("-") + 1)
val otherArtifactName = if (artifactName == "android") "jre" else "android"
val jdkVersion = if (artifactName == "android") 6 else 8
val otherJdkVersion = if (artifactName == "android") 8 else 6

ctx.details.allVariants {
  attributes {
    if (!contains(TARGET_JVM_VERSION_ATTRIBUTE)) {
      attribute(TARGET_JVM_VERSION_ATTRIBUTE, jdkVersion)
    }
  }
  withCapabilities {
    if (!capabilities.any { it.name == "google-collections" }) {
      addCapability("com.google.collections",
          "google-collections", variantVersion)
    }
  }
}

listOf("compile", "runtime").forEach { base ->
  ctx.details.addVariant("jdk${otherJdkVersion}${base.capitalize()}", base) {
    attributes {
      attribute(TARGET_JVM_VERSION_ATTRIBUTE, otherJdkVersion)
    }
    withFiles {
      removeAllFiles()
      addFile("guava-$version-$otherArtifactName.jar",
          "../$version-$otherArtifactName/guava-$version-$otherArtifactName.jar")
    }
  }
}

Guava with added variants

Bonus: Strict version details

Strict version resolution

> Cannot find version of 'guava' that satisfies version constraints:
  Dependency path 'app' --> 'guice:4.2.2' --> 'guava:25.1-android'
  Dependency path 'app' --> 'hello-java-service' --> 'guava:{strictly 24.1.1-android}'

\--- guice:4.2.2
     \--- guava:25.1-android -> 24.1.1-android