jr - Modern JAR launcher with JDK 25 AOT support (started off as a native build of jbang ended up making this)

[ivan-velikanov]

Hi,

I built a small Windows launcher for Java apps called "jr" (jar runner / java runner / something short (and small - jr - junior) therefore named in two letters like uv for python).

It's basically what Launch4j and WinRun4J do, it launches JAR files as native Windows executables, but it is a very simplified implementation, with few extra features which you will definitely love. The basic idea is to run your jars as if exe - literally both in terms of execution friendliness, raw performance, and even ease of development/deployment/configuration.

Unique Features

1. AOT - Ahead of Time

JR supports out of box JDK 25 AOT cache generation, use and cleanup.
AOT can make huge impact in startup performance, depends on use case, in certain tests noticed about 90% faster (20-30ms vs 200-300ms).
With JDK 25 and AOT enabled, first run takes ~200-300ms to create the cache, then subsequent runs are 20-30ms. The launcher overhead itself is only 2-3ms measured via performance counters.

2. Make Jars executable both in command line and guis:

The same exe (jr.exe) has two ways it can be used. One way is to use it as a dedicated launcher for a specific (fat) jar (or a custom complex java command) based on a simple .jrc config format (key=value, similar to WinRun4J etc). This feature is very much like the standard launch4j/winrun4j feature with extra automatic AOT. So basically you can rename this to yourapp.exe and put yourapp.jar next to it, and generate a jrc config file ... and that yourapp.exe becomes a launcher exclusively for yourapp.jar.

But there is another (arguably more interesting) use case!

This tool works as a generic replacement for java/javaw.exe to launch jar files. It auto-detects if your app needs a console window or should run as GUI (delegated to java or javaw accordingly) and it either keeps the console window visible or hidden based on this detection. (Caveat: There is a brief flashing of console window in pure GUI context and I don't know how to even hide that brief flash without spoiling the experience of pure CLI execution.)

Configuration steps:

• If you configure this with windows file association (associate jar files to use this), you can double click jars and they would work (and I must add ... with automatic AOT (jdk25+))

jr.exe "%1" %*

• There is a more interesting use case, if you modify your environment variable PATHEXT.
  Usually it looks like this

.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC

You can make it:

.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.JAR

Now with this configuration the jar files will become executable like exe/batchfiles just by using their name, and will work from anywhere if they are in the path!

# Double-click JARs from Windows Explorer - they just work!

# Run JARs from command line by name (if in PATH)
myapp.jar arg1 arg2

# Or even without .jar extension - just like .exe files!
myapp arg1 arg2

# All with automatic AOT speedup (JDK 25+)

This marks your end in making batch files for easy execution. Even jbang uses a jbang.cmd even maven uses mvn.cmd ... these can now work directly from jar or custom configuration ... upto you. You are freed and liberated from non-java companions you need to make your execution experience feel native.

Side note in PATHEXT you can even include .java and link it with jbang (out of box AOT support currently out of scope of this tool however):

.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.JAR;.JAVA

This makes your jar files really behave like native exes ... both in execution friendliness, invocation from gui or commandline, and also in terms of raw performance due to AOT.
Also you avoid the fragile, long, tedious build process of GraalVM (native image) which additionally gives a large sized exe which we dislike anyway. This gives you best of several worlds ... yes you don't get your java exe in 20KB ... that is not going to happen, it still depends on installed JVM ... but (I guess) this is as good as it can get. Can we do better? I wonder.

3. Bonus: Small EXEs

The exe is quite minimalist, simple and small (~23 KB with vcredist dependency, or ~193 KB standalone with no dependencies)

What jr lacks:

• It needs JDK installed, it will not even attempt installing JDK if not found. I haven't even planned venturing in that field, as it will make the code complex and I hardly know C coding, I wrote the whole thing with Claude Code.
• It is made with a Windows-only mindset, but there is nothing stopping the implementation of the same in Linux/Mac; it is just that Windows is my main operating system, and I did not have personal use-case to even attempt for other operating systems.
• It doesn't support registering/configuring file extension (jar mainly) and PATHEXT variables automatically.
• For all that jr doesn't do, and you wish it did, please consider JBang;
• And if you desire a combo of jr+jbang (native jbang) be clear it will be a huge 10MB+ GraalVM exe (can be even 50MB+) OR someone will have to sacrifice Java and write it in C/Rust/Zig etc., which I am sure nobody will. I myself tried to do in GraalVM but I finally decided to keep it in C and it turned out to be a very good decision for this use-case as far as my experience has been. You have maven-daemon mvnd (or Gradle or Mill) for other use cases where you desire faster friendlier execution of your projects. And JBang supports running projects from GitHub repos / Maven coordinates, so I feel right now jr is in a sweet spot, it just works for what it is meant to work, you have JBang for other use cases.

Anyway, thought some of you might find it useful. Feedback welcome.

The code is open source, written in plain C with no dependencies. It is a single source file, and builds with MS VC Build Tools portable. There are some Java test files for AOT performance testing and general JR tool testing.

Repo: https://github.com/xyz-jphil/jr

[maxandersen]

interesting ideas and thanks for reminding me about PATHEXT and that windows has both java.exe and javaw.exe - something I kinda forgot about as its not used anywhere else.

I like your idea of having name of exe drive which jar to run - combined with the small size its a nice little detail.

Your project reminds me of the jbang-launch (https://github.com/jbangdev/jbang-launch) and that we now have native image of jbang (just not enabled in the jbang scripts yet) - I assume the PATHEXT trick should work as is with jbang.

With respect to AOT what do you actually do to have the training run ?

[quintesse]

There already exists an AOT flag, it's called -XX:AOTCache, and it should be used by people who know what they are doing.
The moment we add an --aot flag ourselves we're setting us up for failure, because just turning on that flag will not work.

I would at least make it a preview feature. So we can always remove it / change it completely in a future version.
I would also make it hidden and either not document it (as we haven't documented our other preview features) or document it with clear preview warnings that everything can change in the future and you shouldn't depend on it.

That way we can play around with it and do those measurements y'all talk about.

[maxandersen]

But that flag doesn't do the thing that makes it work ... Make hash for the cache file,, right?

[maxandersen]

To be clear, I'm talking about launching users apps not jbang itself

[quintesse]

Make hash for the cache file,, right?
To be clear, I'm talking about launching users apps not jbang itself

That's definitely something that would be nice to have, but I'm worried that we could be leaving gigs of files in places where a user won't even notice. Then someday they run out of disk space, start investigating and find that there are many gigabytes of wasted space in some place called ~/.jbang/cache and they'll blame us for being bloated.

Btw, I'm saying Gigs because that's what I've heard complaints about with Leyden, it's not something theoretical. On top of that each time you switch Jdks that number will grow because we'll never clean up any of it, at least automatically. And perhaps you don't switch Jdks often but you might simply be upgrading from version 26.5.23 to 26.5.24! And boom, the scripts you run suddenly start using N megas/gigs more of disk space.

That's why I suggest to please put this behind a preview flag at least until we have good solutions for all these issues.

[wfouche]

That's why I suggest to please put this behind a preview flag at least until we have good solutions for all these issues.

I agree, and also think that AOT should not be enabled by default. During the training phase it prints a lot of additional ouput to the console, which will confuse users.

[wfouche]

Another way to reduce JBang's start-up time and the program it runs, is to use JVM option -XX:TieredStopAtLevel=1 for both.

$ export JBANG_JAVA_OPTIONS=-XX:TieredStopAtLevel=1
$ jbang run --runtime-option -XX:TieredStopAtLevel=1  cliApp.java

Both JBang and the Java application will only use the client JIT.

The total running time was reduced by 0.5 seconds in a quick test that I performed.

One could argue that -XX:TieredStopAtLevel=1 should be the default for JBang.{cmd,sh,ps1}

[maxandersen]

Hmmm. I actually thought we had that enabled already.

[quintesse]

I didn't even know about this flag and that it has so much effect on startup. Is that with all Jdk versions, even modern ones? Because startup has improved immensely since Java 8.

[wfouche]

@quintesse , I used Java 21.0.9-tem for the quick test that I ran.

$ export JBANG_JAVA_OPTIONS=-XX:TieredStopAtLevel=1
$ time jbang run --runtime-option -XX:TieredStopAtLevel=1  jython-cli@jython -c "print 1+2"

-XX:TieredStopAtLevel=1

real	0m1.625s
user	0m7.142s
sys	0m0.537s
3

real	0m1.617s
user	0m7.484s
sys	0m0.465s
3

real	0m1.589s
user	0m7.341s
sys	0m0.568s
3

-XX:TieredStopAtLevel=4

real	0m1.922s
user	0m9.246s
sys	0m0.494s
3

real	0m2.066s
user	0m8.935s
sys	0m0.576s
3

real	0m1.885s
user	0m9.001s
sys	0m0.574s

[ivan-velikanov]

Btw, I'm saying Gigs because that's what I've heard complaints about with Leyden, it's not something theoretical. On top of that each time you switch Jdks that number will grow because we'll never clean up any of it, at least automatically. And perhaps you don't switch Jdks often but you might simply be upgrading from version 26.5.23 to 26.5.24! And boom, the scripts you run suddenly start using N megas/gigs more of disk space.

I am just sharing, as a matter of personal experience, I am appreciative of this concern, however I have implemented a simple method to clean old AOT cache and it works for me. And also I don't claim it will fit all use cases ... but i am surprised what is such a big complication in implementing a solution to cleanup aot files ... after all they can be regenerated. I don't see why old AOT files need to be left bloating. If they haven't been accessed for a certain period of time especially they can be cleaned. What i have implemented is, if source has changes (and i am proposing one more addition that if jdk has changed) ... it regenerates AOT and cleanups old AOT. Right now my implementation keeps only one AOT file at any given time because in my use case any app will be run with only one jdk not multiple ... i don't see such a use case arising for me.

Again I am clarifying, I am not disputing the concern ... I am just wondering, it seem trivial to solve, and feeling it shouldn't be a big worry, especially given as you said it can be experimental feature to start with, and use activated flag (not default).

And to indicate my use case, I could make a alias/shortcut script called jbx which runs jbang with aot. if i need normal jbang i would just do jbang .. this way i keep invocation syntax short and simple for myself. At the same time, in windows as a i explained we can associate java files with either java, jbang or say jbx, and configure PATHEXT ; thus java files become executable. the jbang file additionally could have // comment for AOT ... so if it is present and jbang config also has it enabled .. AOT is used. I mean we can do a couple of years (yes years not even months) of testing ... people who prefer AOT and see value will give feedback. Basically we have a lot of ways of doing it elegantly without disruption.

[wfouche]

AOT support in Java 25 just muddies the waters so to speak. I don't think it is worth using it with CLI applications. There are better and simpler ways to reduce the start-up time of CLI apps. Let's use git@jbangdev as an example.

Test 0

$ time jbang run git@jbangdev log
0.781s

Test 1

$ time jbang run --runtime-option -XX:TieredStopAtLevel=1  git@jbangdev log
0.684s

Test 2

$ jbang export fatjar git@jbangdev
$ time java -jar git-fatjar.jar  log
0.330s

Test 3

$ time java -XX:TieredStopAtLevel=1 -jar git-fatjar.jar log
0.279s

Test 4 - AOT Training

$ time jbang run --runtime-option -XX:AOTCacheOutput=git.aot git@jbangdev log
1.889s

Test 5 - AOT

time jbang run --runtime-option -XX:AOTCache=git.aot git@jbangdev log
0.661s

Test 6 - AOT + Tier1 Jit

$ time jbang run --runtime-option -XX:AOTCache=git.aot --runtime-option -XX:TieredStopAtLevel=1  git@jbangdev log
0.617s

And if you really want quick starting CLI apps, just create a native image of them.

• https://www.jbang.dev/documentation/jbang/latest/native-images.html

AOT in Java 25 seems only useful for micro-services that for some reason are not (yet) compiled to a native image and need fast start-up times and be able to respond quickly to the first few requests received. They are well-served by the current JVM options to perform a carefully considered training run using a single instance and then to use the AOT output file in production across multiple instances of the same micro-service.

[ivan-velikanov]

I did not know about -XX:TieredStopAtLevel=1 until @wfouche brought it up.
Now I tried tweaking mvn.cmd with both AOT flag and this -XX:TieredStopAtLevel=1

• regular clean compile = 5.5sec (tried 4-5 times)
• with AOT = 3.9 sec (sometimes slower 4.4sec)
• with -XX:TieredStopAtLevel=1 = 3.6 sec
• maven native daemon = 2.55 sec avg (2.4,2.6,2.7)

wow that is embarrassing, it makes entire AOT efforts look over-shadowed.

mvn clean compile package -DskipTests

• baseline = 14.6s avg (13.7,14.3,16.4,14.2)
• with aot = 12.24s avg (12.7,12,12.1,12.4,12)
• with -XX:TieredStopAtLevel=1 = 12.47s avg (13.7,14.3,16.4,14.2,12.9,12.3,12.1,12.4)
• maven native daemon = 11sec avg (11.1,10.7,9.8,13,10.6 )

[maxandersen]

see now we are comparing oranges with oranges - and I'm not surprised btw :)

My main reason to add aot flag to jbang is NOT to use it with cli's but with these longer running apps - and mainly in semi-static environments and here an easy way to running those trainings if/when needed is useful - even if takes time/diskspace ...whats nice is that it becomes easier to compare and show actual value.

And yes, AOT for me is just not there yet - compared to native-image or for basic cli startup tieredcompilation is often good...but of course you then have a hit on performance when its long running.

[quintesse]

Definitely. Using Leyden for CLI-level startup times is (right now) not one of its goals. So it's not surprising to see worse timings because AOT is actually doing a lot of work behind the scenes. In fact, if you have a big cache simply loading it into memory might already be more expensive than a tiny CLI command that just start up, quickly does a single thing and shuts down again.

But for longer-running apps we go back again to the difference between training runs and normal runs.

So again, if you don't train your app you'll basically have CDS-level performance (or worse in the future if we start trimming stuff from the cache that supposedly isn't being used by the app!). To actually get an improvement you'll have to do a real training run, meaning using the app in ways that users would normally use it. Exit. And then possibly wait a long time.

To me that seems like something a user should do knowingly: "ok, this stuff is slow, I'm going to do a training run to see if that improves things".

Which to me suggests at least two different options, eg: --aot-train vs --aot. If you run with --aot without having done a training we display a message saying "first run with --aot-train".

Then if you run with --aot-train we can display an explanation telling the user what they should be doing, eg "use as much of the app as a normal user in normal circumstances would, then exit (which might mean needing to hit ctrl+c of the app doesn't have an exit option)" and warning them that at the end they might have to wait a minute or two.

Of course, that also means that if Leyden decides to change how all this works our options might need to change as well.

[wfouche]

Which to me suggests at least two different options, eg: --aot-train vs --aot. If you run with --aot

When we originally started discussing AOT my proposal was to have a --aot=<n> option, where:

• --aot=0 would not use AOT even if the AOT cache file exists.

• --aot=1 would do a training run and create the AOT cache file, or over-write the AOT cache file if it already exists.

• --aot=2 would use the AOT Cache file if it exists, otherwise display a warning that the AOT Cache file could not be found.

Specifying --aot without a value would intelligently default to either 1 or 2 depending on whether an AOT Cache file exists or not.

This proposal could do with an additional --aot-file option allowing the AOT cache file to be created in a known location, and not just in the JBang cache folder. If you are going to deploy 100 instances of a microservice, then 1 of them could do a training run and create the AOT cache file which can then be shared amongst all of them.

But all of this quickly this becomes a circular argument, as one concludes that the functionality that JDK 25 has is sufficient to manage AOT in controlled environments and there are little benefit to be gained by adding AOT support to JBang.