| <!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> |
