[PATCH] D107543: [flang][docs] Document the `flang` wrapper script

[Andrzej Warzynski via Phabricator via llvm-commits]

awarzynski created this revision.
Herald added a reviewer: sscalpone.
awarzynski requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D107543

Files:
  flang/docs/FlangDriver.md


Index: flang/docs/FlangDriver.md
===================================================================
--- flang/docs/FlangDriver.md
+++ flang/docs/FlangDriver.md
@@ -29,6 +29,7 @@
 `-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
@@ -129,6 +130,33 @@
 words, `flang-new -fc1 <input-file>` is equivalent to `flang-new -fc1 -fsyntax-only
 <input-file>`.
 
+## The `flang` script
+The `flang` wrapper script for `flang-new` was introduced as a development tool
+and to facilitate testing. While code-generation is not available in Flang, you
+can use it as a drop-in replacement for other Fortran compilers in your build
+scripts.
+
+The `flang` wrapper script will:
+* use `flang-new` to unparse the input source file (i.e. it will run `flang-new
+  -fc1 -fdebug-unparse <input-file>`), and then
+* call a host Fortran compiler, e.g. `gfortran`, to compile the unparsed file.
+
+Here's a basic breakdown of what happens inside `flang` when you run `flang
+file.f90`:
+```bash
+flang-new -fc1 -fdebug-unparse file.f90 -o file-unparsed.f90
+gfortran file-unparsed.f90
+```
+This is a simplified version for ilustration purpose only. In practice, `flang`
+adds a few more frontend options and it also supports various other use cases
+(e.g. compiling C files, linking existing object files). `gfortran` is the
+default host compiler used by `flang`. You can change it by setting the
+`FLANG_FC` environment variable.
+
+Our intention is to replace `flang` with `flang-new`. Please consider `flang`
+as a temporary substitute for Flang's compiler driver while the actual driver
+is in development.
+
 ## Adding new Compiler Options
 Adding a new compiler option in Flang consists of two steps:
 * define the new option in a dedicated TableGen file,


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D107543.364388.patch
Type: text/x-patch
Size: 1888 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210805/48e18a4b/attachment.bin>