| 1 |
# ANTLR4 Language Target, Runtime for Swift |
| 2 |
|
| 3 |
## Requirements |
| 4 |
|
| 5 |
ANTLR 4.7.2 requires Swift 4.2. It works on Swift 4.2.1 also. |
| 6 |
|
| 7 |
ANTLR 4.7.1 requires Swift 4.0, and does not work on Swift 4.2. (The status of |
| 8 |
Swift 4.1 support is unknown.) |
| 9 |
|
| 10 |
## Performance Note |
| 11 |
|
| 12 |
To use ANTLR4 Swift target in production environment, make sure to turn on compiler optimizations by following [these instructions](https://github.com/apple/swift-package-manager/blob/master/Documentation/Usage.md#build-configurations) 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. |
| 13 |
|
| 14 |
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. |
| 15 |
|
| 16 |
## Install ANTLR4 |
| 17 |
|
| 18 |
Make sure you have the ANTLR |
| 19 |
installed. [The getting started guide](getting-started.md) should get |
| 20 |
you started. |
| 21 |
|
| 22 |
## Create a Swift lexer or parser |
| 23 |
This is pretty much the same as creating a Java lexer or parser, |
| 24 |
except you need to specify the language target, for example: |
| 25 |
|
| 26 |
``` |
| 27 |
$ antlr4 -Dlanguage=Swift MyGrammar.g4 |
| 28 |
``` |
| 29 |
|
| 30 |
If you integrate this as a build step inside Xcode, then you should use the |
| 31 |
"gnu" message format to have any error messages parsed by Xcode. You may |
| 32 |
also want to use the `-o` option to put the autogenerated files in a |
| 33 |
separate subdirectory. |
| 34 |
|
| 35 |
``` |
| 36 |
antlr4 -Dlanguage=Swift -message-format gnu -o Autogen MyGrammar.g4 |
| 37 |
``` |
| 38 |
|
| 39 |
For a full list of antlr4 tool options, please visit the |
| 40 |
[tool documentation page](tool-options.md). |
| 41 |
|
| 42 |
## Build your Swift project with ANTLR runtime |
| 43 |
|
| 44 |
### Note |
| 45 |
|
| 46 |
We use __boot.py__ script located at the root of the Swift runtime folder |
| 47 |
`antlr4/runtime/Swift` to provide additional support for both Xcode-based |
| 48 |
projects and SPM-based projects. Below sections are organized for both of |
| 49 |
the flavors. If you want to quickly get started, try: |
| 50 |
|
| 51 |
``` |
| 52 |
python boot.py --help |
| 53 |
``` |
| 54 |
|
| 55 |
for information about this script. |
| 56 |
|
| 57 |
### Xcode Projects |
| 58 |
|
| 59 |
Note that even if you are otherwise using ANTLR from a binary distribution, |
| 60 |
you should compile the ANTLR Swift runtime from source, because the Swift |
| 61 |
language does not yet have a stable ABI. |
| 62 |
|
| 63 |
ANTLR uses Swift Package Manager to generate Xcode project files. Note that |
| 64 |
Swift Package Manager does not currently support iOS, watchOS, or tvOS, so |
| 65 |
if you wish to use those platforms, you will need to alter the project build |
| 66 |
settings manually as appropriate. |
| 67 |
|
| 68 |
#### Download source code for ANTLR |
| 69 |
|
| 70 |
``` |
| 71 |
git clone https://github.com/antlr/antlr4 |
| 72 |
``` |
| 73 |
|
| 74 |
#### Generate Xcode project for ANTLR runtime |
| 75 |
|
| 76 |
The `boot.py` script includes a wrapper around `swift package |
| 77 |
generate-xcodeproj`. Use this to generate `Antlr4.xcodeproj` for the ANTLR |
| 78 |
Swift runtime. (using _swift package generate-xcodeproj_ is not recommended) |
| 79 |
since the project is dependent on some parser files generated by _boot.py_. |
| 80 |
|
| 81 |
``` |
| 82 |
cd antlr4/runtime/Swift |
| 83 |
python boot.py --gen-xcodeproj |
| 84 |
``` |
| 85 |
|
| 86 |
#### Import ANTLR Swift runtime into your project |
| 87 |
|
| 88 |
Open your own project in Xcode. |
| 89 |
|
| 90 |
Open Finder in the `runtime/Swift` directory: |
| 91 |
|
| 92 |
``` |
| 93 |
# From antlr4/runtime/Swift |
| 94 |
open . |
| 95 |
``` |
| 96 |
|
| 97 |
Drag `Antlr4.xcodeproj` into your project. |
| 98 |
|
| 99 |
After this is done, your Xcode project navigator will be something like the |
| 100 |
screenshot below. In this example, your own project is "Smalltalk", and you |
| 101 |
will be able to see `Antlr4.xcodeproj` shown as a contained project. |
| 102 |
|
| 103 |
<img src=images/xcodenav.png width="300"> |
| 104 |
|
| 105 |
#### Edit the build settings if necessary |
| 106 |
|
| 107 |
Swift Package Manager currently does not support iOS, watchOS, or tvOS. If |
| 108 |
you wish to build for those platforms, you will need to alter the project |
| 109 |
build settings manually. |
| 110 |
|
| 111 |
#### Add generated parser and lexer to project |
| 112 |
|
| 113 |
Make sure the parsers/lexers |
| 114 |
generated in __step 2__ are added to the project. To do this, you can |
| 115 |
drag the generated files from Finder to the Xcode IDE. Remember to |
| 116 |
check __Copy items if needed__ to make sure the files are actually |
| 117 |
moved into the project folder instead of symbolic links (see the |
| 118 |
screenshot below). After moving you will be able to see your files in |
| 119 |
the project navigator. Make sure that the Target Membership settings |
| 120 |
are correct for your project. |
| 121 |
|
| 122 |
<img src=images/dragfile.png width="500"> |
| 123 |
|
| 124 |
#### Add the ANTLR Swift runtime as a dependency |
| 125 |
|
| 126 |
Select your own project in Xcode and go to the Build Phases settings panel. |
| 127 |
Add the ANTLR runtime under __Target Dependencies__ and __Link Binary With |
| 128 |
Libraries__. |
| 129 |
|
| 130 |
<img src=images/xcodedep.png width="800"> |
| 131 |
|
| 132 |
#### Build your project |
| 133 |
|
| 134 |
The runtime and generated grammar should now build correctly. |
| 135 |
|
| 136 |
### Swift Package Manager Projects |
| 137 |
|
| 138 |
Since we cannot have a separate repository for Swift target (see issue [#1774](https://github.com/antlr/antlr4/issues/1774)), |
| 139 |
and Swift is currently not ABI stable. We currently support support SPM-based |
| 140 |
projects by creating temporary local repository. |
| 141 |
|
| 142 |
For people using [Swift Package Manager](https://swift.org/package-manager/), |
| 143 |
the __boot.py__ script supports generating local repository that can be used |
| 144 |
as a dependency to your project. Simply run: |
| 145 |
|
| 146 |
``` |
| 147 |
python boot.py --gen-spm-module |
| 148 |
``` |
| 149 |
|
| 150 |
The prompt will show something like below: |
| 151 |
|
| 152 |
<img src=images/gen_spm_module.png width="800"> |
| 153 |
|
| 154 |
Put the SPM directive that contains the url to temporary repository to your |
| 155 |
project's Package.swift. And run `swift build` in your project. |
| 156 |
|
| 157 |
The project is generated in your system's `/tmp/` directory, if you find it |
| 158 |
inconvenient, consider copy that generated ANTLR repository to some place |
| 159 |
that won't be cleaned automatically and update `url` parameter in your |
| 160 |
`Package.swift` file. |
| 161 |
|
| 162 |
## Swift access levels |
| 163 |
|
| 164 |
You may use the `accessLevel` option to control the access levels on generated |
| 165 |
code. This option can either be specified with `-DaccessLevel=value` on |
| 166 |
the `antlr4` command line, or inside your `.g4` file like this: |
| 167 |
|
| 168 |
``` |
| 169 |
options { |
| 170 |
accessLevel = 'value'; |
| 171 |
} |
| 172 |
``` |
| 173 |
|
| 174 |
By default (with the `accessLevel` option unspecified) the generated code |
| 175 |
uses the following access levels: |
| 176 |
|
| 177 |
* `open` for anything that you can feasibly extend with subclassing: |
| 178 |
the generated parser, lexer, and context classes, the the listener and |
| 179 |
visitor base classes, and all their accessor and setter functions. |
| 180 |
* `public` for anything that should not be subclassed, but otherwise is |
| 181 |
useful to client code: protocols, initializers, and static definitions such |
| 182 |
as the lexer tokens, symbol names, and so on. |
| 183 |
* `internal` or `private` for anything that should not be accessed directly. |
| 184 |
|
| 185 |
If you specify `accessLevel = 'public'` then all items that are `open` by |
| 186 |
default will use `public` instead. Otherwise, the behavior is the same as |
| 187 |
the default. |
| 188 |
|
| 189 |
If you specify `accessLevel = ''` or `accessLevel='internal'` then all items |
| 190 |
that are `open` or `public` by default will use Swift's default (internal) |
| 191 |
access level instead. |
| 192 |
|
| 193 |
Those are the only supported values for `accessLevel` when using the Swift |
| 194 |
code-generator. |
| 195 |
|
| 196 |
We recommend using `accessLevel = ''`. Even if you are creating a parser |
| 197 |
as part of a library, you would usually want to wrap it in an API of your |
| 198 |
own and keep the ANTLR-generated parser internal to your module. You |
| 199 |
only need to use the less restrictive access levels if you need to expose |
| 200 |
the parser directly as part of your own module's API. |