| ============================ |
| Summary Extraction Internals |
| ============================ |
| |
| .. WARNING:: The framework is rapidly evolving. |
| The documentation might be out-of-sync with the implementation. |
| The purpose of this documentation is to give context for upcoming reviews. |
| |
| When ``--ssaf-tu-summary-file=`` is non-empty, ``CreateFrontendAction()`` (in ``ExecuteCompilerInvocation.cpp``) |
| wraps the original ``FrontendAction`` inside a ``TUSummaryExtractorFrontendAction``. |
| This ensures that the summary extraction transparently happens after the original frontend action, which is usually either compilation (``-c``) or just ``-fsyntax-only`` in tests. |
| |
| Lifetime of a summary extraction |
| ******************************** |
| |
| The ``TUSummaryExtractorFrontendAction`` will try to construct a ``TUSummaryRunner`` ASTConsumer and report an error on failure. |
| When it succeeds, it will multiplex the handlers of the ASTConsumer to every summary extractor and in the end, serialize and write the results to the desired file. |
| |
| 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. |
| Each entry in the *registry* holds a name, a description and a pointer to a constructor. |
| Because static linking can discard unreferenced registration objects, the framework |
| uses :doc:`ForceLinkerHeaders` to ensure they are retained. |
| |
| For details on how to add new extractors and formats, see :doc:`HowToExtend`. |
