MSBuild rules for Antlr4 grammars using Antlr4BuildTasks

In order to better support Piggy, which uses Antlr4, I’ve added a NuGet package called Antlr4BuildTasks. This package is a pared-down derivative of the excellent work of Sam Hartwell Antlr4cs code generator package, and includes just the rules and code needed to do builds in MSBuild, Dotnet, or Visual Studio 2017 IDE–just no Antlr4 tool itself. This package decouples the build rules from the Antlr4 tool and runtime, so you can build Antlr programs using the latest Java-based Antlr tool and runtime release. To use this package, make a reference to this package as if you would to any NuGet package; make sure to also reference the Antlr4.Runtime.Standard package, install Java, the Java-based Antler tool, and set JAVA_HOME and Antlr4ToolPath. The tool works with Net Core, Net Framework, or Net Standard code, and on Windows or Linux.

The Changes

Why the change? Well, although an excellent tool, the Antlr4 for C# package on NuGet lags several versions behind the Java Antlr tool. Antlr 4.7.0 was released in March 2017. Antlr4 for C# is version 4.6.6 was released Dec 23 2018–but it is still over a year behind the Java-based tool!

Instead, the Antlr4BuildTasks package allows you to use the latest Java-based Antlr tool version. But, it requires you to separately install Java and the Java-based Antlr4 tool. You will need to set JAVA_HOME and Antlr4ToolPath. The tool has been updated to provide better error messages if it has a problem finding Java and the Java Antlr4 jar file. You will need to take care with a few things: make sure there is no version skew between the Antlr tool you set with Antlr4ToolPath and the Antlr4.Runtime.Standard library selected; add only the .g4 files to your project, not the generated .cs files from the Antlr tool; and, make sure to set the two environment variables mentioned above. The C# Antlr tool, which is the Antlr tool packaged as a NET assembly, was removed from Antlr4BuildTasks, so you can’t dynamically generate parsers on the fly. The C#-based Antlr tool in Antlr4cs outputted to stdout a list of files it generated; in Antlr4BuildTasks, the tool now uses the “-depend” option of the Java Antlr jar. The tool no longer calls ikvm.exe.

The package is now just a Net Standard package; Net Standard supports Net Core, Framework, and Mono frameworks.

MSBuild 15 now supports Nuget metadata and packing directly in CSPROJ files. So, the build and release of the package is from Visual Studio (or MSBuild) via a normal build or rebuild in the IDE. While most of the NUSPEC metadata is supported in the CSPROJ file, some things are not: <files> which copy arbitrary files to particular directories in the package is not supported. Instead, the <Content> and <ContentTargetFolders> properties in the CSPROJ file. Also, <licenseurl> is obsolete, but <license> is not supported. A modified NUSPEC file is still provided to support that old way using packing via Nuget.exe directly. This comes in handy when one wants to create a debug version of Antlr4BuildTasks, and debug the tool. (To debug, open VS, File|Open|File and open MSBuild.exe, then execute as you would when debugging your code.)

Other MSBuild support

I looked around NuGet and Github to find other packages that support MSBuild rules. There were two others I could find, besides Antlr4cs.

Shravan Narayan’s AntlrBuild — This tool is a set of Powershell scripts and MSBuild target rules that appear to wrap Antlr4. It isn’t clear how dependencies are computed. Last modified in 2016.

ANTLR.MSbuild on Codeplex — This tool is similar to Hartwell’s (and Antlr4BuildTasks) tool. It wraps the Java tool in a ITask implementation. There aren’t any instructions or documentation, and I could only assume that it was written by “Billy O’Neal” in 2010 because that is what is in the Assemblyinfo.cs and license. And, there is zilch under O’Neal’s Github.

Language support for editing

Language support in Visual Studio 2017 itself is a separate product, not part of the build rules for Antlr grammar files, which is what this package supports. You can use Hartwell’s Antlr Language Support extension, my own AntlrVSIX extension, or another.

Demo of Antlr4BuildTasks

You can see the NuGet package in action here on Youtube. The Net Core code for the Antlr Hello World example is here in Github.


Posted in Tip