1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
<title>Accessing LLDB Sources</title>
</head>
<body>
<div class="www_title">
The <strong>LLDB</strong> Debugger
</div>
<div id="container">
<div id="content">
<!--#include virtual="sidebar.incl"-->
<div id="middle">
<div class="post">
<h1 class ="postheader">Checking out LLDB sources</h1>
<div class="postcontent">
<p>Refer to the <a href="http://llvm.org/docs/GettingStarted.html#getting-started-with-llvm">LLVM Getting Started Guide</a>
for general instructions on how to check out source. Note that LLDB depends on having a working checkout of LLVM
and Clang, so the first step is to download and build as described at the above URL. The same repository also
contains LLDB.</p>
<p><b>Git browser</b>: https://github.com/llvm/llvm-project/tree/master/lldb </p>
<p>
For macOS building from Xcode, simply checkout LLDB and then build from Xcode. The Xcode project will
automatically detect that it is a fresh checkout, and checkout LLVM and clang automatically. Unlike other
platforms / build systems, it will use the following directory structure.
<pre><tt>
lldb
|
`-- llvm
|
+-- tools
|
`-- clang
</tt>
</pre>
So updating your checkout will consist of updating LLDB, LLVM, and Clang in these locations.
</p>
<p>
Refer to the <a href="build.html">Build Instructions</a> for more detailed instructions on how to build for a particular
platform / build system combination.
</p>
</div>
</div>
<div class="post">
<h1 class ="postheader">Contributing to LLDB</h1>
<div class="postcontent">
<p>
Please refer to the <a href="http://llvm.org/docs/DeveloperPolicy.html">LLVM Developer Policy</a>
for information about authoring and uploading a patch. LLDB differs from the LLVM Developer Policy in
the following respects.
<ul>
<li>
Test infrastructure. It is still important to submit tests with your patches, but LLDB uses a different
system for tests. Refer to the <tt>lldb/test</tt> folder on disk for examples of how to write tests.
</li>
</ul>
For anything not explicitly listed here, assume that LLDB follows the LLVM policy.
</p>
</div>
</div>
<div class="post">
<h1 class ="postheader">Error handling and use of assertions in LLDB</h1>
<div class="postcontent">
<p>
Contrary to clang, which is typically a short-lived process, LLDB debuggers
stay up and running for a long time, often serving multiple debug sessions
initiated by an IDE. For this reason LLDB code needs to be extra thoughtful
about how to handle errors. Below are a couple rules of thumb:
<ul>
<li>Invalid input.
To deal with invalid input, such as malformed DWARF, missing object files, or otherwise
inconsistent debug info, LLVM's error handling types such as
<a href="http://llvm.org/doxygen/classllvm_1_1Expected.html"><tt>llvm::Expected<T></tt></a> or
<a href="http://llvm.org/doxygen/classllvm_1_1Optional.html"><tt>llvm::Optional<T></tt></a>
should be used. Functions that may fail should return their result using these wrapper
types instead of using a bool to indicate success. Returning a default value when an
error occurred is also discouraged.
</li>
<li>Assertions.
Assertions (from <tt>assert.h</tt>) should be used liberally to assert internal consistency.
Assertions shall <em>never</em> be used to detect invalid user input, such as malformed DWARF.
An assertion should be placed to assert invariants that the developer is convinced will
always hold, regardless what an end-user does with LLDB. Because assertions are not
present in release builds, the checks in an assertion may be more expensive than
otherwise permissible. In combination with the LLDB test suite,
assertions are what allows us to refactor and evolve the LLDB code base.
</li>
<li>Logging.
LLDB provides a very rich logging API. When recoverable errors cannot reasonably
by surfaced to the end user, the error may be written to a topical log channel.
<li>Soft assertions.
LLDB provides <tt>lldb_assert()</tt> as a soft alternative to cover the middle ground
of situations that indicate a recoverable bug in LLDB.
In a Debug configuration <tt>lldb_assert()</tt> behaves like
<tt>assert()</tt>. In a Release configuration it will print a warning and encourage the
user to file a bug report, similar to LLVM's crash handler, and then return
execution. Use these sparingly and only if error handling is not otherwise feasible.
Specifically, new code should not be using <tt>lldb_assert()</tt> and existing uses
should be replaced by other means of error handling.
</li>
<li>Fatal errors.
Aborting LLDB's process using <tt>llvm::report_fatal_error()</tt> or <tt>abort</tt>
should be avoided at all costs. It's acceptable to use
<a href="http://llvm.org/doxygen/Support_2ErrorHandling_8h.html"><tt>llvm_unreachable()</tt></a>
for actually unreachable code such as the default in an otherwise exhaustive switch statement.
</li>
</ul>
Overall, please keep in mind that the debugger is often used as a last resort,
and a crash in the debugger is rarely appreciated by the end-user.
</p>
</div>
</div>
<div class="postfooter"></div>
</div>
</div>
</div>
</div>
</body>
</html>
|
