flang/docs/Overview.md

   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
  10 This document goes briefly over compiler phases in Flang. It focuses on the
  11 internal implementation and as such, it is intended for Flang developers rather
  12 than end-users.
  13
  14 # Overview of Compiler Phases
  15
  16 ```eval_rst
  17 .. contents::
  18    :local:
  19 ```
  20
  21 Each phase produces either correct output or fatal errors.
  22
  23 ## Prescan and Preprocess
  24
  25 See: [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).