Chapter 57. The ANTLR Plugin

Table of Contents

57.1. Usage
57.2. Tasks
57.3. Project layout
57.4. Dependency management
57.5. Convention properties
57.6. Source set properties
57.7. Controlling the ANTLR generator process

The ANTLR plugin extends the Java plugin to add support for generating parsers using ANTLR.

The ANTLR plugin supports ANTLR version 2, 3 and 4.

57.1. Usage

To use the ANTLR plugin, include the following in your build script:

Example 57.1. Using the ANTLR plugin

build.gradle

apply plugin: 'antlr'

57.2. Tasks

The ANTLR plugin adds a number of tasks to your project, as shown below.

Table 57.1. ANTLR plugin - tasks

Task name Depends on Type Description
generateGrammarSource - AntlrTask Generates the source files for all production ANTLR grammars.
generateTestGrammarSource - AntlrTask Generates the source files for all test ANTLR grammars.
generateSourceSetGrammarSource - AntlrTask Generates the source files for all ANTLR grammars for the given source set.

The ANTLR plugin adds the following dependencies to tasks added by the Java plugin.

Table 57.2. ANTLR plugin - additional task dependencies

Task nameDepends on
compileJava generateGrammarSource
compileTestJava generateTestGrammarSource
compileSourceSetJava generateSourceSetGrammarSource

57.3. Project layout

Table 57.3. ANTLR plugin - project layout

Directory Meaning
src/main/antlr Production ANTLR grammar files. If the ANTLR grammar is organized in packages, the structure in the antlr folder should reflect the package structure. This ensures that the generated sources end up in the correct target subfolder.
src/test/antlr Test ANTLR grammar files.
src/sourceSet/antlr ANTLR grammar files for the given source set.

57.4. Dependency management

The ANTLR plugin adds an antlr dependency configuration which provides the ANTLR implementation to use. The following example shows how to use ANTLR version 3.

Example 57.2. Declare ANTLR version

build.gradle

repositories {
    mavenCentral()
}

dependencies {
    antlr "org.antlr:antlr:3.5.2" // use ANTLR version 3
    // antlr "org.antlr:antlr4:4.5" // use ANTLR version 4
}

If no dependency is declared, antlr:antlr:2.7.7 will be used as the default. To use a different ANTLR version add the appropriate dependency to the antlr dependency configuration as above.

57.5. Convention properties

The ANTLR plugin does not add any convention properties.

57.6. Source set properties

The ANTLR plugin adds the following properties to each source set in the project.

Table 57.4. ANTLR plugin - source set properties

Property name Type Default value Description
antlr SourceDirectorySet (read-only) Not null The ANTLR grammar files of this source set. Contains all .g or .g4 files found in the ANTLR source directories, and excludes all other types of files.
antlr.srcDirs Set<File>. Can set using anything described in Section 20.5, “Specifying a set of input files”. [projectDir/src/name/antlr] The source directories containing the ANTLR grammar files of this source set.

57.7. Controlling the ANTLR generator process

The ANTLR tool is executed in a forked process. This allows fine grained control over memory settings for the ANTLR process. To set the heap size of a ANTLR process, the maxHeapSize property of AntlrTask can be used. To pass additional command-line arguments, append to the arguments property of AntlrTask.

Example 57.3. setting custom max heap size and extra arguments for ANTLR

build.gradle

generateGrammarSource {
    maxHeapSize = "64m"
    arguments += ["-visitor", "-long-messages"]
}