flang/docs/ModFiles.md

   1 <!--===- docs/ModFiles.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 # Module Files
  10
  11 ```eval_rst
  12 .. contents::
  13    :local:
  14 ```
  15
  16 Module files hold information from a module that is necessary to compile
  17 program units that depend on the module.
  18
  19 ## Name
  20
  21 Module files must be searchable by module name. They are typically named
  22 `<modulename>.mod`. The advantage of using `.mod` is that it is consistent with
  23 other compilers so users will know what they are. Also, makefiles and scripts
  24 often use `rm *.mod` to clean up.
  25
  26 The disadvantage of using the same name as other compilers is that it is not
  27 clear which compiler created a `.mod` file and files from multiple compilers
  28 cannot be in the same directory. This could be solved by adding something
  29 between the module name and extension, e.g. `<modulename>-f18.mod`.
  30
  31 ## Format
  32
  33 Module files will be Fortran source.
  34 Declarations of all visible entities will be included, along with private
  35 entities that they depend on.
  36 Entity declarations that span multiple statements will be collapsed into
  37 a single *type-declaration-statement*.
  38 Executable statements will be omitted.
  39
  40 ### Header
  41
  42 There will be a header containing extra information that cannot be expressed
  43 in Fortran. This will take the form of a comment or directive
  44 at the beginning of the file.
  45
  46 If it's a comment, the module file reader would have to strip it out and
  47 perform *ad hoc* parsing on it. If it's a directive the compiler could
  48 parse it like other directives as part of the grammar.
  49 Processing the header before parsing might result in better error messages
  50 when the `.mod` file is invalid.
  51
  52 Regardless of whether the header is a comment or directive we can use the
  53 same string to introduce it: `!mod$`.
  54
  55 Information in the header:
  56 - Magic string to confirm it is an f18 `.mod` file
  57 - Version information: to indicate the version of the file format, in case it changes,
  58   and the version of the compiler that wrote the file, for diagnostics.
  59 - Checksum of the body of the current file
  60 - Modules we depend on and the checksum of their module file when the current
  61   module file is created
  62 - The source file that produced the `.mod` file? This could be used in error messages.
  63
  64 ### Body
  65
  66 The body will consist of minimal Fortran source for the required declarations.
  67 The order will match the order they first appeared in the source.
  68
  69 Some normalization will take place:
  70 - extraneous spaces will be removed
  71 - implicit types will be made explicit
  72 - attributes will be written in a consistent order
  73 - entity declarations will be combined into a single declaration
  74 - function return types specified in a *prefix-spec* will be replaced by
  75   an entity declaration
  76 - etc.
  77
  78 #### Symbols included
  79
  80 All public symbols from the module need to be included.
  81
  82 In addition, some private symbols are needed:
  83 - private types that appear in the public API
  84 - private components of non-private derived types
  85 - private parameters used in non-private declarations (initial values, kind parameters)
  86 - others?
  87
  88 It might be possible to anonymize private names if users don't want them exposed
  89 in the `.mod` file. (Currently they are readable in PGI `.mod` files.)
  90
  91 #### USE association
  92
  93 A module that contains `USE` statements needs them represented in the
  94 `.mod` file.
  95 Each use-associated symbol will be written as a separate *use-only* statement,
  96 possibly with renaming.
  97
  98 Alternatives:
  99 - Emit a single `USE` for each module, listing all of the symbols that were
 100   use-associated in the *only-list*.
 101 - Detect when all of the symbols from a module are imported (either by a *use-stmt*
 102   without an *only-list* or because all of the public symbols of the module
 103   have been listed in *only-list*s). In that case collapse them into a single *use-stmt*.
 104 - Emit the *use-stmt*s that appeared in the original source.
 105
 106 ## Reading and writing module files
 107
 108 ### Options
 109
 110 The compiler will have command-line options to specify where to search
 111 for module files and where to write them. By default it will be the current
 112 directory for both.
 113
 114 For PGI, `-I` specifies directories to search for include files and module
 115 files. `-module` specifics a directory to write module files in as well as to
 116 search for them. gfortran is similar except it uses `-J` instead of `-module`.
 117
 118 The search order for module files is:
 119 1. The `-module` directory (Note: for gfortran the `-J` directory is not searched).
 120 2. The current directory
 121 3. The `-I` directories in the order they appear on the command line
 122
 123 ### Writing module files
 124
 125 When writing a module file, if the existing one matches what would be written,
 126 the timestamp is not updated.
 127
 128 Module files will be written after semantics, i.e. after the compiler has
 129 determined the module is valid Fortran.<br>
 130 **NOTE:** PGI does create `.mod` files sometimes even when the module has a
 131 compilation error.
 132
 133 Question: If the compiler can get far enough to determine it is compiling a module
 134 but then encounters an error, should it delete the existing `.mod` file?
 135 PGI does not, gfortran does.
 136
 137 ### Reading module files
 138
 139 When the compiler finds a `.mod` file it needs to read, it firsts checks the first
 140 line and verifies it is a valid module file. It can also verify checksums of
 141 modules it depends on and report if they are out of date.
 142
 143 If the header is valid, the module file will be run through the parser and name
 144 resolution to recreate the symbols from the module. Once the symbol table is
 145 populated the parse tree can be discarded.
 146
 147 When processing `.mod` files we know they are valid Fortran with these properties:
 148 1. The input (without the header) is already in the "cooked input" format.
 149 2. No preprocessing is necessary.
 150 3. No errors can occur.
 151
 152 ## Error messages referring to modules
 153
 154 With this design, diagnostics can refer to names in modules and can emit a
 155 normalized declaration of an entity but not point to its location in the
 156 source.
 157
 158 If the header includes the source file it came from, that could be included in
 159 a diagnostic but we still wouldn't have line numbers.
 160
 161 To provide line numbers and character positions or source lines as the user
 162 wrote them we would have to save some amount of provenance information in the
 163 module file as well.