Use `@DslMarker` or other mechanism to restrict DSL scopes

[octylFractal]

Expected Behavior

Certain blocks should not be available in nested scopes, for example the top-level dependencies should not be available in Test Suites blocks to prevent confusion with its dependencies.

Current Behavior / Context

In Kotlin DSL, it is easy to do:

testing {
    suites {
        named("test") { // Should be named<JvmTestSuite>("test")
            dependencies {
                // Oops, this is the top-level one!
            }
        }
    }
}

This should be a warning or error.

Path to Implementation

Kotlin's @DslMarker seems promising, though we would need to be careful to not overly restrict scopes. It might be possible for us to ask the Kotlin team for more features in this vein to allow us to allow certain functions to be kept.

One issue with @DslMarker that is immediately obvious is that there is no way to access the top-level receiver without saving it in a variable explicitly (val topLevelThis = this before a block). It would be nice if we could define e.g. this@project / this@script / this@build implicitly.

Also, it appears we already have @GradleDsl for marking this, though it isn't widely used.

[aSemy]

This would really help in making the Gradle API more understandable.

It would be nice if we could define e.g. this@project / this@script / this@build implicitly.

Isn't this possible already? https://kotlinlang.org/docs/type-safe-builders.html#scope-control-dslmarker

Note that it's still possible to call the members of the outer receiver, but to do that you have to specify this receiver explicitly:

html {
    head {
        this@html.head { } // possible
    }
    // ...
}

[octylFractal]

Isn't this possible already?

No, that accesses the receiver of the html {} lambda, not the receiver that has the html method.

[aSemy]

Sorry, maybe I'm missing something :) The html method doesn't have a receiver, it's a top level function

fun html(init: HTML.() -> Unit): HTML {
    val html = HTML()
    html.init()
    return html
}

[octylFractal]

Sure, but then I'm not sure how this is supposed to show how to access the KotlinBuildScript (Gradle type) that is the implicit receiver of the buildscript as a whole. For example, how could you get the following to compile:

tasks { // Pretend TaskContainer is @GradleDsl
  named("foo") {
    // This won't compile because `sourceSets` is an extension on the top-level receiver (via Project)
    dependsOn(sourceSets.main.get().classesTaskName)
  }
}

// So we need to access the top-level receiver, what goes in place of the '□'?
tasks {
  named("foo") {
    dependsOn(this@□.sourceSets.main.get().classesTaskName)
  }
}

// Edit: Explicit solution I wrote in the original issue is as follows:
val topLevelThis = this
tasks {
  named("foo") {
    dependsOn(topLevelThis.sourceSets.main.get().classesTaskName)
  }
}

[aSemy]

Ah I see, thanks for explaining. There needs to be a way of accessing the an implicit receiver of the Kotlin scripting context.

Here's another example - if copied into a build.gradle.kts it shows the errors.

// pretend this is Project.dependencies() {}
fun Project.dependencies2(config: DependencyHandlerScope.() -> Unit) {}

// pretend this is the `jvm-test-suite` plugin extension
interface TestingExtension2 {
  val suites2: NamedDomainObjectContainer<TestSuite2>
}

fun Project.testing2(configure: TestingExtension2.() -> Unit) {}

@GradleDsl
interface TestSuite2 // stand in for TestSuite, annotated with the DslMarker

interface JvmTestSuite2 : TestSuite2 { // @GradleDsl is inherited
  // conflicts with Project.dependencies2()
  fun dependencies2(config: DependencyHandlerScope.() -> Unit)
}

testing2 {
  suites2 {
    named("test") { // Should be named<JvmTestSuite>("test")
      dependencies2 {} // expect: error, actual: error can't be called in this context by implicit receiver ✅ 
    }
    named<JvmTestSuite2>("test") {
      dependencies2 { // expect: no error, actual: no error ✅
        project.name // expect: can access root context, actual: can't access project ❌
      } 
    }
  }
}

[Vampire]

There needs to be a way of accessing the an implicit receiver of the Kotlin scripting context.

You mean like this@Build_gradle?

Unfortunately, it does not really work.
For project.name you can use this@Build_gradle.project.name to make the IntelliJ Kotlin plugin happy, but build will still fail which probably is a Kotlin plugin bug.
And this@Build_gradle.dependencies2 {} or this@Build_gradle.project.dependencies2 {} does not even work in the IntelliJ Kotlin plugin.

[Vampire]

But actually, I also do not get the topLevelThis example to compile here

[aSemy]

Related issues on YouTrack

• https://youtrack.jetbrains.com/issue/KT-31831 - Kotlin script implicit receiver access
• https://youtrack.jetbrains.com/issue/KT-31021 - Add optional explicit declarations for implicit receivers and dependencies in scripts

[aSemy]

Sure, but then I'm not sure how this is supposed to show how to access the KotlinBuildScript (Gradle type) that is the implicit receiver of the buildscript as a whole. For example, how could you get the following to compile:

tasks { // Pretend TaskContainer is @GradleDsl
  named("foo") {
    // This won't compile because `sourceSets` is an extension on the top-level receiver (via Project)
    dependsOn(sourceSets.main.get().classesTaskName)
  }
}

// So we need to access the top-level receiver, what goes in place of the '□'?
tasks {
  named("foo") {
    dependsOn(this@□.sourceSets.main.get().classesTaskName)
  }
}

// Edit: Explicit solution I wrote in the original issue is as follows:
val topLevelThis = this
tasks {
  named("foo") {
    dependsOn(topLevelThis.sourceSets.main.get().classesTaskName)
  }
}

Until https://youtrack.jetbrains.com/issue/KT-31831 is complete I think the only way to access the script receiver is to use the with scope function (or maybe some other scope function).

with(project) {
  tasks { // Pretend TaskContainer is @GradleDsl
    named("foo") {
      // This won't compile because `sourceSets` is an extension on the top-level receiver (via Project)
      // dependsOn(sourceSets.main.get().classesTaskName)

      // This should use the 'with' receiver, and so 'project' is accessible
      dependsOn(project.sourceSets.main.get().classesTaskName)
    }
  }
}

[Goooler]

Related to #37657.