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