forked from OSchip/llvm-project
127 lines
7.2 KiB
HTML
Executable File
127 lines
7.2 KiB
HTML
Executable File
<!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>
|