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

[Andrzej Warzynski via Phabricator via llvm-commits]

awarzynski updated this revision to Diff 378981.
awarzynski added a comment.

Address comments from @richard.barton.arm and @Leporacanthicus

Thank you all for taking a look!


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D111573

Files:
  flang/docs/FlangDriver.md


Index: flang/docs/FlangDriver.md
===================================================================
--- flang/docs/FlangDriver.md
+++ flang/docs/FlangDriver.md
@@ -20,17 +20,51 @@
 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.
+Fortran compilation job and delegates it to `flang-new -fc1`, the frontend
+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.
 
 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.
+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.
+It accepts many frontend-specific options not available in `flang-new` and as
+such it provides a finer control over the frontend. Note that it is mostly
+intended for Flang developers. In particular, there are no guarantees about the
+stability of its interface.
+
+## Why Do We Need Two Drivers?
+As hinted above, `flang-new` and `flang-new -fc1` are two separate tools. The
+fact that these tools are accessed through one binary, `flang-new`, is just an
+implementation detail. Each tool has a separate list of options, albeit defined
+in the same file: `clang/include/clang/Driver/Options.td`.
+
+The separation helps us split various tasks and allows us to implement more
+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
+-fc1`, needs not to be concerned with linkers or other external tools like
+assemblers. Nor does it need to know where to look for various systems
+libraries, which is usually OS and platform specific.
+
+One helpful way of differentiating these tools is to keep in mind that:
+
+* the compiler driver is an end-user tool
+* frontend-driver is a compiler developer tool with many additional options,
+
+Also, Since the compiler driver can call external tools, e.g. linkers, it can be used
+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
+of
+GCC](https://en.wikibooks.org/wiki/GNU_C_Compiler_Internals/GNU_C_Compiler_Architecture).
+In fact, Flang needs to adhere to this model in order to be able to re-use
+Clang's driver library.  Note that 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:
@@ -92,9 +126,9 @@
 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:
+Flang's frontend driver is the main interface between compiler developers 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D111573.378981.patch
Type: text/x-patch
Size: 4408 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20211012/cd8ca005/attachment.bin>