Export Info and Tips
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 which platforms you want to export to. You may also select if you want the application to run full screen (in present mode). A folder will be created for each of the operating systems selected; each folder contains the application, the source code for the sketch, and all required libraries for a specific platform.
Some hints and notes follow below. If you find problems, file a bug.
- The "application.xxxx" folders will be removed completely on export.
- 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:
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 "Movie" and "Capture" examples do not yet work properly, this will be fixed shortly. (Bug 230)
- Exporting sketches that use the video library may be broken, it's not clear the extent of this issue (Bug 231), but it will be repaired for a future release.
- When exporting for Mac OS X from Windows, be sure to read through the readme.txt file in the application.macosx folder—your application likely won't work on Mac OS X without a minor modification.
- 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.
- 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: (submitted by dxtx)
- 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 updated libraries/howto.txt 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!");
(thanks dxtx for pointing this out)
- Holding down shift while clicking "Export" on the toolbar will export to application instead of an applet.
- Except for Mac OS X, users will need to install Java to use your exported application. To avoid the installation requirement, you can also copy the "java" folder from Processing to the same folder as your application. This also ensures that a certain version of the Java VM is used. At least for now, the error message shown when Java is missing may be nonexistant or cryptic. Similar to Processing itself, the folder can also by a symbolic link (but not a Mac OS X or Windows shortcut) to the Java runtime installation.
- Someday we'll also add features like icon files to the applications produced by Processing. Or at least a default icon for the exported stuff. Or maybe even a splash screen while Java is loading. Again, if you want more control, use your own application generator (see above for Windows, or use the Java package maker whatchamacallit on Mac OS X).
- 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:
- 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(screen.width, screen.height). The "screen" variable will be initialized with the width and height of your main display (your default monitor).
Note: Applets aren't supported in Processing 2.0+
The export feature packages a sketch to run within a Web browser. When code is exported from Processing it is converted into Java code and then compiled as a Java Applet. When a project is exported, a series of files are written to a folder named "applet" that is created within the sketch folder. All files from the sketch folder are exported into a single JAR file with the same name as the sketch. For example, if the sketch is named "Sketch_123", the exported file will be called "Sketch_123.jar".
The applet folder contains the following:
HTML file with the applet embedded and a link to the source code and the Processing homepage. Doubleclick this file to open it in the default Web browser.
Java Archive containing all necessary files for the sketch to run. Includes the Processing core classes, those written for the sketch, and all included media files from the data folder such as images, fonts, and sounds.
The JAVA file generated by the pre-processor from the PDE file. This is the actual file that is compiled into the Applet by the Java Compiler used in Processing.
The original program file. It is linked from the index.html file.
An image file displayed while the program is loading in a Web browser.
Every time a sketch is exported, the contents of the "applet" folder are deleted and the files are written from scratch. Any changes previously made to the "index.html" file are lost.
Media files not needed for the applet should be deleted from the data folder before exporting to keep the file size small. For example, if there are unused images in the "data" folder, they will be added to the JAR file, thus needlessly increasing its size.
When exporting an applet, a description can be included on the default HTML page that's created. Processing will include everything from the first instance of /** to a closing */ as a javadoc comment. So you can add this to your sketch:
/** * You can't rock Processing like I can rock Processing. */
and that text would automatically be embedded in the exported html page. Like a javadoc comment, the text can (and should) be any valid html since it will be embedded directly in the page. Asterisks at the left of each line will be removed.
Applet Security Restrictions
Applets running inside a web browser have several security restrictions, in order to protect web users. For instance, an applet cannot read files from the local disk or connect to servers other than the server from which it came. To avoid these restrictions, it's possible to "sign" an applet. In a signed applet, a dialog box will appear to ask the user whether they trust you as the provider of the applet, and if it's ok for the applet to perform actions that might be a security risk. More information can be found in Sun's documentation.
Customizing the Applet HTML
To customize the HTML that's included when an applet is exported, copy the template.html file from Processing → lib → modes → java → applet to the root of your sketch folder. (On Mac OS X, you'll need to right-click Processing.app, select Show Package Contents, and then look in Contents → Resources → Java → modes → java → applet). Rename the template.html file to applet.html, and then make any changes you'd like to that file. When you export, that new file will be used as the template each time.
Applets Require Internet Access
By default, exported applets use java.com/js/deployJava.js to handle loading sketches in a browser. This means that applets also need an internet connection when they run. To get around this, you have two options:
- Option #1: Download your own copy of deployJava.js, include it in the sketch folder, and modify the exported HTML to remove the http://java.com... part of the URL in the file.
- Option #2: In the exported index.html file (or in the template, if you've customized the HTML per the instructions above), remove the two <script> tags and everything inside them. Also remove the <noscript> and </noscript> tags as well (but not the code inside!)
We use the deployment script because it takes care of handling more special cases (and there are many, in web development) than the regular code in the file. And we don't include deployJava.js with each download because it would add 17kb to every sketch, instead of using something that can be cached once by your browser, and available to any applet that might use it.