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.
This commit is contained in:
Ewan Mellor
parent
7df0c2f478
commit
4d628174df
|
|
@ -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.
|
||||
|
||||
<img src=images/xcodenav.png width="300">
|
||||
|
||||
### 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.
|
||||
|
||||
<img src=images/dragfile.png width="500">
|
||||
|
||||
* __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__.
|
||||
|
||||
<img src=images/xcodenav.png width="300">
|
||||
<img src=images/xcodedep.png width="800">
|
||||
|
||||
* __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
|
||||
|
||||
<img src=images/targetselection.png width="500">
|
||||
|
||||
* __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.
|
||||
|
||||
<img src=images/xcodedep.png width="800">
|
||||
The runtime and generated grammar should now build correctly.
|
||||
|
|
|
|||
Loading…
Reference in New Issue