Build Instructions

If you have questions about the contents of this document, ask them in the forum.

The quick version

Let's try the easy route first:

• Install Java 8

• On Windows and Linux, install the latest JRE 8 from Oracle.

• On Mac OS X, download and install JDK 8.

• Previous versions of Java are not supported.

• Install Apache Ant, using their instructions.

• Ant 1.8 or later is required.

• Clone the processing git repository.

• On the command line, git clone https://github.com/processing/processing.git

• From a GUI client, the URL is https://github.com/processing/processing.git. Git for Windows or Git for Mac should work, however these aren't tested and we only use the command line for development.

[Protip: If you're using git 1.9 or above, you can optionally shallow clone repos using git's --depth option. The download size is reduced to ~50 MB (instead of the full 1.5 GB for the main repo). See this link for more.

git clone https://github.com/processing/processing.git --depth 1

Remember that the above command will fetch the history of just the latest commit instead of all the commits. A shallow clone is helpful if you're planning to submit a quick patch. Git 1.9 is relatively new, so you'll probably need to update your git installation before using this option.]

• When building for the first time on Windows and Linux, you'll need to have an internet connection, because additional files need to be downloaded.

• Starting with 3.0a1, examples are not included in the build by default. You'll have to clone processing-docs alongside processing to build processing with examples.

• Open a terminal/console/command prompt, change to the directory where you cloned Processing, and type:

cd build
ant run

With any luck, there will be all sorts of console spew for a few moments, followed by a Processing window showing up. Hooray!

To get the latest updates, just run git pull from the command line (or GUI client) and repeat the two lines above.

That didn't work

Oh well, here are more details for what may have gone wrong.

• If it was working in the past, try removing the work folder. On OS X, that's build/macosx/work, on Windows, it's build/windows/work, and so on. When larger changes occur, sometimes an old work directory can cause problems.

• Make sure that java is available. From any terminal/console/command prompt, and type java and see what happens. If it says something like command not found, then it may be the case that

• Java may not be installed (did you really skip the first line of the instructions above?)

• The wrong version of Java is installed (32-bit instead of 64-bit, or vice-versa)

• The java command is not in your system's PATH.

• Computers don't like you.

• Make sure that ant is available. Do the same steps as with java, above.

• When running ant, the warnings about JAVA_HOME not being set can be ignored. It's not necessary to set JAVA_HOME to build Processing. (Before Processing 2.1, it was necessary. No longer.)

• You may want to start fresh every once in a while by typing ant clean. Then ant build or ant run to do a new build from scratch.

Some additional notes for other platforms follow:

Mac OS X Notes

• The Mac build requires a specific version of Java. Here's the setting inside build.xml:

<property name="jdk.update.macosx" value="67" />

That means it'll go looking for JDK 7u67 on your system. You can change that value to something higher than 67 (or lower, as long as it's higher than 40), if that's what you're using. Keep in mind that there may be incompatibilities.

• Java 7u40 is the first version that works with Processing. Earlier versions of Java 7 on OS X were complete garbage, and will not work properly.
• Apple's Java 6 no longer works, and the full JDK 7 is required (unlike Windows or Linux, where a JRE is enough).
• Installing Xcode is recommended. After installing Xcode, be sure to add the command line tools. This is in Preferences → Downloads → Command Line Tools.
• We use a modified version of Oracle's appbundler project to bundle the Processing application (and as a skeleton for exported applications). You can browse the code here.
• The appbundler.jar file created by that build process is included in the Processing source, so that it's not necessary to have a full Xcode tools installation just to build Processing.
• To build appbundler, you'll need a full Xcode installation. You'll also need the OS X 10.8 SDK installed so that the necessary header files are present. (Older or newer versions will not work.)

Windows Notes

• As of Processing 2.1, a full JDK is no longer required on Windows. Only the JRE is necessary.
• The trickiest thing on Windows is usually adding ant to the PATH and installing the right 32-bit or 64-bit Java that will work from the Command Prompt or whatever shell you're using. See above.

Linux Notes

• As of Processing 2.1, a full JDK is no longer required on Linux. Just the JRE.
• Use Oracle's Java. We don't test with OpenJDK, and over the years it has been unlikely to work. Please just download the version of Java from Oracle. You may think that Oracle is evil incarnate and that the name is an acronym for “One Rich Asshole Called Larry Ellison”. However, this saves me time because you won't be filing bugs about OpenJDK quirks breaking the build or Processing itself.

Other Notes

• No guarantee is made about the stability of the source on Github. Because almost all development is done by one or two people who are doing this in their free time, we don't work in branches or make excess effort to keep the source stable.

Building with Eclipse

Disclaimer: Processing is intended to be built with ant from the command line. Using Eclipse isn't fully supported and may break from time-to-time. You should always ensure the code compiles with ant before submitting a pull request.

1. Open Eclipse, select File → Import... Expand the “Git” folder, select “Projects from Git”, and hit the Next button.

2. On the “Select Repository Source” screen, choose “URI” and enter https://github.com/processing/processing.git And then click Next.

3. Select “Import existing projects” on the “Wizard for project import” page. Hit Next.

4. Select all the projects shown and finish the wizard.

5. You'll have several errors, because you need to build the projects once with ant (on the command line: cd /path/to/processing/build && ant) so that the “generated” folder is created. After doing that, select the processing-app project in Eclipse and hit F5 to refresh it.

6. Use Run as Application to start processing/app/Base.java, and you should be in business.

Notes

• You'll need to set an ANDROID_LIB classpath variable (Preferences → Java → Build Path → Classpath Variables), that points at the android.jar file for SDK 10. i.e. /path/to/android-sdk/platforms/android-10/android.jar

• For bonus points, you can also set processing/build/formatter.xml as the code formatter for your workspace.

• Be sure to the execution environment is set to Java 1.6, since that's what's used for the PDE. Java 7 code is used inside appbundler, but for the moment, nowhere else.

• Make sure your working directory is set to processing/build/<platform>/work if you want to run Processing from Eclipse for debugging.