{"id":13617408,"url":"https://github.com/openjdk/jmh","last_synced_at":"2025-06-17T14:06:24.123Z","repository":{"id":38416428,"uuid":"186765948","full_name":"openjdk/jmh","owner":"openjdk","description":"https://openjdk.org/projects/code-tools/jmh","archived":false,"fork":false,"pushed_at":"2025-05-14T08:53:53.000Z","size":4189,"stargazers_count":2410,"open_issues_count":1,"forks_count":309,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-06-11T23:15:27.087Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openjdk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-15T06:47:19.000Z","updated_at":"2025-06-09T14:42:13.000Z","dependencies_parsed_at":"2023-02-16T18:46:24.039Z","dependency_job_id":"24190433-b970-4ac6-a27f-97a97d5a0402","html_url":"https://github.com/openjdk/jmh","commit_stats":{"total_commits":1677,"total_committers":66,"mean_commits":25.40909090909091,"dds":"0.12462731067382227","last_synced_commit":"7c6da9526c6544acbe9f19f2cf075793f240b120"},"previous_names":[],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/openjdk/jmh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjmh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjmh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjmh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjmh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openjdk","download_url":"https://codeload.github.com/openjdk/jmh/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openjdk%2Fjmh/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260375263,"owners_count":22999489,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T20:01:41.326Z","updated_at":"2025-06-17T14:06:19.099Z","avatar_url":"https://github.com/openjdk.png","language":"Java","funding_links":[],"categories":["Java","Awesome Tools","测试"],"sub_categories":["Languages"],"readme":"# Java Microbenchmark Harness (JMH)\n\nJMH is a Java harness for building, running, and analysing nano/micro/milli/macro benchmarks\nwritten in Java and other languages targeting the JVM.\n\n## Usage\n\n### Basic Considerations\n\nThe recommended way to run a JMH benchmark is to use Maven to setup a standalone project\nthat depends on the jar files of your application. This approach is preferred to ensure that\nthe benchmarks are correctly initialized and produce reliable results. It is possible to run\nbenchmarks from within an existing project, and even from within an IDE, however setup is more\ncomplex and the results are less reliable.\n\nIn all cases, the key to using JMH is enabling the annotation- or bytecode-processors to\ngenerate the synthetic benchmark code. Maven archetypes are the primary mechanism used\nto bootstrap the project that has the proper build configuration. We strongly recommend new\nusers make use of the archetype to setup the correct environment.\n\n### Samples\n\nIn order to understand JMH tests and maybe write your own, it might be useful\nto work through the [JMH Samples](https://github.com/openjdk/jmh/tree/master/jmh-samples/src/main/java/org/openjdk/jmh/samples). See the test comments for run instructions.\n\n### Preferred Usage: Command Line\n\n**Step 1. Setting up the benchmarking project.** The following command will generate the new JMH-driven project in new `test` folder. Note that current and target folder should not already contain any Maven project for this to work reliably.\n\n    $ mvn archetype:generate \\\n      -DinteractiveMode=false \\\n      -DarchetypeGroupId=org.openjdk.jmh \\\n      -DarchetypeArtifactId=jmh-java-benchmark-archetype \\\n      -DgroupId=org.sample \\\n      -DartifactId=test \\\n      -Dversion=1.0\n\nIf you want to benchmark an alternative JVM language, use another archetype artifact ID from the\n[list of existing ones](https://repo.maven.apache.org/maven2/org/openjdk/jmh/), it usually amounts\nto replacing `java` to another language in the artifact ID given above. Using alternative archetypes\nmay require additional changes in the build configuration, see the `pom.xml` in the generated project.\n\n**Step 2. Building the benchmarks.** After the project is generated, you can build it with the following\nMaven command:\n\n    $ cd test/\n    $ mvn clean verify\n\n**Step 3. Running the benchmarks.** After the build is done, you will get the self-contained executable JAR,\nwhich holds your benchmark, and all essential JMH infrastructure code:\n\n    $ java -jar target/benchmarks.jar\n\nRun with `-h` to see the command line options available.\n\nWhen dealing with large projects, it is customary to keep the benchmarks in a separate sub-project,\nwhich then depends on the tested modules via the usual build dependencies.\n\n### IDE Support\n\nWhile the command line approach is the suggested one, some people prefer to use IDEs.\nThe user experience varies between different IDEs, but we will outline the general things here.\nRunning benchmarks from the IDE is generally not recommended due to generally uncontrolled environment\nin which the benchmarks run.\n\n**Step 1. Setting up the benchmarking project.** Some IDEs provide the GUI to create the Maven project\nfrom the given archetype. Make sure your IDE knows about Central archetype catalog, and look for\n`org.openjdk.jmh:jmh-${lang}-benchmark-archetype` there. Alternatively, you can use the command line\nto generate the benchmark project, see above.\n\n_NOTE: JMH is not intended to be used in the same way as a typical testing library such as JUnit.\nSimply adding the `jmh-core` jar file to your build is not enough to be able to run benchmarks._\n\n**Step 2. Building the benchmarks.** Most IDEs are able to open/import Maven projects, and infer\nthe build configuration from Maven project configuration. IDEA and NetBeans are able to build\nJMH benchmark projects with little to no effort. Eclipse build configuration may need to set up\nJMH annotation processors to run.\n\n**Step 3. Running the benchmarks.** There is no direct support for JMH benchmarks in the IDE, but\none can use JMH Java API to invoke the benchmark. It usually amounts to having the `main` method,\nwhich will then call into JMH. See [JMH Samples](https://github.com/openjdk/jmh/tree/master/jmh-samples/src/main/java/org/openjdk/jmh/samples)\nfor the examples of this approach. Before you run any benchmark, the project build is required.\nMost IDEs do this automatically, but some do require explicit build action to be added before\nthe run: adding Maven target `verify` should help there.\n\n### Other Build Systems\n\nJMH project does not ship the build scripts for build systems other that Maven. But there are\ncommunity-supported bindings:\n - [Gradle JMH Plugin](https://github.com/melix/jmh-gradle-plugin)\n - [Scala SBT JMH Plugin](https://github.com/ktoso/sbt-jmh)\n\nIf you want to build with an alternative build system, you may want to see the\n[Ant sample](https://github.com/openjdk/jmh/tree/master/jmh-ant-sample) which describes\nthe steps to build JMH benchmark projects.\n\n## Support and Development\n\n### Pre-Requisite Steps\n\nMake sure you did this before publishing the benchmark, and/or requesting the JMH feature:\n\n - **JMH annotations Javadocs and Samples are essential reading.** Follow the [JMH Samples](https://github.com/openjdk/jmh/tree/master/jmh-samples/src/main/java/org/openjdk/jmh/samples)\n   to get familiar with the API, use cases, culprits, and pitfalls in building the benchmarks\n   and using JMH.\n - **Your benchmarks should be peer-reviewed.** Do not assume that a nice harness will magically\n   free you from considering benchmarking pitfalls. We only promise to make avoiding them easier,\n   not avoiding them completely.\n\nMake sure you tried these things before getting support:\n\n - **Archetypes provide the golden build configuration.** Try to generate the clean JMH benchmark\n   project and transplant the benchmark there. This is important to try when upgrading to the newer\n   JMH versions, since the minute differences in the build configurations may attribute to the\n   failures you are seeing.\n - **Current development code is usually leaner, meaner, and better.** Make sure you are running\n   the latest JMH version, and/or try to run with bleeding edge JMH to see if the issue is already\n   fixed.\n - **See if your question/issue was discussed already.** Look around mailing list archives to see if\n   there is already an answer.\n\nIf all these did not help, you are welcome to report the issue.\n\n### Reporting Harness and Test Bugs\n\nIf you have the access to [OpenJDK Bug System](https://bugs.openjdk.org/browse/CODETOOLS-7902762?jql=project%20%3D%20CODETOOLS%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20tools%20AND%20Subcomponent%20%3D%20jmh), please submit the bug there:\n * Project: CODETOOLS\n * Component: tools\n * Sub-component: jmh\n\nAlternatively, you can join the [JMH Mailing List](https://mail.openjdk.org/mailman/listinfo/jmh-dev) and report the bugs there.\n\n## Development\n\nJMH project accepts pull requests, like other OpenJDK projects.\nIf you have never contributed to OpenJDK before, then bots would require you to [sign OCA first](http://openjdk.org/contribute).\nNormally, you don't need to post patches anywhere else, or post to mailing lists, etc.\nIf you do want to have a wider discussion about JMH, please refer to [jmh-dev](https://mail.openjdk.org/mailman/listinfo/jmh-dev).\n\nShort instructions to build, test bleeding-edge JMH, and install its JAR to local Maven repo:\n\n    $ mvn clean install\n\nIf you already have the benchmark project, then it is enough to change JMH dependencies version\nto the latest `SNAPSHOT` version (look up the actual latest version in [root `pom.xml`](https://github.com/openjdk/jmh/blob/master/pom.xml)). If not, create the JMH benchmark project and change the version there.\n\nGitHub workflow \"JMH Pre-Integration Tests\" should pass on the changes. It would be triggered\nfor PRs. You can also trigger it manually for your branch.\n\n## Related projects\n\nThese projects are supported by community, not by OpenJDK/JMH developers.\n\n - [IntelliJ IDEA JMH Plugin](https://github.com/artyushov/idea-jmh-plugin)\n - [Jenkins JMH Plugin](https://github.com/brianfromoregon/jmh-plugin)\n - [Teamcity JMH Plugin](https://github.com/presidentio/teamcity-plugin-jmh)\n - [Visualize JMH Benchmarks](https://github.com/jzillmann/jmh-visualizer)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenjdk%2Fjmh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenjdk%2Fjmh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenjdk%2Fjmh/lists"}