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