llvm-project/flang/docs/Overview.md

<!--===- docs/Overview.md 
  
   Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   See https://llvm.org/LICENSE.txt for license information.
   SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  
-->

# Intro
This document goes briefly over compiler phases in Flang. It focuses on the
internal implementation and as such, it is intended for Flang developers rather
than end-users.

# Overview of Compiler Phases

```eval_rst
.. contents::
   :local:
```

Each phase produces either correct output or fatal errors.

## Prescan and Preprocess

See: [Preprocessing.md](Preprocessing.md).

**Input:** Fortran source and header files, command line macro definitions,
  set of enabled compiler directives (to be treated as directives rather than
  comments).

**Output:**
- A "cooked" character stream: the entire program as a contiguous stream of
  normalized Fortran source.
  Extraneous whitespace and comments are removed (except comments that are
  compiler directives that are not disabled) and case is normalized.
- Provenance information mapping each character back to the source it came from.
  This is used in subsequent phases to issue errors messages that refer to source locations.

**Entry point:** `parser::Parsing::Prescan`

**Command:** `flang-new -fc1 -E src.f90` dumps the cooked character stream

## Parse

**Input:** Cooked character stream.

**Output:** A parse tree representing a syntactically correct program,
  rooted at a `parser::Program`.
  See: [Parsing.md](Parsing.md) and [ParserCombinators.md](ParserCombinators.md).

**Entry point:** `parser::Parsing::Parse`

**Command:**
  - `flang-new -fc1 -fdebug-dump-parse-tree src.f90` dumps the parse tree
  - `flang-new -fc1 -fdebug-unparse src.f90` converts the parse tree to normalized Fortran

## Validate Labels and Canonicalize Do Statements

**Input:** Parse tree.

**Output:** The parse tree with label constraints and construct names checked,
  and each `LabelDoStmt` converted to a `NonLabelDoStmt`.
  See: [LabelResolution.md](LabelResolution.md).

**Entry points:** `semantics::ValidateLabels`, `parser::CanonicalizeDo`

## Resolve Names

**Input:** Parse tree (without `LabelDoStmt`) and `.mod` files from compilation
  of USEd modules.

**Output:**
- Tree of scopes populated with symbols and types
- Parse tree with some refinements:
  - each `parser::Name::symbol` field points to one of the symbols
  - each `parser::TypeSpec::declTypeSpec` field points to one of the types
  - array element references that were parsed as function references or
    statement functions are corrected

**Entry points:** `semantics::ResolveNames`, `semantics::RewriteParseTree`

**Command:** `flang-new -fc1 -fdebug-dump-symbols src.f90` dumps the
  tree of scopes and symbols in each scope

## Check DO CONCURRENT Constraints

**Input:** Parse tree with names resolved.

**Output:** Parse tree with semantically correct DO CONCURRENT loops.

## Write Module Files

**Input:** Parse tree with names resolved.

**Output:** For each module and submodule, a `.mod` file containing a minimal
  Fortran representation suitable for compiling program units that depend on it.
  See [ModFiles.md](ModFiles.md).

## Analyze Expressions and Assignments

**Input:** Parse tree with names resolved.

**Output:** Parse tree with `parser::Expr::typedExpr` filled in and semantic
  checks performed on all expressions and assignment statements.

**Entry points**: `semantics::AnalyzeExpressions`, `semantics::AnalyzeAssignments`

## Produce the Intermediate Representation

**Input:** Parse tree with names and labels resolved.

**Output:** An intermediate representation of the executable program.
  See [FortranIR.md](FortranIR.md).