Building a C++ ANTLR Parser

The ANTLR parser generator reads a grammar file and can generate a C++ parser for that grammar. At the time this Web page was written the ANTLR HTML documentation did not provide too many hints on how to compile the C++ parser created by ANTLR. I've seen several notes on asking why there were unresolved references when they compiled the ANTLR generated parser, so this seems to be a problem other people have had as well. Hopefully this Web page will help.

These notes discuss building ANTLR under Windows NT with the Microsoft compiler. However, it should be easy to adapt these directions to UNIX.

Note that in Microsoft terms, this builds a "console" application, using a static link (e.g., no DLLs). I have not tried to build ANTLR as a GUI object on Windows. Minimally the ANTLR Standard Template Library input code would have to be rewritten to work with the Win32 file pointers and I/O. I've done this for POSIX I/O, but I have no idea how to do it for the Standard Template Library I/O objects used by ANTLR. I know that at least one person has run into problems linking ANTLR for a GUI application, following these directions.

Creating a Parser

See the notes on running ANTLR under Microsoft J++ here

Building an ANTLR library

Before the ANTLR parser can be compiled, the ANTLR support library must be built.

The ANTLR release comes with a cpp directory which contains the C++ support functions for ANTLR. For example, this directory contains the skeleton parser and lexer support, the classes to build trees etc... The cpp directory has an hpp sub-directory whcih contains the header files for all the classes.

The approach I took is to compile the code in this directory into an archive library. It would also be possible to compile this code into a dll (or on UNIX, a shared object). I like static linkage because it tends to be simpler and more reliable.

To build the ANTLR support library I use a Makefile and the Microsoft nmake program, which is largely similar to UNIX make. The Makefile I use is here. To download the gzip'ed Makefile, click here (making a file unreadable is the only way I know to force a file to be downloadable, as opposed to viewed by the browser). This Makefile should be placed in the cpp directory. Note that you will either have to change the file name to Makefile or run nmake with the -f option (nmake -f Makefile_lib). You will have to modify the various paths in the Makefile for your local Visual C++ directory structure. The compiler flags for the Microsoft C++ compiler work with version 6.0. The archive library is built in the cpp directory.

Compiling the Parser

After the ANTLR support library is built the ANTLR parser can be compiled and linked with this library. Makefile I use is here. To download the gzip'ed Makefile, click here. This Makefile should go in the same directory as your grammar. It will rebuild the parser using Visual J++ when you make changes to the grammar. As with the library Makefile, you should either change the name of this make file or use the -f argument to nmake.

Executing the Parser

If you used the stock "main()" given in the examples directory, the ANTLR parser will read text from standard input. So to run the parser enter:

myparser < source_language

Where myparser is the executable built by the Makefile and source_language is the language data to be parsed. If you want your parser to read from a filename from the command line you can use the Standard Template Library stream ifstream. For example:

int main(int argc, char *argv[] )
  if (argc == 2) {
    const char *filename;

    filename = argv[1];
    ifstream strm( filename );

    if (strm.is_open()) {
       invoke ANTLR lex and parse here

Finally, make sure that your grammar is terminated by the built in EOF token, or it will hang waiting for token when the end of file is reached.

I have published some examples that I used to learn ANTLR on my ANTLR examples Web page.

Ian Kaplan, July 19, 1999

back to main ANTLR page