Export Info and Tips

Sean Cherven edited this page Feb 27, 2016 · 5 revisions

Application Export

Processing can export Java Applications for the Linux, Macintosh, and Windows platforms. When the "Export Application" button is pressed or "Export Application" is selected from the "File" menu, a dialog box opens and you can select whether you want the application to run full screen (in present mode) along with other options. A folder will be created for the application, the source code for the sketch, and all required libraries.

Some hints and notes follow below. If you find problems, file a bug.

  • Starting with Processing 2.1, the Java runtime (JRE) can be embedded with exported applications. The positive side of this is that it makes the application much more likely to behave exactly as it does when run from the PDE, and that users of the exported application won't have to install anything additional. The downside is that exported applications are much larger (~100 MB), and the export command takes more time.

  • If you don't want to embed the Java runtime, you can uncheck the box in the Export window (starting with 2.1 beta 2). Your users will need to install Java 7u45 or later (just a JRE, a full JDK is not needed). You may also get different results when your application is run on different machines or different versions of Java. We don't recommend it. You're very likely to get different results (visually or performance-wise) if you don't embed.

  • As of Processing 2.1, it's only possible to export applications for the current operating system. For instance, on a 32-bit version of Windows, you can only export the version of the application that runs on 32-bit Windows. While not ideal, any exported application should be tested on other platforms before use anyway, so having access to the platform is hopefully less of an issue. There are two reasons for the change: 1) with the JRE embedding, it's only possible to embed the JRE that's included with Processing, and 2) it saves many megabytes from the Processing download because we don't have to include the video library for all platforms. In Processing 2.2, it's now possible to export for other platforms.

  • An application for Mac OS X can only be exported from OS X. This is due because of the complexity of how Oracle's JDK works on OS X, and the limitations of the appbundler that we use.

  • When exporting, the "application.xxxx" folders will be removed completely on export (unless you turn off that behavior in the Preferences window).

  • It is important that you don't have a method named main() in your sketch, unless you know what you're doing (writing your own main). Otherwise this will fool the preprocessor into thinking you have a clue, when in fact you don't.

  • If running in "Java" mode, where your code starts "public class blah extends PApplet", you'll need to write your own main() method in order for Export to Application to work. It should look something like this:

static public void main(String args[]) {
    PApplet.main("YourClassName");
}

Not doing this, or using your own main can cause problems internally with variables not being properly set up. If you opt not to use PApplet.main(), make sure you read the source code for it so that you understand how it works, and don't whine if it breaks.

  • The Mac OS X export is a nice .app bundle like a regular OS X application. You can change the icon or edit its settings by using "Show Package Contents" and editing Info.plist or replacing sketch.icns with something more exciting.

  • On OS X, you can also customize the exported application automatically by copying the Info.plist.tmpl file from inside the Processing.app package into your sketch. Any changes made to that copy of Info.plist.tmpl will be used whenever that sketch is exported.

  • Windows is a shell .exe that calls the code and requires the "lib" folder along with it be kept intact. Someday we might make Windows be a nice single .exe file, but this requires more time to implement, and more specifically, make work consistently with the libraries. If you're finicky about this, use a Java EXE generator such as JSmooth or launch4j.

  • To set the icon used on the title bar for Windows, use the following code:

ImageIcon titlebaricon = new ImageIcon(loadBytes("myicon.gif"));
frame.setIconImage(titlebaricon.getImage());

or for a Processing 3.0 version:

PImage titlebaricon = loadImage("myicon.png");
surface.setIcon(titlebaricon);
  • Linux is just a shell script, which can probably be used on most Unix platforms (there's almost nothing to it).

  • When distributing your application, the "source" folder can be removed from the export if you'd like, but other files (such as the lib folder and any .dll files or whatever) should be left intact otherwise the application will not work.

  • If you just want an executable jar file, export as an applet. Executable jar files will not work if you're using libraries or a code folder because the path information will not be properly set, and the additional library jars won't be referenced.

  • Library writers can now specify what files to export for each platform, see the Library-Basics page for more information.

  • Your current memory settings will be exported with the application. If you've set outrageous memory requirements, you might want to undo that before exporting for others, or edit the exported files by hand (Contents/Resources/Info.plist on Mac OS X and lib/args.txt on Windows).

  • If you want to replace (or add) titlebar text, just do this in setup():

frame.setTitle("This is in the titlebar!"); 

"Present" Features

  • The ESC key will quit a sketch, even in Present mode. To prevent this from happening, intercept the ESC on keyPressed() so that it isn't passed through to PApplet. Use the following code to prevent ESC from quitting the application:
void keyPressed() {
  if (key == ESC) {
    key = 0;  // Fools! don't let them escape!
  }
}
  • You can hide the stop button with the --hide-stop command line option to PApplet. More details about command line options are above in the "Export to Application" section. From inside the Processing environment, you can't hide the stop button (unless your sketch window obscures it anyway) easily, so better to export as an application.

  • To make a sketch run with a window the size of the screen, use size(displayWidth, displayHeight). These variables will be initialized with the width and height of the display selected in the preferences.