Provided a clarifying message to the debug agent initialization error (#4524)

#4524

Author: mvicsokolova

integration-testing/build.gradle.kts

@@ -3,6 +3,7 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 import org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile
 import org.jetbrains.kotlin.gradle.targets.js.npm.tasks.KotlinNpmInstallTask
 import org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode
+import java.io.*
 
 buildscript {
     /*
@@ -212,6 +213,7 @@ tasks {
         jvmArgs("-javaagent:$coroutinesDebugJar")
         testClassesDirs = sourceSet.output.classesDirs
         classpath = sourceSet.runtimeClasspath
+        System.setProperty("coroutines.debug.agent.path", coroutinesDebugJar.absolutePath) // todo: fixme
     }
 
     create<Test>("javaConsumersTest") {
@@ -231,6 +233,7 @@ tasks {
             ":jpmsTest:check",
             "smokeTest:build",
             "java8Test:check",
+            "safeDebugAgentTest:runWithExpectedFailure"
         )
     }
 

integration-testing/safeDebugAgentTest/build.gradle.kts

@@ -0,0 +1,43 @@
+import java.io.*
+
+plugins {
+    id("java")
+    application
+}
+
+repositories {
+    mavenCentral()
+}
+
+application {
+    mainClass.set("Main")
+}
+
+// In this test coroutine debug agent is attached as a javaagent vm argument
+// to a pure Java project (safeDebugAgentTest) with no Kotlin stdlib dependency.
+// In this case the error should be thrown from AgetnPremain class:
+// "java.lang.IllegalStateException: kotlinx.coroutines debug agent failed to load."
+tasks.register<Test>("runWithExpectedFailure") {
+    val agentJar = System.getProperty("coroutines.debug.agent.path")
+    val errorOutputStream = ByteArrayOutputStream()
+    val standardOutputStream = ByteArrayOutputStream()
+
+    project.javaexec {
+        mainClass.set("Main")
+        classpath = sourceSets.main.get().runtimeClasspath
+        jvmArgs = listOf("-javaagent:$agentJar")
+        errorOutput = errorOutputStream
+        standardOutput = standardOutputStream
+        isIgnoreExitValue = true
+    }
+
+    val expectedAgentError =
+        "kotlinx.coroutines debug agent failed to load.\n" +
+            "Please ensure that the Kotlin standard library is present in the classpath.\n" +
+            "Alternatively, you can disable kotlinx.coroutines debug agent by removing `-javaagent=/path/kotlinx-coroutines-core.jar` from your VM arguments.\n"
+    val errorOutput = errorOutputStream.toString()
+    val standardOutput = standardOutputStream.toString()
+    if (!errorOutput.contains(expectedAgentError)) {
+        throw GradleException("':safeDebugAgentTest:runWithExpectedFailure' completed with an unexpected output:\n" + standardOutput + "\n" + errorOutput)
+    }
+}

integration-testing/safeDebugAgentTest/src/main/java/Main.java

@@ -0,0 +1,5 @@
+public class Main {
+    public static void main(String[] args) {
+        System.out.printf("OK!");
+    }
+}

integration-testing/settings.gradle.kts

@@ -8,6 +8,7 @@ pluginManagement {
 }
 
 include("smokeTest")
+include("safeDebugAgentTest")
 include("java8Test")
 include(":jpmsTest")
 

kotlinx-coroutines-core/jvm/src/debug/internal/AgentPremain.kt

@@ -3,6 +3,7 @@ package kotlinx.coroutines.debug.internal
 import android.annotation.*
 import org.codehaus.mojo.animal_sniffer.*
 import sun.misc.*
+import java.lang.IllegalStateException
 import java.lang.instrument.*
 import java.lang.instrument.ClassFileTransformer
 import java.security.*
@@ -16,6 +17,25 @@ import java.security.*
 @IgnoreJRERequirement // Never touched on Android
 internal object AgentPremain {
 
+    // This should be the first property to ensure the check happens first! Add new properties only below!
+    private val dummy = checkIfStdlibIsAvailable()
+
+    /**
+     * This check ensures that kotlin-stdlib classes are loaded by the time AgentPremain is initialized;
+     * otherwise the debug session would fail with `java.lang.NoClassDefFoundError: kotlin/Result`.
+     */
+    private fun checkIfStdlibIsAvailable() {
+        try {
+            Result.success(42)
+        } catch (t: Throwable) {
+            throw IllegalStateException("kotlinx.coroutines debug agent failed to load.\n" +
+                "Please ensure that the Kotlin standard library is present in the classpath.\n" +
+                "Alternatively, you can disable kotlinx.coroutines debug agent by removing `-javaagent=/path/kotlinx-coroutines-core.jar` from your VM arguments.\n" +
+                t.cause
+            )
+        }
+    }
+
     private val enableCreationStackTraces = runCatching {
         System.getProperty("kotlinx.coroutines.debug.enable.creation.stack.trace")?.toBoolean()
     }.getOrNull() ?: DebugProbesImpl.enableCreationStackTraces