Build Instructions

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

Update February 2013

We moved this document over from Google Code. It is probably out of date. See the comments on that page for troubleshooting and solutions.

Update February/March 2010

• I'm in the midst of moving the build system over to ant, but haven't yet had time to update this document. For the most part, as long as you have a JDK installed, and Ant installed as well, you should be able to cd to processing/build and type ant run to get things going.
• On Windows and Linux, install ant and add c:\apache-ant-xxx\bin directory to your path. On Mac OS X, you'll have ant as long as the Developer Tools are already installed.
• On Windows and Linux, you'll need to set a JAVA_HOME environment variable that points to the root of a full JDK (not JRE).

Troubleshooting the newer Ant build

• As noted on the front page of this site, we're now heading toward 2.0, and things are really messy inside SVN as a result. Use of the source is not for the fainthearted (or those prone to whining about the progress of hard work that others are doing in their spare time).
• An error message that reads "Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre6\lib\tools.jar" means you need to set JAVA_HOME to your JDK (not JRE) installation. Build errors regarding a lot of missing classes for processing.app.debug mean that JAVA_HOME is not set properly.
• Sometimes the build claims that it needs the Android SDK to be installed. If you're running ant dist (which you shouldn't anyway) it is required. If you're not, then it's a temporary problem in the build files and probably needs to be reported as a bug.

More to come...

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're pretty much on your own.. You need a pretty standard development setup along with Subversion.

Grab the Code

As of June 2010, we've moved the repository to Google Code.

To get the code, type this from a prompt:

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

That part may take a while, especially for people outside the US or who have a slow internet connection. (The JRE binaries are stored in SVN so that we can properly test on the exact platform/runtime setup that we'll be releasing. No longer the case.)

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
svn 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 checking in.

1. Download the code from the repository and build the project (more details above):

svn checkout http://processing.googlecode.com/svn/trunk/processing processing
ant processing/build/build.xml

1. Create your Eclipse workspace next to your download:

svn checkout http://processing.googlecode.com/svn/trunk/processing processing

You should now have the following file structure:

processing/
workspace/

1. Next, we're going to trick Eclipse into thinking there are projects in the workspace by creating symbolic links to directories in the processing folder. The process is a little different for each Operating System.
   • For Windows, run the following from the command prompt. On Vista and Windows 7, you'll need to open the command prompt "as an administrator."

rem Run these from the directory containing both processing/ and workspace/

mklink /D workspace\android ..\processing\android
mklink /D workspace\processing ..\processing\app
mklink /D workspace\processing-core ..\processing\core
mklink /D workspace\processing-dxf ..\processing\java\libraries\dxf
mklink /D workspace\processing-net ..\processing\java\libraries\net
mklink /D workspace\processing-opengl ..\processing\java\libraries\opengl
mklink /D workspace\processing-pdf ..\processing\java\libraries\pdf
mklink /D workspace\processing-serial ..\processing\java\libraries\serial
mklink /D workspace\processing-video ..\processing\java\libraries\video

mklink /D processing\app\modes ..\build\windows\work\modes
mklink /H processing\app\lib\preferences.txt processing\build\windows\work\lib\preferences.txt
mklink /H processing\app\lib\about.jpg processing\build\windows\work\lib\about.jpg
mklink /H processing\app\lib\contributions.gif processing\build\windows\work\lib\contributions.gif

* For Linux and Mac OS X, run the following from the terminal:

#!/bin/bash
# Run these from the directory containing both processing/ and workspace/

ln -s ../processing/android workspace/android
ln -s ../processing/app workspace/processing
ln -s ../processing/core workspace/processing-core
ln -s ../processing/java/libraries/dxf workspace/processing-dxf
ln -s ../processing/java/libraries/net workspace/processing-net
ln -s ../processing/java/libraries/opengl workspace/processing-opengl
ln -s ../processing/java/libraries/pdf workspace/processing-pdf
ln -s ../processing/java/libraries/serial workspace/processing-serial
ln -s ../processing/java/libraries/video workspace/processing-video

# For Mac OS X, use:
ln -s ../build/macosx/work/Processing.app/Contents/Resources/Java/modes/ processing/app/modes
ln processing/build/macosx/work/Processing.app/Contents/Resources/Java/lib/preferences.txt processing/app/lib/preferences.txt
ln processing/build/macosx/work/Processing.app/Contents/Resources/Java/lib/contributions.gif processing/app/lib/contributions.gif
ln processing/build/macosx/work/Processing.app/Contents/Resources/Java/lib/about.jpg processing/app/lib/about.jpg

# For Linux, use:
ln -s ../build/linux/work/modes processing/app/modes
ln processing/build/linux/work/lib/preferences.txt processing/app/lib/preferences.txt
ln processing/build/linux/work/lib/contributions.gif processing/app/lib/contributions.gif
ln processing/build/linux/work/lib/about.jpg processing/app/lib/about.jpg

1. Your workspace folder should now be full of symbolic links. Open Eclipse, and use this folder as your workspace. The navigate to "Import Project into Workspace." Select your workspace as the root directory, and select all of the projects that appear. Click Finish.
2. By this point, you should see all of the projects in Package Explorer. Great. You might also see tons of compilation errors. Don't worry. This is generally because the classpaths need to be slightly different for each system. Use your disgression to fix the build path of each project with compilation errors.
   • For the "processing" project, you'll probably need to include jdi.jar, which is generally in ECLIPSE_HOME/plugins/org.eclipse.jdt.debug_<some_version>/jdi.jar.
   • For Android, you'll need to locate android.jar, which is generally in android-sdk/platforms/android-<some_version>/android.jar
3. Once you've fixed the compilation errors, you can run Processing by running processing.app.Base as a Java Application.
4. or bonus points, you can also set processing/build/formatter.xml as the code formatter for your workspace, and set the execution environment to Java 1.5, since that's what's used for ant.