[flang] Document describing overview of compiler phases

Original-commit: flang-compiler/f18@ac7a492a25
Reviewed-on: https://github.com/flang-compiler/f18/pull/282
Tree-same-pre-rewrite: false

flang/documentation/Overview.md

@@ -0,0 +1,88 @@
+<!--
+Copyright (c) 2019, NVIDIA CORPORATION.  All rights reserved.
+-->
+
+# Overview of Compiler Phases
+
+Each phases produces correct output or fatal errors.
+
+## Prescan and Preprocess
+
+**Input:** Fortran source and header files, command line macro definitions
+
+**Output:**
+- A "cooked" character stream: the entire program as a contiguous stream of
+  normalized Fortran source.
+  Extraneous whitespace and comments are removed (except comments that are
+  compiler directives that are not disabled) and case is normalized.
+- Provenance information mapping each character back to the source it came from.
+  This is used in subsequent phases to issue errors messages that refer to source locations.
+
+**Entry point:** `parser::Parsing::Prescan`
+
+**Command:** `f18 -E src.f90` dumps the cooked character stream.
+
+## Parse
+
+**Input:** Cooked character stream.
+
+**Output:** A parse tree representing a syntactially correct program,
+  rooted at a `parser::Program`.
+  See: [parsing.md](parsing.md).
+
+**Entry point:** `parser::Parsing::Parse`
+
+**Command:**
+  - `f18 -fdebug-dump-parse-tree -fparse-only src.f90` dumps the parse tree
+  - `f18 -funparse src.f90` converts the parse tree to normalized Fortran
+
+## Validate Labels and Canonicalize Do Statements
+
+**Input:** Parse tree
+
+**Output:** The parse tree with label constraints and construct names checked,
+  and each `LabelDoStmt` converted to a `NonLabelDoStmt`.
+  See: [LabelResolution.md](LabelResolution.md).
+
+**Entry points:** `semantics::ValidateLabels`, `parser::CanonicalizeDo`
+
+## Resolve Names
+
+**Input:** Parse tree (without `LabelDoStmt`) and `.mod` files from compilation
+  of USEd modules.
+
+**Output:**
+- Tree of scopes populated with symbols and types
+- Parse tree with some refinements:
+  - each `parser::Name::symbol` field points to one of the symbols
+  - each `parser::TypeSpec::declTypeSpec` field points to one of the types
+  - array element references that were parsed as function references or
+    statement functions are corrected
+
+**Entry points:** `semantics::ResolveNames`, `semantics::RewriteParseTree`
+
+**Command:** `f18 -fdebug-dump-symbols -fparse-only src.f90` dumps the
+  tree of scopes and symbols in each
+
+## Check DO CONCURRENT Constraints
+
+**Input:** Parse tree with names resolved.
+
+**Output:** Parse tree with semantically correct DO CONCURRENT loops.have been performed.
+
+## Write Module Files
+
+**Input:** Parse tree with names resolved.
+
+**Output:** For each module and submodule, a `.mod` file containing a minimal
+  Fortran representation suitable for compiling program units that depend on it.
+
+## Analyze Expressions and Assignments
+
+**Input:** Parse tree with names resolved.
+
+**Output:** Parse tree with `parser::Expr::typedExpr` filled in and semantic
+  checks performed on all expressions and assignment statements.
+
+**Entry points**: `semantics::AnalyzeExpressions`, `semantics::AnalyzeAssignments`
+