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