fix: document Gradle fork build and warn on missing native library

AGENTS.md

@@ -30,8 +30,10 @@
 # Build JAR artifact only (useful for local profiling)
 ./gradlew :examples:example-gradle:jmhJar
 
-# Build and install JMH fork to local Maven repo (required before Maven example)
-cd jmh-fork && mvn clean install -DskipTests -q
+# Build and install JMH fork to local Maven repo (required before Maven example).
+# Must use Gradle: only the Gradle build compiles and bundles the native libraries.
+git submodule update --init --recursive
+./gradlew -p jmh-fork publishToMavenLocal
 
 # Build Maven example (after installing JMH fork)
 cd examples/example-maven && mvn package -q
@@ -113,7 +115,7 @@ The repository combines Maven and Gradle via Gradle's composite build feature:
 
 1. Make changes in `jmh-fork/`
 2. Bump version: `cd jmh-fork && mvn versions:set -DnewVersion=X.Y.Z`
-3. Publish locally: `cd jmh-fork && mvn clean install -DskipTests -q`
+3. Publish locally: `./gradlew -p jmh-fork publishToMavenLocal`
 4. Update version reference in root `build.gradle.kts` if needed
 5. Test both Gradle and Maven examples to verify compatibility
 

README.md

@@ -23,14 +23,14 @@ For information on how to integrate it, see the [CodSpeed documentation](https:/
 ### Prerequisites
 
 - JDK 21+
-- Maven (for building the JMH fork)
-- Gradle
+- A C toolchain (Linux only, to build the native libraries)
 
 ### Setup
 
-1. Build and install the JMH fork to your local Maven repository:
+1. Build and install the JMH fork to your local Maven repository. Use Gradle: only the Gradle build compiles and bundles the native libraries needed for CodSpeed measurements.
 ```bash
-cd jmh-fork && mvn clean install -DskipTests -q
+git submodule update --init --recursive
+./gradlew -p jmh-fork publishToMavenLocal
 ```
 
 2. Run the example benchmarks:

jmh-fork/jmh-core/src/main/java/io/codspeed/instrument_hooks/InstrumentHooks.java

@@ -9,6 +9,8 @@
 
 public class InstrumentHooks {
 
+  private static final String CODSPEED_ENV_VAR = "CODSPEED_ENV";
+
   private static final boolean nativeAvailable;
 
   static {
@@ -17,8 +19,12 @@ public class InstrumentHooks {
       loadNativeLibrary("/libinstrument_hooks_jni.so");
       loaded = true;
     } catch (IOException | UnsatisfiedLinkError e) {
-      // Native library not available (e.g. non-Linux platform).
-      // All methods will gracefully no-op.
+      // Expected on non-Linux hosts, so only warn when running under the CodSpeed runner.
+      if (System.getenv(CODSPEED_ENV_VAR) != null) {
+        System.err.println(
+            "[CodSpeed] Failed to load instrument-hooks, running without CodSpeed: "
+                + e.getMessage());
+      }
     }
     nativeAvailable = loaded;
   }