Debian Codegraph @

doc/swift-target.md

raw
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.