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