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 For anything not explicitly listed here, assume that LLDB follows the LLVM
  22 policy.
  23
  24 Coding Style
  25 ++++++++++++
  26
  27 LLDB's code style differs from `LLVM's coding style <https://llvm.org/docs/CodingStandards.html>`_
  28 in a few ways. The 2 main ones are:
  29
  30 * `Variable and function naming <https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_:
  31
  32   * Variables are ``snake_case``.
  33
  34   * Functions and methods are ``UpperCamelCase``.
  35
  36   * Static, global and member variables have ``s_``, ``g_`` and ``m_``
  37     prefixes respectively.
  38
  39 * `Use of asserts <https://llvm.org/docs/CodingStandards.html#assert-liberally>`_:
  40   See the :ref:`section below<Error Handling>`.
  41
  42 For any other contradications, consider the
  43 `golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_
  44 before choosing to update the style of existing code.
  45
  46 All new code in LLDB should be formatted with clang-format. Existing code may
  47 not conform and should be updated prior to being modified. Bulk reformatting
  48 is discouraged.
  49
  50 Test Infrastructure
  51 +++++++++++++++++++
  52
  53 Like LLVM it is important to submit tests with your patches, but note that  a
  54 subset of LLDB tests (the API tests) use a different system. Refer to the
  55 `test documentation <test.html>`_ for more details and the
  56 `lldb/test <https://github.com/llvm/llvm-project/tree/main/lldb/test>`_ folder
  57 for examples.
  58
  59 .. _Error handling:
  60
  61 Error handling and use of assertions in LLDB
  62 --------------------------------------------
  63
  64 Contrary to Clang, which is typically a short-lived process, LLDB
  65 debuggers stay up and running for a long time, often serving multiple
  66 debug sessions initiated by an IDE. For this reason LLDB code needs to
  67 be extra thoughtful about how to handle errors. Below are a couple
  68 rules of thumb:
  69
  70 * Invalid input.  To deal with invalid input, such as malformed DWARF,
  71   missing object files, or otherwise inconsistent debug info,
  72   error handling types such as `llvm::Expected<T>
  73   <https://llvm.org/doxygen/classllvm_1_1Expected.html>`_ or
  74   ``std::optional<T>`` should be used. Functions that may fail
  75   should return their result using these wrapper types instead of
  76   using a bool to indicate success. Returning a default value when an
  77   error occurred is also discouraged.
  78
  79 * Assertions.  Assertions (from ``assert.h``) should be used liberally
  80   to assert internal consistency.  Assertions shall **never** be
  81   used to detect invalid user input, such as malformed DWARF.  An
  82   assertion should be placed to assert invariants that the developer
  83   is convinced will always hold, regardless what an end-user does with
  84   LLDB. Because assertions are not present in release builds, the
  85   checks in an assertion may be more expensive than otherwise
  86   permissible. In combination with the LLDB test suite, assertions are
  87   what allows us to refactor and evolve the LLDB code base.
  88
  89 * Logging. LLDB provides a very rich logging API. When recoverable
  90   errors cannot reasonably be surfaced to the end user, the error may
  91   be written to a topical log channel.
  92
  93 * Soft assertions.  LLDB provides ``lldbassert()`` as a soft
  94   alternative to cover the middle ground of situations that indicate a
  95   recoverable bug in LLDB.  When asserts are enabled ``lldbassert()``
  96   behaves like ``assert()``. When asserts are disabled, it will print a
  97   warning and encourage the user to file a bug report, similar to
  98   LLVM's crash handler, and then return execution. Use these sparingly
  99   and only if error handling is not otherwise feasible.
 100
 101 .. note::
 102
 103   New code should not be using ``lldbassert()`` and existing uses should
 104   be replaced by other means of error handling.
 105
 106 * Fatal errors.  Aborting LLDB's process using
 107   ``llvm::report_fatal_error()`` or ``abort()`` should be avoided at all
 108   costs.  It's acceptable to use ``llvm_unreachable()`` for actually
 109   unreachable code such as the default in an otherwise exhaustive
 110   switch statement.
 111
 112 Overall, please keep in mind that the debugger is often used as a last
 113 resort, and a crash in the debugger is rarely appreciated by the
 114 end-user.