Java | Using JPackage (Quick-Start Guide for Windows)

Hey there! This won’t be one of our typical blogposts. These last couple of days, we’ve been trying to make a build of Robot Farm for internal testing and needed a way to quickly make builds to send out to our team. We ended up using jpackage, and since the documentation on it is still sparse due to how new it is, we thought we’d add to the pile with our own basic step-by-step guide.

Overview

JPackage is a tool that comes with every JRE that allows you to bundle together a runnable JAR with a JRE. This is so that your users can simply download your program and run it with an EXE file, instead of ever having to fool with Java itself. You can either set it up to export an installer, or you can have it export a more portable program that you can just zip up and send out, which is what we’ll be doing.

Step-by-Step

The command is accessed through your command line tool on Windows - we suggest making sure to elevate it to administrator mode before starting or you can sometimes get access denied errors while using it. For the sake of this tutorial, we’ll be making a portable program that doesn’t require an installer.

Step one. First export your runnable JAR and place it in a folder. We’ll be using a folder called “input” and assuming you placed it on your desktop. Anything included in this folder will be copied over into the bundled program’s “app” folder.

Step two. Open Command Prompt (elevate to Administrator access), and use the following multi-line command, and wait for it to finish:

jpackage ^
--input C:\Users\YourName\Desktop\input ^
--dest C:\Users\YourName\Desktop\output ^
--name “Hello World” ^
--main-jar HelloWorld.jar ^
--main-class com.nokoriware.test.HelloWorld ^
--type app-image

Note: If the jpackage command isn’t recognized, try replacing the first line with the full path to the program instead. It’d be something like this, depending on where you have your JDK installed:

"C:\Program Files\Java\jdk-16.0.2\bin\jpackage.exe" ^

Step three. And that’s it! You have a working bundled program. That wasn’t so bad, was it? Your output folder should look something like this:

From here, you’ll want to tweak the command to include more instructions on what to include, depending on whatever your particular setup requires.

Additional Commands & Descriptions

Below are some of the commands you can use with jpackage, along with some basic descriptions. You can use the one supplied as a template and just add these as extra lines.

--win-console = This command will open a console up with your program; place it directly under the main-jar command or it will complain
--app-version = Use this to include what version your program is as a part of the EXE file
--copyright = Allows you to set the copyright on the EXE file
--arguments = Set arguments to pass into main() at startup
--java-options = Set Java Options to pass into the program at startup
--icon = Will allow you to set the .ico file the EXE uses

A complete list of the arguments available for JPackage in Java18 can be found here:

JPackage Command Options

Article last updated on March 28, 2024