ANTLR Rules for Bazel

These build rules are used for processing ANTLR grammars with Bazel.

• Support Matrix
• Workspace Setup
  • Details
• Build Rules
  • Java Example

Support Matrix

Gen: Code Generation
Runtime: Runtime Library bundled

Setup

Add the following to your WORKSPACE file to include the external repository and load the necessary Java dependencies for the antlr rule:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

http_archive(
    name = "rules_antlr",
    sha256 = "26e6a83c665cf6c1093b628b3a749071322f0f70305d12ede30909695ed85591",
    strip_prefix = "rules_antlr-0.5.0",
    urls = ["https://github.com/marcohu/rules_antlr/archive/0.5.0.tar.gz"],
)

load("@rules_antlr//antlr:repositories.bzl", "rules_antlr_dependencies")
rules_antlr_dependencies("4.8")

More detailed instructions can be found in the Setup document.

Build Rules

To add ANTLR code generation to your BUILD files, you first have to load the extension for the desired ANTLR release.

For ANTLR 4:

load("@rules_antlr//antlr:antlr4.bzl", "antlr")

For ANTLR 3:

load("@rules_antlr//antlr:antlr3.bzl", "antlr")

For ANTLR 2:

load("@rules_antlr//antlr:antlr2.bzl", "antlr")

You can then invoke the rule:

antlr(
    name = "parser",
    srcs = ["Hello.g4"],
    package = "hello.world",
)

It's also possible to use different ANTLR versions in the same file via aliasing:

load("@rules_antlr//antlr:antlr4.bzl", antlr4 = "antlr")
load("@rules_antlr//antlr:antlr3.bzl", antlr3 = "antlr")

antlr4(
    name = "parser",
    srcs = ["Hello.g4"],
    package = "hello.world",
)

antlr3(
    name = "old_parser",
    srcs = ["OldHello.g"],
    package = "hello.world",
)

Refer to the rule reference documentation for the available rules and attributes:

• ANTLR 4
• ANTLR 3
• ANTLR 2

Basic Java Example

Suppose you have the following directory structure for a simple ANTLR project:

HelloWorld/
└── src
    └── main
        └── antlr4
            ├── BUILD
            └── Hello.g4
WORKSPACE

HelloWorld/src/main/antlr4/Hello.g4

grammar Hello;
r  : 'hello' ID;
ID : [a-z]+;
WS : [ \t\r\n]+ -> skip;

To add code generation to a BUILD file, you load the desired build rule and create a new antlr target. The output—here a .jar file with the generated source files—can be used as input for other rules.

HelloWorld/src/main/antlr4/BUILD

load("@rules_antlr//antlr:antlr4.bzl", "antlr")

antlr(
    name = "parser",
    srcs = ["Hello.g4"],
    package = "hello.world",
    visibility = ["//visibility:public"],
)

Building the project generates the lexer/parser files:

$ bazel build //HelloWorld/...
INFO: Analyzed 2 targets (23 packages loaded, 400 targets configured).
INFO: Found 2 targets...
INFO: Elapsed time: 15.295s, Critical Path: 14.37s
INFO: 8 processes: 6 processwrapper-sandbox, 2 worker.
INFO: Build completed successfully, 12 total actions

To compile the generated files, add the generating target as input for the java_library or java_binary rules and reference the required ANTLR dependency:

load("@rules_java//java:defs.bzl", "java_library")

java_library(
    name = "HelloWorld",
    srcs = [":parser"],
    deps = ["@antlr4_runtime//jar"],
)

Refer to the examples directory for further samples.

Project Layout

ANTLR rules will store all generated source files in a target-name.srcjar zip archive below your workspace bazel-bin folder. Depending on the ANTLR version, there are three ways to control namespacing and directory structure for generated code, all with their pros and cons.

1. The package rule attribute (antlr4 only). Setting the namespace via the package attribute will generate the corresponding target language specific namespacing code (where applicable) and puts the generated source files below a corresponding directory structure. To not create the directory structure, set the layout attribute to flat.
   Very expressive and allows language independent grammars, but only available with ANTLR 4, requires several runs for different namespaces, might complicate refactoring and can conflict with language specific code in @header {...} sections as they are mutually exclusive.

2. Language specific application code in grammar @header {...} section. To not create the corresponding directory structure, set the layout attribute to flat.
   Allows different namespaces to be processed in a single run and will not require changes to build files upon refactoring, but ties grammars to a specific language and can conflict with the package attribute as they are mutually exclusive.

3. The project layout (antlr4 only). Putting your grammars below a common project directory will determine namespace and corresponding directory structure for the generated source files from the relative project path. ANTLR rules uses different defaults for the different target languages (see below), but you can define the root directory yourself via the layout attribute.
   Allows different namespaces to be processed in a single run without language coupling, but requires conformity to a specific (albeit configurable) project layout and the layout attribute for certain languages.

Common Project Directories

The antlr4 rule supports a common directory layout to figure out namespacing from the relative directory structure. The table below lists the default paths for the different target languages. The version number at the end is optional.

For languages with no default, you would have to set your preference with the layout attribute.