[PATCH] D111573: [Flang][driver] Update docs

[Andrzej Warzynski via Phabricator via llvm-commits]

awarzynski added a comment.

Thank you for the review, Pete.

In D111573#3058546 <https://reviews.llvm.org/D111573#3058546>, @PeteSteinfeld wrote:

> When invoking the compiler driver, I'll want to specify options to the frontend.  How do I do that?

You can do this with -Xflang <https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Driver/Options.td#L4549-L4552>:

  flang-new -Xflang -fdebug-dump-parse-tree input.f95

In the above ^^^ invocation, `-fdebug-dump-parse-tree` is forwarded to `flang-new -fc1`. Here are a few small experiments that illustrate this:

  # Print the input file fist
  $ cat input.f95
  end program
  
  # 1. Compiler driver: `-fdebug-dump-parse-tree` *is not* supported
  $ bin/flang-new -fdebug-dump-parse-tree file.f95
  flang-new: warning: argument unused during compilation: '-fdebug-dump-parse-tree'
  
  # 2. Frontend driver: `-fdebug-dump-parse-tree` *is* supported
  $ bin/flang-new -fc1 -fdebug-dump-parse-tree file.f95
  Program -> ProgramUnit -> MainProgram
  | SpecificationPart
  | | ImplicitPart ->
  | ExecutionPart -> Block
  | EndProgramStmt ->
  
  # 3. Compiler driver: `-fdebug-dump-parse-tree` is forwarded to `flang-new -fc1` with `-Xflang`
  $ bin/flang-new -Xflang -fdebug-dump-parse-tree file.f95
  Program -> ProgramUnit -> MainProgram
  | SpecificationPart
  | | ImplicitPart ->
  | ExecutionPart -> Block
  | EndProgramStmt ->

Note that `Xflang` is similar to the following option flags in Clang:

- Xclang <https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Driver/Options.td#L801-L803>
- Xlinker <https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Driver/Options.td#L816-L818>
- Xassembler <https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Driver/Options.td#L798-L800>

Other, somewhat similar and very popular option: mllvm <https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Driver/Options.td#L3173-L3175>. GCC has similar options too, see e.g. Xassembler <https://gcc.gnu.org/onlinedocs/gcc/Assembler-Options.html>.

> The document implies that the frontend options are specifically designed to be of interest to compiler developers and are potentially unstable.  Neither one of these seems true to me.

The frontend driver has options like `-fdebug-dump-symbols`,  `-fdebug-dump-parse-tree` or `-fdebug-dump-provenance`. These expose the internals of the compiler. Would end-users be interested in these? The very interested ones can use `flang-new -fc1`. By limiting certain options to `flang-new -fc1`, we give ourselves a framework for e.g.:

- experimental flags (i.e. features that we are not yet sure about)
- flags to control code-paths that might be unstable or under active development

For example, what should we do with flags that control pass pipelines for generating MLIR or LLVM IR? In the frontend driver we can introduce many experimental flags to fine-tune every pass separately. But should these flags be available in our main user facing interface (i.e. `flang-new`)? In most cases, we would like users to rely on `-O{0|1|2|3|s|z}` instead. We've also discussed this briefly with folks from MLIR (https://llvm.discourse.group/t/passpipelineclparser-and-flang-driver/4291/2):

> I’d be very cautious about exposing this being a flag that make it very clear that these aren’t stable and meant for development / debugging purpose only: they can change from one Flang release to another.

As for your final point,

> I think it would be good to include a brief overview of the compilation processes controlled by the compiler driver and the frontend driver.

We probably need a diagram for this. I will try to produce something.



================
Comment at: flang/docs/FlangDriver.md:30
+an easy-to-use and intuitive interface to the frontend. It uses LLVM for
+code-generation and as such can be viewed as driver for LLVM libraries. It is
+aware of all the frontend internals that are "hidden" from the compiler driver.
----------------
PeteSteinfeld wrote:
> Should read "viewd as the driver".
There are many tools that "drive" LLVM (e.g. `opt`, `clang` etc). So we probably want "viewed as a driver", right?


================
Comment at: flang/docs/FlangDriver.md:45
+specialised tools. In particular, `flang-new` is not aware of various
+compilation phases within the frontend (e.g. scanning, parsing or semantic
+checks). It does not have to. Conversely, the frontend driver, `flang-new
----------------
PeteSteinfeld wrote:
> There is no scanner in the compiler, so I don't think we should mention scanning.
Would replacing `scanning` with `prescanning & preprocessing` make sense?


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D111573