Jar-Files Guide

1.1 Change References to Static Files

Static files like images, FXML and stylesheets that should be included in jar-files have to be referenced in a special way to work both in your current project and in jar-files.

First, find all usages of the following constructors/methods:

Constructors/Methods in the first block need an URL while those in the second block need a String. In place of URL and String, use:

The "path/to/file.png" should be the path to the file from the root of your project (without / as prefix). If you are unsure about the paths, then you can use the Jar-File/JavaFX Reference Tool.

Extra: Link to the documentation if you want to explorer it: https://openjfx.io/javadoc/19/overview-tree.html

Next step

• Part 2: [Eclipse] Export jar-File
• Part 3: [Eclipse] Export jar-File (With External jar-Files)
• Part 4: [InteliJ] Export jar-File
• Part 5: [VSCode] Export jar-File
• Part 6: [Terminal] Create jar-File (Same Source and Class Folders)
• Part 7: [Terminal] Create jar-File (Different Source and Class Folders)

2.1 Select Export Project

Right-click on your project in Eclipse and select Export... in the drop down.

2.2 Choose JAR File

In the dialog, choose Java > JAR file and then click Next >.

2.3 Export Dialog

The next dialog shows the export settings. There are a lot of things here:

1. Choose the files you want to export in the upper left area.
2. (OPTIONAL) Uncheck the unneeded files like .classpath and .project in the upper right area.
3. Ensure that both Export generated class files and resources and Export Java source files and resources are checked such that all java-files, class-files and media files are exported.
4. Under Select the export destination, select where to place the jar-file.
5. Finally, click on Next >.

2.4 Jar Packing Options

In the next dialog, just ensure that both check boxes at the top (Export class files with compile errors/warnings) are checked and click Next >.

2.5 Manifest

In the final dialog, ensure that Generate the manifest file is selected. Afterwards select the Main class (the class you run/start the application with). Click Finish to create your jar-file!

There might come some dialogs about overwriting files or other unimportant warnings. You most likely just need to click on Yes or Ok.

Next step

• Part 9: Check Contents of jar-File

3.1 Select Export Project

Right-click on your project in Eclipse and select Export... in the drop down.

3.2 Choose Runnable JAR File

In the dialog, choose Java > Runnable JAR file and then click Next >.

3.3 Export Dialog

In the next dialog, select the name of the run configuration that you use to run the code for Launch Configuration. Next, select an Export destination. For Library handling, make sure Package required libraries into generated JAR is checked. Finally, click Finish to create the jar-file.

Note: The jar-file does NOT contain any source files!

Input: Name of the (created) jar-file.

3.4 Include java-Files

The created jar-file does not contain the source files. In order to include them, move the jar-file to the root folder of your Eclipse project. You can find the folder by expanding your project, right-click on the src folder and select Properties in the (bottom of the) drop down. When you have it, paste it below (remember to remove src from the path) and go to Part 8.

Input: Path to the root folder of the project WITH TRALING SLASH.

Next step

• Part 8: Update jar-File

4.1 Open Project Artifacts

In the top menu, choose File and in the dropdown choose Project Structure.... In the newly opened dialog, choose Project Settings > Artifacts in the left sidebar. Next, click on the and in the dropdown choose JAR > From module with dependencies. In the small dialog, select a Main Class (the one you use to run you application). Afterwards, click on OK. The right side should now show a list with content for the jar-file, which should include the jar-file an a sub-item saying '...' compile output.

4.2 Add Source Files

In the top of the right side, select a Name for your jar-file and enter it below:

Input: Name of the (created) jar-file.

Next, click on the (with a small ) right above the items mentioned in the previous step and in the dropdown choose Module Source. In the very small dialog, choose the current project (usually the default) and click OK.

(OPTIONAL) ONLY IF YOU USE EXTERNAL jar-FILES! Click on the again and in the dropdown choose Extracted Directory. Find the jar-file and click OK. Repeat for each external jar-file.

Finish by clicking on OK (in the previous large dialog).

4.3 Build jar-File

In the top-menu, choose Build and in the dropdown Build Artifacts.... In the mid-window dropdown, choose

<jar-filename>

> Build. Then wait... After some time, it the jar-file will be placed in the folder out/artifact in the left sidebar.

Next Step

• Part 9: Check Contents of jar-File

5.1 Avoid Preview features are not enabled Error

In the top-level project folder, create a folder called .settings. In that, create a file called org.eclipse.jdt.core.prefs and add the following content to it:

5.2 Create jar-File

Open the command palette (Windows/Linux: Ctrl + Shift + P, MacOS: ⇧ + ⌘ + P) and find the option Java: Export Jar....

Next, it asks for the main class - choose the one you use to launch your application.

It might also ask which elements to export in case there are more than one. Make sure to include all.

Now, the jar-file is created at the top-level folder of the project (see the left sidebar).

5.3 Include java-Files

The created jar-file does not contain the source files. Find the path to your project (not the src folder), paste it below and go to Part 8.

Input: Path to the root folder of the project WITH TRALING SLASH.

Next Step

• Part 8: Update jar-File

6.1 Pre-Requirements

It is assumed that your source files (java-files) and class-files are in the same folders in your projects. For example Main.java would be in the same folder as Main.class. IF THIS IS NOT THE CASE, go to Part 7.

Open a terminal at the top-level (root) of your project i.e. open a terminal and run:

6.2 Create Manifest File

Create a manifest file in the folder

<project-path>

and name it

manifest.mf

. It should have the following contents:

IMPORTANT: Remember an empty line at the end of the file!

<main-class>

should point to the class that starts the application. If your file is NOT in a package, then simply use the name of the file without the .java-extension. For example write Launcher if the file is called Launcher.java. If your file is in a package and the package is called app.view and your class is called MyView then use with app.view.MyView.

6.3 Create jar-File

The command below will create (c) a jar-file with the filename (f)

<jar-filename>

that includes all files (*). It will include the manifest file

manifest.mf

(m) and list all the added files and directories (verbose v). Run the command:

You should now see all the added files i.e. something like:

Note: Files like SetupController$1.class (with $ and a number) should also be included!

Extra: If you want to only select files with certain file extensions, you can replace * in the above command with for example *.java *.class to select all java-files and class-files.

You have now created a runnable jar-file that also includes source files!

Next step

• Part 9: Check Contents of jar-File

7.1 Pre-Requirements

It is assumed that your source files (java-files) and class-files are separated in two different folders (

src

and

bin

) in your project. For example if Main.java is in

src

/<folder> then Main.class would be in

bin

/<folder>. IF THIS IS NOT THE CASE, go to Part 6.

Open a terminal at the top-level (root) of your project i.e. open a terminal and run:

7.2 Create Manifest File

Create a manifest file in the folder

<project-path>

and name it

manifest.mf

. It should have the following contents:

IMPORTANT: Remember an empty line at the end of the file!

<main-class>

should point to the class that starts the application. If your file is NOT in a package, then simply use the name of the file without the .java-extension. For example write Launcher if the file is called Launcher.java. If your file is in a package and the package is called app.view and your class is called MyView then use with app.view.MyView.

7.3 Create jar-File

The command below will create (c) a jar-file with the filename (f)

<jar-filename>

that includes all files in the

src

folder (-C

src

.). It will include the manifest file

manifest.mf

(m) and list all the added files and directories (verbose v). Run the command:

You should now see all the added source files i.e. something like:

The class-files have to be added by updating the jar-file with the command below. The command updates (u) an existing jar-file with the filename (f)

<jar-filename>

and lists all the added files and directories (verbose v). It adds all files from the

bin

folder at the same level as the

src

folder and thus merges the two directories in the resulting jar-file. Run the command:

You should now see all the added class-files:

Note: Files like SetupController$1.class (with $ and a number) should also be included!

Note: You can only select ALL FILES in both folders and merge them this way or you will have to add the files one by one.

You have now created a runnable jar-file that also includes source files!

Next step

• Part 9: Check Contents of jar-File

8.1 Pre-Requirements

It is assumed that you have a jar-file (

<jar-filename>

) located in your project (

<project-path>

).

Open a terminal at the top-level (root) of your project i.e. open a terminal and run:

8.2 Update jar-File

Note: In the commands below, replace . with *.java, *.class, *.java *.class or similar to only include certain files. In addition, existing files in the jar-file are overwritten if two files have the same path and name.

If the files you want to add are located in a folder (like

src

), then use the following command:

The command updates (u) an existing jar-file with the filename (f)

<jar-filename>

and lists all the added files and directories (verbose v). It adds all files from the

src

folder assuming it is the root i.e. the file

src

/Main.java is placed in jar-file as Main.java.

If (some of) the files you want to add are located in the root, then use the following command:

Does the same as above except it uses the root folder rather than

src

i.e.

src

/Main.java is placed in jar-file as

src

/Main.java.

Next step

• Part 9: Check Contents of jar-File

9.1 Pre-Requirements

Open a terminal in the folder where the jar-file (

<jar-filename>

) is located.

9.2 Check jar-File

To check that all files are included, run the command below that lists (t) all files in the jar-file with filename (f)

<jar-filename>

:

You should get something like:

PLEASE CHECK that all (needed) files in your project are in the jar-file! ALSO CHECK that each java-file has its corresponding class-file(s)! There may be classes like SetupController$1.class which is fine!

Next step

• Part 10: Run jar-File (Built-in JavaFX)
• Part 11: Run jar-File (External JavaFX)

10.1 (OPTIONAL) Check if JavaFX is Built-in

SKIP THIS STEP IF YOU KNOW THAT YOUR JAVA VERSION HAS JavaFX!

To avoid problems, it is checked if the given java-version has JavaFX built-in. The command below will list the modules and then pipe them to a command (find or grep) that extracts the lines of interest:

If you see output like below, then JavaFX is built-in and you can continue to Step 10.2:

If you do not get any output, then the given java-version does not have built-in JavaFX. Check that you used the correct path (use the inputs above)! If you followed the JavaFX Setup Guide, then use the path to the JDK from that guide. Otherwise, have a look at Part 11.

10.2 Move jar-File

It is a very good idea to move the jar-file to a directory outside your project folder to ensure that you can run the jar-file without the need of files that only exist on your system. Navigate to the directory where you moved the file

<jar-filename>

to.

10.3 Run jar-File

Run the jar-file using the following command:

You can also run your application with command line arguments by adding them at the end of the command. Examples:

In Case of Errors

• Part 12: Common Problems

11.1 Pre-requirements

You will need to have a JavaFX SDK (Software Development Kit) on your computer. In case you do not have one then download it here: https://gluonhq.com/products/javafx/ . Make sure to pick the one for your OS (and architecture) and the one saying SDK! Choose, if possible, the same version as your JDK and otherwise a version lower than your JDK. Remember to fill out the path to the unpacked lib folder above.

11.2 Move jar-File

It is a very good idea to move the jar-file to a directory outside your project folder to ensure that you can run the jar-file without the need of files that only exist on your system. Navigate to the directory where you moved the file

<jar-filename>

to.

11.3 Run jar-File

Run the jar-file using the following command:

You can also run your application with command line arguments by adding them at the end of the command. Examples:

Note: Please note that we use a subset of modules and that some modules require other modules that are automatically included.

In Case of Errors

• Part 12: Common Problems

12.1 Java not Found

If you get errors like XXX is not recognized as an internal or external command, operable program or batch file (Windows) or No such file or directory (Unix/Linux) then check that you path to your Java-version is correct. Use the input fields! Eventually checkout Terminal Guide.

12.2 javafx/application/Application not Found

Your should NOT get this error with Built-in JavaFX. Check that you path to your Java-version is correct. Use the input fields! If you get something like the following error (with javafx):

Then have a look at Part 11.

12.3 Missing Files Error

If you get an error like this:

or anything that mentions anything about a missing file then your are most likely referencing the files locally in your file system. Have a look at Part 1.

12.4 I Cannot Double-Click to Run the jar-File!

The reason is (most likely) that you system is set to use a specific Java-version (most likely 8) that does not have JavaFX included. If double-click should work, you would have to change the default action on double-click and make it run a command that is similar to the one you use to run the jar-file (see commands in Part 10 and/or Part 11). I do not recommend this, since:

• you may forget that you changed it
• it only works on your computer
• it is difficult to change it
• and it may break other jar-files (since they expect Java 8) if you ever need to run one.

What people typically do in is to bundle a JRE together with their jar-file(s) such that they KNOW that it works. Maple is a good example (look for the directories java and jre) for doing this. The downside is that the JRE typically takes up a great amount of space making your application much larger (more than 100-200 MB larger).

12.5 My Friend Cannot Run the jar-File!

No, because he/she (most likely) does not have a Java-version with JavaFX or does not have the external JavaFX SDK module. They have to go through the same (trouble) as you did in Part 10 and/or Part 11. So unfortunately, you cannot share your jar-files with JavaFX easily - except if you also share a JDK with built-in JavaFX and include a bat or bash script to run it.