Gradle 8.1

What's new in this version:

New features, performance and usability improvements:
Configuration cache improvements:
- The configuration cache improves build time by caching the result of the configuration phase and reusing it for subsequent builds. This feature, now promoted to stable status, can significantly improve build performance.

Securing the configuration cache:
- To mitigate the risk of accidental exposure of sensitive data, Gradle now encrypts the configuration cache. Gradle will transparently generate a machine-specific secret key as required, cache it under the Gradle user home directory and use it to encrypt the data in the project specific caches.
- By default, the Gradle configuration cache is located under .gradle/configuration-cache in your project directory.
- Every cache entry contains information about the set of tasks to run, along with their configuration and dependency information.
- However, based on a task's implementation or the way it is configured by a plugin or build script, its configuration might contain sensitive information. It is crucial to keep this information secure.

To enhance security further, make sure to:
- prevent the .gradle/configuration-cache folder from being committed to source control or exposed in CI environments;
- secure the Gradle user home directory.

Dependency verification support:
- The configuration cache now fully supports dependency verification. Changes to associated files (keyring files or verification-metadata.xml) are correctly detected and invalidate the configuration cache if necessary.

File system-based repositories support:
- The configuration cache now fully supports file-system-based Ivy and Maven repositories. In particular, this release adds support for dynamic dependencies. Suppose a dynamic dependency is declared in the build script. In that case, changes to the dependency in the file-system-based repository now invalidate the configuration cache to pick up an updated version.

Expanded compatibility with core plugins:
- The Ivy publishing plugin and the Signing plugin are now compatible with the configuration cache.
- The current status of the configuration cache support for all core Gradle plugins can be found in the configuration cache documentation.

Support of Java lambdas:

Gradle can now restore user-provided lambdas from the configuration cache. Using anonymous classes to implement Single Abstract Method (SAM) interfaces is no longer necessary. This also applies to Kotlin code: there is no more need to configure the Kotlin compiler to generate classes instead of lambdas during SAM conversion.
- This release also improves error reporting for lambdas that capture unsupported types, like Configuration.

Better error reporting for Groovy closures:
- This release improves error reporting of unsupported method calls in Groovy closures. For example, a doFirst/doLast action uses a method or property of the Project, which is unsupported with the configuration cache

Previously, a confusing message of Could not get unknown property 'buildDir' for task ':echo' was displayed, but now the error is more accurate

Configuration inputs detection improvements:

The configuration cache needs to detect when the build logic accesses the "outside world" at configuration time (for example, reading files or environment variables) to invalidate the cache if accessed information changes. Every recent Gradle release added new detection capabilities, and this release is no exception. Gradle now detects:
- FileCollections queried at configuration time.
- Methods of java.io.File class used to check file existence and read directory contents.
- Methods of java.nio.files.File class used to open files for reading and to check file existence.
- Kotlin and Groovy helper methods used to read file contents.

Kotlin DSL improvements:
- Gradle's Kotlin DSL provides an alternative syntax to the Groovy DSL with an enhanced editing experience in supported IDEs — superior content assistance, refactoring documentation, and more.

Experimental simple property assignment in Kotlin DSL scripts:
- As an opt-in feature, it is now possible to use the = operator to assign values to Property types in Kotlin scripts as an alternative to the set() method. This reduces the verbosity of Kotlin DSL when lazy property types are used to configure tasks and extensions. It also makes Kotlin DSL behavior consistent with Groovy DSL behavior, where using = to assign lazy properties has always been available.
- Lazy property assignment for Kotlin scripts is an experimental opt-in feature. It is enabled by adding systemProp.org.gradle.unsafe.kotlin.assignment=true to the gradle.properties file.

Access to version catalog for plugins in the plugins {} block:
- Version catalog accessors for plugin aliases in the plugins {} block aren't shown as errors in IntelliJ IDEA and Android Studio Kotlin script editor anymore. If you were using a workaround for this before, see the corresponding section in the upgrading guide.

Useful deprecation warnings and errors from Kotlin script compilation:
- Gradle Kotlin DSL scripts are compiled by Gradle during the configuration phase of your build.
- Deprecation warnings found by the Kotlin compiler are now reported on the console when compiling build scripts. This makes it easier to spot usages of deprecated members in your build scripts.
- Moreover, Kotlin DSL script compilation errors are now always reported in the order they appear in the file. This makes it easier to figure out the first root cause of a script compilation failure.

Easier access to extensions on the Gradle object:
- The Gradle type now declares that it is ExtensionAware. This allows access to extensions without casting to ExtensionAware from Kotlin. This can be useful in initialization scripts.

Easier configuration of Test.forkEvery from Kotlin:
- It is now easier to configure the forkEvery property of Test tasks from Kotlin to set the maximum number of test classes to execute in a forked test process. Instead of requiring to use its setForkEvery(<number>) setter you can now simply assign it a value

Improvements to development of Gradle plugins in Kotlin:
- The kotlin-dsl plugin provides a convenient way to develop Kotlin-based plugins that contribute build logic.
- In addition to plugins written as standalone projects, Gradle also allows you to provide build logic written in Kotlin as precompiled script plugins. You write these as *.gradle.kts files in src/main/kotlin directory.

Easier customization of Kotlin options:
- Customization of Kotlin options in your build logic is now easier and no longer requires afterEvaluate {}.
- The standalone script compilation for build scripts, init scripts, and applied scripts are configured to skip the pre-release check to allow referencing Kotlin code compiled with more recent Kotlin language versions on a best-effort basis.

The kotlin-dsl plugin is now published to the Gradle Plugin Portal with proper licensing information in its metadata. The plugin is published under the same license as the Gradle Build Tool: the Apache License Version 2.0.
- This makes using the kotlin-dsl plugin easier in an enterprise setting where published licensing information is required.

Respect --offline when building precompiled script plugins:
- Building precompiled script plugins now respects the --offline command line execution option.
- This makes using Gradle plugins that react to --offline from precompiled script plugins easier.

Less verbose compilation with precompiled script plugins:
- Building precompiled script plugins includes applying plugins to synthetic projects. This can produce some console output.
- The output is now captured and only shown in case of failures. By default, this is now less verbose and does not clutter the console output.

Better validation of name and path of precompiled script plugins:
- Precompiled script plugins must respect the documented naming conventions. Gradle will now fail with an explicit and helpful error message when naming conventions are not followed.
- Moreover, .gradle.kts files present in resources src/main/resources are not considered as precompiled script plugins anymore. This makes it easier to ship Gradle Kotlin DSL scripts in plugins resources.

JVM:
Support for building projects with Java 20:
- Gradle now supports using Java 20 for compiling, testing, and starting other Java programs. This can be accomplished by configuring your build or task to use a Java 20 toolchain.
- You cannot currently run Gradle on Java 20 because Kotlin lacks support for JDK 20. However, you can expect support for running Gradle with Java 20 in a future version.

Faster Codenarc analysis with parallel execution by default:
- The Codenarc plugin performs quality checks on your project’s Groovy source files using a static code analyzer. It now uses the Gradle worker API and JVM toolchains.
- CodeNarc now performs analysis via an external worker process which allows it to run in parallel within a single project.
- In Groovy projects, this tool will use the same version of Java the project requires. In other types of projects, it will use the same version of Java used by the Gradle daemon.

Other Improvements:
Gradle Wrapper introduces labels for selecting the version:
- The --gradle-version parameter for the wrapper task now supports using predefined labels to select a version.

The recognized labels are:
- latest selects the latest stable version
- release-candidate selects the latest release candidate version
- nightly selects the latest unstable nightly version
- release-nightly selects the latest unstable nightly version for the next release
- More details can be found in the Gradle Wrapper section.

Build Init plugin incubating flag enables more incubating features:
- When generating a new project with the init task with the --incubating option, parallel project execution and task output caching will be enabled for the generated project by creating a gradle.properties file and setting the appropriate flags in it.

Better memory management:
- To better manage memory usage, Gradle proactively stops unused worker processes before starting new ones.
- Gradle first checks if the available physical memory can accommodate the maximum heap requirements of a new worker process. If not, it searches for unused worker processes that can be stopped to free up enough physical memory for the new process.
- Previously, Gradle sought to acquire enough memory to satisfy the minimum heap requirements of the new process. However, in cases where the minimum heap and maximum heap of the worker process are very different, the memory freed up before the process starts may not be close to sufficient for the eventual size of the process.
- Gradle now attempts to acquire enough memory to satisfy the new process's maximum heap requirements.
- This causes the physical memory management to be more aggressive when starting up new processes, and in many cases, will result in better overall memory usage.

Easier consumption of Shared Build Services:
- There is a new @ServiceReference annotation that makes it easier to consume shared build services.
- By annotating a property with @ServiceReference, you no longer need to remember to explicitly declare that your task uses a shared build service via Task#usesService().
- If you also provide the name of the service in the annotation, you no longer need to obtain and assign a build service reference to the property explicitly; if a service registration with the given name exists, the corresponding reference is automatically assigned to the property.
- More details in the Shared Build Services documentation on using build services.

New Dataflow Actions replace buildFinished listeners:
- Previously, Gradle had only Gradle.buildFinished listeners to handle the result of the build. For many reasons, this API doesn't work well with the configuration cache, but there were no proper replacements. With the new Dataflow Actions you can now schedule pieces of work to process the result of the build in a way that is configuration-cache compatible. For example, you can add code to play a sound when the build completes successfully
- Unlike callbacks, actions provide the necessary level of isolation to ensure safe configuration caching.
- In this release, dataflow actions only provide a replacement for the deprecated Gradle.buildFinished callback, but more options to add work outside the task graph are planned.

Gradle user home caches are ignored by backup tools that honor CACHEDIR.TAG:
- Caches in the Gradle user home can become very large and typically do not contain files that need to be searched or backed up. The CACHEDIR.TAG specification proposes a way for archive and backup tools to automatically skip these directories, which makes it unnecessary to explicitly exclude them. Gradle now marks directories that should be ignored with a CACHEDIR.TAG file.

IDE Integration:
- The following improvements are for IDE integrators. They will be available for end-users in future IDE releases once they are used by IDE vendors.
- Builds launched via the IDE use the same log level as the command-line
- Previously, when executing a build via the IDE, the log level settings provided in the project's gradle.properties file were ignored. Some IDE vendors worked around this shortcoming by setting the log level in other ways to meet user expectations.
- The Tooling API now honors the org.gradle.logging.loglevel setting in the project's gradle.properties and applies it as expected to builds started from the IDE.

Promoted features:
- Promoted features are features that were incubating in previous versions of Gradle but are now supported and subject to backwards compatibility.
- See the user manual section on the “Feature Lifecycle” for more information.
- The following are the features that have been promoted in this Gradle release.

Configuration cache:
- The configuration cache feature is now officially out of incubation and is ready for general use. It is important to note, however, that utilizing this feature may require modifications to build logic and applied plugins to ensure full support.
- The implementation of the configuration cache is not yet complete. However, you can expect the configuration cache to evolve with new features and enhancements in upcoming Gradle versions, offering support for a broader range of use cases. To explore the features currently under consideration for implementation, please refer to the documentation.
- Enabling the configuration cache can yield a significant boost in build performance, as it caches the result of the configuration phase and reuses it for subsequent builds. This means that subsequent builds no longer have to re-execute the configuration phase, resulting in faster and more efficient builds.
- Configuration cache was introduced as an experimental feature back in Gradle 6.6.
- To learn how to benefit from this feature, refer to the Configuration Cache documentation.

Promoted features in the Provider API:
The ValueSource API is no longer incubating. The following classes and methods are now considered stable:
- ProviderFactory.of(Class, Action)
- ValueSource
- ValueSourceParameters
- ValueSourceParameters.None
- ValueSourceSpec

Fixed:
- 133 issues have been fixed in Gradle 8.1
- Artifact transforms should be allowed to run external processes
- Upgrading to gradle 8.0.2 causes deadlock
- Narrowing of return type in internal DepedencyResolutionServices breaks IDE tests
- Gradle 8 reports incorrect Configuration flags despite being configured correctly
- The `useJUnitPlatform` setting in `KotlinDSL` does not work correctly since Gradle 8.0
- Gradle throws/catches a lot of exceptions in AttributeMatchingVariantSelector
- `--scan` is ignored if configuration cache is reused
- Exception thrown from ValueSource should be a configuration cache problem
- JUnit 4.13 jar from gradle distribution should not leak into test runtime classpath
- precompiled script plugin "is not supposed to be used along with regular Kotlin sources" in Gradle 8.1
- The `kotlin-dsl` plugin using `afterEvaluate {}` to configure `KotlinCompile` tasks prevents further configuring them
- Exclude rule merging: missing optimization
- Reduce `OutputEventRenderer.onOutput()` locking by refine lock granularity
- Configuration cache failure when tasks are excluded by path
- Deprecate Test task default classpath and testClassesDirs
- Anchor around example captions in the docs includes formatting tags verbatim
- Remove testng from Maven migration integration test
- buildSrc precompiled script plugin named `init.gradle.kts` causes obscure error: Failed to apply plugin class, Char sequence is empty
- Gradle generates broken links in logs
- gradle :help produces wrong output on warm configuration cache
- Make help tasks plugin work with configuration cache/load-after-store
- Make `dependencyInsight` work with CC/load-after-store
- Make :dependentComponents work with Configuration Cache
- Refactor the configuration cache instrumentation/interception machinery
- Dependency verification documentation snippets should reference XSD
- Potentially bad assertion in ClasspathUtil
- Java toolchain auto-detection on linux should look in /usr/local/java
- Building Java Modules with Blackbox Tests Sample new sample returns 404
- Since Gradle 7.6 my integration tests fail - but report "BUILD SUCCESSFUL"
- --offline is not respected for "synthetic root projects"
- Fix Toolchain related test failures on M1 Macs
- Consider supporting assignment overload for ConfigurableFileCollection
- Reintroduce worker api for CodeNarc
- Deprecate org.gradle.cache.cleanup property
- Dependency graph resolution: Equivalent excludes can cause un-necessary graph mutations
- Add documentation for Kotlin DSL assignment overloads
- Dogfood Kotlin DSL assignment overload
- Configure implicit receiver for `KotlinBuildScript`, `KotlinInitScript` and `KotlinSettingsScript`
- Intermittent: "You must specify a base url or at least one artifact pattern for an Ivy repository" even when a base url is specified
- Deprecate running Gradle workers on Java runtimes below 8
- Support compiling and testing with Java 20
- Document and promote use of ServiceReferences
- When configuration cache is enabled report usages of `Gradle.useLogger()`
- Investigate project.layout.buildDirectory property resolution errors on a warm cache
- Signing plugin does not sign Gradle module metadata artifact for Ivy publication
- Should avoid publishing an artifact if the task that created it was skipped
- Use testSourceSets.add(sourceSets.functionalTest) instead of testSourceSets(sourceSets.functionalTest)
- Enable agent-based instrumentation by default
- Regression: Running codenarc against Groovy4 projects is broken
- VersionConstraint.branch and ModuleDependency.endorsing are not copied when a dependency is copied.
- Update documentation for configuration cache improvements in Gradle 8.1
- Stricter validation in BuildServicesRegistry.registerIfAbsent fails in cases it worked before
- Remove/replace retired lgtm
- The `Gradle` type does not expose that it is `ExtensionAware` making accessing extensions and extra properties difficult in the Kotlin DSL
- Add nagging for using `JvmVendorSpec.IBM_SEMERU`
- Missing 'archiveName' attribute in eclipse wtp
- `ValidatePlugins` task fails if configured Java Toolchain > Java running the build
- Version catalogs: library names cannot end with `-class`
- Allow configuration of Eclipse build directory
- change title of upgrade doc for "7.x to latest" to "7.x to 8.0"
- Sporadic NPEs when compiling Java code
- Shared Build Services consumed using @ServiceReference are instantiated even if not used
- DefaultWorkerProcessBuilder asking for too little memory
- Inconsistency between javadocElements and javadoc variants
- Support instrumenting signed build logic JARs
- Gradle complains about invalid tool chain - picking up the source package location - it should just ignore them
- Nag for deprecation of StartParameter.buildFile/settingsFile
- Nag for deprecation of GradleBuild.buildFile
- Version catalog accessors for plugin aliases shown as errors in IDE kotlin script editor
- Fix dependency reporting tasks to be compatible with configuration caching
- Java projects generated with `gradle init` should use toolchains
- Allow directory listing to be an input to config cache.
- Add API to configure SourceSetOutput classesDirs
- Lock Configuration Usage at Creation
- Configuration cache should report a problem when a task extension is accessed at execution time
- publishToMavenLocal does not generate checksums
- Disallow BuildServices to be used as inputs to ValueSources obtained at configuration time
- Kotlin-dsl plugin modifies kotlinOptions.freeCompilerArgs in task action
- Log deprecation for applying Kotlin precompiled script plugins published with Gradle < 6.0
- Load tasks from the configuration cache in the same build they are stored
- includeGroupByRegex with exclusiveContent can be easily misconfigured leading to poor security
- Add deprecation logging to org.gradle.util.ConfigureUtil.configureByMap(props,delegate)
- Add deprecation logging to org.gradle.util.VersionNumber
- Add deprecation logging to org.gradle.util.GUtil.toCamelCase(string)
- Add deprecation logging to org.gradle.util.WrapUtil.toDomainObjectSet()
- gradlew init should set parallel and caching to true
- Configuration cache should report Task.getProject access inside Task.onlyIf, TaskOutputs.cacheIf, and TasksOutputs.upToDateWhen predicates
- Validate unknown implementation snapshots earlier
- application.defaultJvmArgs aren't applied when running from the configuration cache
- [KTS] Pre-release classes were found in dependencies. Remove them from the classpath, recompile with a release compiler or use '-Xskip-prerelease-check' to suppress errors
- Share more information (licensing, repo url) about the Kotlin DSL Plugin both on the Plugin Page and in the published Maven POM
- Support SARIF format in Checkstyle plugin
- In tooling API FileDownloadResult is successful for HTTP 404
- "Error while evaluating property 'javaVersion' of task ':compileJava' > No value present" when using relative javac path
- Provider gets evaluated twice with configuration cache enabled
- Avoid degraded performance for missing task dependency detection
- Laziness issue between historical metadata and GMM metadata for publishing
- Provide explicit path on parse error from toml Version Catalog file
- Mark global cache directories
- Build finished event now deprecated
- Configuration cache should report problems when dehydrating `Closure`s
- Gradle doesn't recognize disabled parameterized junit5 tests
- Promote configuration caching as a stable feature
- `ISE: GradleProperties has not been loaded yet` for included build when restoring from the configuration cache
- Make dependency verification compatible with configuration cache
- Improve naming in DirectorySnapshotter for filtered snapshots
- Build launched via TAPI ignores logger level settings of target build
- Configuration cache doesn't load system properties from included build `gradle.properties` files
- Gradle configuration cache failure when using Gradle Enterprise
- Adding a formerly-missing `build.gradle` to a multi-project build with configuration-cache doesn't get picked up
- Path sensitivity `NONE` in incremental task causes same file to be added then removed
- Build fails when kotlin-dsl plugin is used and src/main/resources/init.gradle.kts file exists
- Introduce a mechanism to obtain the build result when using configuration caching
- Make Gradle's memory management work appropriately in memory constrained docker containers
- Test.forkEvery property awkward to use from Kotlin because of getter/setter nullability mismatch
- Automatically register a build service user when it is wired to a managed property
- Simplify consumption of Shared Build Services
- Builds fail if root project is in root of mount point, with further implications
- Promote incubating `org.gradle.api.provider.ValueSource` and family
- Enable the "Gradle User Manual" page show the vertical menu located in the left for a mobile device
- Configuration cache should support dynamic dependencies with ivy file system repositories
- Restore default excludes from the configuration cache
- Configuration cache should support file-system based repositories
- Possibility to automatically use "latest" Gradle version for wrapper task
- Make `project-report` plugin support the configuration cache
- Make `signing` plugin support the configuration cache
- Make `ivy-publish` plugin support the configuration cache
- Introduce RegularFileProperty to represent output of WriteProperties task
- Misleading javadoc on org.gradle.api.java.archives.Manifest.from() methods
- Gradle should warn against using COD in combination with Kotlin DSL
- Spurious console output when generating accessors for precompiled Kotlin scripts
- Gradle wrapper can't recover from corrupted download
- JUnit 5 Dynamic tests not showing with their displayName