[Lldb-commits] [lldb] r357268 - Don't abort() in lldb_assert and document why.
Adrian Prantl via lldb-commits
lldb-commits at lists.llvm.org
Fri Mar 29 09:12:27 PDT 2019
Author: adrian
Date: Fri Mar 29 09:12:27 2019
New Revision: 357268
URL: http://llvm.org/viewvc/llvm-project?rev=357268&view=rev
Log:
Don't abort() in lldb_assert and document why.
rdar://problem/49356014
Differential Revision: https://reviews.llvm.org/D59911
Added:
lldb/trunk/docs/resources/source.rst
Modified:
lldb/trunk/docs/index.rst
lldb/trunk/source/Utility/LLDBAssert.cpp
lldb/trunk/www/source.html
Modified: lldb/trunk/docs/index.rst
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/docs/index.rst?rev=357268&r1=357267&r2=357268&view=diff
==============================================================================
--- lldb/trunk/docs/index.rst (original)
+++ lldb/trunk/docs/index.rst Fri Mar 29 09:12:27 2019
@@ -7,7 +7,7 @@ LLDB is a next generation, high-performa
reusable components which highly leverage existing libraries in the larger LLVM
Project, such as the Clang expression parser and LLVM disassembler.
-LLDB is the default debugger in Xcode on Mac OS X and supports debugging C,
+LLDB is the default debugger in Xcode on macOS and supports debugging C,
Objective-C and C++ on the desktop and iOS devices and simulator.
All of the code in the LLDB project is available under the standard
@@ -52,6 +52,7 @@ Resources
resources/download
resources/build
+ resources/source
resources/test
resources/sbapi
resources/external
Added: lldb/trunk/docs/resources/source.rst
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/docs/resources/source.rst?rev=357268&view=auto
==============================================================================
--- lldb/trunk/docs/resources/source.rst (added)
+++ lldb/trunk/docs/resources/source.rst Fri Mar 29 09:12:27 2019
@@ -0,0 +1,102 @@
+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.
Modified: lldb/trunk/source/Utility/LLDBAssert.cpp
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/source/Utility/LLDBAssert.cpp?rev=357268&r1=357267&r2=357268&view=diff
==============================================================================
--- lldb/trunk/source/Utility/LLDBAssert.cpp (original)
+++ lldb/trunk/source/Utility/LLDBAssert.cpp Fri Mar 29 09:12:27 2019
@@ -27,5 +27,4 @@ void lldb_private::lldb_assert(bool expr
llvm::sys::PrintStackTrace(errs());
errs() << "please file a bug report against lldb reporting this failure "
"log, and as many details as possible\n";
- abort();
}
Modified: lldb/trunk/www/source.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/source.html?rev=357268&r1=357267&r2=357268&view=diff
==============================================================================
--- lldb/trunk/www/source.html (original)
+++ lldb/trunk/www/source.html Fri Mar 29 09:12:27 2019
@@ -26,7 +26,7 @@
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>
@@ -39,7 +39,7 @@
`-- 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
@@ -57,12 +57,66 @@
<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>
More information about the lldb-commits
mailing list