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

[Pete Steinfeld via Phabricator via llvm-commits]

PeteSteinfeld added a comment.

Thanks for working on this, Andrzej.

In addition to the inline comments, there are some things that I don't understand about the driver.

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

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.

As I hinted in some of my inline comments, my overall understanding of the drivers would be enhanced if I better understood the overall compilation process that they control.  I think it would be good to include a brief overview of the compilation processes controlled by the compiler driver and the frontend driver.



================
Comment at: flang/docs/FlangDriver.md:16-18
 There are two main drivers in Flang:
 * the compiler driver, `flang-new`
 * the frontend driver, `flang-new -fc1`
----------------
It would help me to understand the difference between the frontend driver and the compiler driver if I knew what the inputs and outputs of the compiler and frontend were.  I assume that the inputs of the compiler are source code and module files and that its outputs are executables, libraries, and module files.  I assume that the inputs of the frontend are the same as those of the compiler.  I'm not sure about its outputs.  Where do the tools `bbc` and `tco` fit into this picture?  Are there other tools in the LLVM compilation tool chain that the compiler driver might invoke to do optimization or analysis?


================
Comment at: flang/docs/FlangDriver.md:25
+driver. For linking, it creates a linker job and calls an external linker (e.g.
+LLVM's `lld`). It can also call e.g. external assemblers. This driver is
+intended for Flang's end-users.
----------------
Rather than "e.g.", I would say "other tools such as"


================
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.
----------------
Should read "viewd as the driver".


================
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
----------------
There is no scanner in the compiler, so I don't think we should mention scanning.


================
Comment at: flang/docs/FlangDriver.md:46
+compilation phases within the frontend (e.g. scanning, parsing or semantic
+checks). It does not have to. Conversely, the frontend driver, `flang-new
+-fc1`, needs not to be concerned with linkers or other external tools like
----------------
I think that this should read "have to be".


================
Comment at: flang/docs/FlangDriver.md:54
+* the compiler driver is an end-user tool
+* frontend-driver is a compiler developer tool with many additional options,
+
----------------
In the rest of this document, "frontend driver" is spelled without a hyphen in the middle.


================
Comment at: flang/docs/FlangDriver.md:58
+to generate executables. The frontend driver cannot call external tools and
+hence can only generate object files. Similar model is implemented in Clang
+(`clang` vs `clang -cc1` vs `clang -cc1as`), which is based on the [architecture
----------------
This should read "A similar model".


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D111573