How to build an ANTLR code generation target - ANTLR 3

The following instructions show how to go about starting a new back-end for a new language "XYZ" using the Java back-end as a basis.

All the files in the antlr-3.0/runtime/Java/src/org/antlr/runtime directory are needed to create
a full back-end. You must also copy another group of templates such as antlr-3.0/src/org/antlr/codegen/templates/Java/*.stg. And create antlr-3.0/src/org/antlr/codegen/XYZTarget.java if you need to override anything in Target.java.

But it is in fact pretty easy to get started:

In src/org/antlr/codegen/templates/
- create a directory XYZ
- copy Java/Java.stg to XYZ/XYZ.stg

I recommend building the ANTLR tool 'in place'. Do not create a jar or compile/copy to a build directory. When you run it with 'java -cp path-to-src-dir ...' it will use the original *.stg file, which you'll edit a lot - so rebuilding the tool would be quite a PITA.

Create a directory antlr-3.0/runtime/XYZ. Here you can put anything you need (no need to clone Java 1:1).

Start with a simple lexer like:

lexer grammar T;
options { language = XYZ; }
ZERO: '0';

N.B: The name after the word "grammar" needs to be the same as the filename in which you save it, i.e. T.g.

Look at the generated code and try to figure out which templates in XYZ.stg you have to port to get valid XYZ code. What I did, is to comment out the Java code in all templates replacing it with something like FIXME([number]). Then you fix the templates until no FIXME remains in the
output.

You'll need a basic implementation of a character stream and base recognizer/lexer to get the example running. Just implement the methods that are actually needed to get the example running w/o errors.

You'll either get the feeling "Wow, that was easy!" and move on (that happened to me) or "Eeek, what a pain!" and let someone else to the work.