Introduction to Flang

This guide is meant to help you understand how flang compiler works and is organized internally.

It’s a good idea to see Flang glossary to understand all the abbreviations being used.

Frontend pipeline

Flang1 phases

scanner: extracts text tokens

parser: creates tokensAST and symbol table

transformer: transforms ASTcanonical to AST

output converter: converts canonical AST to optimised AST

output: creates an AST ILM (PGI IR1)

Flang2 phases

expander: ILM expanded to ILI (PGI IR1 expanded to PGI IR2)

optimiser: ILI becomes optimised ILI

code scheduler (The Bridge): Optimized ILI becomes LLVM IR

Code structure

The source code of Flang is mainly ANSI C98 and some C++. Fortran routines are present in runtime library. Documentation is maintained in nroff (*.n) files and can be build with -DLLVM_INCLUDE_DOCS=on.

The main directories are listed here and some of them are explained in more details below:

  • lib, include - auxiliary libraries shared by flang1, flang2 and the Fortran runtime library.

  • runtime - the Fortran runtime library.

  • tools/flang1 - Flang1, Fortran to ILM translator.

  • tools/flang2 - Flang2, ILM to LLVM IR translator.

  • tools/include/symtab - gbldefs.h (one of three headers with that name!) and global.h (one of four) header files.

  • utils - the errmsggen ( errmsg.cpp ) utility, used to generate two errmsgdf.h files (one for flang1, one for flang2), error message text.

lib directory structure

  • ADT (Abstract Data Types) - hash.c - open addressing, quadratically probed hash tables.

  • ArgParser - command line arguments parser routines, common to flang1 and flang2.

  • scutil - various routines, mostly sophisticated file I/O handling.

tools/flang1 directory structure

  • flang1exe - the frontend, stage 1.

  • include/platform.h.in - template for platform.h header file generated by CMake (platform specific definitions).

  • utils - utilities required during flang1 building process.

    • ast - astutil , generates ast.h and astdf.h from ast.in.h .

    • common - nroff-to-C converter used by astutil , machar and fen2rst .

    • machar - machine characteristics utility definitions, generates machar.h and machardf.h.

    • n2rst - nroff ( .n ) to Shpinx ( .rst ) format conversion utility.

    • prstb - parse table generator; grammar definition and parser tables, prodstr utility, lr utility.

    • symtab - symbol table generator and utilities.

tools/flang2 directory structure

  • flang2exe - the frontend, stage 2.

  • include/platform.h.in - template for platform.h header file generated by CMake (platform specific definitions)

  • utils

    • common - nroff-to-C converter used by ilitp , ilmtp , fsymutil , fesymutil , fsymini , fesymini and fmachar.

    • ilmtp - ILM template utility; reads ILM definition file (ilmtp.n) and generates ilmtp.h and ilmtpdf.h; architecture specific .n files for aarch64 , ppc64le and x86_64.

    • ilitp - ILI template utility; reads ILI definition file (ilitp.n) and generates iliatt.h and ilinofodf.h; architecture specific .n files for aarch64 , ppc64le and x86_64.

    • machar - see above.

    • n2rst - see above.

    • symtab - see above.

    • upper - upperl utility, turns upperilm.in into upperilm.h; included by flang2exe/upper.c which imports the lowered Fortran code.