Code Tools: jmh

JMH is a Java harness for building, running, and analysing nano/micro/milli/macro benchmarks written in Java and other languages targetting the JVM.

JMH is Maven-driven, hence having Maven installed will bring the best experience. Also, the working JDK installation should be available to build the project, the build will require the JAVA_HOME set to the correct JDK location. The rest of the page assumes we use Maven. However, there is the Ant sample, which describes how can one use JMH outside Maven world.


Basic usage: Released bundles

OpenJDK Community regularly publishes JMH artifacts and archetypes in Maven Central repository. This allows users to automatically set up JMH for their new projects. This command will generate the new JMH-driven project in test folder:
$ mvn archetype:generate \
          -DinteractiveMode=false \
          -DarchetypeGroupId=org.openjdk.jmh \
          -DarchetypeArtifactId=jmh-java-benchmark-archetype \
          -DgroupId=org.sample \
          -DartifactId=test \
          -Dversion=1.0
If you want to benchmark an alternative JVM language, use another archetypeArtifactId from the list of existing ones. Using alternative archetypes may require additional changes in the build configuration, see the pom.xml in the generated project. After the project is generated, you can build it:
$ cd test/
$ mvn clean install

After the build is done, you will get the self-contained executable JAR, which holds your benchmark, and all essential JMH infrastructure code:

$ java -jar target/microbenchmarks.jar

Run with -h to see the command line options available.

If you have problems running with the current JMH version, or archetype sets you up for an outdated JMH version, try to change <version> tag in pom.xml. Here is the list of versions available.


Advanced usage: "Bleeding Edge"

In many cases, you want bleeding edge code which contains fixes, features, and APIs not available yet in released versions. This section explains how to get the "bleeding edge" JMH in your project.

  1. Check out JMH source with Mercurial:
    $ hg clone http://hg.openjdk.java.net/code-tools/jmh/ jmh
    
  2. Build JMH. You can optionally skip the tests:
    $ cd jmh/
    $ mvn clean install -DskipTests
    

    You only need to do this step once, and Maven will deploy JMH into Maven repo on your local machine.

  3. If you already have the benchmark project, then it is enough to change JMH dependencies versions to 1.0-SNAPSHOT. If not, create the JMH benchmark project and change the version there.

  4. Done! Build the benchmark project, and run it:

    $ mvn clean install
    $ java -jar target/microbenchmarks.jar
    

Getting Support

Make sure you did this before publishing the benchmark, and/or requesting the JMH feature: Make sure you tried these things before getting support:

If all these did not help, you are welcome at the JMH mailing list.


Links