diff --git a/flang/docs/FlangDriver.md b/flang/docs/FlangDriver.md --- a/flang/docs/FlangDriver.md +++ b/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 other tools such as 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 a 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 be. 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. A 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