Building ANTLR Projects with Maven
If you are using ANTLR to target Java, then you really should take a good look at Maven.
Please note that at any given time, the version of the plugin shown here may be updated. I expected that people with common sense will realize that and check to see if there is a newer version than one used here in the examples. However there are apparently people without common sense. before you read this please note that the version number of the ANTLR maven plugin follows the version of ANTLR that you wish to use. If there is a version 3.4 of ANTLR, then you want version 3.4 of the plugin.
Maven is a very popular build mechanism for Java projects and is well integrated into the most popular Java IDEs such as Netbeans and Eclipse. There is a plugin for ANTLR grammars that makes incorporating ANTLR into your projects extremely simple (assuming you know the basics of Maven.)
If you know nothing at all about Maven, then a good place to start is the Sonatype definitive guide.
As well as providing the plugin for ANTLR grammars, we have also produced an archetype for creating Maven projects that use ANTLR grammars. If you use a Java IDE that has Maven integration then you can create a Maven project and select the ANTLR3 Maven Archetype from external repositories (the ANTLR archetype is released to Maven central). However, if you don't know what that means then here is a quick and easy way to get started:
- Download Maven and install it according to the simple instructions on the download page
- Make sure you can run the
mvncommand at the shell prompt - Create a directory somewhere on your file system under which, you will create an ANTLR project
- Change to the directory using the cd command or whatever is the equivalent on your system
Now you can use the ANTLR3 Maven Archetype to create a base project, which will include some sample grammars and which will produce a working parser and tree walker without you doing anything at all. Once you can build this project, then you can replace the sample code and grammar files with your real grammar files.
To create your sample project, you run the following command:
Note
Note that the command shown below is all one command and that the \ characters are just to show that this is the case - you do not need to type them in.
mvn archetype:generate -B -DarchetypeGroupId=org.antlr \ -DarchetypeArtifactId=antlr3-maven-archetype \ -DarchetypeVersion=3.4 \ -DgroupId=com.yourcompany \ -DartifactId=yourproject \ -Dversion=yourversion \ -Dpackage=com.yourcompany.package.path
Obviously, you need to substitute your own values for com.yourcompany, yourproject, yourversion and com.yourcompany.package.path
Once the project is created, you are strongly encouraged to read the comments in the pom.xml file (yes, all of them) and the .java files that drive the sample lexer, parser and tree parser. Please do this before emailing the ANTLR list and asking questions that are already answered within the source code.
Here is a sample session using Linux bash, creating a project called jimdemo under a group id for resulting artifact (the jar file) of com.temporalwave; setting the version number to 1.0-SNAPSHOT and placing the Java code and generated Java code in the package com.temporalwave.tryme. It shows that the generated project can be built immediately, creates an executing parser and tree parser that will produce a dot specification for the AST it builds and then turn that into a png graphic file. I ask you, what have the Romans ever done for us?
server(50_64)-~: mkdir testprojects
server(50_64)-~: cd testprojects/
server(50_64)-~/testprojects: mvn archetype:generate -B -DarchetypeGroupId=org.antlr -DarchetypeArtifactId=antlr3-maven-archetype -DarchetypeVersion=3.4 -DgroupId=com.temporalwave -DartifactId=jimdemo -Dversion=1.0-SNAPSHOT -Dpackage=com.temporalwave.tryme
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'archetype'.
[INFO] ------------------------------------------------------------------------
[INFO] Building Maven Default Project
[INFO] task-segment: [archetype:generate] (aggregator-style)
[INFO] ------------------------------------------------------------------------
[INFO] Preparing archetype:generate
[INFO] No goals needed for project - skipping
[INFO] Setting property: classpath.resource.loader.class => 'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
[INFO] Setting property: velocimacro.messages.on => 'false'.
[INFO] Setting property: resource.loader => 'classpath'.
[INFO] Setting property: resource.manager.logwhenfound => 'false'.
[INFO] [archetype:generate]
[INFO] Generating project in Batch mode
[INFO] Archetype [org.antlr:antlr3-maven-archetype:3.4] found in catalog local
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 second
[INFO] Finished at: Wed Oct 28 14:29:47 PDT 2009
[INFO] Final Memory: 16M/341M
[INFO] ------------------------------------------------------------------------
server(50_64)-~/testprojects: cd jimdemo
server(50_64)-~/testprojects/jimdemo: mvn
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Building ANTLR3 project: com.temporalwave.tryme
[INFO] task-segment: [install]
[INFO] ------------------------------------------------------------------------
[INFO] [antlr3:antlr {execution: default}]
[INFO] ANTLR: Processing source directory /home/jimi/testprojects/jimdemo/src/main/antlr3
ANTLR Parser Generator Version 3.4 Oct 28, 2011 09:03:31
com/temporalwave/tryme/TLexer.g
com/temporalwave/tryme/TParser.g
com/temporalwave/tryme/TTree.g
[INFO] [resources:resources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:compile]
[INFO] Compiling 7 source files to /home/jimi/testprojects/jimdemo/target/classes
[INFO] [resources:testResources]
[INFO] Using default encoding to copy filtered resources.
[INFO] [compiler:testCompile]
[INFO] No sources to compile
[INFO] [surefire:test]
[INFO] No tests to run.
[INFO] [jar:jar]
[INFO] Building jar: /home/jimi/testprojects/jimdemo/target/jimdemo-1.0-SNAPSHOT.jar
[INFO] [assembly:attached {execution: make-assembly}]
[INFO] Processing DependencySet (output=)
[INFO] Building jar: /home/jimi/testprojects/jimdemo/target/jimdemo-1.0-SNAPSHOT-jar-with-dependencies.jar
[INFO] [install:install]
[INFO] Installing /home/jimi/testprojects/jimdemo/target/jimdemo-1.0-SNAPSHOT.jar to
/home/jimi/.m2/repository/com/temporalwave/jimdemo/1.0-SNAPSHOT/jimdemo-1.0-SNAPSHOT.jar
[INFO] Installing /home/jimi/testprojects/jimdemo/target/jimdemo-1.0-SNAPSHOT-jar-with-dependencies.jar to /home/jimi/.m2/repository/com/temporalwave/jimdemo/1.0-SNAPSHOT/jimdemo-1.0-SNAPSHOT-jar-with-dependencies.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 17 seconds
[INFO] Finished at: Wed Oct 28 14:30:13 PDT 2009
[INFO] Final Memory: 37M/597M
[INFO] ------------------------------------------------------------------------
server(50_64)-~/testprojects/jimdemo: cat >t1.dmo
Keyser Soze ;
6 + 7;
server(50_64)-~/testprojects/jimdemo: java -jar target/jimdemo-1.0-SNAPSHOT-jar-with-dependencies.jar t1.dmo
file: /home/jimi/testprojects/jimdemo/t1.dmo
Lexer Start
lexed in 1ms.
Parser Start
Parsed in 5ms.
AST Walk Start
Found Keyser Soze!!
AST Walked in 0ms.
server(50_64)-~/testprojects/jimdemo: java -jar
target/jimdemo-1.0-SNAPSHOT-jar-with-dependencies.jar -dot t1.dmo
file: /home/jimi/testprojects/jimdemo/t1.dmo
Lexer Start
lexed in 1ms.
Parser Start
Parsed in 5ms.
AST Walk Start
Found Keyser Soze!!
AST Walked in 1ms.
Producing AST dot (graphviz) file
Producing png graphic for tree
PNG graphic produced in 117ms.