How to use JMH Gradle Plugin?

Question

Build script snippet for use in all Gradle versions:

build.gradle

buildscript {
  repositories {
    jcenter()
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "me.champeau.gradle:jmh-gradle-plugin:0.5.0"
  }
}

apply plugin: "me.champeau.gradle.jmh"

Build script snippet for new, incubating, plugin mechanism introduced in Gradle 2.1:

build.gradle

plugins {
  id "me.champeau.gradle.jmh" version "0.5.0"
}

What plugin version to use?

Gradle	Minimal plugin version
5.5	0.5.0
5.1	0.4.8
4.9	0.4.7 (to benefit from lazy tasks API)
4.8	0.4.5
4.7	0.4.5
4.6	0.4.5
4.5	0.4.5
4.4	0.4.5
4.3	0.4.5
4.2	0.4.4
4.1	0.4.4

Configuration

The plugin makes it easy to integrate into an existing project thanks to a specific configuration. In particular, benchmark source files are expected to be found in the src/jmh directory:

src/jmh
     |- java       : java sources for benchmarks
     |- resources  : resources for benchmarks

The plugin creates a jmh configuration that you should use if your benchmark files depend on a 3rd party library. For example, if you want to use commons-io, you can add the dependency like this:

build.gradle

dependencies {
    jmh 'commons-io:commons-io:2.4'
}

The plugin uses JMH 1.21. You can upgrade the version just by changing the version in the dependencies block:

build.gradle

dependencies {
    jmh 'org.openjdk.jmh:jmh-core:0.9'
    jmh 'org.openjdk.jmh:jmh-generator-annprocess:0.9'
}

Tasks

The project will add several tasks:

• jmhClasses : compiles raw benchmark code

• jmhRunBytecodeGenerator : runs bytecode generator over raw benchmark code and generates actual benchmarks

• jmhCompileGeneratedClasses : compiles generated benchmarks

• jmhJar : builds the JMH jar containing the JMH runtime and your compiled benchmark classes

• jmh : executes the benchmarks

The jmh task is the main task and depends on the others so it is in general sufficient to execute this task:

gradle jmh