Author: jdevlieghere Date: Mon Sep 30 17:12:47 2019 New Revision: 373277 URL: http://llvm.org/viewvc/llvm-project?rev=373277&view=rev Log: [Docs] Document lldb-instr
This adds some information on how to instrument the API classes. Modified: lldb/trunk/docs/resources/sbapi.rst Modified: lldb/trunk/docs/resources/sbapi.rst URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/docs/resources/sbapi.rst?rev=373277&r1=373276&r2=373277&view=diff ============================================================================== --- lldb/trunk/docs/resources/sbapi.rst (original) +++ lldb/trunk/docs/resources/sbapi.rst Mon Sep 30 17:12:47 2019 @@ -53,3 +53,43 @@ file, and adding documentation and the P decidedly low-tech way, by maintaining the two files in parallel. That simplifies the build process, but it does mean that if you add a method to the C++ API's for an SB class, you have to copy the interface to the .i file. + +API Instrumentation +------------------- + +The reproducer infrastructure requires API methods to be instrumented so that +they can be captured and replayed. Instrumentation consists of two macros, +``LLDB_REGISTER`` and ``LLDB_RECORD``. Both can be automatically generated with +the ``lldb-instr`` utility. + +To add instrumentation for a given file, pass it to the ``lldb-instr`` tool. +Like other clang-based tools it requires a compilation database +(``compile_commands.json``) to be present in the current working directory. + +:: + + ./bin/lldb-instr /path/to/lldb/source/API/SBDebugger.cpp + + +The tool will automatically insert ``LLDB_RECORD`` macros inline, however you +will need to run ``clang-format`` over the processed file, as the tool +(intentionally) makes no attempt to get that right. + +The ``LLDB_REGISTER`` macros are printed to standard out between curly braces. +You'll have to copy-paste those into the corresponding `RegsiterMethods` +function in the implementation file. This function is fully specialized in the +corresponding type. + +:: + + template <> void RegisterMethods<SBDebugger>(Registry &R) { + ... + } + + +When adding a new class, you'll also have to add a call to ``RegisterMethods`` +in the ``SBRegistry`` constructor. + +The tool can be used incrementally. However, it will ignore existing macros +even if their signature is wrong. It will only generate a ``LLDB_REGISTER`` if +it emitted a corresponding ``LLDB_RECORD`` macro. _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits