+

+ 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> or + llvm::Optional<T> + 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() + 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. +

+