ANTLR Rules for Bazel

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

Rules

Different rules are available that align with the ANTLR release streams.

antlr4
antlr3
antlr2

Quick Setup

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

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

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

More detailed instructions can be found in the Setup section.

Basic Example

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

[workspace]/
  WORKSPACE
  HelloWorld/
    BUILD
    src/
      main/
        antlr4/
          Hello.g4

HelloWorld/src/main/antlr4/Hello.g4

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

HelloWorld/BUILD

package(default_visibility = ["//visibility:public"])

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

antlr4(
    name = "generated",
    srcs = ["src/main/antlr4/Hello.g4"],
    package = "hello.world",
)

java_library(
    name = "HelloWorld",
    srcs = [":generated"],
)

Compiling the project generates the lexer/parser files:

$ bazel build //HelloWorld
INFO: Analysed target //HelloWorld:HelloWorld (0 packages loaded).
INFO: Found 1 target...
Target //HelloWorld:HelloWorld up-to-date:
  bazel-bin/HelloWorld/libHelloWorld.jar
INFO: Elapsed time: 0.940s, Critical Path: 0.76s
INFO: Build completed successfully, 4 total actions

The generated source files can be found in the generated.srcjar archive below your workspace bazel-bin/HelloWorld directory.

To just generate the source files you would use:

$ bazel build //HelloWorld:generated

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.

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.
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.
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.

Language	Default Directory
C	`src/antlr4`
Cpp	`src/antlr4`
CSharp, CSharp2, CSharp3	`src/antlr4`
Go
Java	`src/main/antlr4`
JavaScript	`src/antlr4`
Python, Python2, Python3	`src/antlr4`
Swift

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

Build Rule Reference

antlr4

antlr4(name, deps=[], srcs=[], atn, depend, encoding, error,
       force_atn, imports=[], language, layout, listener, log,
       long_messages, message_format, no_listener, no_visitor,
       options={}, package, visitor)

Runs ANTLR 4 on the given grammar files.

Attributes

`name`	`Name; Required` A unique name for this rule.
`deps`	`List of labels; Optional; Default is ['@antlr4_tool//jar', '@antlr4_runtime//jar', '@antlr3_runtime//jar', '@stringtemplate4//jar', '@javax_json//jar']` The dependencies to use. Defaults to the official ANTLR 4 release, but if you need to use a different version, you can specify the dependencies here.
`srcs`	`List of labels; Required` The grammar files to process.
`atn`	`Boolean; Optional; Default is False` Generate rule augmented transition network diagrams.
`depend`	`Boolean; Optional; Default is False` Generate a list of file dependencies instead of parser and/or lexer.
`encoding`	`String; Optional; Default is 'UTF-8'` The grammar file encoding, e.g. euc-jp.
`error`	`Boolean; Optional; Default is False` Treat warnings as errors.
`force_atn`	`Boolean; Optional; Default is False` Use the ATN simulator for all predictions.
`imports`	`List of labels; Optional; Default is []` The grammar and .tokens files to import. Must be all in the same directory.
`language`	`String; Optional; Default is ''` The code generation target language. Either Cpp, CSharp, Go, JavaScript, Java, Python2, Python3 or Swift (case-sensitive).
`layout`	`String; Optional; Default is ''` The directory layout to match file paths against for package/namespace detection by convention. The default depends on the target language.
`listener`	`Boolean; Optional; Default is True` Generate parse tree listener.
`log`	`Boolean; Optional; Default is False` Dump lots of logging info to antlr-timestamp.log.
`long_messages`	`Boolean; Optional; Default is False` Show exception details when available for errors and warnings.
`message_format`	`String; Optional; Default is 'antlr'` The output style for messages. Either antlr, gnu or vs2005.
`no_listener`	`Boolean; Optional; Default is False` Do not generate parse tree listener.
`no_visitor`	`Boolean; Optional; Default is True` Do not generate parse tree visitor.
`options`	`Dictionary mapping strings to string; Optional; Default is {}` Set/override grammar-level options.
`package`	`String; Optional; Default is ''` The package/namespace for the generated code.
`visitor`	`Boolean; Optional; Default is False` Generate parse tree visitor.

antlr3

antlr3(name, deps=[], srcs=[], debug, depend, dfa, dump, imports=[],
       language, message_format, nfa, profile, report, trace,
       Xconversiontimeout, Xdbgst, Xdbgconversion, Xdfa, Xdfaverbose,
       Xgrtree, Xm,  Xmaxdfaedges, Xmaxinlinedfastates, Xminswitchalts,
       Xmultithreaded, Xnfastates, Xnocollapse, Xnomergestopstates,
       Xnoprune, Xsavelexer, Xwatchconversion)

Runs ANTLR 3 on the given grammar files.

Attributes

`name`	`Name; Required` A unique name for this rule.
`deps`	`List of labels; Optional; Default is ['@antlr3_runtime//jar', '@antlr3_tool//jar', '@stringtemplate4//jar']` The dependencies to use. Defaults to the most recent ANTLR 3 release, but if you need to use a different version, you can specify the dependencies here.
`srcs`	`List of labels; Required` The grammar files to process.
`Xconversiontimeout`	`Integer; Optional; Default is 0` Set NFA conversion timeout for each decision.
`Xdbgconversion`	`Boolean; Optional; Default is False` Dump lots of info during NFA conversion.
`Xdbgst`	`Boolean; Optional; Default is False` Put tags at start/stop of all templates in output.
`Xdfa`	`Boolean; Optional; Default is False` Print DFA as text.
`Xdfaverbose`	`Boolean; Optional; Default is False` Generate DFA states in DOT with NFA configs.
`Xgrtree`	`Boolean; Optional; Default is False` Print the grammar AST.
`Xm`	`Integer; Optional; Default is 0` Max number of rule invocations during conversion.
`Xmaxdfaedges`	`Integer; Optional; Default is 0` Max "comfortable" number of edges for single DFA state.
`Xmaxinlinedfastates`	`Integer; Optional; Default is 0` Max DFA states before table used rather than inlining.
`Xminswitchalts`	`Integer; Optional; Default is 0` Don't generate switch() statements for dfas smaller than given number.
`Xmultithreaded`	`Boolean; Optional; Default is False` Run the analysis in 2 threads.
`Xnfastates`	`Boolean; Optional; Default is False` For nondeterminisms, list NFA states for each path.
`Xnocollapse`	`Boolean; Optional; Default is False` Collapse incident edges into DFA states.
`Xnomergestopstates`	`Boolean; Optional; Default is False` Do not merge stop states.
`Xnoprune`	`Boolean; Optional; Default is False` Do not test EBNF block exit branches.
`Xsavelexer`	`Boolean; Optional; Default is False` Don't delete temporary lexers generated from combined grammars.
`Xwatchconversion`	`Boolean; Optional; Default is False` Print a message for each NFA before converting.
`debug`	`Boolean; Optional; Default is False` Generate a parser that emits debugging events.
`depend`	`Boolean; Optional; Default is False` Generate file dependencies; don't actually run antlr.
`dfa`	`Boolean; Optional; Default is False` Generate a DFA for each decision point.
`dump`	`Boolean; Optional; Default is False` Print out the grammar without actions.
`imports`	`List of labels; Optional; Default is []` The grammar and .tokens files to import. Must be all in the same directory.
`language`	`String; Optional; Default is ''` The code generation target language. Either C, Cpp, CSharp2, CSharp3, JavaScript, Java, ObjC, Python, Python3 or Ruby (case-sensitive).
`message_format`	`String; Optional; Default is ''` Specify output style for messages.
`nfa`	`Boolean; Optional; Default is False` Generate an NFA for each rule.
`profile`	`Boolean; Optional; Default is False` Generate a parser that computes profiling information.
`report`	`Boolean; Optional; Default is False` Print out a report about the grammar(s) processed.
`trace`	`Boolean; Optional; Default is False` Generate a parser with trace output. If the default output is not enough, you can override the traceIn and traceOut methods.

antlr2

antlr2(name, deps=[], srcs=[], debug, diagnostic, docbook, html,
       imports=[], traceLexer, traceParser, traceTreeParser)

Runs ANTLR 2 on the given grammar files.

Attributes

`name`	`Name; Required` A unique name for this rule.
`deps`	`List of labels; Optional; Default is ['@antlr2//jar']` The dependencies to use. Defaults to the final ANTLR 2 release, but if you need to use a different version, you can specify the dependencies here.
`srcs`	`List of labels; Optional; Default is []` The grammar files to process.
`debug`	`Boolean; Optional; Default is False` Launch the ParseView debugger upon parser invocation. Unless you have downloaded and unzipped the debugger over the top of the standard ANTLR distribution, the code emanating from ANTLR with this option will not compile.
`diagnostic`	`Boolean; Optional; Default is False` Generate a text file from your grammar with a lot of debugging info.
`docbook`	`Boolean; Optional; Default is False` Generate a docbook SGML file from your grammar without actions and so on. It only works for parsers, not lexers or tree parsers.
`html`	`Boolean; Optional; Default is False` Generate a HTML file from your grammar without actions and so on. It only works for parsers, not lexers or tree parsers.
`imports`	`List of labels; Optional; Default is []` The grammar file to import.
`trace`	`Boolean; Optional; Default is False` Have all rules call traceIn/traceOut.
`traceLexer`	`Boolean; Optional; Default is False` Have lexer rules call traceIn/traceOut.
`traceParser`	`Boolean; Optional; Default is False` Have parser rules call traceIn/traceOut.
`traceTreeParser`	`Boolean; Optional; Default is False` Have tree walker rules call traceIn/traceOut.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

ANTLR Rules for Bazel

Rules

Quick Setup

Basic Example

Project Layout

Common Project Directories

Build Rule Reference

antlr4

Attributes

antlr3

Attributes

antlr2

Attributes

Files

README.md

Latest commit

History

README.md

File metadata and controls

ANTLR Rules for Bazel

Rules

Quick Setup

Basic Example

Project Layout

Common Project Directories

Build Rule Reference

antlr4

Attributes

antlr3

Attributes

antlr2

Attributes