================ @@ -0,0 +1,83 @@ +================== +Summary Extraction +================== + +.. WARNING:: The framework is rapidly evolving. + The documentation might be out-of-sync of the implementation. + The purpose of this documentation to give context for upcoming reviews. + + +The simplest way to think about the lifetime of a summary extraction is by following the handlers of the ``FrontendAction`` implementing it. +There are 3 APIs that are important for us, that are invoked in this order: + + - ``BeingInvocation()``: Checks the command-line arguments related to summary extraction. + - ``CreateASTConsumer()``: Creates the ASTConsumers for the different summary extractors. + - ``EndSourceFile()``: Serializes and writes the extracted summaries. + +Implementation details +********************** + +Global Registries +================= + +The framework uses `llvm::Registry\<\> <https://llvm.org/doxygen/classllvm_1_1Registry.html>`_ +as an extension point for adding new summary analyses or serialization formats. +In short, a static object constructor will insert a note into the linked-list of the *registry*. +Each entry in the *registry* holds a name, a description and a pointer to a constructor. +In plain terms, a *registry* is a list of *recipes* and the *registry* is the *cookbook* if you will. + +**Pros**: + + - Decentralizes the registration. There is not a single place in the source code where we spell out all of the analyses/formats. + - Plays nicely with downstream extensibility, as downstream users can add their own analyses/formats without touching the source code of the framework; while still benefiting from the upstream-provided analyses/formats. + - Works with static and dynamic linking. In other words, plugins as shared objects compose naturally. + +**Cons**: + + - Registration slows down all ``clang`` users by a tiny amount, even if they don't invoke the summary extraction framework. + - As the registration is now decoupled, it's now a global program property; and potentially more difficult to reason about. + - Complicates testing. + +Example for adding a custom summary extraction +---------------------------------------------- + +.. code-block:: c++ + + //--- MyAnalysis.cpp + class MyAnalysis : public TUSummaryExtractor { + using TUSummaryExtractor::TUSummaryExtractor; + // Implementation... + }; + + static TUSummaryExtractorRegistry::Add<MyAnalysis> + RegisterExtractor("MyAwesomeAnalysis", "The analysis produces some awesome results"); + +Details of ``BeingInvocation()`` ---------------- ymand wrote:
BeginInvocation? https://github.com/llvm/llvm-project/pull/172876 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
