jr is a small native launcher for Java apps on Windows and macOS. Your jar gets its own exe or Mac app with your name and icon. jr finds Java or downloads it, starts the app faster from the second run, and can update it in place.
- Its own exe, its own name. An exe (or a macOS app) with your icon and version. It can run the JVM inside that process, so Task Manager shows
myapp.exe, not anotherjava.exe. - Java is taken care of. jr uses an installed Java that fits the app. If there is none, it asks, then downloads Eclipse Temurin into the same cache jbang uses, checked against its SHA-256.
- Faster from the second run. On Java 25 and newer, jr keeps an AOT cache for each jar and rebuilds it when the jar changes.
- Small, nothing to install. About 600 KB, no runtime bundled. Double-clicked, the app opens with no console window; run from a terminal, its output shows there.
Windows:
curl.exe -fLo jr.exe https://github.com/jarrunner/jr/releases/latest/download/jr.exe
.\jr.exe myapp.jar
macOS (installs jr into ~/.local/bin, see docs/macos.md):
curl -fsSL https://github.com/jarrunner/jr/releases/latest/download/install.sh | sh
jr myapp.jar
To give your own app its own launcher, add jr-maven-plugin to its build: the getting-started guide takes you through it.
Guide · macOS · jr-maven-plugin · jr-apputils · Releases · jarrunner.github.io
jr itself is written in Java and compiled to a native program (see Java compiled to a native exe). The rest of this page is the reference.
Pre-built executables are in GitHub Releases:
jr.exe(about 610 KB) - Windows x64. Nothing to install: it needs only DLLs that ship with Windows.jr-windows-arm64.exe- Windows on ARM64. Built and linked for ARM64, not yet run on ARM64 hardware.jr-noicon-*.exe- the same without jr's icon, for tools that stamp their own (this is whatjr-maven-pluginbundles).jr-macos- macOS, one binary for Apple Silicon and Intel (also asjr-macos-arm64andjr-macos-x86_64), signed ad hoc. Install withcurl -fsSL https://github.com/jarrunner/jr/releases/latest/download/install.sh | sh; see docs/macos.md.SHA256SUMS- check a download against it. The release binaries are not code-signed.
Download, rename if you like, and use it: nothing to install. Tested on Windows 11 and macOS 26.
New to jr? Read the getting-started guide: run any jar with jr, then give your own app its own exe with jr-maven-plugin, in your Maven build and in CI.
- jr-maven-plugin builds a jr launcher for your own app in its Maven build: your icon, your version, your config baked in. It bundles the jr binaries of a jr release.
- jr-apputils is the optional library for an app launched by jr: typed access to what jr passes it (
JrApp), and the app's owninstallandupdatecommands on top of jr, with the standard per-OS folders, the Windows PATH and shortcuts, a receipt for uninstall, and a once-a-day update notice. The convention is in docs/apps.md.
mvn package in this folder, needing JDK 25, Maven and llvm-mingw (the ucrt build) on PATH. Details are in docs/development.md. The release workflow (.github/workflows/release.yml) runs the same Maven build on a clean Windows machine, so a release contains nothing built on a developer's machine.
jr began as a hand-written C launcher. That version lives on in its own repository, jarrunner/jr_legacy_c, but it has far fewer features than this one and is no longer developed.
jr is written in Java. TeaVM compiles it to C, and an LLVM toolchain compiles that C to a native exe: llvm-mingw on Windows (x64 and ARM64), zig cc on Linux and macOS. The Windows API bindings (functions, constants, struct layouts) are not written by hand: jextract-teavm generates them from the real system headers, and the C compiler checks every size and offset again on each build.
The result, measured rather than claimed:
- On Windows it is a real, shipping native program. jr runs real tools every day. It has a GUI error dialog, progress windows, an HTTPS downloader, resource editing, Authenticode signing and an in-process JVM, all in Java, in about 610 KB.
- Size. A hand-written C launcher would be smaller, but less so than you might think. When the Java port reached feature parity with the old C launcher it was about 4.8x its size (370 KB against 77 KB). Most of that is a fixed cost: TeaVM's runtime is paid for once. Packed with UPX, today's 610 KB exe is about 160 KB, roughly what a C launcher with today's features would be, by our estimate. See docs/upx.md for the numbers.
- Speed. A jr launch costs about 30 ms on its own. Next to starting a JVM that is noise.
- Cross-platform. macOS runs: tested on GitHub's Mac runners and on an Apple silicon Mac (macOS 26), including the Java download, dialogs when opened from Finder or the Dock, self-update of a binary and of an app, and the JVM inside jr's own process. Linux builds and runs, as the test bench for the Mac code. Windows is the most used.
To a Java developer who already knows the OS functions they are calling, it reads as ordinary modern Java (var, lambdas, switch expressions, small final classes) with native calls that look like static methods. About a third of the source files contain no native code at all. A typical native piece, shortened from Crc32.java:
var crc32 = (RtlComputeCrc32Fn) (Object) fn; // a function pointer from GetProcAddress
return memScoped(() -> { // native memory, freed when the block ends
var f = WinApi.fopen(cstr(path), cstr("rb"));
var buf = alloc(READ_CHUNK);
var crc = 0;
long n;
while ((n = WinApi.fread(buf, 1, READ_CHUNK, f)) > 0) {
crc = crc32.invoke(crc, buf, (int) n);
}
WinApi.fclose(f);
return hex(crc);
});What will feel unfamiliar, in rough order:
- Some everyday JDK calls are avoided on purpose. TeaVM compiles in everything a call can reach, so
String.formatcosts about 580 KB, andString.splitortoLowerCasepull in the regex engine and Unicode tables. jr uses small hand-written helpers instead. This surprises Java developers more than anything native does. - C structs are read through generated accessors by offset, for example
WinOffsets.FILETIME.dwLowDateTime(addr). The offsets are checked against the real compiler, so this is safe, but it reads more like C than Java. - Function pointers and callbacks are small abstract classes extending TeaVM's
Function, and a function pointer is cast to one. - No reflection, and C structs cannot be passed by value (a header macro is the workaround).
- Threads are green threads.
java.lang.Thread,synchronized,joinandwait/notifywork, but TeaVM runs every Java thread as a fiber on one OS thread, switching only where a thread waits (sleep,wait,join). A thread that computes without waiting is never interrupted, and a blocking OS call pauses all of them. There is no parallel Java code, and therefore no data races in it. Real OS threads are fine for native work, but Java code must not run on them, because TeaVM's runtime (its garbage collector included) is not thread-safe. jr itself starts no threads.
The rules for native memory are short and written at the top of N.java: everything is allocated outside the garbage-collected heap, and a pointer never outlives its memScoped block.
Planned, not done:
- macOS: released, built for Apple silicon and Intel; more testing on real Macs, especially of installed apps.
- The POSIX launcher catches up with the Windows one, using the same generated-binding approach.
- Windows on ARM64: run on real hardware.
- Fixes in the bindings generator, so that the code needs fewer workarounds.
The Windows feature set is essentially complete. Size is watched carefully, but it is no longer the main goal.
The most powerful way to use jr is to make ALL jar files on your system executable like native .exe files:
Associate .jar files with jr.exe:
# Windows Registry approach (run as Administrator)
ftype jarfile="C:\path\to\jr.exe" "%1" %*
assoc .jar=jarfileOr use Windows Settings:
- Right-click any
.jarfile → Open with → Choose another app - Browse to
jr.exe→ Check "Always use this app" → OK
This allows running JARs by name without typing .jar extension:
# Add to System Environment Variables
setx PATHEXT "%PATHEXT%;.JAR"Or manually:
- Open System Properties → Environment Variables
- Edit
PATHEXTvariable - Append
;.JARto the end - Original:
.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC - Updated:
.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.JAR
What this gives you:
# Double-click JARs from Windows Explorer - they just work!
# (with automatic console/GUI detection and AOT caching)
# Run JARs from command line by name (if in PATH)
myapp.jar arg1 arg2
# Or even without .jar extension
myapp arg1 arg2
# Works everywhere, with automatic AOT speedup (JDK 25+)No more fragile batch files! Your JARs become first-class citizens like .exe files.
An app's settings are baked into its exe by jr-maven-plugin. For a one-off override, jr takes options in the style of java's own -X options, and they must come first, before the jar or the app's arguments:
jr.exe [-Xjr:options] <jar-file> [app args...]
myapp.exe [-Xjr:options] [app args...] (an app's own exe, its config baked in)-Xjr:<key>=<value>sets any config key for this run, overriding the config:-Xjr:jvm=dll,-Xjr:aot=false,-Xjr:java.home=C:\Java\jdk-25,-Xjr:java.version=25+. Quote values with spaces either way:"-Xjr:java.home=C:\Program Files\Java\jdk-25"or-Xjr:java.home="C:\Program Files\Java\jdk-25".-Xjr:yesdon't ask before auto-installing Java.-Xjr:helpshow help.
jr reads only the leading run of -Xjr: tokens and stops at the first token that is not one. Everything from there on goes to the app exactly as typed, so an app's own --yes, -jar or even -Xjr:... argument is never taken for a jr option and never removed. An unknown -Xjr: option is an error, not silently ignored.
These replace the old --jvm-dll, --jvm-exe, --enable-aot, --disable-aot, --java-home=, --yes and --create-config flags, which were matched anywhere on the command line and collided with apps' own arguments. Passing one of them where the jar should be gives an error naming its replacement.
Use jr.exe directly to launch any JAR file:
# Basic usage
jr.exe myapp.jar
# With arguments
jr.exe myapp.jar --arg1 value1 --arg2 value2
# Disable AOT cache
jr.exe -Xjr:aot=false myapp.jar
# Specify Java location
jr.exe -Xjr:java.home=C:\Java\jdk-21 myapp.jar
# Run the JVM inside jr.exe itself, instead of spawning java.exe
jr.exe -Xjr:jvm=dll myapp.jar
# No Java found? jr offers to download one - skip the prompt for unattended use
jr.exe -Xjr:yes myapp.jar
# Combined
jr.exe -Xjr:aot=false -Xjr:java.home=C:\Java\jdk-25 myapp.jar --verboseHow it works:
- When double-clicked from Explorer → runs with
javaw.exe(no console) - When run from terminal → runs with
java.exe(console output visible) - AOT cache enabled by default for faster subsequent launches
For an app you ship or run often, jr-maven-plugin builds myapp.exe: a copy of jr with your app's name, icon and version, and the app's config baked into it as a jrc-json. Every mvn package builds it again, on your machine or in CI.
# Simply run the app's exe
myapp.exe
# Command-line arguments are appended to the config's app.args
myapp.exe --extra-arg valueThe config cannot be overridden by a file placed beside the exe. jr 1.2 and earlier also read a key=value file named after the exe (myapp.jrc); jr 1.3.0 and later do not. An exe built with an older jr keeps the behaviour of the jr it was built from, so existing exes are unaffected until they are rebuilt.
These are the settings an app's config carries. In jr-maven-plugin each has a parameter of its own (see its README), and any of them can be set for one run with -Xjr:<key>=<value>.
| Key | Description | Example |
|---|---|---|
vm.args |
JVM arguments (before -jar) |
-Xmx512m -Xms128m -Dkey=value |
java.args |
Java arguments (-jar, -cp, main class) |
-jar myapp.jar or -cp lib/*;app.jar com.Main |
app.args |
Application arguments (after jar/class) | --config app.xml --verbose |
aot |
Enable/disable AOT cache | true or false |
jvm |
How the JVM is started | exe (default) or dll |
log.file |
Debug log file path | myapp.log |
log.level |
Log verbosity | info, warning, error, none |
log.overwrite |
Overwrite log on each run | true or false (default: append) |
java.version |
Required Java: NN and NN+ both mean at least NN, with NN preferred |
25, 21+ (default: any Java; installs 25 if none) |
java.min, java.preferred, java.max |
The same, set separately (not together with java.version) |
21, 25, 25 |
java.type |
What auto-install downloads | jre (default) or jdk |
java.autoinstall |
Enable/disable auto-installing a missing JDK | true (default) or false |
java.home |
Use exactly this JDK: no PATH lookup, no version check, no install | C:\Java\jdk-25 |
Settings are applied in this order (later overrides earlier):
- Built-in defaults
- The config baked into the exe
- Environment variables (
JR_JAVA_AUTOINSTALL,JR_ASSUME_YES) -Xjr:options on the command line
The app's own arguments are not overridden but appended: with app.args set to --mode production in the config, myapp.exe --debug runs the app with --mode production --debug.
By default jr spawns java.exe as a child process. That works, but every Java
application on the machine then shows up as an indistinguishable java.exe:
myapp.exe <- the launcher, exits immediately in GUI mode
java.exe <- your application actually lives here
java.exe <- somebody else's application
java.exe <- a build tool
Killing one application by name (taskkill /IM java.exe) kills all of them.
Setting jvm=dll loads the JVM into the launcher process instead, so the
application is the executable:
jvm=dllmyapp.exe <- the JVM and your application, one process
otherapp.exe <- a different application, separately killable
Now taskkill /IM myapp.exe targets exactly one application, Task Manager shows
a meaningful name, and per-application firewall rules, window grouping and
process monitoring all work the way they do for native programs.
How it works: java.exe is itself a ~30 KB stub whose main() loads
jli.dll and calls JLI_Launch(), which loads bin\server\jvm.dll. In
jvm=dll mode jr does exactly the same thing from its own main(). Because
the real JDK launcher does the work, every java.exe feature is preserved:
-jar manifest handling (Main-Class, Class-Path), classpath wildcards,
--module, @argfiles, JDK_JAVA_OPTIONS, AOT cache flags, exit codes,
stdin/stdout/stderr and redirection.
Enable it per-application in the app's config (jr-maven-plugin's jvmMode), or per-invocation on the command
line:
jr.exe -Xjr:jvm=dll myapp.jar # force in-process
jr.exe -Xjr:jvm=exe myapp.jar # force child process (default)-Xjr: options override the app's config.
Notes:
jli.dllis located next to thejava.exe/javaw.exethat was resolved fromPATHorjava.home, following symlinks (such as the Oraclejavapathshim) and falling back to%JAVA_HOME%.- If
jli.dllcannot be found or loaded,jrlogs a warning and falls back to spawningjava.exe, so enabling this can not stop an application from starting. - In GUI mode there is no console, so the standard streams are pointed at
NUL. Unlikejavaw.exe,System.console()is therefore non-null; writes toSystem.outsucceed and are discarded rather than failing. - The launcher no longer exits early in GUI mode - it can't, it is the application. This is the point of the mode, but it means the process stays in the process list for the application's whole lifetime.
How AOT Works:
The launcher automatically manages AOT (Ahead-of-Time) cache files for JDK 25+:
-
First Run: Creates AOT cache file (e.g.,
myapp.g2.4ZBZgN.aot)- Filename encodes JAR size and modification time
- Takes a bit longer to start
-
Subsequent Runs: Reuses existing cache
- ~90% faster startup
- Automatic cache invalidation when JAR changes
-
JAR Update: Detects changes automatically
- Old cache files are cleaned up
- New cache created on next run
AOT Cache Filename Format:
<jarname>.<size_base52>.<modtime_base52>.aot
Control AOT:
# Disable for a single run (command-line)
jr.exe -Xjr:aot=false myapp.jarTo disable it for good, set aot=false in the app's config (jr-maven-plugin's <aot>false</aot>).
If no Java is found (not on PATH, no java.home, no matching config), or the Java on PATH doesn't satisfy the config's java.version, jr offers to download one instead of just failing:
# Normal use - asks first (console: Y/n prompt, GUI: Yes/No dialog)
jr.exe myapp.jar
# Skip the prompt (unattended/scripted use)
jr.exe -Xjr:yes myapp.jarHow it works:
- Downloads a matching Eclipse Temurin build for the requested major version (default: 25), for the machine's native architecture, via the Foojay Disco API - the same API jbang itself uses. On Windows on ARM64 it installs a native ARM64 JDK: Temurin where one is published, otherwise Azul Zulu (Temurin has no Windows ARM64 build of some versions, 25 among them), and Temurin x64 under emulation only if neither exists.
- Installs it into
%USERPROFILE%\.jbang\cache\jdks\<version>\(on macOS and Linux~/.jbang/cache/jdks/<version>, from Temurin's.tar.gz; on macOS the question is a dialog when the app was opened from Finder or the Dock) - the exact same cache location jbang uses, so the two tools share downloads. If jbang already installed that version, jr uses it directly with no download; if jr installs one first,jbang jdk listpicks it up automatically. - Verifies the download's SHA256 checksum before extracting anything.
- Extracts with the
tar.exealready bundled with Windows (10 1803+) - no bundled archive library. - Shows progress matching how jr was launched: a text progress bar in console mode, a small native progress window in GUI mode.
This makes an app's own exe + its shaded jar a genuinely standalone distributable - it works even on a machine with no JDK installed at all.
Control it with config keys (see Config Keys), baked in by jr-maven-plugin (javaVersion, javaMin / javaPreferred / javaMax, javaType, javaAutoinstall) or given for one run as -Xjr: options:
java.version=25(or25+) means at least 25, with 25 preferred;java.min/java.preferred/java.maxset the three separately. jr uses an installed Java of exactly the preferred version; if there is none it offers to download one; only then does it take an installed newer (or older, down to the minimum) Java. The version is read from the JDK's ownreleasefile, so the check costs no extra JVM start.java.homeis an explicit choice and is never version-checked.java.autoinstall=falseturns the whole feature off: jr fails immediately instead of downloading.
jr can turn a copy of itself into a branded launcher - its own icon, its own name in Task Manager, its own version, signed - with no rcedit or signtool. It uses only Windows' own machinery (the resource-update API, and mssign32.dll, which is what signtool itself calls), so it adds no dependency.
# A branded copy of jr.exe: icon, version info, and the name Task Manager shows
jr.exe -Xjr:make=myapp.exe -Xjr:icon=myapp.ico -Xjr:version=1.4.0.0 ^
"-Xjr:version.FileDescription=My App" -Xjr:version.ProductName=MyApp ^
"-Xjr:version.CompanyName=Example Ltd"
# ...and signed, with a timestamp (password comes from the environment, never the command line)
set JR_SIGN_PASSWORD=...
jr.exe -Xjr:make=myapp.exe -Xjr:icon=myapp.ico -Xjr:sign=codesign.pfx -Xjr:sign.timestamp=http://timestamp.digicert.com
# Edit an existing exe in place instead of making a copy
jr.exe -Xjr:edit=myapp.exe -Xjr:version=1.4.1.0
# See what is in an exe
jr.exe -Xjr:list-resources=myapp.exeThen bake the config in with -Xjr:resource.RCDATA.JRC=myapp.jrc.json (see the guide; jr-maven-plugin does all of this for you). With jvm=dll, Task Manager shows the app under its own description and icon.
| Option | What it does |
|---|---|
-Xjr:make=<out.exe> |
Copy this exe to out.exe, then apply the options below |
-Xjr:edit=<exe> |
Apply them to an existing exe, in place |
-Xjr:icon=<file.ico> |
Replace the main icon (the one Explorer and the taskbar show) |
-Xjr:version=<a.b.c.d> |
File and product version; -Xjr:file-version= / -Xjr:product-version= set one |
-Xjr:version.<Name>=<text> |
Any version string: FileDescription (Task Manager's name), ProductName, CompanyName, LegalCopyright, OriginalFilename, ... |
-Xjr:manifest=<file> |
The application manifest |
-Xjr:execution-level=<level> |
asInvoker, highestAvailable or requireAdministrator - changed inside the existing manifest, or a minimal one is generated |
-Xjr:string.<id>=<text> |
A string-table entry |
-Xjr:resource.<type>.<name>=<file> |
Any other resource, raw from a file. Type: a number, RCDATA, HTML, MANIFEST, or a custom name |
-Xjr:sign=<file.pfx> |
Authenticode-sign (SHA-256). Password from JR_SIGN_PASSWORD. The key is used in memory only and never lands in the Windows key store |
-Xjr:sign.thumbprint=<sha1> |
Sign with a certificate from the Windows Personal store (current user, then machine) instead - e.g. one on a hardware token |
-Xjr:sign.timestamp=<url> |
RFC 3161 timestamp server, so the signature outlives the certificate |
-Xjr:list-resources=<exe> |
Print an exe's resources |
The order is always copy, remove any old signature, resources, sign. Signing comes last because any later change to the file invalidates the signature. For the same reason, editing an already-signed exe removes its signature (and says so), rather than leaving a broken one behind. Existing resources are replaced in their own language rather than duplicated, and version fields you don't set are kept.
Logging is opt-in only and never happens automatically:
Set log.file (and optionally log.level, log.overwrite) in the app's config, or for one run:
jr.exe -Xjr:log.file=myapp.log -Xjr:log.level=info myapp.jarLog Content:
========================================
Java Runner Log - 2025-11-21 17:05:06
========================================
[INFO] Launcher started: myapp.exe
[INFO] Execution mode: Console
[INFO] Java executable: java.exe
[INFO] AOT enabled: true
[INFO] Found Java in PATH: C:\Java\jdk-25\bin\java.exe
[INFO] Using config-based mode
[INFO] Creating new AOT cache: myapp.g2.4ZBZgN.aot
[INFO] Final command: "C:\Java\jdk-25\bin\java.exe" -Dio.github.jarrunner.jr.startMicros=0 ...
[INFO] Java process started successfully (PID: 2680)
[INFO] Java process exited with code: 0
========================================
Perfect for troubleshooting:
- Configuration parsing
- Java detection
- AOT decisions
- Full command line executed
- Exit codes
Primary Use Case (Recommended):
- System-wide JAR execution - Set up file association + PATHEXT, make ALL jars executable like .exe files (with automatic AOT!)
Other Use Cases:
2. Branded Application Launchers - Build yourapp.exe with jr-maven-plugin (name, icon, version, config baked in) and distribute it with the jar, or let it download the jar
3. Multi-Java Environments - Test JARs with different Java versions using -Xjr:java.home=
4. Complex Launch Configurations - Bake JVM settings, Java version and arguments into the app's exe
5. Desktop Shortcuts - Create shortcuts that work both ways (console and GUI)
6. Batch Scripts - Use in automation where you need proper exit codes
7. Individually manageable services/apps - Set jvm=dll so each app is its own named process you can kill, monitor or firewall on its own
Build test JAR first:
cd test-scripts
build-test-jar.batRun comprehensive tests:
cd test-scripts
TestJR.batRun the launch-mode tests (non-interactive, builds its own test JAR, prints
PASS/FAIL per check - covers both jvm=exe and jvm=dll):
cd test-scripts
TestJvmMode.batThis tests:
- Help display
- Traditional JAR launch
- Logging functionality
- AOT disable flag
Quick manual tests:
# Test help
jr.exe
# Test traditional mode
jr.exe test-scripts\TestStartupTiming.jar- Language: Java, compiled to C by TeaVM and to a native exe by llvm-mingw (see Java compiled to a native exe)
- Size: about 610 KB (x64)
- Dependencies: only DLLs that ship with Windows (kernel32, user32, the Universal C Runtime that is part of Windows 10 and 11, winhttp, bcrypt and a few more)
- Config: a jrc-json baked into the exe (an
RCDATA/JRCresource; a__DATA,__jrcsection on macOS), written by jr-maven-plugin - Behavior (
jvm=exe, default):- Console mode: Waits for process, returns exit code
- GUI mode: Launches and exits immediately
- Behavior (
jvm=dll):- Both modes: the JVM runs in the launcher process, which returns the application's exit code when the JVM is done
-
Console Detection: Uses Windows API to detect if the process has an attached console
AttachConsole(ATTACH_PARENT_PROCESS)- tries to attach to parent consoleGetConsoleMode()- checks if console already exists
-
Java Selection:
- Console detected → uses
java.exe - No console → uses
javaw.exe
- Console detected → uses
-
Java Location:
- If
java.homeis set (in the config or-Xjr:java.home=) → uses<java.home>\bin\java[w].exe - Otherwise → searches PATH environment variable
- If
-
Config Loading:
- Reads the jrc-json baked into its own exe; a file beside the exe is never read
- If there is none: traditional mode (the first argument is the jar)
-
AOT Cache Management (if enabled):
- Calculates AOT cache filename:
<jarname>.<size_base52>.<modtime_base52>.aot - Checks if cache exists for current JAR version
- If exists: passes
-XX:AOTCache=<path>to JVM - If not: passes
-XX:AOTCacheOutput=<path>to create new cache - Automatically cleans up outdated AOT files from previous JAR versions
- Calculates AOT cache filename:
-
Performance Timing:
- Records start time using high-resolution performance counter
- Records time before JVM invocation
- Passes
-Dio.github.jarrunner.jr.*properties:startMicros,beforeJvmMicros,exe(its own path), and the whole jrc-json, one property per leaf named by its path (app.id,app.version,update.url,jvm.vmArgs.0, ...), so an app can read its own config and show its own update notice (the C launcher,jr_legacy_c, still passes the oldjarrunner.start.micros/jarrunner.beforejvm.micros) - Java code can read these properties to measure launcher overhead
-
Execution:
- Constructs command:
"path\to\java.exe" [timing-props] [vm.args] [aot-cache] [java.args] [app.args] [cmdline-args] jvm=exe(default): runs it withCreateProcess()using handle inheritance for proper I/O, waits for completion and returns the same exit codejvm=dll: hands the identical command string to the JDK's ownJLI_CmdToArgs()+JLI_Launch()injli.dll, which loadsbin\server\jvm.dllinto this process. Same string in both modes, so argument parsing, quoting and precedence can not drift apart.
- Constructs command:
Each example is jr-maven-plugin configuration in the app's pom.xml (see the guide for the whole plugin block). mvn package then builds target/jr/<name>.exe with these settings baked in.
<configuration>
<name>webserver</name>
<vmArgs><vmArg>-Xmx1g</vmArg><vmArg>-Xms256m</vmArg></vmArgs>
<appArgs><appArg>--port</appArg><appArg>8080</appArg><appArg>--host</appArg><appArg>0.0.0.0</appArg></appArgs>
<javaVersion>25</javaVersion>
</configuration>webserver.exe<configuration>
<name>devtool</name>
<vmArgs><vmArg>-Xmx512m</vmArg><vmArg>-Ddev.mode=true</vmArg></vmArgs>
<aot>false</aot>
</configuration>Run with a custom JDK and a debug log, for one run:
devtool.exe -Xjr:java.home=C:\Java\jdk-21 -Xjr:log.file=devtool-debug.log -Xjr:log.overwrite=true<configuration>
<vmArgs><vmArg>-Xmx2g</vmArg></vmArgs>
<javaArgs>-cp lib/*;app.jar com.example.Main</javaArgs>
<appArgs><appArg>--config</appArg><appArg>production.xml</appArg></appArgs>
</configuration>vs Launch4j / WinRun4J:
- One exe with nothing to install alongside it (about 610 KB, or about 160 KB packed with UPX)
- Automatic AOT cache support (90% faster startup with JDK 25+)
- Automatic console/GUI detection (no manual config needed)
- Finds or downloads a suitable Java by itself
- Works without config files (can also work with config when needed)
- Actively maintained (Launch4j: 2017, WinRun4J: 2018, both inactive)
vs jpackage (bundled JRE approach):
- About 100x smaller (doesn't bundle a JRE - about 610 KB vs 50+ MB)
- Users can use any Java version they want
- Easier updates (just replace the JAR, no need to rebuild the entire package)
- Still gets AOT performance benefits with JDK 25+
vs GraalVM native-image:
- Your app stays an ordinary jar: no native-image build, no reflection or JNI configuration
- Much faster build times (only jr itself is compiled ahead of time, once, not your app)
- Flexibility to swap Java versions
- Works with all Java code
The Philosophy: jr doesn't try to hide that your app is Java. It embraces it. It just makes the execution experience feel native - double-click to run, automatic console handling, fast startup with AOT, executable from command line. Best of both worlds.
With JDK 25+ and AOT enabled:
First Run (creating AOT cache):
Startup: ~200-300ms (one-time cost)
Subsequent Runs (with AOT cache):
Startup: ~20-30ms (90% faster!)
Without AOT:
Startup: ~150-200ms (standard)
Launcher Overhead:
- jr overhead: ~2-3ms (measured via performance counters)
- Direct java.exe: 0ms baseline
- Overhead is negligible - AOT gains far outweigh it!
- No Embedded Paths: Executable doesn't contain build machine paths
- Portable: Can be moved between directories/systems
- No Telemetry: No data collection or phone-home features (see Privacy)
- Source Available: The full Java source is in this repository, and release builds are made from it by GitHub Actions
- Checksums: Each release carries
SHA256SUMS. The release exes are not code-signed;-Xjr:signsigns copies you brand yourself with your own certificate
This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. jr uses the network only for these, and only when asked to:
- Java auto-install: when no suitable Java is found, jr asks first (console Y/n or a dialog), and only on a yes contacts the Foojay Disco API and downloads an Eclipse Temurin JDK or JRE (on Windows on ARM64, an Azul Zulu build where Temurin publishes none). It can be turned off with
java.autoinstall=false. - Downloading the app's jar, when its config names a URL or Maven coordinates for it instead of a local file. The download is checked against the sha256 in the config.
- Update checks and self-update, only when run with
-Xjr:update-checkor-Xjr:update, from the update URL in the app's config.
Apache License 2.0 - see LICENSE.
Contributions welcome! Please ensure:
- Code follows existing style
- Test on Windows 10/11
- Update documentation for new features
aot=true in an app's config tells jr to build an AOT cache, but jr cannot decide what goes in it: the JVM
assembles the cache from whatever the training run happened to load. A cache trained on mytool --help is
worse than no cache at all, because naming a cache also switches off the default CDS archive.
jarrunner/aot is the Java side of that — a dependency-free library
(io.github.jarrunner:aot) an application uses to load itself on purpose during jr's training run.
It is what jr signals with JR_AOT_STATE=creating. See its README for how to wire it in, how to choose what to
load (measured: bigger is not automatically better), how to record method profiles as well as classes
(JEP 515), and how to build the cache in the Maven lifecycle.
Two things documented there that bite in jr itself:
- jr's AOT is jar-only, and that is a JVM restriction, not a jr one. The JVM refuses to dump a cache
when the classpath holds a non-empty directory (
Cannot have non-empty directory in paths). So a config withaot=truethat launches-cp target\classes;lib\*has never had a cache. Worth surfacing in jr: today it silently does nothing. - The cache is keyed on the jar's size and mtime (
<name>.<size>.<mtime>.aot), which is why it retrains automatically after a rebuild.
For issues, questions, or feature requests, please file an issue in the repository.