@@ -27,7 +27,6 @@ Swift now supports:
27
27
28
28
* Automatic crash catching and backtrace generation out of the box.
29
29
* Built-in symbolication.
30
- * A choice of unwind algorithms, including "fast", DWARF and SEH.
31
30
* Interactive(!) crash/runtime error catching.
32
31
33
32
Crash catching is enabled by default, and won't interfere with any system-wide
@@ -61,10 +60,7 @@ follows:
61
60
+-----------------+---------+--------------------------------------------------+
62
61
| unwind | auto | Specifies which unwind algorithm to use. |
63
62
| | | ``auto `` means to choose appropriately for the |
64
- | | | platform. Other options are ``fast ``, which |
65
- | | | does a naïve stack walk; and ``precise ``, which |
66
- | | | uses exception handling data to perform an |
67
- | | | unwind. |
63
+ | | | platform. |
68
64
+-----------------+---------+--------------------------------------------------+
69
65
| preset | auto | Specifies which set of preset formatting options |
70
66
| | | to use. Options are ``friendly ``, ``medium `` or |
@@ -106,7 +102,7 @@ follows:
106
102
| | | to the runtime library, or using ``SWIFT_ROOT ``. |
107
103
+-----------------+---------+--------------------------------------------------+
108
104
109
- (*) On macOS, this defaults to ``tty `` rather than ``yes ``.
105
+ (*) On macOS, this defaults to ``no `` rather than ``yes ``.
110
106
111
107
Backtrace limits
112
108
----------------
@@ -179,10 +175,10 @@ triggered automatically by the runtime.
179
175
System specifics
180
176
----------------
181
177
182
- macOS
183
- ^^^^^
178
+ Signal Handling
179
+ ^^^^^^^^^^^^^^^
184
180
185
- On macOS, we catch crashes and other events using a signal handler. At time of
181
+ On macOS and Linux, program crashes are caught using a signal handler. At time of
186
182
writing, this is installed for the following signals:
187
183
188
184
+--------------+--------------------------+-------------------------------------+
@@ -217,9 +213,43 @@ finds that there is already a handler for that signal. Similarly if something
217
213
else has already configured an alternate signal stack, it will leave that
218
214
stack alone.
219
215
220
- Once the backtracer has finished handling the crash, it will allow the crashing
221
- program to continue and crash normally, which will result in the usual Crash
222
- Reporter log file being generated.
216
+ macOS
217
+ ^^^^^
218
+
219
+ The backtracer is not active by default on macOS. You can enable it by setting
220
+ ``SWIFT_BACKTRACE `` to ``enable=yes ``, which is sufficient if you build your
221
+ programs using Xcode. If you are using some other build tool to build your
222
+ program, you will need to sign the program with the entitlement
223
+ ``com.apple.security.get-task-allow `` in order for the backtracer to work. This
224
+ is the same entitlement you would need to make various other tools work on your
225
+ program, so you may already be doing this. If not, you will need to make a
226
+ property list file containing the entitlements you wish to sign your program
227
+ with, e.g. ::
228
+
229
+ <?xml version="1.0" encoding="UTF-8"?>
230
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
231
+ "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
232
+ <plist version="1.0">
233
+ <dict>
234
+ <key>com.apple.security.get-task-allow</key>
235
+ <true/>
236
+ </dict>
237
+ </plist>
238
+
239
+ and then to sign your program you should do::
240
+
241
+ $ codesign --force --sign - --entitlements entitlements.plist \
242
+ /path/to/your/program
243
+
244
+ Note that programs with the ``com.apple.security.get-task-allow `` entitlement
245
+ will not be accepted for distribution in the App Store, and will be rejected by
246
+ notarization. The entitlement is strictly for debugging purposes only and
247
+ software should not be shipped to end users with it enabled.
248
+
249
+ On macOS, we catch crashes and other events using a signal handler. Once the
250
+ backtracer has finished handling the crash, it will allow the crashing program
251
+ to continue and crash normally, which will result in the usual Crash Reporter
252
+ log file being generated.
223
253
224
254
Crash catching *cannot * be enabled for setuid binaries. This is intentional as
225
255
doing so might create a security hole.
@@ -229,3 +259,57 @@ Other Darwin (iOS, tvOS)
229
259
230
260
Crash catching is not enabled for non-macOS Darwin. You should continue to look
231
261
at the system-provided crash logs.
262
+
263
+ Linux
264
+ ^^^^^
265
+
266
+ Frame Pointers
267
+ """"""""""""""
268
+
269
+ The backtracer currently does a simple frame-pointer based unwind. As a result,
270
+ if you compile your code with ``-fomit-frame-pointer ``, which is often the
271
+ default for release builds on Intel Linux, you may find that you get incomplete
272
+ backtraces.
273
+
274
+ If you wish to get a more complete backtrace, at a small cost in performance,
275
+ you can add the compiler flags ``-Xcc -fno-omit-frame-pointer `` when building
276
+ your Swift program.
277
+
278
+ Static Linking Support
279
+ """"""""""""""""""""""
280
+
281
+ For users who statically link their binaries and do not wish to ship the Swift
282
+ runtime library alongside them, there is a statically linked copy of
283
+ ``swift-backtrace ``, named ``swift-backtrace-static `` , in the ``libexec ``
284
+ directory alongside the normal ``swift-backtrace `` binary.
285
+
286
+ By default, to locate ``swift-backtrace ``, the runtime will attempt to look in
287
+ the following locations::
288
+
289
+ <swift-root>/libexec/swift/<platform>
290
+ <swift-root>/libexec/swift/<platform>/<arch>
291
+ <swift-root>/libexec/swift
292
+ <swift-root>/libexec/swift/<arch>
293
+ <swift-root>/bin
294
+ <swift-root>/bin/<arch>
295
+ <swift-root>
296
+
297
+ where ``<swift-root> `` by default is determined from the path to the runtime
298
+ library, ``libswiftCore ``.
299
+
300
+ When the runtime is statically linked with _your_ binary, the runtime will
301
+ instead determine ``<swift-root> `` in the above patterns relative to *your
302
+ binary *. For example, if your binary is installed in e.g. ``/usr/bin ``,
303
+ ``<swift-root> `` would be ``/usr ``.
304
+
305
+ You will therefore need to install a copy of ``swift-backtrace-static ``, renamed
306
+ to ``swift-backtrace ``, in one of the locations above; the simplest option will
307
+ often be to put it in the same directory as your own binary.
308
+
309
+ You can also explicitly specify the value of ``<swift-root> `` using the
310
+ environment variable ``SWIFT_ROOT ``, or you can explicitly specify the location
311
+ of the backtracer using
312
+ ``SWIFT_BACKTRACE=swift-backtrace=<path-to-swift-backtrace> ``.
313
+
314
+ If the runtime is unable to locate the backtracer, it will allow your program to
315
+ crash as it would have done anyway.
0 commit comments