| blob | 5ed0c9e1c107c42d742f7d79f34f6e735ea3acb3 |
1 .TH SF2C 1 "April 11 1994" "Stanford University" "SUIF Compiler"
2 .SH NAME
3 sf2c \- first pass of the SUIF Fortran 77 front end
4 .SH SYNOPSIS
5 .B sf2c
6 [
7 .I options
8 ]
9 .I infile
10 .SH DESCRIPTION
11 The
12 .I sf2c
13 program forms the first part of the SUIF Fortran 77 front end. It is
14 typically run automatically by
15 .I scc,
16 not directly by the user. The output of
17 .I sf2c
18 should be run through
19 .I cpp
20 (the usual C pre-processor, not a part of SUIF)
21 .I snoot,
22 .I fixfortran,
23 and the
24 .I porky \-defaults
25 passes, in that order, to complete the SUIF Fortran front end.
26 .PP
27 The
28 .I sf2c
29 pass converts Fortran code into a special kind of C code. The C code
30 is legal and has the same semantics as the Fortran program, but it
31 also has special Fortran-specific information encoded in things like
32 assignments to dummy variables. The most important information this
33 encodes is the original array type and bound information, including
34 symbolic bounds.
35 .PP
36 This special C program is passed through
37 .I cpp
38 and then
39 .I snoot,
40 the regular ANSI C front end, to translate it into SUIF code. Then
41 fixfortran extracts the Fortran information that had been encoded in
42 C, restoring array types, call-by-reference and common-block
43 variables, and more, when possible. Note that fixfortran is tightly
44 coupled with sf2c and expects its input to be in exactly the form sf2c
45 put it in. Other Fortran to C converters will not work. It is vital
46 that no changes are made to the C code before
47 .I cpp
48 and
49 .I snoot
50 or to the SUIF code coming out of snoot before it gets to fixfortran.
51 If any changes are made, fixfortran will become confused and probably
52 die with some error message, but it is possible it will produce
53 incorrect code in that case.
54 .PP
55 Our
56 .I sf2c
57 pass is based largely on a version of the Bell Labs
58 .I f2c
59 Fortran-to-C converter. Most of the original
60 .I f2c
61 options and features are
62 available in
63 .I sf2c.
64 The major changes we've made have been aimed at getting more
65 high-level Fortran information encoded in the C output. There are
66 some strange contortions we put
67 .I sf2c
68 and fixfortran through to preserve this information given the
69 structure of the old
70 .I f2c.
71 It is strongly recommended that the output of
72 .I sf2c
73 never be used directly; the entire front end of
74 .I sf2c\-cpp\-snoot\-fixfortran\-porky
75 should be treated as a black box. There are a few command line flags
76 to sf2c that might be of general interest, but the internals of the
77 front end are not.
78 .PP
79 The
80 .I sf2c
81 pass takes arguments that end with
82 .I \.f
83 or
84 .I \.F
85 as Fortran 77 source programs. If no output file is specified (the
86 .B \-o
87 option), the output (the special C file) is given the same name but
88 put in the current directory with an extension of
89 .I \.c.
90 If no arguments are given, then
91 .I sf2c
92 reads Fortran from standard input and writes the special C file to
93 standard output.
94 .PP
95 The resulting C code needs to include the
96 .I sf2c.h
97 header file, but this is normally taken care of automatically by
98 .I scc.
99 The code must eventually be linked with the libraries
100 .I libF77
101 (or its variant,
102 .I libF77_doall,
103 in the case of parallelized code)
104 and
105 .I libI77,
106 which are included in the SUIF distribution.
107 This, too, is normally handled automatically when you use scc to link.
108 .SH OPTIONS ADDED FOR SUIF
109 .TP
110 .B \-g
111 Insert C ``#line'' directives to indicate the line numbers in the
112 original Fortran source. That way the eventual SUIF file's "line"
113 annotations will correctly refer to line numbers in the Fortran
114 source, not an intermediate Fortran file.
115 .sp
116 Unfortunately,
117 .I f2c
118 was not set up to keep careful track of line numbers, so the result is
119 line numbers that are often off by one in some parts of the program.
120 They are close enough to be quite useful, though.
121 .sp
122 Note that this option replaces the
123 .B \-g
124 flag in
125 .I f2c.
126 The old version of this flag printed the line numbers in comments, not
127 ``#line'' directives.
128 .TP
129 .BI \-o " filename"
130 Use the given
131 .I filename
132 as the output file, instead of trying to figure out an output file
133 based on the input file name.
134 .TP
135 .B \-pp
136 Put each array reference on a separate line. Line breaks are
137 introduced after each array reference if this option is used. Then if
138 the
139 .B \-g
140 option is not used, array refernce instructions can be uniquely
141 identified by their line numbers.
142 .TP
143 .B \-lab
144 Put a semicolon after each label. Why this might be useful is
145 unclear.
146 .TP
147 .B \-version
148 Print version information to stderr and exit immediately. This is
149 consistent with the
150 .B \-version
151 flag for most other SUIF passes that is implemented in the main SUIF
152 library.
153 .TP
154 .B \-quiet
155 Do not print verbose commentary while compiling. Without this flag,
156 .I sf2c
157 prints out the names of procedures as they are encountered, among
158 other things.
159 .SH OPTIONS IDENTICAL TO f77 AND f2c
160 .TP
161 .B \-C
162 Compile code to check that subscripts are within declared array
163 bounds.
164 .TP
165 .B \-I2
166 Render INTEGER and LOGICAL as short,
167 INTEGER\(**4 as long int. Assume the default \fIlibF77\fR
168 and \fIlibI77\fR: allow only INTEGER\(**4 (and no LOGICAL)
169 variables in INQUIREs. This flag is incompatible with the
170 .I \-I4
171 flag.
172 .TP
173 .B \-onetrip
174 The semantics of a DO loop are changed so that their bodies are
175 performed at least once if reached. (Fortran 77 DO loops are not
176 performed at all if the upper limit is smaller than the lower limit.)
177 .TP
178 .B \-U
179 Honor the case of variables and external names. Fortran keywords must
180 be in lower case.
181 .TP
182 .B \-u
183 Make the default type of a variable `undefined' rather than using the
184 default Fortran rules.
185 .TP
186 .PD 0
187 .B \-w
188 .TP
189 .PD
190 .B \-w66
191 Suppress warning messages. The
192 .B \-w
193 form supresses all warning messages, the
194 .B \-w66,
195 form supresses only Fortran 66 compatibility warnings.
196 .SH OPTIONS RETAINED FROM f2c
197 .TP
198 .B \-A
199 Use ANSI C constructs. The default is old-style (pre-ANSI) C. SUIF
200 note: this option is irrelevant as far as SUIF is concerned because
201 the old-style C used is a common subset of old C and ANSI C. The
202 .I snoot
203 pass is fine with or without this option, as it understands the
204 complete ANSI C language.
205 .TP
206 .B \-a
207 Give local variables automatic (rather than static) storage unless
208 they appear in a DATA, EQUIVALENCE, or SAVE statement. SUIF note: for
209 SUIF it's usually better to use this option because it's easier to
210 analyze automatic variables. But SUIF will still be correct whether
211 or not this flag is set.
212 .TP
213 .B \-c
214 Insert comments showing the original Fortran source. SUIF note: if
215 this option is used along with the appropriate
216 .I cpp
217 and
218 .I snoot
219 options, comments can be retained all through the SUIF code in the
220 form of annotations on mark instructions.
221 .TP
222 .B \-E
223 Declare uninitialized struct created for COMMON to be \f(CWExtern\fR
224 (which \fIsf2c.h\fR \v(CW#define\fRs to be \f(CWextern\fR if it is
225 otherwise undefined).
226 .TP
227 .PD 0
228 .B \-ec
229 .TP
230 .PD
231 .B \-e1c
232 These options are meaningless for SUIF. They cause
233 .B sf2c
234 to emit a separate file for each uninitialized COMMON;
235 e.g. \f(CWCOMMON /ABC/\fR
236 yields \f(CWabc_com.c\fR, which defines \f(CWabc_\fR.
237 If the option is
238 .B \-e1c,
239 then bundle the separate files that would result from
240 .B \-ec
241 into the output file, along with comments giving a
242 .I sed (1)
243 script that separates the output file into the files that
244 .B \-ec
245 would give.
246 .TP
247 .B \-ext
248 Complain about f77 extensions.
249 .TP
250 .B \-i2
251 Do something similar to what is done by
252 .B \-I2,
253 but assume a modified
254 .I libF77
255 and
256 .I libI77
257 (compiled with -Df2c_i2), so INTEGER and LOGICAL variables may be
258 assigned in INQUIREs. This is incompatible with the
259 .I \-I4
260 option.
261 .TP
262 .B \-R
263 Do not promote REAL functions and operations to DOUBLE PRECISION (as
264 .I f77
265 does).
266 .TP
267 .B \-r8
268 Promote REAL to DOUBLE PRECISION, COMPLEX to DOUBLE COMPLEX.
269 .TP
270 .BI \-T dir
271 Put temporary files in directory
272 .I dir
273 instead of /tmp, the default. Note that the
274 .I TMPDIR
275 environment variable may also be used to choose the directory to use
276 for temporary files. The
277 .B \-T
278 option overrides the
279 .I TMPDIR
280 environment variable if both are specified.
281 .TP
282 .BI \-w8
283 Do not complain when COMMON or EQUIVALENCE forces doubles to be
284 word-aligned.
285 .TP
286 .BI \-W n
287 Assume
288 .I n
289 characters/word (default 4) when initializing numeric variables with
290 character data.
291 .TP
292 .B \-z
293 Do not implicitly recognize DOUBLE COMPLEX.
294 .TP
295 .B !I
296 Disable the included statement.
297 .SH OPTIONS THAT ARE UNDOCUMENTED IN f77
298 .B \-66
299 Disallow all extensions to Fortran 66.
300 .TP
301 .B \-d
302 Turn on debugging mode. Some effects of debugging mode are that
303 temporary intermediate files are not removed and some verbose
304 information is generated.
305 .TP
306 .B \-1
307 Undocumented synonym for the
308 .B \-onetrip
309 flag.
310 .TP
311 .B \-I4
312 Render INTEGER and LOGICAL as `long int'. If this option is used,
313 neither of the options
314 .B \-I2
315 or
316 .B \-i2
317 may be used, as they contradict this option.
318 .TP
319 .B \-Is
320 Use `short int' as the type for array subscripts.
321 .TP
322 .BI \-O n
323 Set the maximum number of register variables to use. For SUIF we
324 ignore whether the variable was declared ``register'' in C anyway, so
325 this option is meaningless.
326 .TP
327 .PD 0
328 .BI \-Nq n
329 .TP
330 .BI \-Nx n
331 .TP
332 .BI \-Ns n
333 .TP
334 .BI \-Nc n
335 .TP
336 .PD
337 .BI \-Nn n
338 Set various implementation size limits (internal table sizes). These
339 flags set, respectively, limits on the number of equivalences (default
340 150), external symbols (default 200), statement labels (default 801),
341 nesting of loops or if-then-elses (default 20), and identifier names
342 (default 401).
343 .TP
344 .B \-p
345 Use #defines within each procedure to make references to common block
346 variables look to human readers like local variables. For SUIF this
347 is irrelevant since the macros will have been expanded by the C
348 pre-processor before SUIF code is ever produced. SUIF's Fortran mode
349 allows SUIF programs to see common block variables as locals.
350 .TP
351 .PD 0
352 .BI \-Fr format-string
353 .TP
354 .PD
355 .BI \-Fd format-string
356 Use the specified string to format, respectively, `float' or `double'
357 data written to the output C file. The defaults are "(float)%s" (or
358 "%sf" if the
359 .B \-A
360 flag is used to specify ANSI-C) for `float' and "%.17g" for `double'.
361 .TP
362 .B \-ev
363 This option might mean to #define things in equivalences to look like
364 ordinary local variables to human readers of the C file. If so, it is
365 irrelevant to SUIF since the C pre-processor substitutes for the
366 macros before the code is converted to SUIF.
367 .SH ENVIRONMENT VARIABLES
368 .TP
369 .B TMPDIR
370 This variable specifies the directory to use for temporary files
371 instead of the default /tmp directory. See also the
372 .B \-T
373 option.
374 .SH SEE ALSO
375 .I scc,
376 .I snoot,
377 .I fixfortran,
378 .I porky,
379 and
380 .I f77.
381 .SH HISTORY
382 The version of
383 .I f2c
384 upon which
385 .I sf2c
386 is based calls itself, "VERSION 14 December 1989 7:55:33". It was
387 adapted for an early version of SUIF by Dror Maydan. Chris Wilson
388 made more modifications to get the information required by the current
389 SUIF system.
390 .PP
391 Parts of this document were taken from the man page distributed with
392 .I f2c.