When do I need to use remote debugging?

If your lexer and parser grammar rules are contained in a single file
then you can debug it (for example, AST generation) in ANTLRWorks
without using remote debugging or writing any Java code. To do this,

1. start ANTLRWorks
2. open the combined grammar file
3. select Debug... from the Debugger menu
4. enter the input to be tested or select a file to be used as input

However, if your lexer and parser grammar rules are in separate files
then you must use remote debugging. To do this,

1. generate classes for them using org.antlr.Tool and the -debug option
2. write a main class that uses them to parse some input
3. compile your code and the generated code
4. run your application which will pause waiting for the debugger
5. start ANTLRWorks
6. open the parser grammar file
7. select Debug Remote... from the Debugger menu
8. press the Connect button

Do not pass null to the constructor of your Parser or TreeParser class
and attempt to set the stream they read from later
(using setTokenStream and setTreeNodeStream).
This will result in a NullPointerException in DebugTokenStream.