Skip to content

Commit 27641cb

Browse files
committed
[Docs] Update backtracing documentation for Linux.
Update the backtracing documentation with details on static linking, frame pointer usage and a couple of other matters. rdar://117679284
1 parent a94d22e commit 27641cb

File tree

1 file changed

+96
-12
lines changed

1 file changed

+96
-12
lines changed

docs/Backtracing.rst

Lines changed: 96 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,6 @@ Swift now supports:
2727

2828
* Automatic crash catching and backtrace generation out of the box.
2929
* Built-in symbolication.
30-
* A choice of unwind algorithms, including "fast", DWARF and SEH.
3130
* Interactive(!) crash/runtime error catching.
3231

3332
Crash catching is enabled by default, and won't interfere with any system-wide
@@ -61,10 +60,7 @@ follows:
6160
+-----------------+---------+--------------------------------------------------+
6261
| unwind | auto | Specifies which unwind algorithm to use. |
6362
| | | ``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. |
6864
+-----------------+---------+--------------------------------------------------+
6965
| preset | auto | Specifies which set of preset formatting options |
7066
| | | to use. Options are ``friendly``, ``medium`` or |
@@ -106,7 +102,7 @@ follows:
106102
| | | to the runtime library, or using ``SWIFT_ROOT``. |
107103
+-----------------+---------+--------------------------------------------------+
108104

109-
(*) On macOS, this defaults to ``tty`` rather than ``yes``.
105+
(*) On macOS, this defaults to ``no`` rather than ``yes``.
110106

111107
Backtrace limits
112108
----------------
@@ -179,10 +175,10 @@ triggered automatically by the runtime.
179175
System specifics
180176
----------------
181177

182-
macOS
183-
^^^^^
178+
Signal Handling
179+
^^^^^^^^^^^^^^^
184180

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
186182
writing, this is installed for the following signals:
187183

188184
+--------------+--------------------------+-------------------------------------+
@@ -217,9 +213,43 @@ finds that there is already a handler for that signal. Similarly if something
217213
else has already configured an alternate signal stack, it will leave that
218214
stack alone.
219215

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

224254
Crash catching *cannot* be enabled for setuid binaries. This is intentional as
225255
doing so might create a security hole.
@@ -229,3 +259,57 @@ Other Darwin (iOS, tvOS)
229259

230260
Crash catching is not enabled for non-macOS Darwin. You should continue to look
231261
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

Comments
 (0)