How do I make ANTLRWorks and Visual Studio work together? (CSharp as target language)

How to make ANTLRWorks and Visual Studio work together - with C# as the target language.

This has been tested on Vista (32-bit and 64-bit), and Windows 7 Beta 1 (64-bit) with Visual Studio 2008 and 2005

Download and Unpack ANTLR

1. Download the latest version of the ANTLRWorks GUI Development Environment (Windows, Linux and Mac OS X).
2. Download the latest version of ANTLR v3  (ANTLR Version 3.1.3 source distribution)
3. Create a new folder of your choice.  For this example assume C:\ANTLR, however any location may be chosen
4. Unpack antlr-3.1.3.tar.gz into the new folder C:\ANTLR
5. Unzip the file C:\ANTLR\antlr-3.1.3\runtime\CSharp\dist\DOT-NET-runtime-3.1.3.zip into C:\ANTLR\antlr-3.1.3\runtime\CSharp\Libraries

Install Java runtime and JDK

1. ANTLR requires the Java runtime to run.  Download and install if you don't have it.
2. ANTLRWorks requires the JDK (Java Development Kit) for debugging.  Download and install as needed.

Use ANTLR from Visual Studio

1. Create a new Visual Studio project
2. Add these project references from the folder C:\ANTLR\antlr-3.1.3\runtime\CSharp\Libraries
   • Antlr3.Runtime.dll      (Antlr runtime 3.1.3)
   • antlr.runtime.dll         (Antlr runtime 2.7.7 for StringTemplate)
   • StringTemplate.dll
   • Antlr3.Utility.dll
3. Start ANTLRWorks with a double click on the jar-file (antlrworks-1.2.3.jar)
4. Copy the following test grammar into the new file.  Note the language property in the options section of the grammar is what specifies C# targeted output.

   grammar Test; options {language = 'CSharp2'; output=AST; } expr : mexpr (PLUS^ mexpr)* SEMI! ; mexpr : atom (STAR^ atom)* ; atom: INT ; //class csharpTestLexer extends Lexer; WS : (' ' | '\t' | '\n' | '\r') { $channel = HIDDEN; } ; LPAREN: '(' ; RPAREN: ')' ; STAR: '*' ; PLUS: '+' ; SEMI: ';' ; protected DIGIT : '0'..'9' ; INT : (DIGIT)+ ;

5. Save this file as Test.g (the name of the file has to equal the name of the grammar) in your VS project directory.
6. Add existing item Test.g (the file you just saved) to your project.
7. Now go back to ANTLRWorks. Do Ctrl+R (check grammar): You should get a success message.
8. Open the menu File->Preferences, choose tab General and set the output path to your Visual Studio Project directory. (In case you experience any Java related problems: check tab Compiler to set the path to javac). Click APPLY and close Preferences Window.
9. Now try Ctrl+Shift+G (Generate Code). You should get a success message.
10. Add the generated .cs files to your VS project.
11. Back in Visual Studio you should be able to build your solution and work with the parser.
12. Whenever you need to make changes to your grammar, you can do it in ANTLRWorks now and lexer and parser will be updated automatically in your project.

Debugging with ANTLRWorks

1. From the menu select File->Preferences, choose tab Compile and set the javac path to <JDK Path>\jre\bin
2. Add an exception to the Windows Firewall (or other firewall) to grant network access to java.exe and javaw.exe.  By default these programs are installed to C:\program files (x86)\java\jre6\bin.
3. From the menu select Debugger->Debug..., then set the option "Line Endings" to Windows (CRLF)
4. For the "Text" option type in the expression  "2+3*4", then press the enter key to add a CRLF (carriage return/line feed) to end of the expression, then click OK.
5. You can now use the VCR style buttons to step through, debug, and run the grammar in the debugger.

What Next?

If you're not sure where to go next, a good start is to follow the tutorials on the help page.