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--- 13local: 14--- 15``` 16 17Module files hold information from a module that is necessary to compile 18program units that depend on the module. 19 20## Name 21 22Module 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 24other compilers so users will know what they are. Also, makefiles and scripts 25often use `rm *.mod` to clean up. 26 27The disadvantage of using the same name as other compilers is that it is not 28clear which compiler created a `.mod` file and files from multiple compilers 29cannot be in the same directory. This could be solved by adding something 30between the module name and extension, e.g. `<modulename>-f18.mod`. If this 31is needed, Flang's fc1 accepts the option `-module-suffix` to alter the suffix 32used for the module file. 33 34## Format 35 36Module files will be Fortran source. 37Declarations of all visible entities will be included, along with private 38entities that they depend on. 39Entity declarations that span multiple statements will be collapsed into 40a single *type-declaration-statement*. 41Executable statements will be omitted. 42 43### Header 44 45There will be a header containing extra information that cannot be expressed 46in Fortran. This will take the form of a comment or directive 47at the beginning of the file. 48 49If it's a comment, the module file reader would have to strip it out and 50perform *ad hoc* parsing on it. If it's a directive the compiler could 51parse it like other directives as part of the grammar. 52Processing the header before parsing might result in better error messages 53when the `.mod` file is invalid. 54 55Regardless of whether the header is a comment or directive we can use the 56same string to introduce it: `!mod$`. 57 58Information 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 69The body will consist of minimal Fortran source for the required declarations. 70The order will match the order they first appeared in the source. 71 72Some 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 83All public symbols from the module need to be included. 84 85In 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 91It might be possible to anonymize private names if users don't want them exposed 92in the `.mod` file. (Currently they are readable in PGI `.mod` files.) 93 94#### USE association 95 96A module that contains `USE` statements needs them represented in the 97`.mod` file. 98Each use-associated symbol will be written as a separate *use-only* statement, 99possibly with renaming. 100 101Alternatives: 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 113The compiler will have command-line options to specify where to search 114for module files and where to write them. By default it will be the current 115directory for both. 116 117For PGI, `-I` specifies directories to search for include files and module 118files. `-module` specifics a directory to write module files in as well as to 119search for them. gfortran is similar except it uses `-J` instead of `-module`. 120 121The search order for module files is: 1221. The `-module` directory (Note: for gfortran the `-J` directory is not searched). 1232. The current directory 1243. The `-I` directories in the order they appear on the command line 125 126### Writing module files 127 128When writing a module file, if the existing one matches what would be written, 129the timestamp is not updated. 130 131Module files will be written after semantics, i.e. after the compiler has 132determined the module is valid Fortran.<br> 133**NOTE:** PGI does create `.mod` files sometimes even when the module has a 134compilation error. 135 136Question: If the compiler can get far enough to determine it is compiling a module 137but then encounters an error, should it delete the existing `.mod` file? 138PGI does not, gfortran does. 139 140### Reading module files 141 142When the compiler finds a `.mod` file it needs to read, it firsts checks the first 143line and verifies it is a valid module file. It can also verify checksums of 144modules it depends on and report if they are out of date. 145 146If the header is valid, the module file will be run through the parser and name 147resolution to recreate the symbols from the module. Once the symbol table is 148populated the parse tree can be discarded. 149 150When processing `.mod` files we know they are valid Fortran with these properties: 1511. The input (without the header) is already in the "cooked input" format. 1522. No preprocessing is necessary. 1533. No errors can occur. 154 155## Error messages referring to modules 156 157With this design, diagnostics can refer to names in modules and can emit a 158normalized declaration of an entity but not point to its location in the 159source. 160 161If the header includes the source file it came from, that could be included in 162a diagnostic but we still wouldn't have line numbers. 163 164To provide line numbers and character positions or source lines as the user 165wrote them we would have to save some amount of provenance information in the 166module file as well. 167 168## Hermetic modules files 169 170Top-level module files for libraries can be build with `-fhermetic-module-files`. 171This option causes these module files to contain copies of all of the non-intrinsic 172modules on which they depend, so that non-top-level local modules and the 173modules of dependent libraries need not also be packaged with the library. 174When the compiler reads a hermetic module file, the copies of the dependent 175modules are read into their own scope, and will not conflict with other modules 176of the same name that client code might `USE`. 177