antlr/doc/swift-target.md

ANTLR4 Language Target, Runtime for Swift

Performance Note

To use ANTLR4 Swift target in production environment, make sure to turn on compiler optimizations by following these instructions if you use SwiftPM to build your project. If you are using Xcode to build your project, it's unlikely you will not use release build for production build.

Conclusion is, you need to turn on release mode (which will have all the optimization pre configured for you) so the ANTLR4 Swift target can have reasonable parsing speed.

Install ANTLR4

Make sure you have the ANTLR installed. The getting started guide should get you started.

Create a Swift lexer or parser

This is pretty much the same as creating a Java lexer or parser, except you need to specify the language target, for example:

$ antlr4 -Dlanguage=Swift MyGrammar.g4 

For a full list of antlr4 tool options, please visit the tool documentation page.

Build your Swift project with ANTLR runtime

The following instructions are assuming Xcode as the IDE:

• Add parser/lexer to project. Make sure the parsers/lexers generated in step 2 are added to the project. To do this, you can drag the generated files from Finder to the Xcode IDE. Remember to check Copy items if needed to make sure the files are actually moved into the project folder instead of symbolic links (see the screenshot below). After moving you will be able to see your files in the project navigator. But when you open one of the files, you will see Xcode complaining the module "Antlr4" could not be found at the import statement. This is expected, since we still need the ANTLR Swift runtime for those missing symbols.

• Download ANTLR runtime. Due to unstable ABI of Swift language, there will not be a single "library" for the Swift ANTLR runtime for now. To get Swift ANTLR runtime, clone the ANTLR repository. Open it in finder. From the root directory of the repo, go to runtime/Swift folder. You will see the Xcode project manifest file: Antlr4.xcodeproj.

• Import ANTLR Swift runtime into project. Drag Antlr4.xcodeproj into your project, after this is done, your Xcode project navigator will be something like the screenshot below. In this case, your own project is "Smalltalk", and you will be able to see the Antlr4.xcodeproj shown as a contained project. The error message will still be there, that's because we still need to tell Xcode how to find the runtime.

• Build ANTLR runtime. By expanding the "Products" folder in the inner project (Antlr4.xcodeproj), you will see two Antlr4.framework files. ".framework" file is the swift version of ".jar", ".a" as in JAVA, C/C++ Initially those two files should be red, that's because they are not built. To build, click the "target selection" button right next to your Xcode run button. And in the drop down select the target you want to build. And you will see the two Antlr4.framework files are for iOS and OSX, as shown below. After target selection, press "CMD+B", and Xcode will build the framework for you. Then you will see one of the frameworks become black.

• Add dependencies. Simply adding ANTLR Swift runtime and build the artifact is not enough. You still need to specify dependencies. Click your own project (Smalltalk), and you will see project setting page. Go to "Build Phase", and inside it make sure your ANTLR Swift runtime framework is added to both "Target Dependencies" and "Link Binary With Libraries" sections, as shown below. After correctly added dependencies, the error message for importing library will be gone.