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