[PATCH] D108283: [flang][driver] Add documentation for Plugins

[Andrzej Warzynski via Phabricator via llvm-commits]

awarzynski added a comment.

This is a great first draft, thank you for working on this @stuartellis ! Could you expand a bit and add more code examples? Also, it would be nice to mention `Fortran::parser::Walk` here. It's quite key to your example in https://reviews.llvm.org/D107089.

More comments inline.



================
Comment at: flang/docs/FlangDriver.md:278
+Plugins are an extension to the Frontend Driver that make it possible to run
+extra user defined actions, in the form of FrontendActions, during a compilation.
+The Flang Plugins are based on how Clang Plugins work.
----------------



================
Comment at: flang/docs/FlangDriver.md:279
+extra user defined actions, in the form of FrontendActions, during a compilation.
+The Flang Plugins are based on how Clang Plugins work.
+The process for using Plugins includes:
----------------
Both Clang and Flang leverage the API available in LLVM (e.g. [[ https://github.com/llvm/llvm-project/blob/main/llvm/include/llvm/Support/DynamicLibrary.h#L85 | LoadLibraryPermanently ]]. Perhaps: 
> Similarly to Clang, Flang leverges `LoadLibraryPermanently` from LLVM's `llvm::sys::DynamicLibrary` to load dynamic objects that implement plugins.
?


================
Comment at: flang/docs/FlangDriver.md:280-285
+The process for using Plugins includes:
+* Creating a Plugin Shared Object library
+* Loading the Plugin library
+* Registering the Plugin
+* Calling the Plugin
+
----------------
This list mixes two things: 
* implementation ("Creating a Plugin Shared Object library", "Registering the Plugin")
* usage ("Loading the Plugin library", "Calling the Plugin")

I would simplify as:
> The process for using Plugins includes:
> * Creating a Plugin Shared Object library (i.e. implementation)
> * Loading and Running a  Plugin Shared Object library (i.e. usage)

I would also restructure the document and make the above your 2 top sections.


================
Comment at: flang/docs/FlangDriver.md:289
+## Creating the Plugin
+The two parts required for Plugins to work are:
+1. A main class that inherits from `PluginParseTreeAction`
----------------
I would expand this into 3 parts (copying code from https://reviews.llvm.org/D107089, every item is one part):
* `class PrintFunctionNamesAction : public PluginParseTreeAction` that wraps everything together and represents the frontend action class corresponding to your plugin
* `PrintFunctionNamesAction::ExecuteAction` that implements the actual action (i.e. **what** it does)
* `static FrontendPluginRegistry::Add<PrintFunctionNamesAction> X` that registers the plugin

It would also be worthwhile to mention `struct ParseTreeVisitor` (and `Pre` and `Post` methods). No need to go into too much detail - you can provide links to the relevant docs/implementation.


================
Comment at: flang/docs/FlangDriver.md:314
+
+## Command Line
+In order to use Plugins, there are 2 command line options for the Frontend Driver:
----------------
This whole section would be more interesting with a sample invocation line. You can use your example from as reference: https://reviews.llvm.org/D107089.


================
Comment at: flang/docs/FlangDriver.md:338-341
+In `flang/example/PrintFlangFunctionNames` is an example Plugin, to demonstrate
+using the Parse Tree to print out function names. It has a `CMakeLists.txt`
+alongside to build it into a shared object. This uses a Visitor struct, which
+defines Pre/Post functions for different types of nodes, to traverse the Parse Tree.
----------------
Instead of this section, I suggest extracting snippets of code from your example plugin and use those throughout this document. Similarly to https://clang.llvm.org/docs/ClangPlugins.html.



Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108283/new/

https://reviews.llvm.org/D108283