1<!--
2Copyright (c) 2019, NVIDIA CORPORATION.  All rights reserved.
3-->
4
5# Overview of Compiler Phases
6
7Each phase produces either correct output or fatal errors.
8
9## Prescan and Preprocess
10
11See: [Preprocessing.md](Preprocessing.md).
12
13**Input:** Fortran source and header files, command line macro definitions,
14  set of enabled compiler directives (to be treated as directives rather than
15  comments).
16
17**Output:**
18- A "cooked" character stream: the entire program as a contiguous stream of
19  normalized Fortran source.
20  Extraneous whitespace and comments are removed (except comments that are
21  compiler directives that are not disabled) and case is normalized.
22- Provenance information mapping each character back to the source it came from.
23  This is used in subsequent phases to issue errors messages that refer to source locations.
24
25**Entry point:** `parser::Parsing::Prescan`
26
27**Command:** `f18 -E src.f90` dumps the cooked character stream
28
29## Parse
30
31**Input:** Cooked character stream.
32
33**Output:** A parse tree representing a syntactically correct program,
34  rooted at a `parser::Program`.
35  See: [Parsing.md](Parsing.md) and [ParserCombinators.md](ParserCombinators.md).
36
37**Entry point:** `parser::Parsing::Parse`
38
39**Command:**
40  - `f18 -fdebug-dump-parse-tree -fparse-only src.f90` dumps the parse tree
41  - `f18 -funparse src.f90` converts the parse tree to normalized Fortran
42
43## Validate Labels and Canonicalize Do Statements
44
45**Input:** Parse tree.
46
47**Output:** The parse tree with label constraints and construct names checked,
48  and each `LabelDoStmt` converted to a `NonLabelDoStmt`.
49  See: [LabelResolution.md](LabelResolution.md).
50
51**Entry points:** `semantics::ValidateLabels`, `parser::CanonicalizeDo`
52
53## Resolve Names
54
55**Input:** Parse tree (without `LabelDoStmt`) and `.mod` files from compilation
56  of USEd modules.
57
58**Output:**
59- Tree of scopes populated with symbols and types
60- Parse tree with some refinements:
61  - each `parser::Name::symbol` field points to one of the symbols
62  - each `parser::TypeSpec::declTypeSpec` field points to one of the types
63  - array element references that were parsed as function references or
64    statement functions are corrected
65
66**Entry points:** `semantics::ResolveNames`, `semantics::RewriteParseTree`
67
68**Command:** `f18 -fdebug-dump-symbols -fparse-only src.f90` dumps the
69  tree of scopes and symbols in each scope
70
71## Check DO CONCURRENT Constraints
72
73**Input:** Parse tree with names resolved.
74
75**Output:** Parse tree with semantically correct DO CONCURRENT loops.
76
77## Write Module Files
78
79**Input:** Parse tree with names resolved.
80
81**Output:** For each module and submodule, a `.mod` file containing a minimal
82  Fortran representation suitable for compiling program units that depend on it.
83  See [ModFiles.md](ModFiles.md).
84
85## Analyze Expressions and Assignments
86
87**Input:** Parse tree with names resolved.
88
89**Output:** Parse tree with `parser::Expr::typedExpr` filled in and semantic
90  checks performed on all expressions and assignment statements.
91
92**Entry points**: `semantics::AnalyzeExpressions`, `semantics::AnalyzeAssignments`
93
94## Produce the Intermediate Representation
95
96**Input:** Parse tree with names and labels resolved.
97
98**Output:** An intermediate representation of the executable program.
99  See [FortranIR.md](FortranIR.md).
100