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 uses Maven as the build system, and it will bring the best experience. There is the Ant sample which describes the steps to build JMH benchmarks with Ant, and that example provides the insight how to use JMH with other build systems.


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, it usually amounts to replacing java to another language in the command above. 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/benchmarks.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/benchmarks.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