1. Overview
In this tutorial, we’ll start by learning how to package a Java program into an executable Java ARchive (JAR) file. Then, we’ll see how to generate a Microsoft Windows-supported executable file using that executable JAR.
We’ll use the jar command-line tool that comes with Java for creating JAR files. We’ll then learn to use the jpackage tool, available with Java 16 and later versions as jdk.jpackage, to generate an executable file.
2. Basics of the jar and the jpackage Commands
A JAR file is a container for compiled Java class files and other resources. It’s based on the popular ZIP file format.
An executable JAR file is also a JAR file but contains a main class as well. The main class is referenced in a manifest file, which we’ll discuss shortly.
In order to run an application delivered in a JAR format, we must have a Java Runtime Environment (JRE).
Unlike JAR files, a platform-specific executable file can run natively on the platform it was built for. For example, that platform could be Microsoft Windows, Linux, or Apple macOS.
For a good end-user experience, it’s preferred to provide clients with a platform-specific executable file.
2.1. The jar Command
The general syntax for creating a JAR file is:
jar cf jar-file input-file(s)
Let’s go through some options that can be used when creating a new archive with the jar command:
- c specifies that we want to create a JAR file
- f specifies that we want the output to go to a file
- m is used to include manifest information from an existing manifest file
- jar-file is the name that we want for the resulting JAR file. JAR files are generally given a .jar extension, but it’s not required.
- input-file(s) is a space-separated list of filenames that we want to include in our JAR file. The wildcard * can be used here as well.
Once we create a JAR file, we’ll often be checking its contents. To view what a JAR file contains, we use the following syntax:
jar tf jar-file
Here, t indicates that we want to list the contents of the JAR file. The f option denotes that the JAR file that we want to check is specified on the command line.
2.2. The jpackage Command
The jpackage command-line tool helps us generate installable packages for modular and non-modular Java applications.
It uses the jlink command to generate a Java Runtime Image for our application. As a result, we get a self-contained application bundle for a specific platform.
Since the application packages are built for a target platform, that system must contain the following:
- the application itself
- a JDK
- a software that is needed by the packaging tool. For Windows, jpackage requires WiX 3.0 or later.
Here’s the commonly-used form of the jpackage command:
jpackage --input . --main-jar MyAppn.jar
3. Creating Executable Files
Now let’s go through creating an executable JAR file. Once that’s ready, we’ll work on generating a Windows executable file.
3.1. Creating an Executable JAR File
Creating an executable JAR is fairly simple. We’ll first need a Java project with at least one class with the main() method. We created a Java class named MySampleGUIAppn for our example.
The second step is to create a manifest file. Let’s create our manifest file as MySampleGUIAppn.mf:
Manifest-Version: 1.0
Main-Class: MySampleGUIAppn
We have to make sure there’s a newline at the end of this manifest file for it to work correctly.
Once the manifest file’s ready, we’ll create an executable JAR:
jar cmf MySampleGUIAppn.mf MySampleGUIAppn.jar MySampleGUIAppn.class MySampleGUIAppn.java
Let’s view the contents of the JAR that we created:
jar tf MySampleGUIAppn.jar
Here’s a sample output:
META-INF/
META-INF/MANIFEST.MF
MySampleGUIAppn.class
MySampleGUIAppn.java
Next, we can run our JAR executable via a CLI or in a GUI.
Let’s run it on the command line:
java -jar MySampleGUIAppn.jar
In a GUI, we can simply double-click the relevant JAR file. That should launch it normally as any other application.
3.2. Creating a Windows Executable
Now that our executable JAR is ready and working, let’s generate a Windows executable file for our sample project:
jpackage --input . --main-jar MySampleGUIAppn.jar
This command takes a short while to complete. Once completed, it produces an exe file in the current working folder. The executable’s file name will be concatenated with the version number mentioned in the manifest file. We’ll be able to launch it just like any other Windows application.
Here are some more Windows-specific options that we can use with the jpackage command:
- –type: to specify msi instead of the default exe format
- –win-console: to start our application with a console window
- –win-shortcut: to create a short-cut file in the Windows Start menu
- –win-dir-chooser: to let an end-user specify a custom directory to install the executable
- –win-menu –win-menu-group: to let an end-user specify a custom directory in the Start menu
4. Conclusion
In this article, we learned some basics about JAR files and executable JAR files. We also saw how to convert a Java program into a JAR executable, and later into a Microsoft Windows-supported executable file.
As always, the source code for the examples is available over on GitHub.