HOWTO-HACK.txt

Instructions for folks who want to contribute to processing.py itself.

Prerequisites:

    git - http://git-scm.com/downloads
    Latest JDK 8 - http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
    Apache ant - http://ant.apache.org/bindownload.cgi

The Processing and Python Mode developers use Eclipse for their development,
but it is not required. There are Eclipse project configs in our source trees.

    Eclipse - https://www.eclipse.org/downloads/

Steps
-----

Create a directory to organize your Processing-related source, say

    $ mkdir processing-source
    $ cd processing-source

These build steps assume your file structure will look like this:

    processing-source/
        |- processing.py/
        |- processing/
        |- processing-video/

If you think you're going to want to submit your own work to processing.py,
you should start by creating a fork of processing.py on GitHub. Let's say
you've done so, and that your fork can be found at:

    https://github.com/JRandomHacker/processing.py

I'll also assume you've uploaded your SSH public key to GitHub.

    $ git clone git@github.com:JRandomHacker/processing.py.git

Otherwise, if you just want to build or examine Python Mode, you can clone
the original repo:

    $ git clone https://github.com/jdf/processing.py.git


You'll need source for processing and processing-video.

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

If you are a Linux user, you'll also have to create a directory named `linux`
inside your `processing.py` directory.

Then, to sanity-check your environment and run all of Python Mode's
integration tests, do the following:

    $ cd processing.py
    $ ant test

That will take 2-5 minutes.

Take a look at the script testmode.sh and modify it, if necessary, to
match your Processing install. This script will build Python Mode,
install it in your copy of Processing, and launch it.


Configuring Eclipse
-------------------

If you want to modify the code, and you're an Eclipse user, you can "Import
existing project into workspace" a few of times, once for processing.py
itself (which lives in the processing.py top level directory), and once
each for processing.core, processing-java, processing-app, and
processing-video, which you'll find in the directories where you've
cloned processing and processing-video.

Once you've imported those projects, you should be able to run
test.jycessing.JycessingTests as a JUnit test.

There are several Eclipse Run Configurations included in the processing.py
directory, which are essential for debugging the Python mode sketch runner,
which is an independent application, and which communicates with the Mode
stuff via sockets.

To run or debug the SketchRunner, launch the "SketchRunner" Run Configuration
from Eclipse's Java runner menu. Once it has started up, run the "Base - Sketch
Runner First" configuration. This sequence runs things backwards; normally the
Mode runs, and itself launches the SketchRunner.