Don't abort() in lldb_assert and document why.

rdar://problem/49356014

Differential Revision: https://reviews.llvm.org/D59911

llvm-svn: 357268

1 files changed, 102 insertions, 0 deletions

diff --git a/lldb/docs/resources/source.rst b/lldb/docs/resources/source.rst
new file mode 100644
index 00000000000..8ef69b04b23
--- /dev/null
+++ b/lldb/docs/resources/source.rst
@@ -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.