From 4d628174df4e8c287961e87eb0e9fbaa56dfd507 Mon Sep 17 00:00:00 2001 From: Ewan Mellor Date: Wed, 27 Sep 2017 11:17:39 -0700 Subject: [PATCH] Update Swift runtime documentation. We now use boot.py and Swift Package Manager to generate the .xcodeproj rather than having those committed in the source repo. --- doc/swift-target.md | 107 +++++++++++++++++++++++++++----------------- 1 file changed, 65 insertions(+), 42 deletions(-) diff --git a/doc/swift-target.md b/doc/swift-target.md index 09dd17de3..57a8f8022 100644 --- a/doc/swift-target.md +++ b/doc/swift-target.md @@ -23,60 +23,83 @@ $ antlr4 -Dlanguage=Swift MyGrammar.g4 For a full list of antlr4 tool options, please visit the [tool documentation page](tool-options.md). + ## Build your Swift project with ANTLR runtime -The following instructions are assuming Xcode as the IDE: +The following instructions assume Xcode as the IDE. -* __Add parser/lexer to project__. Make sure the parsers/lexers +Note that even if you are otherwise using ANTLR from a binary distribution, +you should compile the ANTLR Swift runtime from source, because the Swift +language does not yet have a stable ABI. + +ANTLR uses Swift Package Manager to generate Xcode project files. Note that +Swift Package Manager does not currently support iOS, watchOS, or tvOS, so +if you wish to use those platforms, you will need to alter the project build +settings manually as appropriate. + +### Download source code for ANTLR + +``` +git clone https://github.com/antlr/antlr4 +``` + +### Generate Xcode project for ANTLR runtime + +The `boot.py` script includes a wrapper around `swift package +generate-xcodeproj`. Use this to generate `Antlr4.xcodeproj` for the ANTLR +Swift runtime. + +``` +cd antlr4/runtime/Swift +python boot.py --gen-xcodeproj +``` + +### Import ANTLR Swift runtime into your project + +Open your own project in Xcode. + +Open Finder in the `runtime/Swift` directory: + +``` +# From antlr4/runtime/Swift +open . +``` + +Drag `Antlr4.xcodeproj` into your project. + +After this is done, your Xcode project navigator will be something like the +screenshot below. In this example, your own project is "Smalltalk", and you +will be able to see `Antlr4.xcodeproj` shown as a contained project. + + + +### Edit the build settings if necessary + +Swift Package Manager currently does not support iOS, watchOS, or tvOS. If +you wish to build for those platforms, you will need to alter the project +build settings manually. + +### Add generated parser and 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. +the project navigator. Make sure that the Target Membership settings +are correct for your project. -* __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__. +### Add the ANTLR Swift runtime as a dependency -* __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. +Select your own project in Xcode and go to the Build Phases settings panel. +Add the ANTLR runtime under __Target Dependencies__ and __Link Binary With +Libraries__. - + -* __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. +### Build your project - - -* __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. - - \ No newline at end of file +The runtime and generated grammar should now build correctly.