lldb/docs/resources/contributing.rst

   1 Contributing
   2 ============
   3
   4 Getting Started
   5 ---------------
   6
   7 Please refer to the `LLVM Getting Started Guide
   8 <https://llvm.org/docs/GettingStarted.html>`_ for general information on how to
   9 get started on the LLVM project. A detailed explanation on how to build and
  10 test LLDB can be found in the `build instructions <build.html>`_ and `test
  11 instructions <test.html>`_ respectively.
  12
  13 Contributing to LLDB
  14 --------------------
  15
  16 Please refer to the `LLVM Developer Policy
  17 <https://llvm.org/docs/DeveloperPolicy.html>`_ for information about
  18 authoring and uploading a patch. LLDB differs from the LLVM Developer
  19 Policy in the following respects.
  20
  21  - **Test infrastructure**: Like LLVM it is  important to submit tests with your
  22    patches, but note that LLDB uses a different system for tests. Refer to the
  23    `test documentation <test.html>`_ for more details and the ``lldb/test``
  24    folder on disk for examples.
  25
  26  - **Coding Style**: LLDB's code style differs from LLVM's coding style.
  27    Unfortunately there is no document describing the differences. Please be
  28    consistent with the existing code.
  29
  30 For anything not explicitly listed here, assume that LLDB follows the LLVM
  31 policy.
  32
  33
  34 Error handling and use of assertions in LLDB
  35 --------------------------------------------
  36
  37 Contrary to Clang, which is typically a short-lived process, LLDB
  38 debuggers stay up and running for a long time, often serving multiple
  39 debug sessions initiated by an IDE. For this reason LLDB code needs to
  40 be extra thoughtful about how to handle errors. Below are a couple
  41 rules of thumb:
  42
  43 * Invalid input.  To deal with invalid input, such as malformed DWARF,
  44   missing object files, or otherwise inconsistent debug info, LLVM's
  45   error handling types such as `llvm::Expected<T>
  46   <https://llvm.org/doxygen/classllvm_1_1Expected.html>`_ or
  47   `std::optional<T>
  48   <https://llvm.org/doxygen/classllvm_1_1Optional.html>`_ should be
  49   used. Functions that may fail should return their result using these
  50   wrapper types instead of using a bool to indicate success. Returning
  51   a default value when an error occurred is also discouraged.
  52
  53 * Assertions.  Assertions (from ``assert.h``) should be used liberally
  54   to assert internal consistency.  Assertions shall **never** be
  55   used to detect invalid user input, such as malformed DWARF.  An
  56   assertion should be placed to assert invariants that the developer
  57   is convinced will always hold, regardless what an end-user does with
  58   LLDB. Because assertions are not present in release builds, the
  59   checks in an assertion may be more expensive than otherwise
  60   permissible. In combination with the LLDB test suite, assertions are
  61   what allows us to refactor and evolve the LLDB code base.
  62
  63 * Logging. LLDB provides a very rich logging API. When recoverable
  64   errors cannot reasonably be surfaced to the end user, the error may
  65   be written to a topical log channel.
  66
  67 * Soft assertions.  LLDB provides ``lldb_assert()`` as a soft
  68   alternative to cover the middle ground of situations that indicate a
  69   recoverable bug in LLDB.  In a Debug configuration ``lldb_assert()``
  70   behaves like ``assert()``. In a Release configuration it will print a
  71   warning and encourage the user to file a bug report, similar to
  72   LLVM's crash handler, and then return execution. Use these sparingly
  73   and only if error handling is not otherwise feasible.  Specifically,
  74   new code should not be using ``lldb_assert()`` and existing
  75   uses should be replaced by other means of error handling.
  76
  77 * Fatal errors.  Aborting LLDB's process using
  78   ``llvm::report_fatal_error()`` or ``abort()`` should be avoided at all
  79   costs.  It's acceptable to use `llvm_unreachable()
  80   <https://llvm.org/doxygen/Support_2ErrorHandling_8h.html>`_ for
  81   actually unreachable code such as the default in an otherwise
  82   exhaustive switch statement.
  83
  84 Overall, please keep in mind that the debugger is often used as a last
  85 resort, and a crash in the debugger is rarely appreciated by the
  86 end-user.