1Contributing
2============
3
4Getting Started
5---------------
6
7Please refer to the `LLVM Getting Started Guide
8<https://llvm.org/docs/GettingStarted.html>`_ for general information on how to
9get started on the LLVM project. A detailed explanation on how to build and
10test LLDB can be found in the `build instructions <build.html>`_ and `test
11instructions <test.html>`_ respectively.
12
13Contributing to LLDB
14--------------------
15
16Please refer to the `LLVM Developer Policy
17<https://llvm.org/docs/DeveloperPolicy.html>`_ for information about
18authoring and uploading a patch. LLDB differs from the LLVM Developer
19Policy 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
30For anything not explicitly listed here, assume that LLDB follows the LLVM
31policy.
32
33
34Error handling and use of assertions in LLDB
35--------------------------------------------
36
37Contrary to Clang, which is typically a short-lived process, LLDB
38debuggers stay up and running for a long time, often serving multiple
39debug sessions initiated by an IDE. For this reason LLDB code needs to
40be extra thoughtful about how to handle errors. Below are a couple
41rules 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
84Overall, please keep in mind that the debugger is often used as a last
85resort, and a crash in the debugger is rarely appreciated by the
86end-user.
87