Make version a lazily evaluated property (#71)

In this changeset, we allow configuring JxBrowser version with a [lazily
evaluated
value](https://docs.gradle.org/current/userguide/properties_providers.html)
by changing `version` field to be a lazy `Property`.

## Problem

The Gradle [documentation
states](https://docs.gradle.org/current/userguide/properties_providers.html):

> When implementing a custom task or plugin, it’s imperative that you
use these lazy properties.

We use regular `String` properties instead. That is OK when a version is
a string literal in `build.gradle.kts`. But it's not OK, when the value
is taken from elsewhere. For example, from the version catalog:

```
jxbrowser {
    // Calling `get()` this way is a bad practice, because the value may not be available yet. 
    version = libs.versions.jxbrowser.asProvider().get()
}
```

## Solution

We change the `version` field from `String` to `Property<String>`. We
don't change other fields because they're less likely to come from the
lazily evaluated sources. And we want to avoid breaking changes. More on
this in the next section.

## Backward compatibility

The plug-in stays backward compatible for Gradle 8.2 and newer. No
changes are required, because of
[`Property::assign`](https://github.com/gradle/gradle/blob/fcef0ec368956438f2c1272b64bad82c996ab236/platforms/core-configuration/kotlin-dsl/src/main/kotlin/org/gradle/kotlin/dsl/PropertyExtensions.kt#L41)
extension method.

Users of older Gradle versions, will need to replace `version = "8.2.2"`
with `version.set("8.2.2")`. Otherwise, the build will fail.

## Version bump

Since this change is breaking for some of the users, we bump the version
to `2.0.0`.

Author: vlad-lubenskyi

README.md

@@ -8,13 +8,16 @@ A Gradle plug-in that provides convenience methods for adding JxBrowser dependen
 import com.teamdev.jxbrowser.gradle.Repository
 
 plugins {
-    id("com.teamdev.jxbrowser") version "1.2.1"
+    id("com.teamdev.jxbrowser") version "2.0.0"
 }
 
 jxbrowser {
     // The JxBrowser version (required).
     // Obtain the latest release version number at https://teamdev.com/jxbrowser/.
     version = "8.2.2"
+    
+    // If you're using Gradle 8.1.1 or older, use the following syntax:
+    // version.set("8.2.2")
 
     // The location of JxBrowser repository to use (optional).
     // It's either North America or Europe.

build.gradle.kts

@@ -22,7 +22,7 @@ import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 object BuildSettings {
     const val GROUP = "com.teamdev.jxbrowser"
-    const val VERSION = "1.2.1"
+    const val VERSION = "2.0.0"
     const val JXBROWSER_VERSION = "8.2.2"
     val javaVersion = JavaVersion.VERSION_1_8
 }

src/main/kotlin/com/teamdev/jxbrowser/gradle/JxBrowserExtension.kt

@@ -29,7 +29,9 @@ import com.teamdev.jxbrowser.gradle.Environment.isX64Bit
 import com.teamdev.jxbrowser.gradle.Environment.jvmArch
 import com.teamdev.jxbrowser.gradle.Environment.osName
 import com.vdurmont.semver4j.Semver
+import org.gradle.api.InvalidUserDataException
 import org.gradle.api.Project
+import org.gradle.api.provider.Property
 import org.gradle.api.provider.Provider
 
 /**
@@ -40,12 +42,20 @@ import org.gradle.api.provider.Provider
  * and various JxBrowser dependencies based on your project's needs.
  */
 public open class JxBrowserExtension(private val project: Project) {
+    init {
+        project.afterEvaluate {
+            if (!version.isPresent) {
+                throw InvalidUserDataException("JxBrowser version is not specified.")
+            }
+        }
+    }
+
     /**
      * A version of the JxBrowser.
      *
      * This is a mandatory field.
      */
-    public var version: String = ""
+    public val version: Property<String> = project.objects.property(String::class.java)
 
     /**
      * The preferred location of the JxBrowser repository.
@@ -175,26 +185,29 @@ public open class JxBrowserExtension(private val project: Project) {
         return platformMap.entries.firstOrNull { it.key() }?.value
             ?: project.providers.provider {
                 val currentPlatform = "${osName()} ${jvmArch()}"
-                val errorMessage = "The current $currentPlatform platform is not supported by JxBrowser $version."
+                val errorMessage = "The current $currentPlatform platform is not supported by JxBrowser ${version.get()}"
                 throw IllegalStateException(errorMessage)
             }
     }
 
-    private fun artifact(shortName: String) =
-        project.providers.provider {
-            check(version.isNotBlank()) { "JxBrowser version is not specified." }
-            checkArtifactSupported(shortName)
+    private fun artifact(shortName: String): Provider<String> {
+        return version.map { versionValue ->
+            checkArtifactSupported(shortName, versionValue)
             if (shortName == "core") {
-                "$GROUP:jxbrowser:$version"
+                "$GROUP:jxbrowser:$versionValue"
             } else {
-                "$GROUP:jxbrowser-$shortName:$version"
+                "$GROUP:jxbrowser-$shortName:$versionValue"
             }
         }
+    }
 
     /**
      * Checks if the artifact with [shortName] exists in JxBrowser [version].
      */
-    private fun checkArtifactSupported(shortName: String) {
+    private fun checkArtifactSupported(
+        shortName: String,
+        version: String,
+    ) {
         val artifactNameToReleaseVersion =
             mapOf(
                 "compose" to "8.0.0",

src/main/kotlin/com/teamdev/jxbrowser/gradle/JxBrowserPlugin.kt

@@ -36,7 +36,7 @@ import org.gradle.api.Project
  *
  * jxbrowser {
  *     // Obtain the latest release version number at https://teamdev.com/jxbrowser/.
- *     version = "7.36"
+ *     version = "8.2.2"
  *
  *     // Use JxBrowser repository at specific location. It's North America by default.
  *     repository = Repository.NORTH_AMERICA

src/test/kotlin/com/teamdev/jxbrowser/gradle/JxBrowserPluginFunctionalTest.kt

@@ -22,6 +22,7 @@ package com.teamdev.jxbrowser.gradle
 
 import io.kotest.matchers.collections.shouldContainExactlyInAnyOrder
 import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
 import org.gradle.testkit.runner.BuildResult
 import org.gradle.testkit.runner.GradleRunner
 import org.gradle.testkit.runner.TaskOutcome.SUCCESS
@@ -217,14 +218,42 @@ internal class JxBrowserPluginFunctionalTest {
                 """.trimIndent(),
             )
 
+            val failure =
+                assertFails {
+                    GradleRunner.create()
+                        .withProjectDir(testProjectDir)
+                        .withPluginClasspath()
+                        .withArguments("build")
+                        .build()
+                }
+            failure.message shouldContain "is not supported by JxBrowser"
+        }
+    }
+
+    @Test
+    fun `require JxBrowser version`() {
+        buildFile.writeText(
+            """ 
+            plugins {
+                base
+                id("com.teamdev.jxbrowser")
+            }
+
+            jxbrowser {
+                includePreviewBuilds()
+            }
+            """.trimIndent(),
+        )
+
+        val failure =
             assertFails {
                 GradleRunner.create()
                     .withProjectDir(testProjectDir)
                     .withPluginClasspath()
-                    .withArguments("build")
+                    .withArguments("check")
                     .build()
             }
-        }
+        failure.message shouldContain "JxBrowser version is not specified"
     }
 
     private fun BuildResult.outcome(taskName: String) = this.task(taskName)!!.outcome

src/test/kotlin/com/teamdev/jxbrowser/gradle/JxBrowserPluginTest.kt

@@ -54,7 +54,7 @@ internal class JxBrowserPluginTest {
     @Test
     fun `resolve dependencies`() {
         with(extension) {
-            version = jxBrowserVersion
+            version.set(jxBrowserVersion)
             val group = "com.teamdev.jxbrowser"
 
             swt.get() shouldBe "$group:jxbrowser-swt:$jxBrowserVersion"
@@ -78,6 +78,7 @@ internal class JxBrowserPluginTest {
         mavenRepositoryUrls() shouldContain customRepository
 
         val eapRepository = "https://europe-maven.pkg.dev/jxbrowser/eaps"
+        extension.version.set("8.2.2")
         extension.includePreviewBuilds()
         project.evaluationDependsOn(":")
         mavenRepositoryUrls() shouldContain eapRepository