forked from jasder/antlr
Updated installation instructions in Readme.md
This commit is contained in:
Sam Harwell
parent
9d73c12b30
commit
b9745beaac
205
Readme.md
205
Readme.md
|
|
@ -1,96 +1,169 @@
|
|||
# C# target for ANTLR 4
|
||||
|
||||
## Introduction
|
||||
## Getting Started
|
||||
|
||||
This document gives a basic overview of using the C# target for ANTLR 4
|
||||
with C# projects in Visual Studio.
|
||||
### Step 1: Install Java
|
||||
|
||||
### Available Targets
|
||||
The C# target for ANTLR 4 requires Java for *compiling* applications. The resulting compiled C# applications will not require Java to be installed (at least not due to the use of ANTLR 4). You can install *any* of the following versions of Java to use this target.
|
||||
|
||||
This target provides several C# targets, numbered according to the target
|
||||
framework version. When the grammars are generated by Antlr4.targets as
|
||||
part of the build, the code generation target will be *automatically selected*
|
||||
to match the `TargetFrameworkVersion` property in the project file.
|
||||
If you already have one of the following installed, you should check to make sure the installation is up-to-date.
|
||||
|
||||
* Java 7 runtime environment (x86 or x64)
|
||||
* Java 7 development kit (x86 or x64, provided that the JRE option is also installed during the development kit installation)
|
||||
* Java 6 runtime environment (x86 or x64)
|
||||
* Java 6 development kit (x86 or x64, provided that the JRE option is also installed during the development kit installation)
|
||||
|
||||
| Target Name | Runtime Library | .NET Framework Version | C# compiler version |
|
||||
| ----------- | --------------- | ---------------------- | ------------------- |
|
||||
| `CSharp_v4_5` | Antlr4.Runtime.v4.5.dll | .NET 4.5 | C# 3+ (Visual Studio 2008+) |
|
||||
| `CSharp_v4_0` | Antlr4.Runtime.v4.0.dll | .NET 4.0 | C# 3+ |
|
||||
| `CSharp_v3_5` | Antlr4.Runtime.v3.5.dll | .NET 3.5 | C# 3+ |
|
||||
| `CSharp_v3_0` | Antlr4.Runtime.v2.0.dll (same as below) | .NET 3.0 | C# 3+ |
|
||||
| `CSharp_v2_0` | Antlr4.Runtime.v2.0.dll | .NET 2.0 | C# 3+ |
|
||||
### 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.
|
||||
|
||||
### Visual Studio Support for ANTLR 4 Grammars
|
||||
1. Open Visual Studio
|
||||
2. Select **Tools** → **Extensions and Updates...**
|
||||
3. In the left pane, select **Online**
|
||||
4. In the top right, type **ANTLR** to search for extensions
|
||||
5. If your version of Visual Studio is supported, the results pane will show the extension **ANTLR Language Support** by **Sam Harwell**. You can click the result and then select **Download** to install the extension.
|
||||
6. Restart Visual Studio after installing the extension
|
||||
|
||||
Currently there is no Visual Studio extension specifically designed for editing
|
||||
ANTLR 4 grammars. However, now that a C# target for ANTLR 4 is available an
|
||||
editor should be available in the "reasonably near" future. If this feature is
|
||||
particularly important to your team,
|
||||
[Tunnel Vision Labs' Sponsored Development Program](http://tunnelvisionlabs.com/SponsoredDevelopment.pdf)
|
||||
may be a cost effective option for reducing the release timeframe.
|
||||
### Step 3: Update the NuGet Package Manager
|
||||
|
||||
### Base Project Layout
|
||||
#### For nearly all Visual Studio 2010 and newer installations
|
||||
|
||||
C:\dev\CoolTool\
|
||||
CoolProject\
|
||||
CoolProject.csproj
|
||||
CoolTool.sln
|
||||
1. Open Visual Studio
|
||||
2. Select **Tools** → **Extensions and Updates...**
|
||||
3. In the left pane, select **Updates**, then select **Product Updates**
|
||||
4. Wait for ~10 seconds while the application checks for updates (it might not notify you that it's checking in the background)
|
||||
5. If an update for **NuGet Package Manager** is listed in the results, click to update it
|
||||
6. Repeat steps 3-5 for any other sections listed under **Updates** in the left pane
|
||||
7. If you updated NuGet, restart Visual Studio before continuing to Step 4 below
|
||||
|
||||
### Adding ANTLR to the Project Structure
|
||||
#### For Visual Studio 2008, and Visual C# 2010 Express Edition
|
||||
|
||||
1. Download the current C# release from the following location: **TODO**
|
||||
2. Extract the files to `C:\dev\CoolTool\Reference\Antlr4`
|
||||
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](http://docs.nuget.org/docs/start-here/installing-nuget) instead of working directly within Visual Studio.
|
||||
|
||||
After these steps, your folder should resemble the following.
|
||||
### Step 4: Install ANTLR 4 support in a C# project
|
||||
|
||||
C:\dev\CoolTool\
|
||||
CoolProject\...
|
||||
Reference\
|
||||
Antlr4\
|
||||
Antlr4.targets
|
||||
Antlr4BuildTasks.dll
|
||||
antlr4-csharp-[version]-complete.jar
|
||||
CoolTool.sln
|
||||
#### For nearly all Visual Studio 2010 and newer installations
|
||||
|
||||
### MSBuild Support for ANTLR
|
||||
1. Create or open a C# project which will use ANTLR
|
||||
2. Right click the top-level solution node in the Solution Explorer window and select **Manage NuGet Packages for Solution...**
|
||||
3. In the left pane, select **Online**, then select **nuget.org**
|
||||
4. At the top of the middle pane, if a drop down says **Stable Only**, change the selection to **Include Prerelease**
|
||||
5. In the top right, type **Antlr4** to search for the package
|
||||
6. In the search results, locate and select the package called **ANTLR 4**. In the right pane, verify that the **Id** is listed as exactly **Antlr4**.
|
||||
7. Click install on the search result
|
||||
8. Select the C# projects you want to add support for ANTLR 4 to, and click **OK** to update those projects
|
||||
|
||||
Since the steps include manual modification of the Visual Studio project files,
|
||||
I *very strongly* recommend you back up your project (or commit it to source control)
|
||||
before attempting these steps.
|
||||
#### For Visual C# 2010 Express Edition
|
||||
|
||||
1. Open the `CoolTool.sln` solution in Visual Studio
|
||||
2. Unload the `CoolProject` project by right-clicking the project in Solution
|
||||
Explorer and selecting Unload Project
|
||||
3. Open `CoolProject.csproj` for editing by right-clicking the unloaded project
|
||||
in Solution Explorer and selecting Edit CoolProject.csproj
|
||||
4. For reference, locate the following line
|
||||
*TODO: This section needs more detail.*
|
||||
|
||||
<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets"/>
|
||||
Use the NuGet Package Manager Console to install the latest version of the **Antlr4** package, as described on the following page.
|
||||
|
||||
Note: the line appears as follows in some projects
|
||||
[ANTLR 4](http://www.nuget.org/packages/Antlr4)
|
||||
|
||||
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets"/>
|
||||
#### For Visual Studio 2008
|
||||
|
||||
5. After the line in step 4, add the following code
|
||||
*TODO: This section needs more detail.*
|
||||
|
||||
<PropertyGroup>
|
||||
<!-- Folder containing Antlr4BuildTasks.dll -->
|
||||
<Antlr4BuildTaskPath>$(ProjectDir)..\Reference\Antlr4</Antlr4BuildTaskPath>
|
||||
<!-- Path to the ANTLR Tool itself. -->
|
||||
<Antlr4ToolPath>$(ProjectDir)..\Reference\Antlr4\antlr4-csharp-4.0.1-SNAPSHOT-complete.jar</Antlr4ToolPath>
|
||||
</PropertyGroup>
|
||||
<Import Project="$(ProjectDir)..\Reference\Antlr4\Antlr4.targets" />
|
||||
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.
|
||||
|
||||
6. Save and close `CoolProject.csproj`
|
||||
7. Reload the CoolProject project by right-clicking the project in Solution
|
||||
Explorer and selecting Reload Project
|
||||
[ANTLR 4 (Visual Studio 2008)](http://www.nuget.org/packages/Antlr4.VS2008)
|
||||
|
||||
### Adding a Reference to the C# Runtime
|
||||
## Working with ANTLR 4 in Visual Studio
|
||||
|
||||
In the CoolProject project, add a reference to `Antlr4.Runtime.dll`, which is
|
||||
located at `C:\dev\CoolTool\Reference\Antlr4\Antlr4.Runtime.dll`.
|
||||
The 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 extension
|
||||
|
||||
1. Right click the project (or subfolder) in **Solution Explorer** where the new grammar should be placed
|
||||
2. Select **Add** → **New Item...**
|
||||
3. In the left pane, expand **Visual C# Items** and select **ANTLR**
|
||||
4. Select one of the ANTLR 4 templates and give it a name, and click **Add** to create the new grammar file and add it to the project
|
||||
|
||||
#### Without using the ANTLR Language Support extension
|
||||
|
||||
1. Right click the project (or subfolder) in **Solution Explorer** where the new grammar should be placed
|
||||
2. Select **Add** → **New Item...**
|
||||
3. In the left pane, expand **Visual C# Items** and select **General**
|
||||
4. In the middle pane, select **Text File**
|
||||
5. 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
|
||||
6. Select **File** → **Advanced Save Options...**
|
||||
7. For **Encoding**, select **Unicode (UTF-8 without signature) - Codepage 65001**
|
||||
8. Click **OK**, and then save the file
|
||||
9. Add the grammar declaration at the top of the file, e.g. the following for a grammar named `CustomLanguage.g4`
|
||||
|
||||
```antlr
|
||||
grammar CustomLanguage;
|
||||
```
|
||||
|
||||
10. 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
|
||||
|
||||
### Add an existing grammar to the project
|
||||
|
||||
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.
|
||||
|
||||
1. Add the **\*.g4** grammar file to the C# project using one of the following methods.
|
||||
* Right click the project or folder in **Solution Explorer** and click **Add** → **Existing Item...**
|
||||
* Select the project in **Solution Explorer**, and click the toolbar button for **Show All Files**. Then locate the **\*.g4** grammar file within the project structure, right click the file, and select **Include In Project**.
|
||||
2. *If you have the ANTLR Language Support extension installed, this step is automatically performed.* Otherwise, you will need to right click the grammar file in **Solution Explorer** and select **Properties**. In the properties window, configure the following items.
|
||||
* **Build Action**: `Antlr4`
|
||||
* **Custom Tool**: `MSBuild:Compile`
|
||||
* **Custom Tool Namespace**: The complete name of the namespace you want the generated classes to be located within. The ANTLR Language Support extension configures this field according to the root namespace configured for the C# project combined with the subfolder within the project where the grammar is located.
|
||||
|
||||
### Configure the compile-time options for a grammar in the project
|
||||
|
||||
The 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.
|
||||
|
||||
1. **MSBuild Property**: This is the name of the XML element in the project file responsible for customizing the property
|
||||
2. **Display Name**: This is the name of the property as it appears in the Visual Studio **Properties** window for users with the ANTLR Language Support extension installed
|
||||
3. **Value**: The allowed value(s) for the property
|
||||
4. **Details**: A description of the impact of the property on the build process
|
||||
|
||||
| MSBuild Property | Display Name | Value | Details |
|
||||
| ---------------- | ------------ | ----- | ------- |
|
||||
| `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
|
||||
|
||||
1. Right click the grammar file in **Solution Explorer** and select **Properties**
|
||||
2. Locate the property to customize according to the **Display Name** column in the table above
|
||||
3. Update the value as appropriate
|
||||
|
||||
#### Manually editing the project file
|
||||
|
||||
1. Right click the project in **Solution Explorer** and select **Unload Project**
|
||||
2. Right click the project in **Solution Explorer** and select **Edit *ProjectName*.csproj**
|
||||
3. Locate the XML element for the ANTLR grammar project item, which should look like the following
|
||||
|
||||
```xml
|
||||
<Antlr4 Include="CustomLanguage.g4">
|
||||
<Generator>MSBuild:Compile</Generator>
|
||||
<CustomToolNamespace>MyProject.Folder</CustomToolNamespace>
|
||||
</Antlr4>
|
||||
```
|
||||
|
||||
4. 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.
|
||||
|
||||
```xml
|
||||
<Antlr4 Include="CustomLanguage.g4">
|
||||
<Generator>MSBuild:Compile</Generator>
|
||||
<CustomToolNamespace>MyProject.Folder</CustomToolNamespace>
|
||||
<Listener>True</Listener>
|
||||
<Visitor>True</Visitor>
|
||||
</Antlr4>
|
||||
```
|
||||
|
||||
5. Save and close the project file
|
||||
6. Right click the project in **Solution Explorer** and select **Reload Project**
|
||||
|
||||
## Grammars
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue