165 lines · plain
1Contributing2============3 4Getting Started5---------------6 7Please refer to the `LLVM Getting Started Guide8<https://llvm.org/docs/GettingStarted.html>`_ for general information on how to9get started on the LLVM project. A detailed explanation on how to build and10test LLDB can be found in the `build instructions <build.html>`_ and `test11instructions <test.html>`_ respectively.12 13Contributing to LLDB14--------------------15 16Please refer to the `LLVM Developer Policy17<https://llvm.org/docs/DeveloperPolicy.html>`_ for information about18authoring and uploading a patch. LLDB differs from the LLVM Developer19Policy in the following respects.20 21For anything not explicitly listed here, assume that LLDB follows the LLVM22policy.23 24Coding Style25++++++++++++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 contradictions, consider the43`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 may47not conform and should be updated prior to being modified. Bulk reformatting48is discouraged.49 50Test Infrastructure51+++++++++++++++++++52 53Like LLVM it is important to submit tests with your patches, but note that a54subset of LLDB tests (the API tests) use a different system. Refer to the55`test documentation <test.html>`_ for more details and the56`lldb/test <https://github.com/llvm/llvm-project/tree/main/lldb/test>`_ folder57for examples.58 59 60LLDB plugins and their dependencies61-----------------------------------62 63LLDB has a concept of *plugins*, which are used to provide abstraction64boundaries over functionality that is specific to a certain architecture,65operating system, programming language, etc. A plugin implements an abstract66base class (rarely, a set of related base classes), which is a part of LLDB67core. This setup allows the LLDB core to remain generic while making it possible68to support for new architectures, languages, and so on. For this to work, all69code needs to obey certain rules.70 71The principal rule is that LLDB core (defined as: everything under lldb/source72*minus* lldb/source/Plugins) must not depend on any specific plugin. The only73way it can interact with them is through the abstract interface. Explicit74dependencies such as casting the base class to the plugin type are not permitted75and neither are more subtle dependencies like checking the name plugin or or76other situations where some code in LLDB core is tightly coupled to the77implementation details of a specific plugin.78 79The rule for interaction between different plugins is more nuanced. We recognize80that some cross-plugin dependencies are unavoidable or even desirable. For81example, a plugin may want to extend a plugin of the same kind to82add/override/refine some functionality (e.g., Android is a "kind of" Linux, but83it handles some things differently). Alternatively, a plugin of one kind may84want to build on the functionality offered by a specific plugin of another kind85(ELFCore Process plugin uses ELF ObjectFile plugin to create a process out of an86ELF core file).87 88In cases such as these, direct dependencies are acceptable. However, to keep the89dependency graph manageable, we still have some rules to govern these90relationships:91 92* All dependencies between plugins of the same kind must flow in the same93 direction (if plugin `A1` depends on plugin `B1`, then `B2` must not depend on94 `A2`)95* Dependency graph of plugin kinds must not contain loops (dependencies like96 `A1->B1`, `B2->C2` and `C3->A3` are forbidden because they induce a cycle in97 the plugin kind graph even though the plugins themselves are acyclical)98 99 100The first of these rules is checked via CMake scripts (using the101`LLDB_ACCEPTABLE_PLUGIN_DEPENDENCIES` property). Dependencies in this category102are expected and permitted (subject to other constraints such as that dependency103making sense for the particular pair of plugins). Unfortunately, due to historic104reasons, not all plugin dependencies follow this rule, which is why we have105another category called `LLDB_TOLERATED_PLUGIN_DEPENDENCIES`. New dependencies106are forbidden (even though they are accepted by CMake) and existing ones should107be removed wherever possible.108 109.. _Error handling:110 111Error handling and use of assertions in LLDB112--------------------------------------------113 114Contrary to Clang, which is typically a short-lived process, LLDB115debuggers stay up and running for a long time, often serving multiple116debug sessions initiated by an IDE. For this reason LLDB code needs to117be extra thoughtful about how to handle errors. Below are a couple118rules of thumb:119 120* Invalid input. To deal with invalid input, such as malformed DWARF,121 missing object files, or otherwise inconsistent debug info,122 error handling types such as `llvm::Expected<T>123 <https://llvm.org/doxygen/classllvm_1_1Expected.html>`_ or124 ``std::optional<T>`` should be used. Functions that may fail125 should return their result using these wrapper types instead of126 using a bool to indicate success. Returning a default value when an127 error occurred is also discouraged.128 129* Assertions. Assertions (from ``assert.h``) should be used liberally130 to assert internal consistency. Assertions shall **never** be131 used to detect invalid user input, such as malformed DWARF. An132 assertion should be placed to assert invariants that the developer133 is convinced will always hold, regardless what an end-user does with134 LLDB. Because assertions are not present in release builds, the135 checks in an assertion may be more expensive than otherwise136 permissible. In combination with the LLDB test suite, assertions are137 what allows us to refactor and evolve the LLDB code base.138 139* Logging. LLDB provides a very rich logging API. When recoverable140 errors cannot reasonably be surfaced to the end user, the error may141 be written to a topical log channel.142 143* Soft assertions. LLDB provides ``lldbassert()`` as a soft144 alternative to cover the middle ground of situations that indicate a145 recoverable bug in LLDB. When asserts are enabled ``lldbassert()``146 behaves like ``assert()``. When asserts are disabled, it will print a147 warning and encourage the user to file a bug report, similar to148 LLVM's crash handler, and then return execution. Use these sparingly149 and only if error handling is not otherwise feasible.150 151.. note::152 153 New code should not be using ``lldbassert()`` and existing uses should154 be replaced by other means of error handling.155 156* Fatal errors. Aborting LLDB's process using157 ``llvm::report_fatal_error()`` or ``abort()`` should be avoided at all158 costs. It's acceptable to use ``llvm_unreachable()`` for actually159 unreachable code such as the default in an otherwise exhaustive160 switch statement.161 162Overall, please keep in mind that the debugger is often used as a last163resort, and a crash in the debugger is rarely appreciated by the164end-user.165