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