================ @@ -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. ---------------- steakhal wrote:
It is to allow downstream users to define their own analyses and formats with minimal merge-conflict friction. For example: A user want to use the set of basic analyses provided by upstream, but enable some custom domain-specific ones serving their needs. For example, some custom analysis that looks for transformation opportunities for migrating away from using our LegacyFancyType to a BetterReplacementType. Since this migration is not really useful upstream, that analysis makes more sense to keep downstream. Similarly with serialisation formats. If someone already has support in their complicated build system for generating some custom metadata, then they could piggyback on that format for their downstream use. As a theoretical example, if one was already generating llvm IR, they could define a custom serialisation format that would serialise the analysis data into the same file to a specific section or something like that. The important part is that some users may have a custom desire, like protobufs, or beyond imagination that they don't want to share upstream, but want to employ this framework. To enable this, both analyses and formats need to be extensible. If registration would be at a centralised place, that would continuously cause merge conflicts for every downstream users, causing friction. Do you think I should elaborate this to the document? If this was a question for you, probably the audience would also need to know this, right? https://github.com/llvm/llvm-project/pull/172876 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
