Added a test project with legacy kotlin-gradle-plugin application.

And a README note.

#384

README.md

@@ -107,6 +107,10 @@ operations. They can be also atomically modified via `+=` and `-=` operators.
 
 Gradle configuration is supported for all platforms, minimal version is Gradle 6.8.
 
+**PLEASE NOTE!**
+
+Application of the atomicfu-gradle-plugin now requires manual addition of the compiler plugin dependency, please follow the instructions below.
+
 To apply kotlinx-atomicfu plugin, you need to add 2 dependencies to the project classpath:
 1. `atomicfu-gradle-plugin`: it provides the necessary library dependencies and manages transformation modes.
 2. `atomicfu` compiler plugin: the compiler plugin is used to perform IR transformations (see [Atomicfu compiler plugin](#atomicfu-compiler-plugin) section).
@@ -155,6 +159,60 @@ apply plugin: 'kotlinx-atomicfu'
 ```
 </details>
 
+----
+**WARNING:**
+In case you got a compilation error after plugin application: 
+```
+error: unresolved reference: kotlinx
+import kotlinx.atomicfu.*
+       ^
+```
+
+and you apply `kotlin-gradle-plugin` in an old manner via the `buildscript` like below:
+
+```groovy
+buildscript {
+    repositories {
+        mavenLocal()
+        mavenCentral()
+    }
+
+    dependencies {
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${libs.versions.kotlinVersion.get()}")
+        classpath("org.jetbrains.kotlinx:atomicfu-gradle-plugin:${libs.versions.atomicfuVersion.get()}")
+        classpath("org.jetbrains.kotlin:atomicfu:${libs.versions.kotlinVersion.get()}")
+    }
+}
+
+apply plugin: 'org.jetbrains.kotlin.multiplatform'
+apply plugin: 'kotlinx-atomicfu'
+```
+
+Then this is what you can do to fix the compilation error:
+1. Apply kotlin-gradle-plugin by it's id: 
+   - remove kotlin-gradle-plugin from the classpath 
+   - replace `apply plugin: 'org.jetbrains.kotlin.multiplatform'` with 
+
+    `plugins { 
+        id  'org.jetbrains.kotlin.multiplatform' version '1.9.21' 
+    }`
+
+2. Or you can also swap the dependencies to `atomicfu-gradle-plugin` and `kotlin-gradle-plugin` in the classpath:
+```groovy
+buildscript {
+    ....
+  
+    dependencies {
+      // Swap dependencies to atomicfu-gradle-plugin and kotlin-gradle-plugin
+      // atomicfu-gradle-plugin should go first
+      classpath("org.jetbrains.kotlinx:atomicfu-gradle-plugin:${libs.versions.atomicfuVersion.get()}")
+      classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${libs.versions.kotlinVersion.get()}")
+      classpath("org.jetbrains.kotlin:atomicfu:${libs.versions.kotlinVersion.get()}")
+    }
+}
+```
+----
+
 #### Maven configuration
 
 Maven configuration is supported for JVM projects.

integration-testing/examples/plugin-order-bug/build.gradle

@@ -0,0 +1,52 @@
+buildscript {
+    repositories {
+        mavenLocal()
+        mavenCentral()
+    }
+
+    dependencies {
+        // If the order of adding atomicfu-gradle-plugin and kotlin-gradle-pluin to the classpath is changed, 
+        // then atomicfu dependency is not added to the classpath
+        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${libs.versions.kotlinVersion.get()}")
+        classpath("org.jetbrains.kotlinx:atomicfu-gradle-plugin:${libs.versions.atomicfuVersion.get()}")
+        classpath("org.jetbrains.kotlin:atomicfu:${libs.versions.kotlinVersion.get()}")
+    }
+}
+
+apply plugin: 'org.jetbrains.kotlin.multiplatform'
+// The issue is described in #384. Application of kotlin-gradle-plugin by id fixes the compilation error.
+//plugins {
+//    id 'org.jetbrains.kotlin.multiplatform' version '1.9.21'
+//}
+apply plugin: 'kotlinx-atomicfu'
+
+repositories {
+    mavenCentral()
+    maven{ url = "https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev" }
+    mavenLocal()
+}
+
+kotlin {
+    jvm()
+
+    js()
+
+    wasmJs {}
+    wasmWasi {}
+
+    macosArm64()
+    macosX64()
+    linuxArm64()
+    linuxX64()
+    mingwX64()
+
+    sourceSets {
+        commonMain {
+            dependencies {
+                implementation(kotlin("stdlib"))
+                implementation(kotlin("test-junit"))
+            }
+        }
+        commonTest {}
+    }
+}

integration-testing/examples/plugin-order-bug/gradle.properties

@@ -0,0 +1,5 @@
+##
+## Copyright 2016-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+##
+kotlin_version=1.9.21
+atomicfu_version=0.23.1-SNAPSHOT

integration-testing/examples/plugin-order-bug/settings.gradle.kts

@@ -0,0 +1,19 @@
+pluginManagement {
+    repositories {
+        mavenLocal()
+        mavenCentral()
+        maven("https://maven.pkg.jetbrains.space/kotlin/p/kotlin/dev")
+        gradlePluginPortal()
+    }
+}
+
+dependencyResolutionManagement {
+    versionCatalogs {
+        create("libs") {
+            version("atomicfuVersion", providers.gradleProperty("atomicfu_version").orNull)
+            version("kotlinVersion", providers.gradleProperty("kotlin_version").orNull)
+        }
+    }
+}
+
+rootProject.name = "plugin-order-bug"

integration-testing/examples/plugin-order-bug/src/commonMain/kotlin/AtomicSampleClass.kt

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2016-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package examples.mpp_sample
+
+import kotlinx.atomicfu.*
+import kotlinx.atomicfu.locks.*
+import kotlin.test.*
+
+public class AtomicSampleClass {
+    private val _x = atomic(0)
+    val x get() = _x.value
+
+    public fun doWork(finalValue: Int) {
+        assertEquals(0, x)
+        assertEquals(0, _x.getAndSet(3))
+        assertEquals(3, x)
+        assertTrue(_x.compareAndSet(3, finalValue))
+    }
+
+    private val lock = reentrantLock()
+
+    public fun synchronizedFoo(value: Int): Int {
+        return lock.withLock { value }
+    }
+}

integration-testing/examples/plugin-order-bug/src/commonTest/kotlin/AtomicSampleTest.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2016-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import kotlin.test.*
+import examples.mpp_sample.*
+
+class AtomicSampleTest {
+
+    @Test
+    fun testInt() {
+        val a = AtomicSampleClass()
+        a.doWork(1234)
+        assertEquals(1234, a.x)
+        assertEquals(42, a.synchronizedFoo(42))
+    }
+}

integration-testing/src/functionalTest/kotlin/kotlinx.atomicfu.gradle.plugin.test/cases/PluginOrderBugTest.kt

@@ -0,0 +1,22 @@
+package kotlinx.atomicfu.gradle.plugin.test.cases
+
+import kotlinx.atomicfu.gradle.plugin.test.framework.runner.*
+import kotlinx.atomicfu.gradle.plugin.test.framework.runner.GradleBuild
+import kotlinx.atomicfu.gradle.plugin.test.framework.runner.cleanAndBuild
+import kotlinx.atomicfu.gradle.plugin.test.framework.runner.createGradleBuildFromSources
+import kotlin.test.*
+
+/**
+ * This test reproduces and tracks the issue #384.
+ */
+class PluginOrderBugTest {
+    private val pluginOrderBugProject: GradleBuild = createGradleBuildFromSources("plugin-order-bug")
+
+    @Test
+    fun testUserProjectBuild() {
+        val e = assertFailsWith<IllegalArgumentException> {
+            pluginOrderBugProject.cleanAndBuild()
+        }
+        check(e.message?.contains("unresolved reference: kotlinx") == true)
+    }
+}