[clang] f1315c6 - [docs] Add note about interaction between clang plugins and -clear-ast-before-backend

[Arthur Eubanks via cfe-commits]

Author: Arthur Eubanks
Date: 2022-02-28T12:53:09-08:00
New Revision: f1315c61a03ea6ef72ec11522f9abecd782f4856

URL: https://github.com/llvm/llvm-project/commit/f1315c61a03ea6ef72ec11522f9abecd782f4856
DIFF: https://github.com/llvm/llvm-project/commit/f1315c61a03ea6ef72ec11522f9abecd782f4856.diff

LOG: [docs] Add note about interaction between clang plugins and -clear-ast-before-backend

Reviewed By: rnk

Differential Revision: https://reviews.llvm.org/D120666

Added: 
    

Modified: 
    clang/docs/ClangPlugins.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/ClangPlugins.rst b/clang/docs/ClangPlugins.rst
index cf2c8721c12ae..001e66e434efb 100644
--- a/clang/docs/ClangPlugins.rst
+++ b/clang/docs/ClangPlugins.rst
@@ -200,3 +200,17 @@ action (i.e. the same as using `-add-plugin`):
   PluginASTAction::ActionType getActionType() override {
     return AddAfterMainAction;
   }
+
+Interaction with ``-clear-ast-before-backend``
+----------------------------------------------
+
+To reduce peak memory usage of the compiler, plugins are recommended to run
+*before* the main action, which is usually code generation. This is because
+having any plugins that run after the codegen action automatically turns off
+``-clear-ast-before-backend``.  ``-clear-ast-before-backend`` reduces peak
+memory by clearing the Clang AST after generating IR and before running IR
+optimizations. Use ``CmdlineBeforeMainAction`` or ``AddBeforeMainAction`` as
+``getActionType`` to run plugins while still benefitting from
+``-clear-ast-before-backend``. Plugins must make sure not to modify the AST,
+otherwise they should run after the main action.
+