[flang][nfc] Fix variable names in FrontendOptions & PreprocessorOptions

As all member variables in `FrontendOptions` and `PreprocessorOptions`
are public, we should be naming them as `variable` rather than
`variable_` [1]. This patch fixes that.

Also, `FrontendOptions` & `PreprocessorOptions` are re-defined as a
structs rather than classes (all fields are meant to be public).

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

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

Author: banach-space

flang/docs/FlangDriver.md

@@ -0,0 +1,247 @@
+<!--===- docs/FlangDriver.md
+
+   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
+
+-->
+
+# Flang drivers
+
+```eval_rst
+.. contents::
+   :local:
+```
+
+There are two main drivers in Flang:
+* the compiler driver, `flang-new`
+* the frontend driver, `flang-new -fc1`
+
+The compiler driver will allow you to control all compilation phases (i.e.
+preprocessing, frontend code-generation, middlend/backend code-optimisation and
+lowering, linking). For frontend specific tasks, the compiler driver creates a
+Fortran compilation job and delegates it to `flang-new -fc1`, the frontend driver.
+
+The frontend driver glues all of the frontend libraries together and provides
+an easy-to-use and intuitive interface to the frontend. It accepts many
+frontend-specific options not available in `flang-new` and as such it provides a
+finer control over the frontend. Similarly to `-Xclang` in `clang`, you can use
+`-Xflang` to forward the frontend specific flags from the compiler directly to
+the frontend driver.
+
+## Compiler Driver
+
+The main entry point for Flang's compiler driver is implemented in
+`flang/tools/flang-driver/driver.cpp`.  Flang's compiler driver is implemented
+in terms of Clang's driver library, `clangDriver`. This approach allows us to:
+* benefit from Clang's support for various targets, platforms and operating systems
+* leverage Clang's ability to drive various backends available in LLVM, as well
+  as linkers and assemblers.
+One implication of this dependency on Clang is that all of Flang's compiler
+options are defined alongside Clang's options in
+`clang/include/clang/Driver/Options.td`. For options that are common for both
+Flang and Clang, the corresponding definitions are shared.
+
+Internally, a `clangDriver` based compiler driver works by creating actions
+that correspond to various compilation phases, e.g. `PreprocessJobClass`,
+`CompileJobClass`, `BackendJobClass` or `LinkJobClass` from the
+`clang::driver::Action::ActionClass` enum. There are also other, more
+specialised actions, e.g. `MigrateJobClass` or `InputClass`, that do not map
+directly to common compilation steps. The actions to run are determined from
+the supplied compiler flags, e.g.
+
+* `-E` for `PreprocessJobClass`,
+* `-c` for `CompileJobClass`.
+
+In most cases, the driver creates a chain of actions/jobs/phases where the
+output from one action is the input for the subsequent one. You can use the
+`-ccc-print-phases` flag to see the sequence of actions that the driver will
+create for your compiler invocation:
+```bash
+flang-new -ccc-print-phases -E file.f
++- 0: input, "file.f", f95-cpp-input
+1: preprocessor, {0}, f95
+```
+As you can see, for `-E` the driver creates only two jobs and stops immediately
+after preprocessing. The first job simply prepares the input. For `-c`, the
+pipeline of the created jobs is more complex:
+```bash
+flang-new -ccc-print-phases -c file.f
+         +- 0: input, "file.f", f95-cpp-input
+      +- 1: preprocessor, {0}, f95
+   +- 2: compiler, {1}, ir
++- 3: backend, {2}, assembler
+4: assembler, {3}, object
+```
+Note that currently Flang does not support code-generation and `flang-new` will
+fail during the second step above with the following error:
+```bash
+error: code-generation is not available yet
+```
+The other phases are printed nonetheless when using `-ccc-print-phases`, as
+that reflects what `clangDriver`, the library, will try to create and run.
+
+For actions specific to the frontend (e.g. preprocessing or code generation), a
+command to call the frontend driver is generated (more specifically, an
+instance of `clang::driver::Command`). Every command is bound to an instance of
+`clang::driver::Tool`. For Flang we introduced a specialisation of this class:
+`clang::driver::Flang`. This class implements the logic to either translate or
+forward compiler options to the frontend driver, `flang-new -fc1`.
+
+You can read more on the design of `clangDriver` in Clang's [Driver Design &
+Internals](https://clang.llvm.org/docs/DriverInternals.html).
+
+## Frontend Driver
+Flang's frontend driver is the main interface between end-users and the Flang
+frontend. The high-level design is similar to Clang's frontend driver, `clang
+-cc1` and consists of the following classes:
+* `CompilerInstance`, which is a helper class that encapsulates and manages
+  various objects that are always required by the frontend (e.g. `AllSources`,
+  `AllCookedSources, `Parsing`, `CompilerInvocation`, etc.). In most cases
+  `CompilerInstance` owns these objects, but it also can share them with its
+  clients when required. It also implements utility methods to construct and
+  manipulate them.
+* `CompilerInvocation` encapsulates the configuration of the current
+  invocation of the compiler as derived from the command-line options and the
+  input files (in particular, file extensions). Among other things, it holds an
+  instance of `FrontendOptions`. Like `CompilerInstance`, it owns the objects
+  that it manages. It can share them with its clients that want to access them
+  even after the corresponding `CompilerInvocation` has been destructed.
+* `FrontendOptions` holds options that control the behaviour of the frontend,
+  as well as e.g. the list of the input files. These options come either
+  directly from the users (through command-line flags) or are derived from
+  e.g. the host system configuration.
+* `FrontendAction` and `FrontendActions` (the former being the base class for
+  the latter) implement the actual actions to perform by the frontend. Usually
+  there is one specialisation of `FrontendActions` for every compiler action flag
+  (e.g. `-E`, `-fdebug-unparse`). These classes also contain various hooks that
+  allow you to e.g. fine-tune the configuration of the frontend based on the
+  input.
+
+This list is not exhaustive and only covers the main classes that implement the
+driver. The main entry point for the frontend driver, `fc1_main`, is
+implemented in `flang/tools/flang-driver/driver.cpp`. It can be accessed by
+invoking the compiler driver, `flang-new`, with the `-fc1` flag.
+
+The frontend driver will only run one action at a time. If you specify multiple
+action flags, only the last one will be taken into account. The default action
+is `ParseSyntaxOnlyAction`, which corresponds to `-fsyntax-only`. In other
+words, `flang-new -fc1 <input-file>` is equivalent to `flang-new -fc1 -fsyntax-only
+<input-file>`.
+
+## Adding new Compiler Options
+Adding a new compiler option in Flang consists of two steps:
+* define the new option in a dedicated TableGen file,
+* parse and implement the option in the relevant drivers that support it.
+
+### Option Definition
+All of Flang's compiler and frontend driver options are defined in
+`clang/include/clang/Driver/Options.td` in Clang. When adding a new option to
+Flang, you will either:
+  * extend the existing definition for an option that is already available
+    in one of Clang's drivers (e.g.  `clang`), but not yet available in Flang, or
+  * add a completely new definition if the option that you are adding has not
+    been defined yet.
+
+There are many predefined TableGen classes and records that you can use to fine
+tune your new option. The list of available configurations can be overwhelming
+at times. Sometimes the easiest approach is to find an existing option that has
+similar semantics to your new option and start by copying that.
+
+For every new option, you will also have to define the visibility of the new
+option. This is controlled through the `Flags` field. You can use the following
+Flang specific option flags to control this:
+  * `FlangOption` - this option will be available in the `flang-new` compiler driver,
+  * `FC1Option` - this option will be available in the `flang-new -fc1` frontend driver,
+  * `FlangOnlyOption` - this option will not be visible in Clang drivers.
+
+Please make sure that options that you add are only visible in drivers that can
+support it. For example, options that only make sense for Fortran input files
+(e.g. `-ffree-form`) should not be visible in Clang and be marked as
+`FlangOnlyOption`.
+
+When deciding what `OptionGroup` to use when defining a new option in the
+`Options.td` file, many new options fall into one of the following two
+categories:
+  * `Action_Group` - options that define an action to run (e.g.
+    `-fsyntax-only`, `-E`)
+  * `f_Group` - target independent compiler flags (e.g. `-ffixed-form`,
+    `-fopenmp`)
+There are also other groups and occasionally you will use them instead of the
+groups listed above.
+
+### Option Implementation
+First, every option needs to be parsed. Flang compiler options are parsed in
+two different places, depending on which driver they belong to:
+
+* frontend driver: `flang/lib/Frontend/CompilerInvocation.cpp`,
+* compiler driver: `clang/lib/Driver/ToolChains/Flang.cpp`.
+
+The parsing will depend on the semantics encoded in the TableGen definition.
+
+When adding a compiler driver option (i.e. an option that contains
+`FlangOption` among its `Flags`) that you also intend to be understood by the
+frontend, make sure that it is either forwarded to `flang-new -fc1` or translated
+into some other option that is accepted by the frontend driver. In the case of
+options that contain both `FlangOption` and `FC1Option` among its flags, we
+usually just forward from `flang-new` to `flang-new -fc1`. This is then tested in
+`flang/test/Driver/frontend-forward.F90`.
+
+What follows is usually very dependant on the meaning of the corresponding
+option. In general, regular compiler flags (e.g. `-ffree-form`) are mapped to
+some state within the driver. A lot of this state is stored within an instance
+of `FrontendOptions`, but there are other more specialised classes too. Action
+flags (e.g. `-fsyntax-only`) are usually more complex overall, but also more
+structured in terms of the implementation.
+
+### Action Options
+For options that correspond to an action (i.e. marked as `Action_Group`), you
+will have to define a dedicated instance of `FrontendActions` in
+`flang/include/flang/Frontend/FrontendOptions.h`. For example, for
+`-fsyntax-only` we defined:
+```cpp
+class ParseSyntaxOnlyAction : public PrescanAndSemaAction {
+  void ExecuteAction() override;
+};
+```
+Command line options are mapped to frontend actions through the
+`Fortran::frontend::ActionKind` enum.  For every new action option that you
+add, you will have to add a dedicated entry in that enum (e.g.
+`ParseSyntaxOnly` for `-fsyntax-only`) and a corresponding `case` in
+`ParseFrontendArgs` function in the `CompilerInvocation.cpp` file, e.g.:
+```cpp
+    case clang::driver::options::OPT_fsyntax_only:
+      opts.programAction = ParseSyntaxOnly;
+      break;
+```
+Note that this simply sets the program/frontend action within the frontend
+driver. You still have make sure that the corresponding frontend action class
+is instantiated when your new action option is used. The relevant `switch`
+statement is implemented in `Fortran::frontend::CreatedFrontendBaseAction` in
+the `ExecuteCompilerInvocation.cpp` file. Here's an example for
+`-fsyntax-only`:
+```cpp
+  case ParseSyntaxOnly:
+    return std::make_unique<ParseSyntaxOnlyAction>();
+```
+At this point you should be able to trigger that frontend action that you have
+just added using your new frontend option.
+
+# Testing
+In LIT, we define two variables that you can use to invoke Flang's drivers:
+* `%flang` is expanded as `flang-new` (i.e. the compiler driver)
+* `%flang_fc1` is expanded as `flang-new -fc1` (i.e. the frontend driver)
+
+For most regression tests for the frontend, you will want to use `%flang_fc1`.
+In some cases, the observable behaviour will be identical regardless of whether
+`%flang` or `%flang_fc1` is used. However, when you are using `%flang` instead
+of `%flang_fc1`, the compiler driver will add extra flags to the frontend
+driver invocation (i.e. `flang-new -fc1 -<extra-flags>`). In some cases that might
+be exactly what you want to test.  In fact, you can check these additional
+flags by using the `-###` compiler driver command line option.
+
+Lastly, you can use `! REQUIRES: <feature>` for tests that will only work when
+`<feature>` is available. For example, you can use`! REQUIRES: shell` to mark a
+test as only available on Unix-like systems (i.e. systems that contain a Unix
+shell). In practice this means that the corresponding test is skipped on
+Windows.

flang/include/flang/Frontend/CompilerInstance.h

@@ -179,7 +179,7 @@ class CompilerInstance {
   ///
   /// \param binary     The mode to open the file in.
   /// \param baseInput  If the invocation contains no output file name (i.e.
-  ///                   outputFile_ in FrontendOptions is empty), the input path
+  ///                   outputFile in FrontendOptions is empty), the input path
   ///                   name to use for deriving the output path.
   /// \param extension  The extension to use for output names derived from
   ///                   \p baseInput.

flang/include/flang/Frontend/FrontendOptions.h

@@ -199,60 +199,58 @@ class FrontendInputFile {
 };
 
 /// FrontendOptions - Options for controlling the behavior of the frontend.
-class FrontendOptions {
-public:
+struct FrontendOptions {
+  FrontendOptions()
+      : showHelp(false), showVersion(false), instrumentedParse(false),
+        needProvenanceRangeToCharBlockMappings(false) {}
+
   /// Show the -help text.
-  unsigned showHelp_ : 1;
+  unsigned showHelp : 1;
 
   /// Show the -version text.
-  unsigned showVersion_ : 1;
+  unsigned showVersion : 1;
 
   /// Instrument the parse to get a more verbose log
-  unsigned instrumentedParse_ : 1;
+  unsigned instrumentedParse : 1;
 
   /// Enable Provenance to character-stream mapping. Allows e.g. IDEs to find
   /// symbols based on source-code location. This is not needed in regular
   /// compilation.
-  unsigned needProvenanceRangeToCharBlockMappings_ : 1;
+  unsigned needProvenanceRangeToCharBlockMappings : 1;
 
   /// Input values from `-fget-definition`
   struct GetDefinitionVals {
     unsigned line;
     unsigned startColumn;
     unsigned endColumn;
   };
-  GetDefinitionVals getDefVals_;
+  GetDefinitionVals getDefVals;
 
   /// The input files and their types.
-  std::vector<FrontendInputFile> inputs_;
+  std::vector<FrontendInputFile> inputs;
 
   /// The output file, if any.
-  std::string outputFile_;
+  std::string outputFile;
 
   /// The frontend action to perform.
-  frontend::ActionKind programAction_;
+  frontend::ActionKind programAction;
 
   // The form to process files in, if specified.
-  FortranForm fortranForm_ = FortranForm::Unknown;
+  FortranForm fortranForm = FortranForm::Unknown;
 
   // The column after which characters are ignored in fixed form lines in the
   // source file.
-  int fixedFormColumns_ = 72;
+  int fixedFormColumns = 72;
 
   /// The input kind, either specified via -x argument or deduced from the input
   /// file name.
-  InputKind dashX_;
+  InputKind dashX;
 
   // Language features
-  common::LanguageFeatureControl features_;
+  common::LanguageFeatureControl features;
 
   // Source file encoding
-  Fortran::parser::Encoding encoding_{Fortran::parser::Encoding::UTF_8};
-
-public:
-  FrontendOptions()
-      : showHelp_(false), showVersion_(false), instrumentedParse_(false),
-        needProvenanceRangeToCharBlockMappings_(false) {}
+  Fortran::parser::Encoding encoding{Fortran::parser::Encoding::UTF_8};
 
   // Return the appropriate input kind for a file extension. For example,
   /// "*.f" would return Language::Fortran.

flang/include/flang/Frontend/PreprocessorOptions.h

@@ -31,9 +31,11 @@ enum class PPMacrosFlag : uint8_t {
 
 /// This class is used for passing the various options used
 /// in preprocessor initialization to the parser options.
-class PreprocessorOptions {
-public:
+struct PreprocessorOptions {
+  PreprocessorOptions() {}
+
   std::vector<std::pair<std::string, /*isUndef*/ bool>> macros;
+
   // Search directories specified by the user with -I
   // TODO: When adding support for more options related to search paths,
   // consider collecting them in a separate aggregate. For now we keep it here
@@ -42,17 +44,14 @@ class PreprocessorOptions {
   // Search directories specified by the user with -fintrinsic-modules-path
   std::vector<std::string> searchDirectoriesFromIntrModPath;
 
-  PPMacrosFlag macrosFlag_ = PPMacrosFlag::Unknown;
+  PPMacrosFlag macrosFlag = PPMacrosFlag::Unknown;
 
   // -P: Suppress #line directives in -E output
   bool noLineDirectives{false};
 
   // -fno-reformat: Emit cooked character stream as -E output
   bool noReformat{false};
 
-public:
-  PreprocessorOptions() {}
-
   void addMacroDef(llvm::StringRef name) {
     macros.emplace_back(std::string(name), false);
   }

flang/lib/Frontend/CompilerInstance.cpp

@@ -89,7 +89,7 @@ CompilerInstance::CreateDefaultOutputFile(
 
   // Get the path of the output file
   std::string outputFilePath =
-      GetOutputFilePath(frontendOpts().outputFile_, baseName, extension);
+      GetOutputFilePath(frontendOpts().outputFile, baseName, extension);
 
   // Create the output file
   std::unique_ptr<llvm::raw_pwrite_stream> os =
@@ -150,7 +150,7 @@ bool CompilerInstance::ExecuteAction(FrontendAction &act) {
   invoc.setSemanticsOpts(*this->allCookedSources_);
 
   // Run the frontend action `act` for every input file.
-  for (const FrontendInputFile &fif : frontendOpts().inputs_) {
+  for (const FrontendInputFile &fif : frontendOpts().inputs) {
     if (act.BeginSourceFile(*this, fif)) {
       if (llvm::Error err = act.Execute()) {
         consumeError(std::move(err));