[flang][nfc] Move `Semantics` from `FrontendAction` to `CompilerInstance`

[awarzynski]

Summary

CompilerInstance is a more appropriate place for a key component of
the frontend like Semantics.

This change opens a path for us to introduce new frontend actions that
will also run semantics, but for which inheriting from
PrescanAndSemaAction wouldn't make much sense. For example, for
code-gen actions we plan to introduce a dedicate hierarchy of action
classes.

I've also added a doxyment for CompilerInstance to add a bit of
context for this change (and also make future refactoring more informed).
As CompilerInstance in Flang has been inspired by its counterpart in
Clang, this comment is roughly a verbatim copy of the comment in Clang
(with some adjustments from me). Credits to Daniel Dunbar for the great
design and the original comment.

[ashermancinelli]

This introduces a very clean level of indirection imo. +1 for adapting the clang documentation as well!

flang/include/flang/Frontend/CompilerInstance.h

 #include "flang/Frontend/PreprocessorOptions.h"
 #include "flang/Parser/parsing.h"
 #include "flang/Parser/provenance.h"
 #include "flang/Semantics/semantics.h"
 #include "llvm/Support/raw_ostream.h"
 
 namespace Fortran::frontend {
 
+/// Helper class for managing a single instance of the Flang compiler.
+///
+/// This class serves two purposes:
+///  (1) It manages the various objects which are necessary to run the compiler
+///  (2) It provides utility routines for constructing and manipulating the
+///      common Flang objects.
+///
+/// The compiler instance generally owns the instance of all the objects that it
+/// manages. However, clients can still share objects by manually setting the
+/// object and retaking ownership prior to destroying the CompilerInstance.
+///
+/// The compiler instance is intended to simplify clients, but not to lock them
+/// in to the compiler instance for everything. When possible, utility functions
+/// come in two forms; a short form that reuses the CompilerInstance objects,
+/// and a long form that takes explicit instances of any required objects.
 class CompilerInstance {
 
   /// The options used in this compiler instance.
   std::shared_ptr<CompilerInvocation> invocation_;
 
   /// Flang file  manager.
   std::shared_ptr<Fortran::parser::AllSources> allSources_;
 
   std::shared_ptr<Fortran::parser::AllCookedSources> allCookedSources_;
 
   std::shared_ptr<Fortran::parser::Parsing> parsing_;
 
+  std::unique_ptr<Fortran::semantics::Semantics> semantics_;
+
   /// The stream for diagnostics from Semantics
   llvm::raw_ostream *semaOutputStream_ = &llvm::errs();
 
   /// The stream for diagnostics from Semantics if owned, otherwise nullptr.
   std::unique_ptr<llvm::raw_ostream> ownedSemaOutputStream_;
 
   /// The diagnostics engine instance.
   llvm::IntrusiveRefCntPtr<clang::DiagnosticsEngine> diagnostics_;
public:
   void set_semaOutputStream(llvm::raw_ostream &Value);
 
   /// Replace the current stream for verbose output.
   void set_semaOutputStream(std::unique_ptr<llvm::raw_ostream> Value);
 
   /// Get the current stream for verbose output.
   llvm::raw_ostream &semaOutputStream() { return *semaOutputStream_; }
 
+  Fortran::semantics::Semantics &semantics() { return *semantics_; }
+  const Fortran::semantics::Semantics &semantics() const { return *semantics_; }
+
+  void setSemantics(std::unique_ptr<Fortran::semantics::Semantics> semantics) {
+    semantics_ = std::move(semantics);
+  }
+
   /// }
   /// @name High-Level Operations
   /// {
 
   /// Execute the provided action against the compiler's
   /// CompilerInvocation object.
   /// \param act - The action to execute.
   /// \return - True on success.

flang/include/flang/Frontend/FrontendActions.h

 class DebugDumpParseTreeNoSemaAction : public PrescanAndParseAction {
   void ExecuteAction() override;
 };
 
 //===----------------------------------------------------------------------===//
 // PrescanAndSema Actions
 //===----------------------------------------------------------------------===//
 class PrescanAndSemaAction : public FrontendAction {
-  std::unique_ptr<Fortran::semantics::Semantics> semantics_;
 
   void ExecuteAction() override = 0;
   bool BeginSourceFileAction(CompilerInstance &ci) override;
-
-public:
-  Fortran::semantics::Semantics &semantics() { return *semantics_; }
-  const Fortran::semantics::Semantics &semantics() const { return *semantics_; }
-
-  void setSemantics(std::unique_ptr<Fortran::semantics::Semantics> semantics) {
-    semantics_ = std::move(semantics);
-  }
 };
 
 class DebugUnparseWithSymbolsAction : public PrescanAndSemaAction {
   void ExecuteAction() override;
 };
 
 class DebugUnparseAction : public PrescanAndSemaAction {
   void ExecuteAction() override;

flang/lib/Frontend/FrontendActions.cpp

if (reportFatalParsingErrors(this))
     return false;
 
   // Report the diagnostics from parsing
   ci.parsing().messages().Emit(llvm::errs(), ci.allCookedSources());
 
   auto &parseTree{*ci.parsing().parseTree()};
 
   // Prepare semantics
-  setSemantics(std::make_unique<Fortran::semantics::Semantics>(
+  ci.setSemantics(std::make_unique<Fortran::semantics::Semantics>(
       ci.invocation().semanticsContext(), parseTree,
       ci.invocation().debugModuleDir()));
-  auto &semantics = this->semantics();
+  auto &semantics = ci.semantics();
 
   // Run semantic checks
   semantics.Perform();
 
   // Report the diagnostics from the semantic checks
   semantics.EmitMessages(ci.semaOutputStream());
 
   return true;
void PrintPreprocessedAction::ExecuteAction() {
   }
 }
 
 void DebugDumpProvenanceAction::ExecuteAction() {
   this->instance().parsing().DumpProvenance(llvm::outs());
 }
 
 void ParseSyntaxOnlyAction::ExecuteAction() {
-  reportFatalSemanticErrors(semantics(), this->instance().diagnostics(),
-      GetCurrentFileOrBufferName());
+  CompilerInstance &ci = this->instance();
+
+  reportFatalSemanticErrors(
+      ci.semantics(), ci.diagnostics(), GetCurrentFileOrBufferName());
 }
 
 void DebugUnparseNoSemaAction::ExecuteAction() {
   auto &invoc = this->instance().invocation();
   auto &parseTree{instance().parsing().parseTree()};
 
   // TODO: Options should come from CompilerInvocation
   Unparse(llvm::outs(), *parseTree,
void DebugUnparseAction::ExecuteAction() {
   // TODO: Options should come from CompilerInvocation
   Unparse(*os, *parseTree,
       /*encoding=*/Fortran::parser::Encoding::UTF_8,
       /*capitalizeKeywords=*/true, /*backslashEscapes=*/false,
       /*preStatement=*/nullptr,
       invoc.useAnalyzedObjectsForUnparse() ? &invoc.asFortran() : nullptr);
 
   // Report fatal semantic errors
-  reportFatalSemanticErrors(semantics(), this->instance().diagnostics(),
+  reportFatalSemanticErrors(ci.semantics(), this->instance().diagnostics(),
       GetCurrentFileOrBufferName());
 }
 
 void DebugUnparseWithSymbolsAction::ExecuteAction() {
+  CompilerInstance &ci = this->instance();
   auto &parseTree{*instance().parsing().parseTree()};
 
   Fortran::semantics::UnparseWithSymbols(
       llvm::outs(), parseTree, /*encoding=*/Fortran::parser::Encoding::UTF_8);
 
   // Report fatal semantic errors
-  reportFatalSemanticErrors(semantics(), this->instance().diagnostics(),
-      GetCurrentFileOrBufferName());
+  reportFatalSemanticErrors(
+      ci.semantics(), ci.diagnostics(), GetCurrentFileOrBufferName());
 }
 
 void DebugDumpSymbolsAction::ExecuteAction() {
   CompilerInstance &ci = this->instance();
-  auto &semantics = this->semantics();
+  auto &semantics = ci.semantics();
 
   auto tables{Fortran::semantics::BuildRuntimeDerivedTypeTables(
       instance().invocation().semanticsContext())};
   // The runtime derived type information table builder may find and report
   // semantic errors. So it is important that we report them _after_
   // BuildRuntimeDerivedTypeTables is run.
   reportFatalSemanticErrors(
       semantics, this->instance().diagnostics(), GetCurrentFileOrBufferName());
void DebugDumpAllAction::ExecuteAction() {
   // Dump parse tree
   auto &parseTree{instance().parsing().parseTree()};
   llvm::outs() << "========================";
   llvm::outs() << " Flang: parse tree dump ";
   llvm::outs() << "========================\n";
   Fortran::parser::DumpTree(
       llvm::outs(), parseTree, &ci.invocation().asFortran());
 
-  auto &semantics = this->semantics();
+  auto &semantics = ci.semantics();
   auto tables{Fortran::semantics::BuildRuntimeDerivedTypeTables(
       instance().invocation().semanticsContext())};
   // The runtime derived type information table builder may find and report
   // semantic errors. So it is important that we report them _after_
   // BuildRuntimeDerivedTypeTables is run.
   reportFatalSemanticErrors(
       semantics, this->instance().diagnostics(), GetCurrentFileOrBufferName());
 
void DebugDumpParseTreeNoSemaAction::ExecuteAction() {
   auto &parseTree{instance().parsing().parseTree()};
 
   // Dump parse tree
   Fortran::parser::DumpTree(
       llvm::outs(), parseTree, &this->instance().invocation().asFortran());
 }
 
 void DebugDumpParseTreeAction::ExecuteAction() {
+  CompilerInstance &ci = this->instance();
   auto &parseTree{instance().parsing().parseTree()};
 
   // Dump parse tree
   Fortran::parser::DumpTree(
       llvm::outs(), parseTree, &this->instance().invocation().asFortran());
 
   // Report fatal semantic errors
-  reportFatalSemanticErrors(semantics(), this->instance().diagnostics(),
-      GetCurrentFileOrBufferName());
+  reportFatalSemanticErrors(
+      ci.semantics(), ci.diagnostics(), GetCurrentFileOrBufferName());
 }
 
 void DebugMeasureParseTreeAction::ExecuteAction() {
   CompilerInstance &ci = this->instance();
 
   // Parse. In case of failure, report and return.
   ci.parsing().Parse(llvm::outs());
 
llvm::outs() << "Parse tree comprises " << visitor.objects
                << " objects and occupies " << visitor.bytes
                << " total bytes.\n";
 }
 
 void DebugPreFIRTreeAction::ExecuteAction() {
   CompilerInstance &ci = this->instance();
   // Report and exit if fatal semantic errors are present
   if (reportFatalSemanticErrors(
-          semantics(), ci.diagnostics(), GetCurrentFileOrBufferName())) {
+          ci.semantics(), ci.diagnostics(), GetCurrentFileOrBufferName())) {
     return;
   }
 
   auto &parseTree{*ci.parsing().parseTree()};
 
   // Dump pre-FIR tree
   if (auto ast{Fortran::lower::createPFT(
           parseTree, ci.invocation().semanticsContext())}) {
     Fortran::lower::dumpPFT(llvm::outs(), *ast);
   } else {
     unsigned diagID = ci.diagnostics().getCustomDiagID(
         clang::DiagnosticsEngine::Error, "Pre FIR Tree is NULL.");
     ci.diagnostics().Report(diagID);
   }
 }
 
 void DebugDumpParsingLogAction::ExecuteAction() {
   CompilerInstance &ci = this->instance();
 
   ci.parsing().Parse(llvm::errs());
   ci.parsing().DumpParsingLog(llvm::outs());
 }
 
 void GetDefinitionAction::ExecuteAction() {
+  CompilerInstance &ci = this->instance();
+
   // Report and exit if fatal semantic errors are present
-  if (reportFatalSemanticErrors(semantics(), this->instance().diagnostics(),
-          GetCurrentFileOrBufferName()))
+  if (reportFatalSemanticErrors(
+          ci.semantics(), ci.diagnostics(), GetCurrentFileOrBufferName()))
     return;
 
-  CompilerInstance &ci = this->instance();
   parser::AllCookedSources &cs = ci.allCookedSources();
   unsigned diagID = ci.diagnostics().getCustomDiagID(
       clang::DiagnosticsEngine::Error, "Symbol not found");
 
   auto gdv = ci.invocation().frontendOpts().getDefVals;
   auto charBlock{cs.GetCharBlockFromLineAndColumns(
       gdv.line, gdv.startColumn, gdv.endColumn)};
   if (!charBlock) {
void GetDefinitionAction::ExecuteAction() {
   llvm::outs() << "Found symbol name: " << symbol->name().ToString() << "\n";
   llvm::outs() << symbol->name().ToString() << ": "
                << sourceInfo->first.file.path() << ", "
                << sourceInfo->first.line << ", " << sourceInfo->first.column
                << "-" << sourceInfo->second.column << "\n";
 }
 
 void GetSymbolsSourcesAction::ExecuteAction() {
+  CompilerInstance &ci = this->instance();
+
   // Report and exit if fatal semantic errors are present
-  if (reportFatalSemanticErrors(semantics(), this->instance().diagnostics(),
-          GetCurrentFileOrBufferName()))
+  if (reportFatalSemanticErrors(
+          ci.semantics(), ci.diagnostics(), GetCurrentFileOrBufferName()))
     return;
 
-  semantics().DumpSymbolsSources(llvm::outs());
+  ci.semantics().DumpSymbolsSources(llvm::outs());
 }
 
 void EmitObjAction::ExecuteAction() {
   CompilerInstance &ci = this->instance();
   unsigned DiagID = ci.diagnostics().getCustomDiagID(
       clang::DiagnosticsEngine::Error, "code-generation is not available yet");
   ci.diagnostics().Report(DiagID);
 }