Proposal: Implement the debugger in PDE
===================================

# Introduction

Processing is now a popular tool for interactive art creation. Many non-programmers are attracted to Processing due to its simplicity and a bundled development environment. However lacking of a functional debugger is really painful for people who are just getting into the language, especially for those who have little experience in programming. A working debugger in PDE would help people through the first steps of learning Processing, and help experienced user inspect their code better.

In this proposal I'd show my plan for implementing the debugger in PDE.

# Steps

I have built Processing on my machine and been reading the code and related instructions. Here I concluded these steps which are needed to be done:

## Generate pde to Java mapping.

The debugger should be able to tell which line in the pde file it is currently excuting. Processing is using antlr to compile pde files to standard Java files. We need mappings from pde line numbers to Java line numbers, pde variables to Java variables and maybe something else. I've found that latest antlr2 have API to get line number and column in AST tree. So I think we need to update dependent antlr2 first, and figure a way to generate the mapping and store them.

## Implement debugging API in Runner.

currently Runner has all the JDI related code. I think this is where to implement methods for debugger functions. I've read JPDA document and found that the bundled jdb and Trace in JDK is intended to be used as a example to learn JPDA. I noticed that the Runner in Processing in PDE is based on the code in the JDI examples. I suppose I should refer to this on implementing debugging interface.

## Implement GUI in PDE.

The debugger should be intergrated into the PDE for users. If we have debugging API done then GUI development is more about designing a intuitive interface. Currently PDE does not have a debugging state(as in Eclipse and MSVC). Also the debugger is Implemented through JDI and it would be Java mode only. Also we should decide which functions should be implemented and how can they be intergrated into PDE.

# Features

Currently I think these features should be implemented:

* Pausing, stepping through frames(between draw calls).
* Breakpoints and stepping excution.
* Investigating variables.

How these features should be presented in PDE still need more disscusion.

# Milestones

Here are the scheduled milestones based on GSOC 2012 timeline.

## Before Starting

* Get familiar with Processing code base, get Eclipse build working.
* Read document about antlr and JDI.
* Test with related API and writing prototypes.
* Determine the features of the debugger and if it is possible to implement.

## Start of Program (May 21)

* Move dependent antlr2 to latest version.
* Implementing mapping generator and debugging methods.
* Test with common pde projects.

## Mid-term Evaluation (July 13)

* Finishing works with JDI and antlr.
* Try to pin down the debugger interface in PDE as soon as possible.
* Test on other supported platforms.
* Test with more complicated pde files.

## Final Evaluation (August 24)

* Finish implementing the debugger.