Per-Task Toolchain Documentation Incomplete?

Help/Discuss
1

This per-task toolchain configuration documentation appears to be missing a description of constraints on when/where those configurations can be placed in the build script.

I had this exact block in a 7.1 java-library build script on Windows:

tasks.withType(JavaCompile).configureEach {
    javaCompiler = javaToolchains.compilerFor {
        languageVersion = JavaLanguageVersion.of(8)
    }
}

…and when it ran I would get this error:

* What went wrong:
A problem occurred evaluating root project 'my-project'.
> The value for task ':compileJava' property 'javaCompiler' is final and cannot be changed any further.

I found that this was occurring because the toolchain configuration block above was placed in the build script below this code, which was collecting the paths of specific jars for use elsewhere in the build script (for test task configuration):

def paths = [:]
configurations.runtimeClasspath.files.each {
    if ( it.path.endsWith("<some-jar-file>") ) {
        paths['<jar-name>'] = it.path
    }
}

When the toolchain configuration block was relocated so it appeared before this code, the error no longer occurred. This indicates that there are some side-effects of some operations that can appear in a build script that will affect the ability for the toolchain configuration to work.

It seems like either these side-effects are bugs that shouldn’t be interfering with that configuration, or the documentation is missing some details on build script requirements for when/where these configurations can be placed.