diff --git a/runtime/CSharp/README.md b/runtime/CSharp/README.md index f4decd5a3..d4675da41 100644 --- a/runtime/CSharp/README.md +++ b/runtime/CSharp/README.md @@ -1,12 +1,15 @@ # C# target for ANTLR 4 -### Note to existing users +### Note to historical users -Versions of ANTLR 4.4.x and before managed the C# target as a [separate tool provided by Sam Harwell](https://github.com/tunnelvisionlabs/antlr4cs/releases/tag/v4.3.0). As of 4.5, we our releasing a (mono-compatible) C# target derived from Sam's with the main tool. ANTLR 4.5 is now able to generate C#, Java, Python 2, Python 3 and JavaScript. Sam continues to work on his version of the ANTLR tool and so a C# target is also available through that. +Versions of ANTLR 4.4.x and before managed the C# target as a [separate tool provided by Sam Harwell](https://github.com/tunnelvisionlabs/antlr4cs/releases/tag/v4.3.0). +As of 4.5, we our releasing a (mono-compatible) C# target together with the main tool. -This makes it possible to use ANTLR 4 in any C# development environment, including of course Microsoft Visual Studio, but also Xamarin Studio, which runs on MacOS X. +Mono compatibility makes it possible to use ANTLR 4 in any C# development environment, including of course Microsoft Visual Studio, but also Xamarin Studio, which runs on MacOS X. Given Microsoft's recent commitment to *cross-platform developer experiences*, we believe this is a great opportunity for C# developers. +Releasing the runtime with the tool ensures that you can get the exact same behavior across many languages: Java, C#, Python, JavaScript, Go, Swift and C++. + ## Getting Started ### Step 1: Install Java @@ -16,39 +19,37 @@ 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. +* Java 8 runtime environment (x86 or x64) +* Java 8 development kit (x86 or x64, provided that the JRE option is also installed during the development kit installation) * 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) -### Step 2: Download the tool and runtime, and install the runtime +### Step 2: Download the tool -You need to download the following from the ANTLR web site: +You need to download the ANTLR tool from the ANTLR web site. +This is a Java archive (*.jar) used to generate the C# code from an ANTLR grammar. -1. The ANTLR tool. This is a Java archive (*.jar) used to generate the C# code from an ANTLR grammar. -2. The ANTLR runtime assembly. This is a regular .Net assembly (*.dll). -You then need to install the runtime assembly in the GAC. -This is required to easily reference the runtime from your project. -Go the the directory where you downloaded the runtime, and type the following command: -`gacutil -i Antlr4.Runtime.dll` - -### Step 3: Add a reference to the ANTLR runtime in your project - -We trust that you know how to do this :-). - -### Step 4: Add or create a grammar file (*.g4) in your project +### Step 3: Add or create a grammar file (*.g4) in your project To avoid confusing your IDE, we suggest setting the build action to None for this file. See the docs and the book to learn about writing lexer and parser grammars. -### Step 5: Generate the C# code -This can be done either from the cmd line, or by adding a custom pre-build command. -At minimal, the cmd line should look as follows: ``java -jar antlr4-4.5.jar -Dlanguage=CSharp grammar.g4`` +### Step 4: Generate the C# code + +This can be done either from the cmd line, or by adding a custom pre-build command in your project. +At minimal, the cmd line should look as follows: ``java -jar antlr4-4.6.jar -Dlanguage=CSharp grammar.g4`` This will generate the files, which you can then integrate in your project. -This is just a quick start. The tool has many useful options to control generation, please refer to its documentation. - +This is just a quick start. The tool has many useful options to control generation, please refer to its documentation. + +### Step 5: Add a reference to the ANTLR runtime in your project + +The Antlr 4 standard runtime for C# is now available from NuGet. +We trust that you know how to do add NuGet references to your project :-). +The package id is Antlr.4.Runtime. We do not support other packages. + + ### Step 6: You're done! Of course, the generated code is not going to meet your requirement by magic.