2013-02-20 23:24:51 +08:00
|
|
|
# Work in progress
|
|
|
|
|
|
|
|
|
|
This document is a work in progress, and may or may not resemble the final
|
|
|
|
|
documentation for creating a new language target (runtime+templates) for ANTLR 4.
|
|
|
|
|
|
|
|
|
|
# Creating a runtime port
|
|
|
|
|
|
|
|
|
|
## Development directory structure
|
|
|
|
|
|
|
|
|
|
The directory structure for developing a new ANTLR 4 target does not have a required
|
|
|
|
|
form. The following directory structure may be used to provide the same form as the
|
|
|
|
|
ANTLR 4 reference code base. This form is especially recommended for developers who
|
|
|
|
|
plan to port both the ANTLR 4 Tool *and* Runtime to a new language.
|
|
|
|
|
|
|
|
|
|
/
|
|
|
|
|
/runtime/[target]/
|
|
|
|
|
/tool/src/org/antlr/v4/codegen/[target]Target.java
|
|
|
|
|
/tool/resources/org/antlr/v4/tool/templates/codegen/[target]/[target].stg
|
|
|
|
|
|
|
|
|
|
### Tracking progress against the reference repository
|
|
|
|
|
|
|
|
|
|
To assist in updating your target as changes are made in the reference (Java) repository,
|
|
|
|
|
you can include the reference repository as a submodule of the Git repository for your
|
|
|
|
|
target. The submodule will also allow other users to see which commit your target is
|
|
|
|
|
synchronized with. I included this submodule at the following location.
|
|
|
|
|
|
|
|
|
|
/reference/antlr4
|
|
|
|
|
|
|
|
|
|
The following command will add the submodule to your working repository.
|
|
|
|
|
|
|
|
|
|
git submodule add -b "master" "git://github.com/antlr/antlr4.git" "reference/antlr4"
|
|
|
|
|
|
2013-02-26 01:48:24 +08:00
|
|
|
*Note:* the C# target uses a special branch of ANTLR 4 as a reference. The branch "sharpen"
|
|
|
|
|
is based on the "optimized" branch, but modified to operate as an input to the Sharpen tool
|
|
|
|
|
for automatically converting Java code to C#. The submodule for this target was added
|
|
|
|
|
using the following command.
|
|
|
|
|
|
|
|
|
|
git submodule add -b "sharpen" "git://github.com/sharwell/antlr4.git" "reference/antlr4"
|
|
|
|
|
|
2013-02-20 23:24:51 +08:00
|
|
|
## Release structure
|
|
|
|
|
|
|
|
|
|
### Code generation support
|
|
|
|
|
|
|
|
|
|
The target must provide a `.jar` file for the ANTLR 4 Tool to use for code generation.
|
|
|
|
|
The key file to include is the following:
|
|
|
|
|
|
|
|
|
|
/META-INF/services/org.antlr.v4.codegen.Target
|
|
|
|
|
|
|
|
|
|
This file should contain the fully qualified name of the class extending `Target` for
|
|
|
|
|
your runtime. This will likely look like the following.
|
|
|
|
|
|
|
|
|
|
org.antlr.v4.codegen.[target]Target
|
|
|
|
|
|
|
|
|
|
If you are providing multiple code generation targets in a single `.jar` file, you
|
|
|
|
|
should include one line for each target. The C# code generation target provides the
|
|
|
|
|
following entries.
|
|
|
|
|
|
|
|
|
|
org.antlr.v4.codegen.CSharp2Target
|
|
|
|
|
org.antlr.v4.codegen.CSharp3Target
|
|
|
|
|
org.antlr.v4.codegen.CSharp4Target
|
|
|
|
|
|
|
|
|
|
The code generation templates themselves are loaded by the runtime via the `TODO()`
|
|
|
|
|
method. The default implementation (inherited from the `Target` superclass) will
|
|
|
|
|
attempt to load the template from the following path in the `.jar` file.
|
|
|
|
|
|
|
|
|
|
/org/antlr/v4/tool/templates/codegen/[target]/[target].stg
|
|
|
|
|
|
|
|
|
|
### Runtime
|
|
|
|
|
|
|
|
|
|
The runtime for a new target may be distributed in any form relevant to that target
|
|
|
|
|
language.
|
|
|
|
|
|
