[flang][driver] Add print function name Plugin example

[stuartellis]

Summary

Replacing Hello World example Plugin with one that counts and prints the names of
functions and subroutines.
This involves changing the PluginParseTreeAction Plugin base class to
inherit from PrescanAndSemaAction class to get access to the Parse Tree
so that the Plugin can walk it.
Additionally, there are tests of this new Plugin to check it prints the correct
things in different circumstances.

Depends on: D106137

[awarzynski]

Thank you for working on this @stuartellis ! This plugin is going to be a great reference example for walking the parse tree.

I have a couple of suggestions:

• I think that you can replace flangHelloWorldPlugin with flangPrintFunctionNames. The former becomes uninteresting when compared to the latter :)
• Could you add more tests? More on this below.

Ideas for extra tests:

• function + subroutine calls (these should not be taken into account, right?)
• functions within INTERFACE s
• external vs internal functions and subroutines

I know that @kiranchandramohan used the visitor API before, so perhaps he'll have another suggestion.

flang/examples/PrintFlangFunctionNames/CMakeLists.txt

6

FIXME

flang/examples/PrintFlangFunctionNames/PrintFlangFunctionNames.cpp

82

FIXME

flang/test/Driver/plugin-print-fns.f90

29 ↗

(On Diff #362820)

FIXME

[kiranchandramohan]

I think using Function and Subroutine Statement in the Post statement will cause to include function interface specification and miss cases like module procedures.

https://www.ibm.com/docs/en/xl-fortran-aix/16.1.0?topic=attributes-module-procedure-fortran-2008

[stuartellis]

Address review comments
Extending testing to different types of functions/subroutines
Removing flangHelloWorldPlugin

[awarzynski]

Thank you for addressing my comments @stuartellis ! I've left a couple of comments inline. I would be tempted to further split the test file into multiple files:

• one test file to show that function and subroutine definitions are counted as expected (count should be != 0)
• one test file to show that function/subroutine calls are ignored (with count == 0, if possible)
• one test file to show that interfaces are not taken into account (with count == 0, if possible)
• one test file with a misspelled plugin name

Also, the tests should probably be located in flang/test/examples rather than flang/test/Driver.

flang/examples/PrintFlangFunctionNames/PrintFlangFunctionNames.cpp

68

Non-public data members should be named with leading miniscule (lower-case) letters, internal camelCase capitalization, and a trailing underscore, e.g. DoubleEntryBookkeepingSystem myLedger_;.

https://github.com/llvm/llvm-project/blob/main/flang/docs/C%2B%2Bstyle.md#naming

flang/test/Driver/plugin-print-fns.f90

9–13 ↗

(On Diff #366285)

Could you move this test to a separate file? It's orthogonal to other things being tested here and IMO it makes sense to keep it separate. Basically, I would split the testing as follows:

• test for expected output to verify that the plugin works as expected when _everything is fine_
• test for diagnostics to verify that any abnormal behavior is reported in a sane way.

Otherwise, different tests blend with each other. And by moving them to separate files, you can give the test files a bit more accurate/descriptive names, e.g.:

• functions_and_subroutines.f90
• invalid_plugin_name.f90

[kiranchandramohan]

LGTM. I have one comment.

flang/examples/PrintFlangFunctionNames/PrintFlangFunctionNames.cpp

61

Nit: Do you want to count this along with Subroutines or as a separate category? If you are not counting then it might be OK to skip it completely.

There are also statement functions. How will you count them? If not counting then feel free to skip.
https://docs.oracle.com/cd/E19957-01/805-4939/6j4m0vnb9/index.html

[stuartellis]

Addressing review comments:
Split test into multiple files

[stuartellis]

I have split up the test and moved them into a new flang/text/Examples directory, but kept one test in the flang/test/Drivers directory, which doesn't reference the example plugin, for testing the incorrect plugin name Error diagnostic.

I have chosen for this plugin to skip counting/printing of Statement Functions or Module Procedures, which would be dealt with through StmtFunctionStmt and MpSubprogramStmt nodes respectively. I have adjusted the comment in the Plugin to make note of this.

[awarzynski]

With the latest update, the tests make it clear what is supported. Thank you, LGTM!

flang/examples/CMakeLists.txt

 if(NOT FLANG_BUILD_EXAMPLES)
   set(EXCLUDE_FROM_ALL ON)
 endif()
 
 # This test is not run by default as it requires input.
 add_executable(external-hello-world
   external-hello.cpp
 )
 
 target_link_libraries(external-hello-world
   FortranRuntime
 )
 
-add_subdirectory(HelloWorld)
+add_subdirectory(PrintFlangFunctionNames)

flang/examples/HelloWorld/HelloWorldPlugin.cpp

-//===-- HelloWorldPlugin.cpp ----------------------------------------------===//
-//
-// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
-// See https://llvm.org/LICENSE.txt for license information.
-// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
-//
-//===----------------------------------------------------------------------===//
-//
-// Basic example Flang plugin which simply prints a Hello World statement
-//
-//===----------------------------------------------------------------------===//
-
-#include "flang/Frontend/FrontendActions.h"
-#include "flang/Frontend/FrontendPluginRegistry.h"
-
-using namespace Fortran::frontend;
-
-class HelloWorldFlangPlugin : public PluginParseTreeAction {
-  void ExecuteAction() override {
-    llvm::outs() << "Hello World from your new Flang plugin\n";
-  }
-};
-
-static FrontendPluginRegistry::Add<HelloWorldFlangPlugin> X(
-    "-hello-world", "Hello World Plugin example");

flang/examples/PrintFlangFunctionNames/CMakeLists.txt

 # TODO: Note that this is currently only available on Linux.
 # On Windows, we would also have to specify e.g. `PLUGIN_TOOL`.
 add_llvm_library(
-    flangHelloWorldPlugin
+    flangPrintFunctionNames
     MODULE
-    HelloWorldPlugin.cpp
+    PrintFlangFunctionNames.cpp
 )

flang/examples/PrintFlangFunctionNames/PrintFlangFunctionNames.cpp

+//===-- PrintFlangFunctionNames.cpp ---------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+//
+// Small example Flang plugin to count/print Functions & Subroutines names.
+// It walks the Parse Tree using a Visitor struct that has Post functions for
+// FunctionStmt and SubroutineStmt to access the names of functions &
+// subroutines. It also has Pre functions for FunctionSubprogram and
+// SubroutineSubprogram so a Bool can be set to show that it is the definition
+// of a function/subroutine, and not print those that are in an Interface.
+// This plugin does not recognise Statement Functions or Module Procedures,
+// which could be dealt with through StmtFunctionStmt and MpSubprogramStmt nodes
+// respectively.
+//
+//===----------------------------------------------------------------------===//
+
+#include "flang/Frontend/CompilerInstance.h"
+#include "flang/Frontend/FrontendActions.h"
+#include "flang/Frontend/FrontendPluginRegistry.h"
+#include "flang/Parser/dump-parse-tree.h"
+#include "flang/Parser/parsing.h"
+
+using namespace Fortran::frontend;
+
+class PrintFunctionNamesAction : public PluginParseTreeAction {
+
+  // Visitor struct that defines Pre/Post functions for different types of nodes
+  struct ParseTreeVisitor {
+    template <typename A> bool Pre(const A &) { return true; }
+    template <typename A> void Post(const A &) {}
+
+    bool Pre(const Fortran::parser::FunctionSubprogram &) {
+      isInSubprogram_ = true;
+      return true;
+    }
+    void Post(const Fortran::parser::FunctionStmt &f) {
+      if (isInSubprogram_) {
+        llvm::outs() << "Function:\t"
+                     << std::get<Fortran::parser::Name>(f.t).ToString() << "\n";
+        fcounter++;
+        isInSubprogram_ = false;
+      }
+    }
+
+    bool Pre(const Fortran::parser::SubroutineSubprogram &) {
+      isInSubprogram_ = true;
+      return true;
+    }
+    void Post(const Fortran::parser::SubroutineStmt &s) {
+      if (isInSubprogram_) {
+        llvm::outs() << "Subroutine:\t"
+                     << std::get<Fortran::parser::Name>(s.t).ToString() << "\n";
+        scounter++;
+        isInSubprogram_ = false;
+      }
+    }
+
+    int fcounter{0};
+    int scounter{0};
+
+  private:
+    bool isInSubprogram_{false};
+  };
+
+  void ExecuteAction() override {
+    auto &parseTree{instance().parsing().parseTree()};
+
+    ParseTreeVisitor visitor;
+    Fortran::parser::Walk(parseTree, visitor);
+
+    llvm::outs() << "\n====   Functions: " << visitor.fcounter << " ====\n";
+    llvm::outs() << "==== Subroutines: " << visitor.scounter << " ====\n";
+  }
+};
+
+static FrontendPluginRegistry::Add<PrintFunctionNamesAction> X(
+    "print-fns", "Print Function names");

flang/include/flang/Frontend/FrontendActions.h

struct MeasurementVisitor {
   }
   size_t objects{0}, bytes{0};
 };
 
 //===----------------------------------------------------------------------===//
 // Custom Consumer Actions
 //===----------------------------------------------------------------------===//
 
-class PluginParseTreeAction : public FrontendAction {
-  void ExecuteAction() override;
-};
-
 class InputOutputTestAction : public FrontendAction {
   void ExecuteAction() override;
 };
 
 class EmitObjAction : public FrontendAction {
   void ExecuteAction() override;
 };
 

 class GetSymbolsSourcesAction : public PrescanAndSemaAction {
   void ExecuteAction() override;
 };
 
 class ParseSyntaxOnlyAction : public PrescanAndSemaAction {
   void ExecuteAction() override;
 };
 
+class PluginParseTreeAction : public PrescanAndSemaAction {
+  void ExecuteAction() override;
+};
+
 } // namespace Fortran::frontend
 
 #endif // LLVM_FLANG_FRONTEND_FRONTENDACTIONS_H

flang/test/CMakeLists.txt

 
 if (FLANG_INCLUDE_TESTS)
   if (FLANG_GTEST_AVAIL)
     list(APPEND FLANG_TEST_DEPENDS FlangUnitTests)
   endif()
 endif()
 
 if (FLANG_BUILD_EXAMPLES)
-  list(APPEND FLANG_TEST_DEPENDS flangHelloWorldPlugin)
+  list(APPEND FLANG_TEST_DEPENDS
+    flangPrintFunctionNames
+    )
 endif ()
 
 add_custom_target(flang-test-depends DEPENDS ${FLANG_TEST_DEPENDS})
 
 add_lit_testsuite(check-flang "Running the Flang regression tests"
   ${CMAKE_CURRENT_BINARY_DIR}
   PARAMS ${FLANG_TEST_PARAMS}
   DEPENDS ${FLANG_TEST_DEPENDS}

flang/test/Driver/plugin-example.f90

-! Check that loading and running the Hello World plugin example results in the correct print statement
-! Also check that when a plugin name isn't found, the error diagnostic is correct
-! This requires that the examples are built (FLANG_BUILD_EXAMPLES=ON)
-
-! REQUIRES: plugins, examples, shell
-
-! RUN: %flang_fc1 -load %llvmshlibdir/flangHelloWorldPlugin%pluginext -plugin -hello-world %s 2>&1 | FileCheck %s
-! CHECK: Hello World from your new Flang plugin
-
-! RUN: not %flang_fc1 -load %llvmshlibdir/flangHelloWorldPlugin%pluginext -plugin -wrong-name %s 2>&1 | FileCheck %s --check-prefix=ERROR
-! ERROR: error: unable to find plugin '-wrong-name'

flang/test/Driver/plugin-invalid-name.f90

+! Check the correct error diagnostic is reported when a plugin name isn't found
+
+! REQUIRES: plugins, shell
+
+! RUN: not %flang_fc1 -plugin -wrong-name %s 2>&1 | FileCheck %s --check-prefix=ERROR
+
+! ERROR: error: unable to find plugin '-wrong-name'

flang/test/Examples/print-fns-calls.f90

+! Check the Flang Print Function Names example plugin doesn't count/print function/subroutine calls (should only count definitions)
+! This requires that the examples are built (FLANG_BUILD_EXAMPLES=ON) to access flangPrintFunctionNames.so
+
+! REQUIRES: plugins, examples, shell
+
+! RUN: %flang_fc1 -load %llvmshlibdir/flangPrintFunctionNames%pluginext -plugin print-fns %s 2>&1 | FileCheck %s
+
+!-----------------------------
+! EXPECTED OUTPUT: Counts == 0
+!-----------------------------
+! CHECK: ==== Functions: 0 ====
+! CHECK-NEXT: ==== Subroutines: 0 ====
+
+!-----------------------------
+! INPUT
+!-----------------------------
+program main
+    call subroutine1
+    fn1 = function1()
+    fn2 = function2()
+end program main

flang/test/Examples/print-fns-definitions.f90

+! Check the Flang Print Function Names example plugin prints and counts function/subroutine definitions
+! This includes internal and external Function/Subroutines, but not Statement Functions
+! This requires that the examples are built (FLANG_BUILD_EXAMPLES=ON) to access flangPrintFunctionNames.so
+
+! REQUIRES: plugins, examples, shell
+
+! RUN: %flang_fc1 -load %llvmshlibdir/flangPrintFunctionNames%pluginext -plugin print-fns %s 2>&1 | FileCheck %s
+
+!-------------------------------------------------
+! EXPECTED OUTPUT: Names printed and counts != 0
+!-------------------------------------------------
+! CHECK: Function: external_func1
+! CHECK-NEXT: Function: external_func2
+! CHECK-NEXT: Subroutine: external_subr
+! CHECK-NEXT: Function: internal_func
+! CHECK-NEXT: Subroutine: internal_subr
+! CHECK-EMPTY:
+! CHECK-NEXT: ==== Functions: 3 ====
+! CHECK-NEXT: ==== Subroutines: 2 ====
+
+!--------------------------
+! INPUT
+!--------------------------
+function external_func1()
+end function
+
+function external_func2()
+end function
+
+subroutine external_subr
+end subroutine
+
+program main
+contains
+    function internal_func()
+    end function
+
+    subroutine internal_subr
+    end subroutine
+end program main

flang/test/Examples/print-fns-interfaces.f90

+! Check the Flang Print Function Names example plugin doesn't count/print Functions/Subroutines in interfaces
+! (It should only count definitions, which will appear elsewhere for interfaced functions/subroutines)
+! This requires that the examples are built (FLANG_BUILD_EXAMPLES=ON) to access flangPrintFunctionNames.so
+
+! REQUIRES: plugins, examples, shell
+
+! RUN: %flang_fc1 -load %llvmshlibdir/flangPrintFunctionNames%pluginext -plugin print-fns %s 2>&1 | FileCheck %s
+
+!-----------------------------
+! EXPECTED OUTPUT: Counts == 0
+!-----------------------------
+! CHECK: ==== Functions: 0 ====
+! CHECK-NEXT: ==== Subroutines: 0 ====
+
+!--------------------------
+! INPUT
+!--------------------------
+program main
+    interface
+        function interface_func()
+        end function
+
+        subroutine interface_subr()
+        end subroutine
+    end interface
+end program main