In this tutorial, we will look at 3 ways to package your Java project into a JAR file, so you can ship your application to your users.
A JAR file is an archive that contains compiled Java source code and other things needed to run your program. With a functioning JAR, your user should only need a Java Runtime to run your code. They shouldn't need to compile your code by opening up an IDE or using a build tool. This makes it easy to deploy on different platforms. Hence, Java's slogan "Write once, run anywhere".
1. Building a single JAR
When your project is simple and you don't have many dependencies, building a JAR from your project is very easy. The jar
task on Gradle is enough. Just make sure your build.gradle
has your application's entry point (main class/main method) defined.
jar {
// this is necessary to run your JAR
manifest {
attributes 'Main-Class': 'yourpackages.morepackages.YourMainClass'
}
// the rest is to access resource files like images, etc.
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
from {
configurations.runtimeClasspath.collect { it.isDirectory() ? it : zipTree(it) }
}
}
Then run this on the command line.
gradle jar
Your JAR file is produced inside the directory depending on your project IDE. For projects initialized with gradle
only, that is build/libs/
.
2. Building a JAR and delivering it with other JARs
It is possible that a fat JAR cannot be produced for reasons outside of your control. Fat JARs are supposed to contain everything you need to run the program, besides the Java Runtime. But sometimes, a certain dependency creates a problem with the building process. For example, building a Java project with JavaFX creates problems when attaching the JavaFX runtime to your JAR.
To remedy this, you can deliver several JARs at once and provide a script that launches the Java Runtime properly by referencing the third-party JARs.
A. Acquire the third-party JARs
For every third-party JARs you cannot integrate into your JAR, get the version of those JARs that you need. For example, download a version of the JavaFX runtime JAR to your computer.
B. Build your JAR alone
This step is similar to the situation where you build a single JAR.
C. Write a shell script (aka command-line script)
A shell script is a file that contains commands that you would run interactively on the command line. Instead of typing every command by hand one by one, you can write them into a file and run the file through the command line. The language of a shell depends on the system you intend to deploy your Java project. Here is a short list of commonly found shell languages.
- Windows:
- Batch (.bat)
- Bash (.sh), if Git Bash is installed
- Mac:
- Z Shell (.zsh)
- Bash (.sh), if the Mac is set up properly
- Linux:
- Bash (.sh)
Begin your shell script with a shebang. This tells the command line what the file is. For example, the following shebang is for a Bash file. It must always be the first line of a shell script.
#!/bin/bash
Create a shell script. Usually, they are named run.sh
or execute.sh
. Inside it, you call the Java Runtime while referencing the third-party libraries' JARs and your JAR.
java --module-path path/to/your/third-party-JARs --add-modules module.you.need,second.module.you.need -jar your-project/build/libs/YourOwnJAR.jar
In this command, we call java
by giving it a module path. The parameter path/to/your/third-party-JARs
you supply here should be the location where you store your third-party JARs. Since we are deploying, we expect the JARs to be located in the same folder as the shell script. Therefore, we can use relative paths, e.g. javafx-sdk-20.0.1/lib
. This assumes you moved the JavaFX folder next to your shell script.
Example file setup
your-current-working-directory/
| YourOwnJAR.jar
| javafx-sdk-20.0.1/
| | lib/
| | | ... lots of JARs
|
| run.sh
Example run.sh
for a JavaFX project
#!/bin/bash
java --module-path javafx-sdk-20.0.1/lib --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media -jar YourOwnJar.jar
Don't forget to grant permission to the script with chmod
.
chmod +x run.sh
To deliver this to your user, you would zip your-current-working-directory
and send the archive. You would notify your user to unzip the archive and run the shell script by double-clicking it or through the command line with ./run.sh
. This assumes your user has the appropriate shell language and Java Runtime.
3. Delivering a native application
This method is unlike the other two because it does not require the user to have anything installed, not even a Java Runtime! For situations where you want to deliver maximum application independence, this should be your go-to solution. For example, if you are dealing with people who have no idea what a shell script is or even what coding is, you should be sending everything as a self-contained double-clickable program.
The way this last method works is by shipping the Java Runtime with your JAR and dependencies. For those who don't know, the Java Runtime is an application designed to run compiled Java code on a specific operating system. As developers, we use the runtime that comes with the Java Development Kit (JDK). Two limitations of this method are the rather large deployment binary and the breaking of the slogan "Write once, run anywhere".
We will make use of the running example. This method builds upon Method 2.
A. Put all of your JARs (third-party or not) into a folder with your shell script
This step is the same as all of Method 2.
B. Download a copy of the Java Runtime Environment (JRE)
Next, you need to download a version of the Java Runtime. Head over to a distributor like the Eclipse Foundation and download a JRE that matches the version of your JDK. Although you can ship the JDK to your user, the file size would be very large (200+ MB) and it would contain many features that your user will never use. That's why we only need the JRE (40+ MB).
C. Move the JRE into your bundling folder
Assuming you have the same file structure from Method 2, you only need to move the unzipped JRE into your folder. The final file structure should look like this.
Example bundling folder structure
your-bundling-directory/
| jre/ # <------------------------ moved here
| YourOwnJAR.jar
| javafx-sdk-20.0.1/
| | lib/
| | | ... lots of JARs
|
| run.sh
D. Edit the shell script
After being bundled (in later steps), the shell script cannot be directly run by the user clicking on it. As such, we need to make the script more independent.
One dependence that the script from Method 2 has is the assumption that the user has the java
command installed on their machine. This time, we don't make this assumption and use the java
from the Java Runtime copied to your-bundling-directory/jre/
.
Shell scripts like Bash are also dependent on where the user calls them from. After being bundled, the user no longer calls the run.sh
script directly. But it is still called by the bundling tool's runtime service when the user clicks on the executable. Therefore, we need to make sure the paths inside the script are all relative to the script's location.
In Bash, there is a special variable called BASH_SOURCE
which contains the path to the directory where the Bash script is located. We will use this as a way to have relative paths.
Declare a variable in your run.sh
called HERE
. Pay attention to the spacing around the assignment operator =
. It matters in Bash!
HERE=${BASH_SOURCE%/*}
In the above assignment, we make use of another Bash feature, string manipulation. This is done with the curly braces. In our case, we use the percent symbol %
to truncate the /
symbol and everything after inside the variable. *
is the wild card operator from regular expressions. Since BASH_SOURCE
contains a path to a directory, it ends with a slash on Linux and we don't want that.
Modify the java
command of your run.sh
.
"$HERE/jre/bin/java" --module-path "$HERE/javafx-sdk-20.0.1/lib" --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media -jar "$HERE/YourOwnJAR.jar" "$@"
Now, all the paths starts with the $HERE
variable, which means it is all relative to the location of the run.sh
script. In Bash, we reference variable using the $
symbol followed by the name of the variable. Notice here we put all the paths containing $HERE
in double quotes. That is to take care of potential spaces inside path names, such as "Program Files".
You may also notice the last argument is "$@"
. This is also one of the default variables in Bash. $@
is a special variable that represents all the parameters the run.sh
script has received through the command line. If your Java application takes command line arguments, this is absolutely necessary. Otherwise, it doesn't hurt to have it. This special variable is also enclosed in double quotes, because some arguments may contain white space themselves and that can cause argument splitting issues.
In summary, this is what a run.sh
can look like for independent bundling.
#!/bin/bash
HERE=${BASH_SOURCE%/*}
"$HERE/jre/bin/java" --module-path "$HERE/javafx-sdk-20.0.1/lib" --add-modules javafx.controls,javafx.fxml,javafx.graphics,javafx.media -jar "$HERE/YourOwnJAR.jar" "$@"
Don't forget to test your shell script. Assuming you are outside the bundling directory, you can run the script through the command line.
./bundle/run.sh
E. Use warp-packer
to produce a binary
Download the warp-packer
tool to your system.
If you put the tool next to your bundling directory, then you can run the following commands.
./warp-packer --arch linux-x64 --input_dir your-bundling-directory --exec run.sh --output app.bin
chmod +x app.bin
In the first command,
-
--arch
: the architecture you are deploying to.linux-x64
is the Linux operating system withx64
hardware. -
--input_dir
: the bundling directory you just prepared all this time -
--exec
: the executable shell script that runs when the binary is clicked -
--output
: the name of the produced binary with an extension of your choosing.
The second command grants permission to run the binary.
Test your binary.
./app.bin
In the JavaFX example, the binary size is about 108M for one of my students' projects. This is quite expected if you have resources like images in your Java project. Even after warp-packer
compresses your files, most of the space is still taken by the Java Runtime Environment.
Competing tools for bundling Java
In a previous version of this article, I recommended jlink
and jpackage
for bundling Java into a native application. For simple applications, that can still work. However, these default tools in Java are no longer as reliable and as flexible as before. You can still find tutorials on them, but they only teach you how to bundle "Hello World"-level apps with little dependencies. This article dives deeper into software deployment with problematic Java dependencies such as JavaFX. As of the update of this article, I still couldn't get the default JDK tools to work with JavaFX.
Conclusion
In this blog, I explained 3 ways of deploying your Java project. Each method depends on your target user base. If they are okay with having some installed software on their machine. Delivering a JAR or a group of JARs + script is an acceptable solution. However, if you cannot expect your user to have any software installed, you should bundle everything into a standalone executable.
Top comments (0)