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 21For anything not explicitly listed here, assume that LLDB follows the LLVM 22policy. 23 24Coding Style 25++++++++++++ 26 27LLDB's code style differs from `LLVM's coding style <https://llvm.org/docs/CodingStandards.html>`_ 28in 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 42For any other contradications, consider the 43`golden rule <https://llvm.org/docs/CodingStandards.html#introduction>`_ 44before choosing to update the style of existing code. 45 46All new code in LLDB should be formatted with clang-format. Existing code may 47not conform and should be updated prior to being modified. Bulk reformatting 48is discouraged. 49 50Test Infrastructure 51+++++++++++++++++++ 52 53Like LLVM it is important to submit tests with your patches, but note that a 54subset 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 57for examples. 58 59.. _Error handling: 60 61Error handling and use of assertions in LLDB 62-------------------------------------------- 63 64Contrary to Clang, which is typically a short-lived process, LLDB 65debuggers stay up and running for a long time, often serving multiple 66debug sessions initiated by an IDE. For this reason LLDB code needs to 67be extra thoughtful about how to handle errors. Below are a couple 68rules 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 112Overall, please keep in mind that the debugger is often used as a last 113resort, and a crash in the debugger is rarely appreciated by the 114end-user. 115