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&lt;T&gt;</tt></a>
 or                            
+                            <a 
href="http://llvm.org/doxygen/classllvm_1_1Optional.html";><tt>llvm::Optional&lt;T&gt;</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>


_______________________________________________
lldb-commits mailing list
lldb-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits

Reply via email to