Repository files navigation

Public Service Announcement: With packr v2.0, command line interfaces to both packr.jar and the native executable have changed, as well as the format of minimize profiles! If you upgrade from a previous version, please read this documentation again to make sure you've updated your configuration(s) accordingly.

Packages your JAR, assets and a JVM for distribution on Windows, Linux and Mac OS X, adding a native executable file to make it appear like a native app. Packr is most suitable for GUI applications, such as games made withlibGDX.

The latest build is available fordownload here.

You point packr at your JAR file(s) containing your code and assets, some configuration parameters, and a URL or local file location to a JDK build for your target platform.

Invoking packr from the command line may look like this:

java -jar packr.jar \     --platform mac \     --jdk openjdk-1.7.0-u45-unofficial-icedtea-2.4.3-macosx-x86_64-image.zip \     --executable myapp \     --classpath myapp.jar \     --removelibs myapp.jar \     --mainclass com.my.app.MainClass \     --vmargs Xmx1G \     --resources src/main/resources path/to/other/assets \     --minimizejre soft \     --output out-mac

Alternatively, you can put all the command line arguments into a JSON file which might look like this:

{"platform":"mac","jdk":"/Users/badlogic/Downloads/openjdk-1.7.0-u45-unofficial-icedtea-2.4.3-macosx-x86_64-image.zip","executable":"myapp","classpath": ["myapp.jar"    ],"removelibs": ["myapp.jar"    ],"mainclass":"com.my.app.MainClass","vmargs": ["Xmx1G"    ],"resources": ["src/main/resources","path/to/other/assets"    ],"minimizejre":"soft","output":"out-mac"}

You can then invoke the tool like this:

java -jar packr.jar my-packr-config.json

It is possible to combine a JSON configuration and the command line. For single options, the command line parameter overrides the equivalent JSON option. For multi-options (e.g.classpath orvmargs), the options are merged.

This is an example which overrides the output folder and adds another VM argument. Note that the config file name is delimited by-- because the option prior to it,--vmargs, allows multiple arguments:

java -jar packr.jar --output target/out-mac --vmargs Xms256m -- my-packr-config.json

Finally, you can use packr from within your Java code. Just add the JAR file to your project, either manually, or via the following Maven dependency:

<repositories>  <repository>    <url>https://oss.sonatype.org/content/repositories/snapshots</url>    <snapshots>      <enabled>true</enabled>    </snapshots>  </repository></repositories><dependency>   <groupId>com.badlogicgames.packr</groupId>   <artifactId>packr</artifactId>   <version>2.1</version></dependency>

To invoke packr, you need to create an instance ofPackrConfig and pass it toPackr.pack():

PackrConfigconfig =newPackrConfig();config.platform =PackrConfig.Platform.Windows32;config.jdk ="/User/badlogic/Downloads/openjdk-for-mac.zip";config.executable ="myapp";config.classpath =Arrays.asList("myjar.jar");config.removePlatformLibs =config.classpath;config.mainClass ="com.my.app.MainClass";config.vmArgs =Arrays.asList("Xmx1G");config.minimizeJre ="soft";config.outDir =newjava.io.File("out-mac");newPackr().pack(config);

A standard OpenJDK JRE weighs about 90 mb unpacked. Packr helps you cut down on that size, thus also reducing the download size of your app.

To minimize the JRE that is bundled with your app, you have to specify a minimization configuration file via theminimizejre flag you supply to Packr. A minimization configuration is a JSON file containing paths to files and directories within the JRE to be removed.

As an example, have a look at thesoft profile configuration:

{"reduce": [    {"archive":"jre/lib/rt.jar","paths": ["com/sun/corba","com/sun/jndi","com/sun/media","com/sun/naming","com/sun/rowset","sun/applet","sun/corba","sun/management"      ]    }  ],"remove": [    {"platform":"*","paths": ["jre/lib/rhino.jar"      ]    },    {"platform":"windows","paths": ["jre/bin/*.exe","jre/bin/client"      ]    }  ]}

This configuration will unpackrt.jar, remove all the listed packages and classes incom.sun.* andsun.*, then repackrt.jar again. By default, the JRE uses zero-compression on its JAR files to make application startup a little faster, so this step will reduce the size ofrt.jar substantially.

Then, rhino.jar (about 1.1MB) and, in case of a Windows JRE, all executable files injre/bin/ and the folderjre/bin/client/ will be removed.

Packr comes with two such configurations out of the box,soft andhard. Thehard profile removes a few more files, and repacks some additional JAR files.

There's also a new,experimental configuration,oraclejre8, which reduces size of an Oracle 8 JRE following Oracle's redistribution rules describedhere. It also repacks JAR files, reducing (unpacked) JRE size from about 180 mb to 70 mb.This version is pretty much untested, so please use with care!

Minimization aside, packr can remove all dynamic libraries which do not match the target platform from your project JAR file(s):

This step is optional. If you don't need it, just remove the configuration parameter to speed up packr.

Extracting and minimizing a JRE can take quite some time. If thecachejre option is used, the result of these operations is cached in the given folder, and can be reused in subsequent runs of packr.

As of now, packr doesn't do any elaborate checks to validate the content of this cache folder. So if you update the JDK, or change the minimize profile, you need to empty or remove this folder manually to force a change.

When packing for Windows, the following folder structure will be generated

outdir/   executable.exe   yourjar.jar   config.json   jre/

Linux

outdir/   executable   yourjar.jar   config.json   jre/

Mac OS X

outdir/   Contents/      Info.plist      MacOS/         executable      Resources/         yourjar.jar         config.json         jre/         icons.icns [if config.icon is set]

You can further modify the Info.plist to your liking, e.g. add icons, a bundle identifier etc. If youroutput folder has the.app extension it will be treated as an application bundle by Mac OS X.

By default, the native executables forward any command line parameters to your Java application's main() function. So, with the configurations above,./myapp -x y.z is passed ascom.my.app.MainClass.main(new String[] {"-x", "y.z" }).

The executables themselves expose an own interface, which has to be enabled explicitly by passing-c or--cli as thevery first parameter. In this case, the special delimiter parameter-- is used to separate the native CLI from parameters to be passed to Java. In this case, the example above would be equal to./myapp -c [arguments] -- -x y.z.

Try./myapp -c --help for a list of available options. They are also listedhere.

Note: On Windows, the executable does not show any output by default. Here you can usemyapp.exe -c --console [arguments] to spawn a console window, making terminal output visible.

If you want to modify the Java code only, it's sufficient to invoke Maven.

mvn clean package

This will create apackr-VERSION.jar file intarget which you can invoke as described in the Usage section above.

If you want to compile the native executables, please followthese instructions. Each of the build scripts will create executable files for the specific platform and copy them to src/main/resources.

• Icons aren't set yet on Windows and Linux, you need to do that manually.
• Minimum platform requirement on MacOS is OS X 10.7.
• JRE minimization is very conservative. Depending on your app, you can carve out stuff from a JRE yourself, disable minimization and pass your custom JRE to packr.
• On MacOS, the JVM is spawned in its own thread by default, which is a requirement of AWT. This does not work with code based on LWJGL3/GLFW, which needs the JVM be spawned on the main thread. You can enforce the latter with adding the-XstartOnFirstThread VM argument to your MacOS packr config.

The code is licensed under theApache 2 license. By contributing to this repository, you automatically agree that your contribution can be distributed under the Apache 2 license by the author of this project. You will not be able to revoke this right once your contribution has been merged into this repository.

Distributing a bundled JVM has security implications, just like bundling any other runtimes like Mono, Air, etc. Make sure you understand the implications before deciding to use this tool. Here's adiscussion on the topic.