How to use ant with ANTLR3

Verify that all prerequisites are fulfilled

1. Make sure antlr2, antlr3, ST are in classpath. All in one is here:
   
   http://antlr.org/download/antlr-3.3-complete.jar
   
   
2. For a quick check if ANTLR3 can be found via classpath, copy the following lines into a file named build.xml:
   
   
   
   Execute ant in the directory you saved the build.xml file in:
   
   
   
   The ant command should result in some output similar to that shown below:
   
   
   
   In case ANTLR3 is not contained in the class path, the build will fail. To convince you that ANLTR3 is not part of the CLASSPATH, the complete CLASSPATH visible to ant is printed.
   
   

In summary, what we have done up to this point:

• Verified that ant is installed and working
• Proved that ANTLR3 is contained in the classpath

Now, we are ready to let ant compile the first ANTLR3 grammar.

A first example using the Java-task

In the following sections the grammar CMinus.g is used. The grammar is part of the ANTLR V3 sample grammars archive and can be downloaded from here: http://www.antlr.org/download/examples-v3.tar.gz

The ant Java-task will be used to let ANTLR3 compile a grammar. As you can see, it is mainly a mapping of the command-line onto the syntax of the ant Java-task:

The order of command-line arguments must match  ANLTR3s command line syntax.

Save the few XML lines below in a file named build.xml in the CMinus example directory.

All ANTLR3 command-line options which refer to a directory or file path (e.g. -o or -lib) should use the path attribute within the embedded <argv> element. This means to break up a sequence like into: The path attribute will convert the path to the platform's local conventions.

As the default task is defined as "antlr" in the project statement, just type on the command-line to let ANTLR3 compile the grammar CMinus.g:

 This should give the following result:

The available ANTLR3 command-line options can be found here http://www.antlr.org/wiki/display/ANTLR3/Command+line+options or by calling ANTLR3 from the command-line without arguments:

The next step is to compile the ANLTR3 generated Java-files. We already assured that ANTLR3 is contained in the CLASSPATH in the last chapter.

The output generated should be similar to this:

The ANLTR3 command-line option "-make" only generates new files in case they are older than the grammar. This behaviour might have an effect on dependent tasks like "compile", which could result in nothing to be processed because it is up to date.

A second execution of the build-file shows that nothing is built by ANLTR3 and therefore nothing has to be recompiled:

A more complex build with multiple dependent grammars

The Polydiff example is also part of the ANTLR V3 sample grammars archive. This example consists of four dependent grammars.

The ANTLR3 make option will be used to decide if a recompilation of the grammar is necessary.

ANTLR3 and Netbeans

To make the ANTLR3 libraries available to the Netbeans classpath, use the project properties dialog:

Add the ANTLR3 libraries to the Compile- and the Run-Path.

The ANTLR3 libraries can be referenced in the netbeans build file via the ${javac.classpath} and the ${run.classpath} properties.

ANTLR3 task for ant

The ANTLR3 task for ant is another choice to invoke ANTLR3 which can be used instead of the Java-task or Exec-task in ant.

It seamlessly integrates in the ant build process and supports the ant syntax.

The ANTLR3-task is implicitely evaluating dependencies via ANTLR3s depend option. This makes a difference when multiple grammar files are involved.

The ANTLR3 task for ant is available for ANTLR3 V3.2 and later.

Installation of the ANTLR3 task for ant

1. Download ant-antlr3 task from
   
   http://www.antlr.org/share/1169924912745/antlr3-task.zip
   
   
2. Copy the antlr3-task.zip file to a convenient temporary location. e.g /tmp and unpack the archive
   
   
   
   The directory structure unveiled should look like this:
   
   
   
   
3. Make ant-antlr3.jar visible to ant. The recommended way to achieve this, is to copy the ant-antlr3.jar into your $ANT_HOME/lib directory.
   
   Assuming apache-ant-1.8.2 is installed in /usr/local, you might proceed as shown below:
   
   
   
   Check that the antlib ant-antlr3.jar is correctly recognized by ant:
   
   
   
   should show:
   
   
   
   Make sure that antlr-3.3-complete.jar is contained in the classpath. The same #prerequisites have to be fulfilled and should be checked as described before.

A first example using the ANTLR3 task

In this section the grammar CMinus.g is used.

The ANTLR3 task for ant will be used to let ANTLR3 compile a grammar. The order of arguments does not matter, which is not true when you use the Java-task or Exec-task.

Save the few XML lines below in a file named build.xml in the CMinus example directory.

As the default task is defined as "antlr" in the project statement, to let ANTLR3 compile the grammar CMinus.g type on the command-line:

 This should give the following result:

The next step is to compile the ANLTR3 generated Java-files. We already assured that ANTLR3 is contained in the CLASSPATH in the last chapter.

The output generated should be similar to this:

How does the ANTLR3 task for ant handle multiple grammar files

The Polydiff example is also part of the ANTLR V3 sample grammars archive. This example consists of four dependent grammars. The ANTLR3 task for ant will use ANLTR3s depend option to receive a list of affected files. The time stamps of the files delivered are used by the ANTLR3 task for ant to decide if a recompile of a grammar is necessary.

The output generated should be similar to this:

A second execution of the polydiff build without any changes of the grammar files will result in no new generation of java sources or a recompilation of the compile target.

ANTLR3, the ANTLR3 task for ant and Netbeans

To give Netbeans access to the ANTLR3 task for ant, add the ant-antlr3.jar file to the ant classpath:

Equivalent is to copy the ant-antlr3.jar into the netbeans ant home/lib directory.

To make the ANTLR3 libraries available to the Netbeans classpath, use the project properties dialog:

Add the ANTLR3 libraries to the Compile- and the Run-Path.

The ANTLR3 libraries can be referenced in the netbeans build file via the ${javac.classpath} and the ${run.classpath} properties.

Environment variables supported by ANTLR3 task for ant

The ANTLR3 task for ant supports two environment variables:

1. ANTLR_LIBDIR
   Should point to the directory which contains the ANTLR3 libraries
   
   
   The ANLTR3 task for ant looks for all "antlr-*.jar", "stringtemplate-*.jar", "antlr-runtime-*.jar" files in the directory $ANTLR_LIBDIR points to and adds them to the classpath of the ANTLR3 Tool. As wildcards are being used for the version part of the jar-archives, it makes the task independent of new releases.
   
   
2. ANTLR_HOME
   ANTLR_HOME tries to find the ANTLR libraries in the $ANTLR_HOME/lib directory
   The ANLTR3 task for ant looks for all "antlr-.jar", "stringtemplate-.jar", "antlr-runtime-*.jar" files in the lib subdirectory $ANTLR_HOME points to and adds them to the classpath of the ANTLR3 Tool. As wildcards are being used for the version part of the jar-archives, it makes the task independent of new releases. In the event that no such jar-archives were found, a second search is done in the directory ANTLR_HOME points to.

Always use only one way to reference the ANTLR3 libraries: Either let the ANTLR libraries be part of the CLASSPATH or use the ANTLR_LIBDIR environment variable or use the ANTLR_HOME environment variable

The next lines show how to make sure that the ANLTR3 libraries can be found via the ANTLR_LIBDIR environment variable.

As it resembles the previous examples very much, only a snippet of a build file using the ANLTR_LIBDIR environment variable is shown. The important difference is the reference to "antlr.path", as defined in the preceding build-file, instead of the ${java.class.path} in the antlr3-task for ant and the javac-task.

ANTLR3 task for ant parameters

When should I use the ANTLR3 task for ant ?

Here are some statements which should help you to decide if you are better off using the ANTLR3 task for ant or the Java task.