You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Aug 11, 2023. It is now read-only.
- Replaced command line parser, now uses JewelCLI.
- Extracted config & minimization code into separate modules.
- Added more minimize options. Minimize profiles now use a JSON format to utilize these options.
- Aligned command line & JSON parameter names.
- Amended error checks & log output.
- Added 'oraclejre8' minimization profile, following Oracle's rules for JRE redistribution.
- Updated documentation.
Copy file name to clipboardExpand all lines: README.md
+102-40
Original file line number
Diff line number
Diff line change
@@ -1,39 +1,47 @@
1
1
# packr
2
2
3
-
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 the app is a native app. Packr is most suitable for GUI applications, such as games made with [libGDX](http://libgdx.badlogicgames.com/).
3
+
__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.__
4
+
5
+
## About
6
+
7
+
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 with [libGDX](http://libgdx.badlogicgames.com/).
4
8
5
9
#### [Download Packr](http://bit.ly/packrgdx)
6
10
7
11
## Usage
8
12
9
-
You point packr at your JAR file (containing all your code and assets), a JSON config file (specifying parameters to the JVM and the main class) and a URL or local file location to an OpenJDK build for the platform you want to build. Invoking packr from the command line may look like this:
13
+
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.
14
+
15
+
Invoking packr from the command line may look like this:
| platform | one of "windows32", "windows64", "linux32", "linux64", "mac" |
27
-
| jdk | ZIP file location or URL to an OpenJDK build containing a JRE. Prebuild JDKs can be found at https://github.com/alexkasko/openjdk-unofficial-builds|
33
+
| jdk | ZIP file location or URL to an OpenJDK or Oracle JDK build containing a JRE. Prebuild OpenJDK packages can be found at https://github.com/alexkasko/openjdk-unofficial-builds|
28
34
| executable | name of the native executable, without extension such as ".exe" |
35
+
| classpath | file locations of the JAR files to package |
36
+
| mainclass | the fully qualified name of the main class, using dots to delimit package names |
37
+
| vmargs | list of arguments for the JVM, without leading dashes, e.g. "Xmx1G" |
38
+
| resources (optional) | list of files and directories to be packaged next to the native executable |
39
+
| minimizejre | 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. |
40
+
| output | the output directory |
29
41
| icon (optional, OS X) | location of an AppBundle icon resource (.icns file) |
30
-
| classpath | file locations of the JAR files to package, separated by `;`|
31
42
| bundleidentifier (optional, OS X) | the bundle identifier of your Java application, e.g. "com.my.app" |
32
-
| mainclass | the fully qualified name of the main class, using dots to delimit package names |
33
-
| vmargs | list of arguments for the JVM, separated by `;`, e.g. "-Xmx1G" |
34
-
| outdir | output directory |
35
-
| resources (optional) | list of files and directories to be packaged next to the native executable, separated by `;`.
36
-
| minimizejre | minimize the JRE by removing directories and files as specified by the config file. Comes with two config files out of the box called "soft" and "hard". See below for details on the minimization config file. |
43
+
| verbose | prints more status information during processing, which can be useful for debugging |
44
+
| help | shows the command line interface help |
37
45
38
46
Alternatively, you can put all the command line arguments into a JSON file which might look like this:
39
47
@@ -47,14 +55,14 @@ Alternatively, you can put all the command line arguments into a JSON file which
47
55
],
48
56
"mainclass": "com.my.app.MainClass",
49
57
"vmargs": [
50
-
"-Xmx1G"
58
+
"Xmx1G"
51
59
],
52
60
"resources": [
53
61
"src/main/resources",
54
62
"path/to/other/assets"
55
63
],
56
64
"minimizejre": "soft",
57
-
"outdir": "out-mac"
65
+
"output": "out-mac"
58
66
}
59
67
```
60
68
@@ -64,7 +72,15 @@ You can then invoke the tool like this:
64
72
java -jar packr.jar my-packr-config.json
65
73
```
66
74
67
-
Finally, you can use packr from within your code. Just add the JAR file to your project, either manually, or via the following Maven dependency:
75
+
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.
76
+
77
+
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:
A standard JRE weighs about 90mb unpacked and about 50mb packed. Packr helps you cut down on that size, thus also reducing the download size of your app.
111
+
### JRE
96
112
97
-
To minimize the JRE that is bundled with your app, you have to specify a minimization configuration file via the `minimizejre` flag you supply to Packr. Such a minimization configuration contains the names of files and directories within the JRE to be removed, one per line in the file. E.g.:
113
+
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.
98
114
99
-
```
100
-
jre/lib/rhino.jar
101
-
jre/lib/rt/com/sun/corba
115
+
To minimize the JRE that is bundled with your app, you have to specify a minimization configuration file via the `minimizejre` flag you supply to Packr. A minimization configuration is a JSON file containing paths to files and directories within the JRE to be removed.
116
+
117
+
As an example, have a look at the `soft` profile configuration:
118
+
119
+
```json
120
+
{
121
+
"reduce": [
122
+
{
123
+
"archive": "jre/lib/rt.jar",
124
+
"paths": [
125
+
"com/sun/corba",
126
+
"com/sun/jndi",
127
+
"com/sun/media",
128
+
"com/sun/naming",
129
+
"com/sun/rowset",
130
+
"sun/applet",
131
+
"sun/corba",
132
+
"sun/management"
133
+
]
134
+
}
135
+
],
136
+
"remove": [
137
+
{
138
+
"platform": "*",
139
+
"paths": [
140
+
"jre/lib/rhino.jar"
141
+
]
142
+
},
143
+
{
144
+
"platform": "windows",
145
+
"paths": [
146
+
"jre/bin/*.exe",
147
+
"jre/bin/client"
148
+
]
149
+
}
150
+
]
151
+
}
102
152
```
103
153
104
-
This will remove the rhino.jar (about 1.1MB) and all the packages and classes in com.sun.corba from the rt.jar file. To specify files and packages to be removed from the JRE, simply prepend them with `jre/lib/rt/`.
154
+
This configuration will unpack `rt.jar`, remove all the listed packages and classes in `com.sun.*` and `sun.*`, then repack `rt.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 of `rt.jar` substantially.
105
155
106
-
Packr comes with two such configurations out of the box, [`soft`](https://github.com/libgdx/packr/blob/master/src/main/resources/minimize/soft) and [`hard`](https://github.com/libgdx/packr/blob/master/src/main/resources/minimize/hard)
156
+
Then, rhino.jar (about 1.1MB) and, in case of a Windows JRE, all executable files in `jre/bin/` and the folder `jre/bin/client/` will be removed.
107
157
108
-
Additionally, Packr will compress the rt.jar file. By default, the JRE uses zero-compression on the rt.jar file to make application startup a little faster.
158
+
Packr comes with two such configurations out of the box, [`soft`](https://github.com/libgdx/packr/blob/master/src/main/resources/minimize/soft) and [`hard`](https://github.com/libgdx/packr/blob/master/src/main/resources/minimize/hard). The `hard` profile removes a few more files, and repacks some additional JAR files.
159
+
160
+
There's also a new, *experimental* configuration, [`oraclejre8`](https://github.com/libgdx/packr/blob/master/src/main/resources/minimize/oraclejre8), which reduces size of an Oracle 8 JRE following Oracle's redistribution rules described [here](http://www.oracle.com/technetwork/java/javase/jre-8-readme-2095710.html). 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!**
161
+
162
+
### Classpath
163
+
164
+
Minimization aside, packr also removes all dynamic libraries which do not match the target platform from your project JAR file(s):
165
+
166
+
| platform | files removed |
167
+
| --- | --- |
168
+
| Windows |`*.dylib`, `*.so`|
169
+
| Linux |`*.dll`, `*.dylib`|
170
+
| MacOS |`*.dll`, `*.so`|
109
171
110
172
## Output
111
173
@@ -144,19 +206,19 @@ outdir/
144
206
icons.icns [if config.icon is set]
145
207
```
146
208
147
-
You can further modify the Info.plist to your liking, e.g. add icons, a bundle identifier etc. If your `outdir` has the `.app` extension it will be treated as an application bundle by Mac OS X.
209
+
You can further modify the Info.plist to your liking, e.g. add icons, a bundle identifier etc. If your `output` folder has the `.app` extension it will be treated as an application bundle by Mac OS X.
148
210
149
211
## Executable command line interface
150
212
151
213
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 as `com.my.app.MainClass.main(new String[] {"-x", "y.z" })`.
152
214
153
-
The executables themselves expose an own interface, which has to be explicitly enabled by passing `-c` or `--cli` as the **very first** parameter. In this case, a 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`.
215
+
The executables themselves expose an own interface, which has to be enabled explicitly by passing `-c` or `--cli` as the **very 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`.
154
216
155
217
Try `./myapp -c --help` for a list of available options. They are also listed [here](https://github.com/libgdx/packr/blob/master/src/main/native/README.md#command-line-interface).
156
218
157
-
> Note: On Windows, the executable does not show any output by default. Here you can use `myapp.exe -c --console --help` to spawn a console window, making terminal output visible.
219
+
> Note: On Windows, the executable does not show any output by default. Here you can use `myapp.exe -c --console [arguments]` to spawn a console window, making terminal output visible.
158
220
159
-
## Building
221
+
## Building from source code
160
222
161
223
If you want to modify the Java code only, it's sufficient to invoke Maven.
162
224
@@ -173,7 +235,7 @@ If you want to compile the native executables, please follow [these instructions
173
235
* Icons aren't set yet on Windows and Linux, you need to do that manually.
174
236
* Minimum platform requirement on MacOS is OS X 10.7.
175
237
* 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.
176
-
* 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 the `-XstartOnFirstThread` VM argument in your packr config.
238
+
* 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.
0 commit comments