|
221
|
1 <!--===- docs/Preprocessing.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 # Fortran Preprocessing
|
|
|
10
|
|
|
11 ```eval_rst
|
|
|
12 .. contents::
|
|
|
13 :local:
|
|
|
14 ```
|
|
|
15
|
|
|
16 ## Behavior common to (nearly) all compilers:
|
|
|
17
|
|
|
18 * Macro and argument names are sensitive to case.
|
|
|
19 * Fixed form right margin clipping after column 72 (or 132)
|
|
|
20 has precedence over macro name recognition, and also over
|
|
|
21 recognition of function-like parentheses and arguments.
|
|
|
22 * Fixed form right margin clipping does not apply to directive lines.
|
|
|
23 * Macro names are not recognized as such when spaces are inserted
|
|
|
24 into their invocations in fixed form.
|
|
|
25 This includes spaces at the ends of lines that have been clipped
|
|
|
26 at column 72 (or whatever).
|
|
|
27 * Text is rescanned after expansion of macros and arguments.
|
|
|
28 * Macros are not expanded within quoted character literals or
|
|
|
29 quoted FORMAT edit descriptors.
|
|
|
30 * Macro expansion occurs before any effective token pasting via fixed form
|
|
|
31 space removal.
|
|
|
32 * C-like line continuations with backslash-newline are allowed in
|
|
|
33 directives, including the definitions of macro bodies.
|
|
|
34 * `/* Old style C comments */` are ignored in directives and
|
|
|
35 removed from the bodies of macro definitions.
|
|
|
36 * `// New style C comments` are not removed, since Fortran has OPERATOR(//).
|
|
|
37 * C-like line continuations with backslash-newline can appear in
|
|
|
38 old-style C comments in directives.
|
|
|
39 * After `#define FALSE TRUE`, `.FALSE.` is replaced by `.TRUE.`;
|
|
|
40 i.e., tokenization does not hide the names of operators or logical constants.
|
|
|
41 * `#define KWM c` allows the use of `KWM` in column 1 as a fixed form comment
|
|
|
42 line indicator.
|
|
|
43 * A `#define` directive intermixed with continuation lines can't
|
|
|
44 define a macro that's invoked earlier in the same continued statement.
|
|
|
45
|
|
|
46 ## Behavior that is not consistent over all extant compilers but which probably should be uncontroversial:
|
|
|
47
|
|
|
48 * Invoked macro names can straddle a Fortran line continuation.
|
|
|
49 * ... unless implicit fixed form card padding intervenes; i.e.,
|
|
|
50 in fixed form, a continued macro name has to be split at column
|
|
|
51 72 (or 132).
|
|
|
52 * Comment lines may appear with continuations in a split macro names.
|
|
|
53 * Function-like macro invocations can straddle a Fortran fixed form line
|
|
|
54 continuation between the name and the left parenthesis, and comment and
|
|
|
55 directive lines can be there too.
|
|
|
56 * Function-like macro invocations can straddle a Fortran fixed form line
|
|
|
57 continuation between the parentheses, and comment lines can be there too.
|
|
|
58 * Macros are not expanded within Hollerith constants or Hollerith
|
|
|
59 FORMAT edit descriptors.
|
|
|
60 * Token pasting with `##` works in function-like macros.
|
|
|
61 * Argument stringization with `#` works in function-like macros.
|
|
|
62 * Directives can be capitalized (e.g., `#DEFINE`) in fixed form.
|
|
|
63 * Fixed form clipping after column 72 or 132 is done before macro expansion,
|
|
|
64 not after.
|
|
|
65 * C-like line continuation with backslash-newline can appear in the name of
|
|
|
66 a keyword-like macro definition.
|
|
|
67 * If `#` is in column 6 in fixed form, it's a continuation marker, not a
|
|
|
68 directive indicator.
|
|
|
69 * `#define KWM !` allows KWM to signal a comment.
|
|
|
70
|
|
|
71 ## Judgement calls, where precedents are unclear:
|
|
|
72
|
|
|
73 * Expressions in `#if` and `#elif` should support both Fortran and C
|
|
|
74 operators; e.g., `#if 2 .LT. 3` should work.
|
|
|
75 * If a function-like macro does not close its parentheses, line
|
|
|
76 continuation should be assumed.
|
|
|
77 * ... However, the leading parenthesis has to be on the same line as
|
|
|
78 the name of the function-like macro, or on a continuation line thereof.
|
|
|
79 * If macros expand to text containing `&`, it doesn't work as a free form
|
|
|
80 line continuation marker.
|
|
|
81 * `#define c 1` does not allow a `c` in column 1 to be used as a label
|
|
|
82 in fixed form, rather than as a comment line indicator.
|
|
|
83 * IBM claims to be ISO C compliant and therefore recognizes trigraph sequences.
|
|
|
84 * Fortran comments in macro actual arguments should be respected, on
|
|
|
85 the principle that a macro call should work like a function reference.
|
|
|
86 * If a `#define` or `#undef` directive appears among continuation
|
|
|
87 lines, it may or may not affect text in the continued statement that
|
|
|
88 appeared before the directive.
|
|
|
89
|
|
|
90 ## Behavior that few compilers properly support (or none), but should:
|
|
|
91
|
|
|
92 * A macro invocation can straddle free form continuation lines in all of their
|
|
|
93 forms, with continuation allowed in the name, before the arguments, and
|
|
|
94 within the arguments.
|
|
|
95 * Directives can be capitalized in free form, too.
|
|
|
96 * `__VA_ARGS__` and `__VA_OPT__` work in variadic function-like macros.
|
|
|
97
|
|
|
98 ## In short, a Fortran preprocessor should work as if:
|
|
|
99
|
|
|
100 1. Fixed form lines are padded up to column 72 (or 132) and clipped thereafter.
|
|
|
101 2. Fortran comments are removed.
|
|
|
102 3. C-style line continuations are processed in preprocessing directives.
|
|
|
103 4. C old-style comments are removed from directives.
|
|
|
104 5. Fortran line continuations are processed (outside preprocessing directives).
|
|
|
105 Line continuation rules depend on source form.
|
|
|
106 Comment lines that are enabled compiler directives have their line
|
|
|
107 continuations processed.
|
|
|
108 Conditional compilation preprocessing directives (e.g., `#if`) may be
|
|
|
109 appear among continuation lines, and have their usual effects upon them.
|
|
|
110 6. Other preprocessing directives are processed and macros expanded.
|
|
|
111 Along the way, Fortran `INCLUDE` lines and preprocessor `#include` directives
|
|
|
112 are expanded, and all these steps applied recursively to the introduced text.
|
|
|
113 7. Any Fortran comments created by macro replacement are removed.
|
|
|
114
|
|
|
115 Steps 5 and 6 are interleaved with respect to the preprocessing state.
|
|
|
116 Conditional compilation preprocessing directives always reflect only the macro
|
|
|
117 definition state produced by the active `#define` and `#undef` preprocessing directives
|
|
|
118 that precede them.
|
|
|
119
|
|
|
120 If the source form is changed by means of a compiler directive (i.e.,
|
|
|
121 `!DIR$ FIXED` or `FREE`) in an included source file, its effects cease
|
|
|
122 at the end of that file.
|
|
|
123
|
|
|
124 Last, if the preprocessor is not integrated into the Fortran compiler,
|
|
|
125 new Fortran continuation line markers should be introduced into the final
|
|
|
126 text.
|
|
|
127
|
|
|
128 OpenMP-style directives that look like comments are not addressed by
|
|
|
129 this scheme but are obvious extensions.
|
|
|
130
|
|
|
131 ## Appendix
|
|
|
132 `N` in the table below means "not supported"; this doesn't
|
|
|
133 mean a bug, it just means that a particular behavior was
|
|
|
134 not observed.
|
|
|
135 `E` signifies "error reported".
|
|
|
136
|
|
|
137 The abbreviation `KWM` stands for "keyword macro" and `FLM` means
|
|
|
138 "function-like macro".
|
|
|
139
|
|
|
140 The first block of tests (`pp0*.F`) are all fixed-form source files;
|
|
|
141 the second block (`pp1*.F90`) are free-form source files.
|
|
|
142
|
|
|
143 ```
|
|
|
144 f18
|
|
|
145 | pgfortran
|
|
|
146 | | ifort
|
|
|
147 | | | gfortran
|
|
|
148 | | | | xlf
|
|
|
149 | | | | | nagfor
|
|
|
150 | | | | | |
|
|
|
151 . . . . . . pp001.F keyword macros
|
|
|
152 . . . . . . pp002.F #undef
|
|
|
153 . . . . . . pp003.F function-like macros
|
|
|
154 . . . . . . pp004.F KWMs case-sensitive
|
|
|
155 . N . N N . pp005.F KWM split across continuation, implicit padding
|
|
|
156 . N . N N . pp006.F ditto, but with intervening *comment line
|
|
|
157 N N N N N N pp007.F KWM split across continuation, clipped after column 72
|
|
|
158 . . . . . . pp008.F KWM with spaces in name at invocation NOT replaced
|
|
|
159 . N . N N . pp009.F FLM call split across continuation, implicit padding
|
|
|
160 . N . N N . pp010.F ditto, but with intervening *comment line
|
|
|
161 N N N N N N pp011.F FLM call name split across continuation, clipped
|
|
|
162 . N . N N . pp012.F FLM call name split across continuation
|
|
|
163 . E . N N . pp013.F FLM call split between name and (
|
|
|
164 . N . N N . pp014.F FLM call split between name and (, with intervening *comment
|
|
|
165 . E . N N . pp015.F FLM call split between name and (, clipped
|
|
|
166 . E . N N . pp016.F FLM call split between name and ( and in argument
|
|
|
167 . . . . . . pp017.F KLM rescan
|
|
|
168 . . . . . . pp018.F KLM rescan with #undef (so rescan is after expansion)
|
|
|
169 . . . . . . pp019.F FLM rescan
|
|
|
170 . . . . . . pp020.F FLM expansion of argument
|
|
|
171 . . . . . . pp021.F KWM NOT expanded in 'literal'
|
|
|
172 . . . . . . pp022.F KWM NOT expanded in "literal"
|
|
|
173 . . E E . E pp023.F KWM NOT expanded in 9HHOLLERITH literal
|
|
|
174 . . . E . . pp024.F KWM NOT expanded in Hollerith in FORMAT
|
|
|
175 . . . . . . pp025.F KWM expansion is before token pasting due to fixed-form space removal
|
|
|
176 . . . E . E pp026.F ## token pasting works in FLM
|
|
|
177 E . . E E . pp027.F #DEFINE works in fixed form
|
|
|
178 . N . N N . pp028.F fixed-form clipping done before KWM expansion on source line
|
|
|
179 . . . . . . pp029.F \ newline allowed in #define
|
|
|
180 . . . . . . pp030.F /* C comment */ erased from #define
|
|
|
181 E E E E E E pp031.F // C++ comment NOT erased from #define
|
|
|
182 . . . . . . pp032.F /* C comment */ \ newline erased from #define
|
|
|
183 . . . . . . pp033.F /* C comment \ newline */ erased from #define
|
|
|
184 . . . . . N pp034.F \ newline allowed in name on KWM definition
|
|
|
185 . E . E E . pp035.F #if 2 .LT. 3 works
|
|
|
186 . . . . . . pp036.F #define FALSE TRUE ... .FALSE. -> .TRUE.
|
|
|
187 N N N N N N pp037.F fixed-form clipping NOT applied to #define
|
|
|
188 . . E . E E pp038.F FLM call with closing ')' on next line (not a continuation)
|
|
|
189 E . E . E E pp039.F FLM call with '(' on next line (not a continuation)
|
|
|
190 . . . . . . pp040.F #define KWM c, then KWM works as comment line initiator
|
|
|
191 E . E . . E pp041.F use KWM expansion as continuation indicators
|
|
|
192 N N N . . N pp042.F #define c 1, then use c as label in fixed-form
|
|
|
193 . . . . N . pp043.F #define with # in column 6 is a continuation line in fixed-form
|
|
|
194 E . . . . . pp044.F #define directive amid continuations
|
|
|
195 . . . . . . pp101.F90 keyword macros
|
|
|
196 . . . . . . pp102.F90 #undef
|
|
|
197 . . . . . . pp103.F90 function-like macros
|
|
|
198 . . . . . . pp104.F90 KWMs case-sensitive
|
|
|
199 . N N N N N pp105.F90 KWM call name split across continuation, with leading &
|
|
|
200 . N N N N N pp106.F90 ditto, with & ! comment
|
|
|
201 N N E E N . pp107.F90 KWM call name split across continuation, no leading &, with & ! comment
|
|
|
202 N N E E N . pp108.F90 ditto, but without & ! comment
|
|
|
203 . N N N N N pp109.F90 FLM call name split with leading &
|
|
|
204 . N N N N N pp110.F90 ditto, with & ! comment
|
|
|
205 N N E E N . pp111.F90 FLM call name split across continuation, no leading &, with & ! comment
|
|
|
206 N N E E N . pp112.F90 ditto, but without & ! comment
|
|
|
207 . N N N N E pp113.F90 FLM call split across continuation between name and (, leading &
|
|
|
208 . N N N N E pp114.F90 ditto, with & ! comment, leading &
|
|
|
209 N N N N N . pp115.F90 ditto, with & ! comment, no leading &
|
|
|
210 N N N N N . pp116.F90 FLM call split between name and (, no leading &
|
|
|
211 . . . . . . pp117.F90 KWM rescan
|
|
|
212 . . . . . . pp118.F90 KWM rescan with #undef, proving rescan after expansion
|
|
|
213 . . . . . . pp119.F90 FLM rescan
|
|
|
214 . . . . . . pp120.F90 FLM expansion of argument
|
|
|
215 . . . . . . pp121.F90 KWM NOT expanded in 'literal'
|
|
|
216 . . . . . . pp122.F90 KWM NOT expanded in "literal"
|
|
|
217 . . E E . E pp123.F90 KWM NOT expanded in Hollerith literal
|
|
|
218 . . E E . E pp124.F90 KWM NOT expanded in Hollerith in FORMAT
|
|
|
219 E . . E E . pp125.F90 #DEFINE works in free form
|
|
|
220 . . . . . . pp126.F90 \ newline works in #define
|
|
|
221 N . E . E E pp127.F90 FLM call with closing ')' on next line (not a continuation)
|
|
|
222 E . E . E E pp128.F90 FLM call with '(' on next line (not a continuation)
|
|
|
223 . . N . . N pp129.F90 #define KWM !, then KWM works as comment line initiator
|
|
|
224 E . E . . E pp130.F90 #define KWM &, use for continuation w/o pasting (ifort and nag seem to continue #define)
|
|
|
225 ```
|
