⚠️ Starting with release 4.5.0-alpha003, users are no longer required to install the Java Runtime in order to compile .NET applications using ANTLR 4. However, installing Java will dramatically improve the performance of the code generation process. It is highly recommended, especially on developer machines where background code generation is used for IntelliSense functionality.
The C# target for ANTLR 4 uses Java for compiling applications. The resulting compiled C# applications will not require Java to be installed. You can install any of the following versions of Java to use this target.
If you already have one of the following installed, you should check to make sure the installation is up-to-date.
If no suitable version of Java could be located on the machine, the build tools will automatically fall back to using the new C# implementation of the code generation tool instead.
Step 2: Install ANTLR Language Support for Visual Studio (optional)This step is optional, but highly recommended for users working with a version of Visual Studio that the extension supports. If you have one of the Express Editions of Visual Studio, or would like to skip this step, move on to the following step.
These versions of Visual Studio do not support the NuGet Package Manager extension, but the C# target for ANTLR 4 does support .NET 2.0 and higher so you should be able to use the command line NuGet utility instead of working directly within Visual Studio.
Step 4: Install ANTLR 4 support in a C# project For nearly all Visual Studio 2010 and newer installationsTODO: This section needs more detail.
Use the NuGet Package Manager Console to install the latest version of the Antlr4 package, as described on the following page.
TODO: This section needs more detail.
A special NuGet package is available for installation in Visual Studio 2008 projects. You should be able to use the NuGet Package Manager Console to install the latest version of the Antlr4.VS2008 package, as described on the following page.
Working with ANTLR 4 in Visual StudioThe sections below may be performed multiple times in any order as necessary to add and configure the grammars used in your project.
Add a new grammar to the project Using templates provided by the ANTLR Language Support extensionRight click the project (or subfolder) in Solution Explorer where the new grammar should be placed
Select Add → New Item...
In the left pane, expand Visual C# Items and select General
In the middle pane, select Text File
In the name box, type the complete name of the grammar file (including the .g4 extension), e.g. CustomLanguage.g4, and click Add to create the new file and add it to the project
Select File → Advanced Save Options...
For Encoding, select Unicode (UTF-8 without signature) - Codepage 65001
Click OK, and then save the file
Add the grammar declaration at the top of the file, e.g. the following for a grammar named CustomLanguage.g4
Follow step 2 of the Add an existing grammar to the project section below to configure the build properties of the newly added grammar file
The steps for adding an existing grammar to a project are similar for users with and without the ANTLR Language Support extension installed. The primary difference between these cases involves configuring the grammar to generate C# code during the build process, a step which is automated when the ANTLR Language Support extension is installed.
Antlr4MSBuild:CompileThe code generation process for ANTLR grammars is configured by setting specific MSBuild properties on the grammar files included in the C# project file. The ANTLR Language Support extension for Visual Studio exposes the customizable properties for easy configuration in the Properties pane of Visual Studio, but they can also be manually configured by editing the project file.
Note: this section assumes you have already added the grammar file(s) you wish to customize to the project via the steps described above.
The following table describes the properties available for customizing the code generation process for grammars in C# projects.
Abstract Abstract Grammar True or False When True, the generated lexer and/or parser classes are marked as abstract. ForceAtn Force ATN True or False When True, the generated parser will use AdaptivePredict for all decisions, including LL(1) decisions. Listener Generate Listener True or False When True, a parse tree listener interface and base class will be generated for the parLitser. Visitor Generate Visitor True or False When True, a parse tree visitor interface and base class will be generated for the parser. Using the ANTLR Language Support extension
Right click the project in Solution Explorer and select Unload Project
Right click the project in Solution Explorer and select Edit ProjectName.csproj
Locate the XML element for the ANTLR grammar project item, which should look like the following
<Antlr4 Include="CustomLanguage.g4"> <Generator>MSBuild:Compile</Generator> <CustomToolNamespace>MyProject.Folder</CustomToolNamespace> </Antlr4>
Locate an existing XML element according to the MSBuild Property column in the table above, or add one if it does not already exist. For example, to generate both the parse tree listener and visitor interfaces and base classes for your parser, update the project item to resemble the following.
<Antlr4 Include="CustomLanguage.g4"> <Generator>MSBuild:Compile</Generator> <CustomToolNamespace>MyProject.Folder</CustomToolNamespace> <Listener>True</Listener> <Visitor>True</Visitor> </Antlr4>
Save and close the project file
Right click the project in Solution Explorer and select Reload Project
Starting with the beta release of version 4.4.1 of the C# target, a new strong name policy is used for this target. The new policy is designed to make it easy to write libraries referencing a specific target framework (e.g. .NET 4.0), and then replace the Antlr4.Runtime.dll assembly at runtime built for a newer target framework (e.g. .NET 4.5). For authors of intermediate library, this dramatically simplifies the process of distributing libraries targeting many target frameworks. The following graph show the supported replacements which retain binary compatibility. Note that the dashed line represents a currently-untested link in the graph (see #91).
To ensure the highest level of reliability for developers targeting final releases of particular versions of the ANTLR 4 Runtime, pre-release builds use a different strong name key than final builds. Library authors are encouraged to use strong-named assemblies when referencing the final builds, especially when code is executing in an environment where other libraries may be referencing ANTLR 4 (e.g. Visual Studio extensions).
While the strong name keys used for the build are included in the repository, users are strongly discouraged from distributing builds of the ANTLR 4 Runtime using a strong name produced by antlr4.snk. Failure to follow this rule will compromise the reliability of the millions of other users using applications that reference ANTLR on a daily basis.
Suppose a library writer wishes to use ANTLR 4, and produce output which supports the .NET Framework 3.0 and newer, including the wide selection of targets offered by the Portable Class Library profile 328. In this example library, also suppose that all referenced dependencies are present in both the .NET Framework 3.0 and Profile 328, so the same code compiles in both cases without problems. This library writer only needs to produce and distribute two builds of the library: a net30 build which is built against the net30 build of ANTLR 4, and a portable-net40 build which is built against the portable-net40 build of ANTLR 4.
Now suppose an application developer wishes to use the library described previously. This application is a desktop application targeting .NET 4.5, and the application developer wishes to use the highest-performing available build of ANTLR 4. By simply installing the previous library from NuGet, an additional reference will automatically be added to the Antlr4.Runtime package. Without additional configuration, the application will build against the portable-net40 build of the library and the net45 build of ANTLR 4. This situation is fully supported (and recommended), because the Framework Compatibility graph above includes a chain extending from portable-net40 to net45.
TODO
Custom Token Specifications (*.tokens)TODO
During the build, generated code for a grammar is placed in the intermediate output directory. By default, this is obj\Debug for debug builds, and obj\Release for release builds. These generated files are managed during the build process:
The generated files are not intended to be included in source control, so there is no need to copy them to another location or manually include them in the project. Since each generated type is declared with the partial modifier, users wishing to extend the behavior of the generated code can do so by including a separate file in the project which has another definition for the partial type. When adding files to a project using the templates in the ANTLR Language Support extension, empty code files for this purpose are created and added to the project automatically.
TODO
TODO
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4
