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:

• On Windows and Linux, install the latest JRE 7 from Oracle.
• On Mac OS X, download and install JDK 7.
• Install Apache Ant
• Clone the processing git repository. This will be git clone https://github.com/processing/processing.git from the command line, or using that URL to download using a GUI client.
• When building for the first time on Windows and Linux, you'll need to be online, because additional files need to be downloaded.
• 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.

• 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.)

Some additional notes for other platforms follow:

Mac OS X Notes

• The Mac build requires a specific version of the Java update. As I write this, it's 7u45. This will be updated over time, but if you're using a later version of Java and it's not been updated in the Processing source, you may need to manually change the setting inside build.xml. It reads like this:

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

You can change that value to something higher than 45 if that's what you're using (though keep in mind that there may be incompatibilities).

• Java 7u40 is the first version that works with Processing. Earlier versions of Java 7 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).

Windows Notes

• As of Processing 2.1, a full JDK is no longer required on Windows. Just the JRE.
• 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. This saves us time because you won't be filing bugs about OpenJDK quirks breaking the build.

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, we don't spend any time making changes in branches or attempting to keep the source 100% stable.

Building on Windows

1. Download and install the following. Follow the instructions on their respective pages for how to install.
   • Subversion
   • Apache Ant
   • Java 6 – Be sure you get the full JDK, not the JRE. I recommended you install it into somewhere like c:\jdk-1.6.0_26, to make it easier to refer to in the next step.
2. Set environment variables.
   • On Windows XP, right-click My Computer → Properties → Advanced. On Windows 7, use Start → Control Panel → System → Advanced System Settings. On both, next click Environment Variables.
   • You'll need to add the bin folder from apache-ant-1.8.2 to your PATH. Under "User variables" click New, and enter PATH for the variable name, and %PATH%;c:\apache-ant-1.8.2\bin or replace the C:\ part with wherever you've installed Ant.
   • Set a JAVA_HOME environment variable to the location of the folder where the JDK is installed. Click New again, enter JAVA_HOME, and then c:\jdk-1.6.0_26 (if you followed the recommendation above) or include the full path for wherever you installed the JDK.
3. Open a new Command Prompt so that it picks up the variables you just changed.
4. Next download the code by typing this from a prompt:

svn checkout http://processing.googlecode.com/svn/trunk/processing processing-read-only

1. Now build the beast. In the Command Prompt, cd to the processing/build, and type:

ant run

1. With any luck, Processing should start right up and you'll be on your way.
2. To update to the latest, cd to the root processing folder, and type:

svn up

Updated 24 June 2011

Steps for First Time Setup

These are the old instructions, but are still partially true and may offer clues.

Install Development Tools

On Windows

Install Cygwin. It's downloadable from here. Be sure to select "Unix line endings" in the installer. When asked for packages, begin with the defaults, and add:

• subversion – for version control
• make, gcc-mingw, and g++ – to build processing.exe (this will also pull in gcc-core)
• perl – use this version from cygwin, activestate or other windows perl distributions have trouble
• unzip, zip – for dealing with archives
• coreutils, gzip, tar – should be included in the defaults, but make sure
• openssh – not required, but useful command line ssh client
• nano – not required, but a handy/simple text editor (gnu pico ripoff)

Again, be sure to leave the option selected for 'Unix line endings'. If you're not using Cygwin, then be sure to find the preference in your SVN client.

The Cygwin installer is sometimes a little flaky, so it may take more than one try to get everything in there. In fact, it's often best to run the installer once, and let it install all its defaults, then run it again, and select the items above. It's also useful to run the installer every few months to keep things fresh.

On Mac OS X

Install Apple's Developer Tools (Xcode). You'll also need Subversion. Install it from Fink, Darwinports, or download as a package.

On Linux

You will need to have git installed (either sudo apt-get install git, sudo rpm -i git for common distros) Then use git to clone the repository git clone https://github.com/processing/processing.git By default this repository gets cloned into processing in the current directory. To build you need a full jdk (from Oracle preferred currently jdk1.7.0_25) and ant (currently 1.9.1), the convention is to install these in the /opt directory obviously you will need to add paths to use the binaries. For debian based distros this can be done using update-alternatives for other distros you could create symbolic links or bash script in your local bin folder and/or update your path (.bashrc). However since openjdk1.7+ you may find that your distro provided ant and jdk actually work just as well and this is actually far simpler. To build processing from a console:-

cd processing/build
ant clean && ant linux-run

Using clean is highly advisable to remove any crud from any previous builds (it doesn't take that long to build anyway). The build gets created in processing/build/linux/work folder, so you can create symbolic links to processing/processing-java so you won't need to always call ant. To update to the latest development version you need to be in the outer processing folder and just

git pull

to update, unless you've been futzing with the processing code / build (in which case you may need to "stash those changes first").

Grab the Code

As of 2013, we've moved the repository to Github.

To get the code on unix, type this from a shell prompt:

git clone https://github.com/processing/processing.git

For Windows users you can use Git for Windows. For Mac users you can use Git for Mac.

Those wedded to mercurial can even get a Hg-Git mercurial plugin and:-

hg clone git://github.com/processing/processing.git

Install QuickTime for Java (Windows users only)

You'll also need to install QuickTime for Java. Grab the QuickTime (and iTunes) installer from here or a version that doesn't include iTunes from here. As of QuickTime 7 (iTunes 6), QuickTime for Java is mercifully included by default.

QuickTime 6 is no longer supported. QuickTime Alternative has never been supported. Just use QuickTime 7.

Build It

Now to build for the first time:

cd /path/to/processing/build/windows

Or if you're on Linux:

cd /path/to/processing/build/linux

Let's say you're into black turtlenecks and jeans:

cd /path/to/processing/build/macosx

And then..

./make.sh

If everything went well, you'll have no errors. (Feel free to make suggestions for things to include here for common problems.)

Then to run:

./run.sh

Each time you make a change, use make to build the thing and run to get it up and running.

Updating to the Latest Version

Each time you want to update to latest version:

cd /path/to/processing
git pull

Unless you've been messing with the code in which case:-

git stash

Will archive your local changes before you update.

If you're getting strange errors when you try to build, especially if new folders have been added to the Processing repository, remove your work folder and rebuild. Generally, this is a good idea to do whenever a new release has been made, since that will involve files that may have been changed (or folders that have been moved).

Get to the processing folder:

cd /path/to/processing

Remove the work directory:

cd build/yourplatform
rm -rf work

And try again

./make.sh

Unfortunately there isn't a way to know if new folders have since been added. But if you're getting "class not found" errors while building, then that's a good indicator that something is missing from a subfolder.

Building with Eclipse

Disclaimer: Processing is intended to be built with ant. 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.

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

• Make sure that you're using a full JDK to build, otherwise you'll get errors about missing com.sun.jdi.* classes.

• 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. There are no plans to move to 1.7 anytime soon.

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