About

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

On the topic of games, Packr version 2.4.2+ supports Java 14 and the Z garbage collector has been verified to work. Because who doesn't want GC pause times guaranteed to not exceed 10ms with work in progress for sub 1ms GC pauses. When bundling Java 14+ make sure to use --useZgcIfSupportedOs instead of passing --vmargs XX:+UseZGC because versions of Windows before Windows 10 1803 are not supported by the Z garbage collector.

Starting with Java 14, there's a new tool that is included with the JDK called jpackage. There's a lot of overlap between jpackage and packr. Considering jpackage is supported by the broader OpenJDK community, it's worth looking into. It might be a better solution for your product. There's also Conveyor which can build self-updating packages, do signing and notarization, and cross-build (Windows/Mac packages from Linux, Linux/Mac from Windows etc). It's free for open source projects but requires payment for commercial projects.

Download

The latest build is available for download here.

Resource artifacts are available at Maven Central

Until Maven central publishing is working, the following Maven repository is available:
- http://artifactory.nimblygames.com/artifactory/ng-public/

Usage

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 the following. For a more complete example look at the PackrAllTestApp/packrAllTestApp.gradle.kts:

java -jar packr-all.jar \
     --platform mac \
     --jdk OpenJDK11U-jre_x64_mac_hotspot_11.0.10_9.tar.gz \
     --useZgcIfSupportedOs \
     --executable myapp \
     --classpath myjar.jar \
     --mainclass com.my.app.MainClass \
     --vmargs -Xmx1G \
     --resources src/main/resources path/to/other/assets \
     --output out-mac

| Parameter | Meaning | | --- | --- | | platform | one of "windows64", "linux64", "mac" | | jdk | Directory, zip file, tar.gz file, or URL to an archive file of a JRE or Java 8 JDK with a JRE folder in it. Adopt OpenJDK 8, 11, and 15 are tested against https://adoptopenjdk.net/releases.html. You can also specify a directory to an unpacked JDK distribution. E.g. using ${java.home} in a build script.| | executable | name of the native executable, without extension such as ".exe" | | jrePath (optional) | path to the bundled JRE. By default, the JRE will be placed in a folder called "jre". | | classpath | file locations of the JAR files to package | | removelibs (optional) | file locations of JAR files to remove native libraries which do not match the target platform. See below for details. | | mainclass | the fully qualified name of the main class, using dots to delimit package names | | vmargs (optional) | list of arguments for the JVM, including leading dashes, e.g. "-Xmx1G" | | useZgcIfSupportedOs (optional) | When bundling a Java 14+ JRE, the launcher will check if the operating system supports the Z garbage collector and use it. At the time of this writing, the supported operating systems are Linux, macOS, and Windows version 1803 (Windows 10 or Windows Server 2019) or later." | | resources (optional) | list of files and directories to be packaged next to the native executable | | minimizejre (optional) | Only use on Java 8 or lower. Minimize the JRE by removing directories and files as specified by an additional config file. Comes with a few config files out of the box. See below for details on the minimization config file. | | output | the output directory. This must be an existing empty directory or a path that does not exist. Packr will create the directory if it doesn't exist but will fail if the path is not a directory or is not an empty directory. | | cachejre (optional) | An optional directory to cache the result of JRE extraction and minimization. See below for details. | | icon (optional, OS X) | location of an AppBundle icon resource (.icns file) | | bundle (optional, OS X) | the bundle identifier of your Java application, e.g. "com.my.app" | | verbose (optional) | prints more status information during processing, which can be useful for debugging | | help | shows the command line interface help |

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

{
    "platform": "mac",
    "jdk": "/Users/badlogic/Downloads/OpenJDK8U-jdk_x64_mac_hotspot_8u252b09.tar.gz",
    "executable": "myapp",
    "classpath": [
        "myjar.jar"
    ],
    "removelibs": [
        "myjar.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-all.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 or vmargs), 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-all.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 Gradle dependency:

repositories {
   mavenCentral() // Packr artifacts will be published to Maven Central in the future
   maven(uri("https://oss.sonatype.org/content/repositories/snapshots/")) // Packr snapshot artifacts will be published to Maven Central in the future

   // The following repositories are available until artifacts can be published to Maven Central
   maven(uri("http://artifactory.nimblygames.com/artifactory/ng-public-snapshot/"))
   maven(uri("http://artifactory.nimblygames.com/artifactory/ng-public-release/"))
}
dependencies {
   implementation("com.badlogicgames.packr:packr:3.0.3")
}

To invoke packr, you need to create an instance of PackrConfig and pass it to Packr.pack():

PackrConfig config = new PackrConfig();
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 = new java.io.File("out-mac");
config.useZgcIfSupportedOs = true;

new Packr().pack(config);

macOS notarization and entitlements

The following entitlements when signing the PackrLauncher executable are known to work on macOS 10.15 (Catalina) and Java 14.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>com.apple.security.cs.allow-jit</key>
	<true/>
	<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
	<true/>
	<key>com.apple.security.cs.disable-executable-page-protection</key>
	<true/>
	<key>com.apple.security.cs.disable-library-validation</key>
	<true/>
	<key>com.apple.security.cs.allow-dyld-environment-variables</key>
	<true/>
</dict>
</plist>

If all the bundled dylibs are signed, fewer entitlements might be possible. When using Java 8, com.apple.security.cs.allow-unsigned-executable-memory, and com.apple.security.cs.disable-executable-page-protection were not needed.

Example macOS code signing and notarization command line steps

These steps assume you have an Apple developer account, have saved your Apple code signing certificate into Keychain and have generated an app-specific password for your Apple developer account, allowing you to pass your username and token as command line arguments. The example commands also assume you saved the app-specific password in your Keychain allowing these commands to run in an automated way, e.g., your CI pipeline can execute all these commands.

codesign --sign <keychain id for certiticate> --verbose=10 --timestamp --force --options runtime --entitlements <path-to-entitlements-file> <path to exe or shared lib>
- You have to codesign every executable and shared library, --deep is for "emergency repairs".
/usr/bin/ditto -c -k --keepParent <app path> <app path>.zip
- ditto is a commandline zip tool, any tool that creates a zip file from a directory can be used.
xcrun altool --notarize-app --verbose --primary-bundle-id com.mydomain.myproduct --username '<username>' --password "@keychain:<app-specific password>" --file <app path>.zip
- If this step fails, it will exit with a non-zero return code and provide good output as to why it failed. E.g., "You must first sign the relevant contracts online."

Optional steps, you can choose to wait for an email notification

`xcrun altool --n

Packr

Install / Use

README

About

Download

Usage

macOS notarization and entitlements

Example macOS code signing and notarization command line steps