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