[PATCH] D104229: [flang][docs] Add documentation for the new Flang driver

[Richard Barton via Phabricator via llvm-commits]

richard.barton.arm added a comment.

Great to see some docs added Andrzej - this should help us maintain the new Driver in future.

I have swept through with some comments - mostly typographical nits. More diagrams would help to explain the structure of Actions, and perhaps the relationship between the compiler driver and other jobs/binaries it could call.



================
Comment at: flang/docs/FlangDriver.md:22
+preprocessing, frontend code-generation, middlend/backend code-optimisation and
+lowering, linking). For frontend specific tasks, the compiler driver creates a
+frontend job and delegates it to `flang -fc1`, the frontend driver.
----------------
Is that the right word choice? I think it's for Fortran compilation jobs isn't it?

I wonder if "toolchain driver" == flang and "compiler driver" -> flang -fc1 might work better?


================
Comment at: flang/docs/FlangDriver.md:44
+
+Internally, a `clangDriver` based compiler driver works by creating actions
+that correspond to various compiler phases (e.g. `PreprocessJobClass`,
----------------
I think a diagram would really help explain this part.


================
Comment at: flang/docs/FlangDriver.md:60
+`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 -fc1`.
----------------



================
Comment at: flang/docs/FlangDriver.md:109
+Flang, you will either:
+  * extend the existing definition for an option that is are already available
+    in one of Clang's drivers (e.g.  `clang`), but not yet available in Flang, or
----------------



================
Comment at: flang/docs/FlangDriver.md:115
+The are many predefined TableGen classes and records that you can use to fine
+tune you new option. The list of available configurations can be overwhelming
+at times. Sometimes the easiest approach is to find an existing option that has
----------------



================
Comment at: flang/docs/FlangDriver.md:122
+Flang specific option flags to control this:
+  * `FLangOption` - this option will be available in the `flang` compiler driver,
+  * `FC1Option` - this option will be available in the `flang -fc1` frontend driver,
----------------
sp? Should it be FlangOption ?


================
Comment at: flang/docs/FlangDriver.md:128
+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` 


================
Comment at: flang/docs/FlangDriver.md:131
+When adding a compiler driver option (i.e. an option that contains
+`FlangOption` among its `Flags`) that's meant for the frontend, make sure that
+it is either forwarded to `flang -fc1` or translated into some other option
----------------



================
Comment at: flang/docs/FlangDriver.md:132
+`FlangOption` among its `Flags`) that's meant for the frontend, make sure that
+it is either forwarded to `flang -fc1` or translated into some other option
+that is accepted by the frontend driver. You can implement this in
----------------
I guess you do this by adding FlangFc1Option do you?


================
Comment at: flang/docs/FlangDriver.md:156
+
+When you are using `%flang` instead of `%flang_fc1`, the compiler driver will
+add extra flags to the frontend driver invocation (i.e. `flang -fc1
----------------
Not sure what this para is trying to say.

Are you suggesting that all tests for flang (i.e. the Fortran compiler part of it) ought to use -fc1 command lines and only tests for compiler driver should invoke the compiler driver? So tests in flang/test/Driver should use `%flang -###` and all the others use `%flang_fc1`? If so, do you think that will work?

Or are you trying to teach a newcomer how to add a tests for the compiler driver and for frontend driver options handling specifically? If so, then I think it needs a bit more prescriptive detail.


================
Comment at: flang/docs/FlangDriver.md:158
+add extra flags to the frontend driver invocation (i.e. `flang -fc1
+-<extra-flags>`). In some cases that might exactly what you want to test. You
+can check these additional flags by using `-###` compiler driver command line
----------------



Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D104229