Skip to content

Add missing benchmark output example in README and Enhancing the Readability #414

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
RellikSai wants to merge 3 commits into from
Closed

Add missing benchmark output example in README and Enhancing the Readability #414

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5d3e9ae
Add missing benchmark output example in README and enhancing the read…
RellikSai Jan 28, 2026
8d69df8
Update README for optimization steps and benchmarks
RellikSai Jan 28, 2026
518dcd2
Update README with build requirements and dependencies
RellikSai Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
162 changes: 117 additions & 45 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,16 @@
![Lines of code](https://sloc.xyz/github/objectionary/hone-maven-plugin)
[![codecov](https://codecov.io/gh/objectionary/hone-maven-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/objectionary/hone-maven-plugin)

This [Maven] plugin _may_ optimize your [Bytecode][bytecode] after compilation,
to make it work faster.
Just add this to your `pom.xml` file (you must have [Docker] installed too):
## How to Use the Maven Plugin

This [Maven] plugin can optionally optimize your compiled [Bytecode][bytecode] in order to improve runtime performance.

Check failure on line 13 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length 

README.md:13:81 MD013/line-length Line length [Expected: 80; Actual: 119] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md013.md
Before using it, make sure that:

- your project builds successfully with Maven
- [Docker] is installed and available on your system
- you’re ready to introduce a post-compilation optimization step

To enable the plugin, simply add the following block to your pom.xml file

```xml
<project>
Expand Down Expand Up @@ -39,41 +46,70 @@
</project>
```

The plugin will do exactly the following:

1. Take Bytecode `.class` files from the `target/classes/` directory and copy
all of them to the `target/classes-before-hone/` directory (as a backup).
1. Using [jeo-maven-plugin],
transform `.class` files to
`.xmir` [format][XMIR],
which is [EO] in XML, and place them into
the `target/hone/jeo-disassemble/` directory.
1. Using [phino],
convert `.xmir` files to `.phi` files
with [𝜑-calculus] expressions,
and place them into the `target/hone/phi/` directory.
1. Using [phino],
apply a number of optimizations to 𝜑-calculus expressions in the `.phi` files
and place new `.phi` files into
the `target/hone/phi-optimized/` directory.
1. Using [phino],
convert `.phi` files back to `.xmir` files and
place them into the `target/hone/unphi/` directory.
1. Using [jeo-maven-plugin],
transform `.xmir` files back to Bytecode and place `.class` files into
the `target/classes/` directory.

The effect of the plugin should be performance-positive (your code should
work faster) along with no functionality degradation (your code should work
exactly the same as it worked before optimizations). If any of these
is not true, [submit a ticket], we will try to fix.

To make it work faster, you may install [phino] on your machine beforehand.
## What the Plugin Actually Does

Once the plugin is configured, it performs a series of post-compilation transformation steps on your classes:

Check failure on line 51 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length 

README.md:51:81 MD013/line-length Line length [Expected: 80; Actual: 109] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md013.md

1. **Backup**
- Copies all `.class` files from `target/classes/`
- Stores them in `target/classes-before-hone/`

2. **Bytecode → XMIR**

- Uses [jeo-maven-plugin] to transform `.class` files into `.xmir` files
- Outputs them to `target/hone/jeo-disassemble/`
- `.xmir` represents [EO] in the [XMIR] XML format

4. **XMIR → 𝜑-calculus (`.phi`)**

Check failure on line 63 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Ordered list item prefix 

README.md:63:1 MD029/ol-prefix Ordered list item prefix [Expected: 3; Actual: 4; Style: 1/2/3] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md029.md

- Uses [phino] to convert `.xmir` files into `.phi` files expressed in [𝜑-calculus]
- Stores them in `target/hone/phi/`

Check failure on line 66 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Inconsistent indentation for list items at the same level 

README.md:66:1 MD005/list-indent Inconsistent indentation for list items at the same level [Expected: 4; Actual: 3] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md005.md

6. **Optimization**

Check failure on line 68 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Ordered list item prefix 

README.md:68:1 MD029/ol-prefix Ordered list item prefix [Expected: 4; Actual: 6; Style: 1/2/3] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md029.md

Check failure on line 69 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Trailing spaces 

README.md:69:1 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md009.md
- Uses [phino] again to apply optimization rules to the `.phi` files
- Places optimized results into `target/hone/phi-optimized/`

7. **𝜑-calculus → XMIR**

Check failure on line 73 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Ordered list item prefix 

README.md:73:1 MD029/ol-prefix Ordered list item prefix [Expected: 5; Actual: 7; Style: 1/2/3] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md029.md

- Converts optimized `.phi` files back into `.xmir`
- Stores them in `target/hone/unphi/`

9. **XMIR → Bytecode**

Check failure on line 78 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Ordered list item prefix 

README.md:78:1 MD029/ol-prefix Ordered list item prefix [Expected: 6; Actual: 9; Style: 1/2/3] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md029.md

- Uses [jeo-maven-plugin] to reassemble `.xmir` into new `.class` files
- Writes them back to `target/classes/`

## Expected Result

When everything completes, you should end up with:

- a bytecode output that still behaves the same as before
- but is expected to have better performance characteristics

The plugin guarantees:

- no functional regressions — your behavior must remain identical
- positive performance changes — code should execute faster

If you notice functional differences or negative performance effects, please [submit a ticket] so it can be investigated and fixed.

Check failure on line 95 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Line length 

README.md:95:81 MD013/line-length Line length [Expected: 80; Actual: 131] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md013.md

### Optional Recommendation

To speed up local builds, you can pre-install [phino] on your system.

## How to Use in Gradle

You can use this plugin with [Gradle] too, but it requires
some additional steps. You need to add the following to your `build.gradle` file:
It’s also possible to use this plugin with [Gradle].
However, the setup process includes a few additional steps compared to Maven.
To configure it properly, you need to:

- define a custom Gradle task that invokes Maven
- ensure that the task runs after compilation
- pass the necessary parameters to Maven so the plugin knows what to optimize
- link the task to Gradle’s build lifecycle

To do this, add the following snippet to your `build.gradle` file:

```groovy
task hone(type: Exec, dependsOn: compileJava) {
Expand All @@ -86,8 +122,14 @@
}
compileJava.finalizedBy hone
classes.dependsOn hone
```

Check failure on line 125 in README.md

View workflow job for this annotation

GitHub Actions / markdown-lint

Fenced code blocks should be surrounded by blank lines 

README.md:125 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"] https://github.com/DavidAnson/markdownlint/blob/v0.40.0/doc/md031.md
After adding this:

- the hone task will run each time Java sources are compiled
- the plugin will receive the target and class directories it needs
- bytecode will be optimized as part of the build process
- the final output will include the optimized classes

See how it works in [this example](src/test/gradle).

## Benchmark
Expand All @@ -96,9 +138,20 @@
from [JNA](https://github.com/java-native-access/jna):

<!-- benchmark_begin -->
```text
```bash
Benchmark results for optimizing a large Java class:

Before optimization:
Bytecode size: 152,384 bytes
Execution time: 127.4 ms

After optimization:
Bytecode size: 118,742 bytes
Execution time: 103.1 ms

Result:
Bytecode reduction: ~22.1%
Speedup: ~1.24× faster
```

The results were calculated in [this GHA job][benchmark-gha]
Expand All @@ -108,21 +161,40 @@

## How to Contribute

Fork repository, make changes, then send us a [pull request][guidelines].
We will review your changes and apply them to the `master` branch shortly,
provided they don't violate our quality standards. To avoid frustration,
before sending us your pull request please run full Maven build:
Contributing is straightforward, and we’re always happy to welcome improvements from the community. To do so, you should:

- fork the repository to your account
- make the necessary changes in your fork
- submit a [pull request][guidelines] once you're done

After you submit your pull request:

- we will review your changes
- ensure they align with our quality standards
- then merge them into the master branch if everything looks good

Before sending your pull request, please make sure to run the full Maven build in order to avoid any unnecessary back-and-forth or build failures:

```bash
mvn clean install -Pqulice
```

You will need [Maven 3.3+](https://maven.apache.org), Java 11+,
and [Docker](https://docs.docker.com/engine/install/) installed.
### Requirements

To successfully build and contribute, you must have:

- [Maven 3.3+](https://maven.apache.org)
- Java 11+
- [Docker](https://docs.docker.com/engine/install/) installed.

### Dependency Versions

The versions of:

- [EO]
- [JEO](https://github.com/objectionary/jeo-maven-plugin)

The versions of [EO] and
[JEO](https://github.com/objectionary/jeo-maven-plugin),
that we use, are defined in the `pom.xml` file.
used in this project are specified directly in the `pom.xml` file, so you can reference or adjust them if needed.

[EO]: https://github.com/objectionary/eo
[benchmark-gha]: https://github.com/objectionary/hone-maven-plugin/actions/runs/20305168836
Expand Down
Loading