--- /dev/null
+Checking out LLDB Sources
+=========================
+
+Refer to the `LLVM Getting Started Guide
+<http://llvm.org/docs/GettingStarted.html#getting-started-with-llvm>`_
+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.
+
+Git browser: https://github.com/llvm/llvm-project/tree/master/lldb
+
+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.
+
+ ::
+
+ lldb
+ |
+ `-- llvm
+ |
+ +-- tools
+ |
+ `-- clang
+
+
+So updating your checkout will consist of updating LLDB, LLV<, and
+Clang in these locations. Refer to the `Build Instructions
+<build.html>`_ for more detailed instructions on how to build for a
+particular platform / build system combination.
+
+Contributing to LLDB
+====================
+
+Please refer to the `LLVM Developer Policy
+<http://llvm.org/docs/DeveloperPolicy.html>`_ for information about
+authoring and uploading a patch. LLDB differs from the LLVM Developer
+Policy in the following respects.
+
+Test infrastructure. It is still important to submit tests with your
+patches, but LLDB uses a different system for tests. Refer to the
+`lldb/test` folder on disk for examples of how to write tests. For
+anything not explicitly listed here, assume that LLDB follows the LLVM
+policy.
+
+
+Error handling and use of assertions in LLDB
+============================================
+
+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:
+
+* 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 `llvm::Expected<T>
+ <http://llvm.org/doxygen/classllvm_1_1Expected.html>`_ or
+ `llvm::Optional<T>
+ <http://llvm.org/doxygen/classllvm_1_1Optional.html>`_ 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.
+
+* Assertions. Assertions (from `assert.h`) should be used liberally
+ to assert internal consistency. Assertions shall **never** 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.
+
+* 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.
+
+* Soft assertions. LLDB provides `lldb_assert()` as a soft
+ alternative to cover the middle ground of situations that indicate a
+ recoverable bug in LLDB. In a Debug configuration `lldb_assert()`
+ behaves like `assert()`. 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 `lldb_assert()` and existing
+ uses should be replaced by other means of error handling.
+
+* Fatal errors. Aborting LLDB's process using
+ `llvm::report_fatal_error()` or `abort()` should be avoided at all
+ costs. It's acceptable to use `llvm_unreachable()
+ <http://llvm.org/doxygen/Support_2ErrorHandling_8h.html>`_ for
+ actually unreachable code such as the default in an otherwise
+ exhaustive switch statement.
+
+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.
contains LLDB.</p>
<p><b>Git browser</b>: https://github.com/llvm/llvm-project/tree/master/lldb </p>
<p>
- For MacOSX building from Xcode, simply checkout LLDB and then build from Xcode. The Xcode project will
+ 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>
`-- clang
</tt>
</pre>
- So updating your checkout will consist of updating lldb, llvm, and clang in these locations.
+ 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
<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 lldb/test folder on disk for examples of how to write tests.
+ 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>
+ <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>
projects / platform / upstream / llvm.git / commitdiff