Dependency and version information

[jmh-clojure/task "0.1.1"]

{jmh-clojure/task {:mvn/version "0.1.1"}}

<dependency>
  <groupId>jmh-clojure</groupId>
  <artifactId>task</artifactId>
  <version>0.1.1</version>
</dependency>

What is it?

Various convenience utilities for jmh-clojure intended to be used by higher-level tools. Note that while the examples below use tools.deps, this library can also be used via a Leiningen plugin, or standalone, as well.

Usage

For clj, the recommend way to use this library is by adding an alias to your deps.edn. The following will be sufficient for most users:

{#_...
 :aliases
 {:jmh {:extra-paths ["classes"]
        :extra-deps {jmh-clojure/task {:mvn/version "0.1.1"}}
        :ns-default jmh.task
        :exec-fn jmh.task/run}}}

It's important to notice that the "classes" directory is added to the project paths. This is required for jmh-clojure since it generates .class files dynamically (written to *compile-path*, by default). We must add this output directory so it's available on the classpath when running.

By default, a jmh.edn file at the root of your project is used to configure the benchmark runner. Please see the sample file for a complete guide. For example, the following runs all benchmarks, enables the standard JMH status log, and outputs pretty-printed benchmark result data:

$ mkdir -p classes
$ clj -X:jmh :format :pprint, :status true

(If you're new to the -X flag, it allows us to omit the Clojure map curly braces ({}) on the command line.)

Notice again that we must manually create the classes directory before running. Ensuring the *compile-path* directory exists is not automated by tools.deps as it is with other tools like Leiningen.

Available options

The optional map to jmh.task/run specifies the normal jmh-clojure run options. The extra task options provided by this library include:

Please run clj -X:jmh help for more information on the available options. Note that some formats (e.g., :table) exclude some result information due to space considerations. See the previously mentioned help for details.

The available JMH profilers may be listed with: clj -X:jmh profilers.

Uberjar example

Along with integrating with the Clojure project tool of your choice, you can also create a standalone jar file. This is useful if you intend to run benchmarks on a different machine than your development one and want to package everything up so you don't have to re-create the project build environment. The jmh.main namespace is designed to be used as the jar entry point.

For Clojure tools, we'll use the uberdeps library to create the jar. In the root of a hypothetical project:

mkdir -p classes uberdeps
echo '{:deps {uberdeps/uberdeps {:mvn/version "1.0.4"}}}' > uberdeps/deps.edn
clj -Ajmh -M -e "(compile 'jmh.main)"
cd uberdeps
clj -M -m uberdeps.uberjar --aliases jmh --deps-file ../deps.edn --main-class jmh.main --target ../target/jmh.jar
mkdir classes
java -cp classes:../target/jmh.jar jmh.main :help

Note again that even when running as an uberjar, we still need to create the classes directory beforehand to enable the dynamic compilation. Running with -Dfile.encoding=UTF-8 is also advisable depending on your platform due to the unicode characters JMH can output.

The procedure for other tools should be similarly straightforward.

More information

Please see the jmh-clojure project for everything else about jmh-clojure.

Running the tests

lein test

Or, lein test-all for all supported Clojure versions.

License

Copyright © 2017-2021 Justin Conklin

Distributed under the Eclipse Public License, the same as Clojure.