]>
Commit | Line | Data |
---|---|---|
5ff904cd | 1 | \input texinfo @c -*-texinfo-*- |
66d18ad7 | 2 | @c %**start of header |
5ff904cd | 3 | @setfilename g77.info |
e72d9e6b | 4 | |
37cfb17c | 5 | @set last-update 1999-05-06 |
51efa892 CB |
6 | @set copyrights-g77 1995-1999 |
7 | ||
8 | @include root.texi | |
9 | ||
10 | @c This tells @include'd files that they're part of the overall G77 doc | |
11 | @c set. (They might be part of a higher-level doc set too.) | |
12 | @set DOC-G77 | |
e72d9e6b | 13 | |
5ff904cd JL |
14 | @c @setfilename useg77.info |
15 | @c @setfilename portg77.info | |
16 | @c To produce the full manual, use the "g77.info" setfilename, and | |
17 | @c make sure the following do NOT begin with '@c' (and the @clear lines DO) | |
18 | @set INTERNALS | |
19 | @set USING | |
20 | @c To produce a user-only manual, use the "useg77.info" setfilename, and | |
21 | @c make sure the following does NOT begin with '@c': | |
22 | @c @clear INTERNALS | |
23 | @c To produce a porter-only manual, use the "portg77.info" setfilename, | |
24 | @c and make sure the following does NOT begin with '@c': | |
25 | @c @clear USING | |
26 | ||
51efa892 CB |
27 | @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. (from gcc.texi) |
28 | @c @smallbook | |
5ff904cd | 29 | |
51efa892 CB |
30 | @c i also commented out the finalout command, so if there *are* any |
31 | @c overfulls, you'll (hopefully) see the rectangle in the right hand | |
32 | @c margin. -- burley 1999-03-13 (from mew's comment in gcc.texi). | |
33 | @c @finalout | |
5ff904cd JL |
34 | |
35 | @ifset INTERNALS | |
36 | @ifset USING | |
37 | @settitle Using and Porting GNU Fortran | |
38 | @end ifset | |
39 | @end ifset | |
40 | @c seems reasonable to assume at least one of INTERNALS or USING is set... | |
41 | @ifclear INTERNALS | |
42 | @settitle Using GNU Fortran | |
43 | @end ifclear | |
44 | @ifclear USING | |
45 | @settitle Porting GNU Fortran | |
66d18ad7 | 46 | @end ifclear |
5ff904cd JL |
47 | @c then again, have some fun |
48 | @ifclear INTERNALS | |
49 | @ifclear USING | |
50 | @settitle Doing Squat with GNU Fortran | |
51 | @end ifclear | |
52 | @end ifclear | |
53 | ||
54 | @syncodeindex fn cp | |
55 | @syncodeindex vr cp | |
56 | @c %**end of header | |
51efa892 CB |
57 | |
58 | @c Cause even numbered pages to be printed on the left hand side of | |
59 | @c the page and odd numbered pages to be printed on the right hand | |
60 | @c side of the page. Using this, you can print on both sides of a | |
61 | @c sheet of paper and have the text on the same part of the sheet. | |
62 | ||
63 | @c The text on right hand pages is pushed towards the right hand | |
64 | @c margin and the text on left hand pages is pushed toward the left | |
65 | @c hand margin. | |
66 | @c (To provide the reverse effect, set bindingoffset to -0.75in.) | |
67 | ||
68 | @c @tex | |
69 | @c \global\bindingoffset=0.75in | |
70 | @c \global\normaloffset =0.75in | |
71 | @c @end tex | |
5ff904cd JL |
72 | |
73 | @ifinfo | |
51efa892 CB |
74 | @dircategory Programming |
75 | @direntry | |
76 | * g77: (g77). The GNU Fortran compiler. | |
77 | @end direntry | |
78 | @ifset INTERNALS | |
79 | @ifset USING | |
80 | This file documents the use and the internals of the GNU Fortran (@code{g77}) | |
81 | compiler. | |
82 | It corresponds to the @value{which-g77} version of @code{g77}. | |
83 | @end ifset | |
84 | @end ifset | |
85 | @ifclear USING | |
86 | This file documents the internals of the GNU Fortran (@code{g77}) compiler. | |
87 | It corresponds to the @value{which-g77} version of @code{g77}. | |
88 | @end ifclear | |
89 | @ifclear INTERNALS | |
90 | This file documents the use of the GNU Fortran (@code{g77}) compiler. | |
91 | It corresponds to the @value{which-g77} version of @code{g77}. | |
92 | @end ifclear | |
5ff904cd JL |
93 | |
94 | Published by the Free Software Foundation | |
95 | 59 Temple Place - Suite 330 | |
96 | Boston, MA 02111-1307 USA | |
97 | ||
51efa892 | 98 | Copyright (C) @value{copyrights-g77} Free Software Foundation, Inc. |
5ff904cd JL |
99 | |
100 | Permission is granted to make and distribute verbatim copies of | |
101 | this manual provided the copyright notice and this permission notice | |
102 | are preserved on all copies. | |
103 | ||
104 | @ignore | |
105 | Permission is granted to process this file through Tex and print the | |
106 | results, provided the printed document carries copying permission | |
107 | notice identical to this one except for the removal of this paragraph | |
108 | (this paragraph not being relevant to the printed manual). | |
109 | ||
110 | @end ignore | |
111 | Permission is granted to copy and distribute modified versions of this | |
112 | manual under the conditions for verbatim copying, provided also that the | |
113 | sections entitled ``GNU General Public License,'' ``Funding for Free | |
114 | Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are | |
115 | included exactly as in the original, and provided that the entire | |
116 | resulting derived work is distributed under the terms of a permission | |
117 | notice identical to this one. | |
118 | ||
119 | Permission is granted to copy and distribute translations of this manual | |
120 | into another language, under the above conditions for modified versions, | |
121 | except that the sections entitled ``GNU General Public License,'' | |
122 | ``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look | |
123 | And Feel'@w{}'', and this permission notice, may be included in | |
124 | translations approved by the Free Software Foundation instead of in the | |
125 | original English. | |
126 | @end ifinfo | |
127 | ||
d79904b8 | 128 | Contributed by James Craig Burley (@email{@value{email-burley}}). |
5ff904cd JL |
129 | Inspired by a first pass at translating @file{g77-0.5.16/f/DOC} that |
130 | was contributed to Craig by David Ronis (@email{ronis@@onsager.chem.mcgill.ca}). | |
131 | ||
51efa892 CB |
132 | @setchapternewpage odd |
133 | @c @finalout | |
5ff904cd | 134 | @titlepage |
51efa892 CB |
135 | @ifset INTERNALS |
136 | @ifset USING | |
137 | @center @titlefont{Using and Porting GNU Fortran} | |
138 | ||
139 | @end ifset | |
140 | @end ifset | |
141 | @ifclear INTERNALS | |
142 | @title Using GNU Fortran | |
143 | @end ifclear | |
144 | @ifclear USING | |
145 | @title Porting GNU Fortran | |
146 | @end ifclear | |
5ff904cd JL |
147 | @sp 2 |
148 | @center James Craig Burley | |
149 | @sp 3 | |
51efa892 | 150 | @center Last updated @value{last-update} |
5ff904cd | 151 | @sp 1 |
0063c777 | 152 | @center for version @value{version-g77} |
5ff904cd JL |
153 | @page |
154 | @vskip 0pt plus 1filll | |
51efa892 | 155 | Copyright @copyright{} @value{copyrights-g77} Free Software Foundation, Inc. |
5ff904cd | 156 | @sp 2 |
51efa892 | 157 | For the @value{which-g77} Version* |
5ff904cd JL |
158 | @sp 1 |
159 | Published by the Free Software Foundation @* | |
160 | 59 Temple Place - Suite 330@* | |
161 | Boston, MA 02111-1307, USA@* | |
162 | @c Last printed ??ber, 19??.@* | |
163 | @c Printed copies are available for $? each.@* | |
164 | @c ISBN ??? | |
165 | @sp 1 | |
166 | Permission is granted to make and distribute verbatim copies of | |
167 | this manual provided the copyright notice and this permission notice | |
168 | are preserved on all copies. | |
169 | ||
170 | Permission is granted to copy and distribute modified versions of this | |
171 | manual under the conditions for verbatim copying, provided also that the | |
172 | sections entitled ``GNU General Public License,'' ``Funding for Free | |
173 | Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are | |
174 | included exactly as in the original, and provided that the entire | |
175 | resulting derived work is distributed under the terms of a permission | |
176 | notice identical to this one. | |
177 | ||
178 | Permission is granted to copy and distribute translations of this manual | |
179 | into another language, under the above conditions for modified versions, | |
180 | except that the sections entitled ``GNU General Public License,'' | |
181 | ``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look | |
182 | And Feel'@w{}'', and this permission notice, may be included in | |
183 | translations approved by the Free Software Foundation instead of in the | |
184 | original English. | |
185 | @end titlepage | |
186 | @page | |
187 | ||
188 | @ifinfo | |
189 | ||
5ff904cd JL |
190 | @node Top, Copying,, (DIR) |
191 | @top Introduction | |
192 | @cindex Introduction | |
193 | ||
194 | @ifset INTERNALS | |
195 | @ifset USING | |
51efa892 CB |
196 | This manual documents how to run, install and port @code{g77}, |
197 | as well as its new features and incompatibilities, | |
198 | and how to report bugs. | |
199 | It corresponds to the @value{which-g77} version of @code{g77}. | |
5ff904cd JL |
200 | @end ifset |
201 | @end ifset | |
202 | ||
203 | @ifclear INTERNALS | |
51efa892 | 204 | This manual documents how to run and install @code{g77}, |
5ff904cd | 205 | as well as its new features and incompatibilities, and how to report |
51efa892 CB |
206 | bugs. |
207 | It corresponds to the @value{which-g77} version of @code{g77}. | |
5ff904cd JL |
208 | @end ifclear |
209 | @ifclear USING | |
51efa892 CB |
210 | This manual documents how to port @code{g77}, |
211 | as well as its new features and incompatibilities, | |
212 | and how to report bugs. | |
213 | It corresponds to the @value{which-g77} version of @code{g77}. | |
5ff904cd JL |
214 | @end ifclear |
215 | ||
216 | @end ifinfo | |
51efa892 CB |
217 | |
218 | @ifset DEVELOPMENT | |
219 | @emph{Warning:} This document is still under development, | |
220 | and might not accurately reflect the @code{g77} code base | |
221 | of which it is a part. | |
222 | Efforts are made to keep it somewhat up-to-date, | |
223 | but they are particularly concentrated | |
224 | on any version of this information | |
225 | that is distributed as part of a @emph{released} @code{g77}. | |
226 | ||
227 | In particular, while this document is intended to apply to | |
228 | the @value{which-g77} version of @code{g77}, | |
229 | only an official @emph{release} of that version | |
230 | is expected to contain documentation that is | |
231 | most consistent with the @code{g77} product in that version. | |
232 | @end ifset | |
233 | ||
5ff904cd JL |
234 | @menu |
235 | * Copying:: GNU General Public License says | |
236 | how you can copy and share GNU Fortran. | |
237 | * Contributors:: People who have contributed to GNU Fortran. | |
238 | * Funding:: How to help assure continued work for free software. | |
239 | * Funding GNU Fortran:: How to help assure continued work on GNU Fortran. | |
240 | * Look and Feel:: Protect your freedom---fight ``look and feel''. | |
241 | @ifset USING | |
242 | * Getting Started:: Finding your way around this manual. | |
243 | * What is GNU Fortran?:: How @code{g77} fits into the universe. | |
244 | * G77 and GCC:: You can compile Fortran, C, or other programs. | |
245 | * Invoking G77:: Command options supported by @code{g77}. | |
246 | * News:: News about recent releases of @code{g77}. | |
247 | * Changes:: User-visible changes to recent releases of @code{g77}. | |
248 | * Language:: The GNU Fortran language. | |
249 | * Compiler:: The GNU Fortran compiler. | |
250 | * Other Dialects:: Dialects of Fortran supported by @code{g77}. | |
251 | * Other Compilers:: Fortran compilers other than @code{g77}. | |
252 | * Other Languages:: Languages other than Fortran. | |
253 | * Installation:: How to configure, compile and install GNU Fortran. | |
254 | * Debugging and Interfacing:: How @code{g77} generates code. | |
255 | * Collected Fortran Wisdom:: How to avoid Trouble. | |
256 | * Trouble:: If you have trouble with GNU Fortran. | |
257 | * Open Questions:: Things we'd like to know. | |
258 | * Bugs:: How, why, and where to report bugs. | |
259 | * Service:: How to find suppliers of support for GNU Fortran. | |
260 | @end ifset | |
261 | @ifset INTERNALS | |
262 | * Adding Options:: Guidance on teaching @code{g77} about new options. | |
263 | * Projects:: Projects for @code{g77} internals hackers. | |
75e8000e | 264 | * Front End:: Design and implementation of the @code{g77} front end. |
5ff904cd JL |
265 | @end ifset |
266 | ||
267 | * M: Diagnostics. Diagnostics produced by @code{g77}. | |
268 | ||
269 | * Index:: Index of concepts and symbol names. | |
270 | @end menu | |
271 | @c yes, the "M: " @emph{is} intentional -- bad.def references it (CMPAMBIG)! | |
272 | ||
273 | @node Copying | |
274 | @unnumbered GNU GENERAL PUBLIC LICENSE | |
275 | @center Version 2, June 1991 | |
276 | ||
277 | @display | |
278 | Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. | |
279 | 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA | |
280 | ||
281 | Everyone is permitted to copy and distribute verbatim copies | |
282 | of this license document, but changing it is not allowed. | |
283 | @end display | |
284 | ||
285 | @unnumberedsec Preamble | |
286 | ||
287 | The licenses for most software are designed to take away your | |
288 | freedom to share and change it. By contrast, the GNU General Public | |
289 | License is intended to guarantee your freedom to share and change free | |
290 | software---to make sure the software is free for all its users. This | |
291 | General Public License applies to most of the Free Software | |
292 | Foundation's software and to any other program whose authors commit to | |
293 | using it. (Some other Free Software Foundation software is covered by | |
294 | the GNU Library General Public License instead.) You can apply it to | |
295 | your programs, too. | |
296 | ||
297 | When we speak of free software, we are referring to freedom, not | |
298 | price. Our General Public Licenses are designed to make sure that you | |
299 | have the freedom to distribute copies of free software (and charge for | |
300 | this service if you wish), that you receive source code or can get it | |
301 | if you want it, that you can change the software or use pieces of it | |
302 | in new free programs; and that you know you can do these things. | |
303 | ||
304 | To protect your rights, we need to make restrictions that forbid | |
305 | anyone to deny you these rights or to ask you to surrender the rights. | |
306 | These restrictions translate to certain responsibilities for you if you | |
307 | distribute copies of the software, or if you modify it. | |
308 | ||
309 | For example, if you distribute copies of such a program, whether | |
310 | gratis or for a fee, you must give the recipients all the rights that | |
311 | you have. You must make sure that they, too, receive or can get the | |
312 | source code. And you must show them these terms so they know their | |
313 | rights. | |
314 | ||
315 | We protect your rights with two steps: (1) copyright the software, and | |
316 | (2) offer you this license which gives you legal permission to copy, | |
317 | distribute and/or modify the software. | |
318 | ||
319 | Also, for each author's protection and ours, we want to make certain | |
320 | that everyone understands that there is no warranty for this free | |
321 | software. If the software is modified by someone else and passed on, we | |
322 | want its recipients to know that what they have is not the original, so | |
323 | that any problems introduced by others will not reflect on the original | |
324 | authors' reputations. | |
325 | ||
326 | Finally, any free program is threatened constantly by software | |
327 | patents. We wish to avoid the danger that redistributors of a free | |
328 | program will individually obtain patent licenses, in effect making the | |
329 | program proprietary. To prevent this, we have made it clear that any | |
330 | patent must be licensed for everyone's free use or not licensed at all. | |
331 | ||
332 | The precise terms and conditions for copying, distribution and | |
333 | modification follow. | |
334 | ||
335 | @iftex | |
336 | @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
337 | @end iftex | |
338 | @ifinfo | |
339 | @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION | |
340 | @end ifinfo | |
341 | ||
342 | @enumerate 0 | |
343 | @item | |
344 | This License applies to any program or other work which contains | |
345 | a notice placed by the copyright holder saying it may be distributed | |
346 | under the terms of this General Public License. The ``Program'', below, | |
347 | refers to any such program or work, and a ``work based on the Program'' | |
348 | means either the Program or any derivative work under copyright law: | |
349 | that is to say, a work containing the Program or a portion of it, | |
350 | either verbatim or with modifications and/or translated into another | |
351 | language. (Hereinafter, translation is included without limitation in | |
352 | the term ``modification''.) Each licensee is addressed as ``you''. | |
353 | ||
354 | Activities other than copying, distribution and modification are not | |
355 | covered by this License; they are outside its scope. The act of | |
356 | running the Program is not restricted, and the output from the Program | |
357 | is covered only if its contents constitute a work based on the | |
358 | Program (independent of having been made by running the Program). | |
359 | Whether that is true depends on what the Program does. | |
360 | ||
361 | @item | |
362 | You may copy and distribute verbatim copies of the Program's | |
363 | source code as you receive it, in any medium, provided that you | |
364 | conspicuously and appropriately publish on each copy an appropriate | |
365 | copyright notice and disclaimer of warranty; keep intact all the | |
366 | notices that refer to this License and to the absence of any warranty; | |
367 | and give any other recipients of the Program a copy of this License | |
368 | along with the Program. | |
369 | ||
370 | You may charge a fee for the physical act of transferring a copy, and | |
371 | you may at your option offer warranty protection in exchange for a fee. | |
372 | ||
373 | @item | |
374 | You may modify your copy or copies of the Program or any portion | |
375 | of it, thus forming a work based on the Program, and copy and | |
376 | distribute such modifications or work under the terms of Section 1 | |
377 | above, provided that you also meet all of these conditions: | |
378 | ||
379 | @enumerate a | |
380 | @item | |
381 | You must cause the modified files to carry prominent notices | |
382 | stating that you changed the files and the date of any change. | |
383 | ||
384 | @item | |
385 | You must cause any work that you distribute or publish, that in | |
386 | whole or in part contains or is derived from the Program or any | |
387 | part thereof, to be licensed as a whole at no charge to all third | |
388 | parties under the terms of this License. | |
389 | ||
390 | @item | |
391 | If the modified program normally reads commands interactively | |
392 | when run, you must cause it, when started running for such | |
393 | interactive use in the most ordinary way, to print or display an | |
394 | announcement including an appropriate copyright notice and a | |
395 | notice that there is no warranty (or else, saying that you provide | |
396 | a warranty) and that users may redistribute the program under | |
397 | these conditions, and telling the user how to view a copy of this | |
398 | License. (Exception: if the Program itself is interactive but | |
399 | does not normally print such an announcement, your work based on | |
400 | the Program is not required to print an announcement.) | |
401 | @end enumerate | |
402 | ||
403 | These requirements apply to the modified work as a whole. If | |
404 | identifiable sections of that work are not derived from the Program, | |
405 | and can be reasonably considered independent and separate works in | |
406 | themselves, then this License, and its terms, do not apply to those | |
407 | sections when you distribute them as separate works. But when you | |
408 | distribute the same sections as part of a whole which is a work based | |
409 | on the Program, the distribution of the whole must be on the terms of | |
410 | this License, whose permissions for other licensees extend to the | |
411 | entire whole, and thus to each and every part regardless of who wrote it. | |
412 | ||
413 | Thus, it is not the intent of this section to claim rights or contest | |
414 | your rights to work written entirely by you; rather, the intent is to | |
415 | exercise the right to control the distribution of derivative or | |
416 | collective works based on the Program. | |
417 | ||
418 | In addition, mere aggregation of another work not based on the Program | |
419 | with the Program (or with a work based on the Program) on a volume of | |
420 | a storage or distribution medium does not bring the other work under | |
421 | the scope of this License. | |
422 | ||
423 | @item | |
424 | You may copy and distribute the Program (or a work based on it, | |
425 | under Section 2) in object code or executable form under the terms of | |
426 | Sections 1 and 2 above provided that you also do one of the following: | |
427 | ||
428 | @enumerate a | |
429 | @item | |
430 | Accompany it with the complete corresponding machine-readable | |
431 | source code, which must be distributed under the terms of Sections | |
432 | 1 and 2 above on a medium customarily used for software interchange; or, | |
433 | ||
434 | @item | |
435 | Accompany it with a written offer, valid for at least three | |
436 | years, to give any third party, for a charge no more than your | |
437 | cost of physically performing source distribution, a complete | |
438 | machine-readable copy of the corresponding source code, to be | |
439 | distributed under the terms of Sections 1 and 2 above on a medium | |
440 | customarily used for software interchange; or, | |
441 | ||
442 | @item | |
443 | Accompany it with the information you received as to the offer | |
444 | to distribute corresponding source code. (This alternative is | |
445 | allowed only for noncommercial distribution and only if you | |
446 | received the program in object code or executable form with such | |
447 | an offer, in accord with Subsection b above.) | |
448 | @end enumerate | |
449 | ||
450 | The source code for a work means the preferred form of the work for | |
451 | making modifications to it. For an executable work, complete source | |
452 | code means all the source code for all modules it contains, plus any | |
453 | associated interface definition files, plus the scripts used to | |
454 | control compilation and installation of the executable. However, as a | |
455 | special exception, the source code distributed need not include | |
456 | anything that is normally distributed (in either source or binary | |
457 | form) with the major components (compiler, kernel, and so on) of the | |
458 | operating system on which the executable runs, unless that component | |
459 | itself accompanies the executable. | |
460 | ||
461 | If distribution of executable or object code is made by offering | |
462 | access to copy from a designated place, then offering equivalent | |
463 | access to copy the source code from the same place counts as | |
464 | distribution of the source code, even though third parties are not | |
465 | compelled to copy the source along with the object code. | |
466 | ||
467 | @item | |
468 | You may not copy, modify, sublicense, or distribute the Program | |
469 | except as expressly provided under this License. Any attempt | |
470 | otherwise to copy, modify, sublicense or distribute the Program is | |
471 | void, and will automatically terminate your rights under this License. | |
472 | However, parties who have received copies, or rights, from you under | |
473 | this License will not have their licenses terminated so long as such | |
474 | parties remain in full compliance. | |
475 | ||
476 | @item | |
477 | You are not required to accept this License, since you have not | |
478 | signed it. However, nothing else grants you permission to modify or | |
479 | distribute the Program or its derivative works. These actions are | |
480 | prohibited by law if you do not accept this License. Therefore, by | |
481 | modifying or distributing the Program (or any work based on the | |
482 | Program), you indicate your acceptance of this License to do so, and | |
483 | all its terms and conditions for copying, distributing or modifying | |
484 | the Program or works based on it. | |
485 | ||
486 | @item | |
487 | Each time you redistribute the Program (or any work based on the | |
488 | Program), the recipient automatically receives a license from the | |
489 | original licensor to copy, distribute or modify the Program subject to | |
490 | these terms and conditions. You may not impose any further | |
491 | restrictions on the recipients' exercise of the rights granted herein. | |
492 | You are not responsible for enforcing compliance by third parties to | |
493 | this License. | |
494 | ||
495 | @item | |
496 | If, as a consequence of a court judgment or allegation of patent | |
497 | infringement or for any other reason (not limited to patent issues), | |
498 | conditions are imposed on you (whether by court order, agreement or | |
499 | otherwise) that contradict the conditions of this License, they do not | |
500 | excuse you from the conditions of this License. If you cannot | |
501 | distribute so as to satisfy simultaneously your obligations under this | |
502 | License and any other pertinent obligations, then as a consequence you | |
503 | may not distribute the Program at all. For example, if a patent | |
504 | license would not permit royalty-free redistribution of the Program by | |
505 | all those who receive copies directly or indirectly through you, then | |
506 | the only way you could satisfy both it and this License would be to | |
507 | refrain entirely from distribution of the Program. | |
508 | ||
509 | If any portion of this section is held invalid or unenforceable under | |
510 | any particular circumstance, the balance of the section is intended to | |
511 | apply and the section as a whole is intended to apply in other | |
512 | circumstances. | |
513 | ||
514 | It is not the purpose of this section to induce you to infringe any | |
515 | patents or other property right claims or to contest validity of any | |
516 | such claims; this section has the sole purpose of protecting the | |
517 | integrity of the free software distribution system, which is | |
518 | implemented by public license practices. Many people have made | |
519 | generous contributions to the wide range of software distributed | |
520 | through that system in reliance on consistent application of that | |
521 | system; it is up to the author/donor to decide if he or she is willing | |
522 | to distribute software through any other system and a licensee cannot | |
523 | impose that choice. | |
524 | ||
525 | This section is intended to make thoroughly clear what is believed to | |
526 | be a consequence of the rest of this License. | |
527 | ||
528 | @item | |
529 | If the distribution and/or use of the Program is restricted in | |
530 | certain countries either by patents or by copyrighted interfaces, the | |
531 | original copyright holder who places the Program under this License | |
532 | may add an explicit geographical distribution limitation excluding | |
533 | those countries, so that distribution is permitted only in or among | |
534 | countries not thus excluded. In such case, this License incorporates | |
535 | the limitation as if written in the body of this License. | |
536 | ||
537 | @item | |
538 | The Free Software Foundation may publish revised and/or new versions | |
539 | of the General Public License from time to time. Such new versions will | |
540 | be similar in spirit to the present version, but may differ in detail to | |
541 | address new problems or concerns. | |
542 | ||
543 | Each version is given a distinguishing version number. If the Program | |
544 | specifies a version number of this License which applies to it and ``any | |
545 | later version'', you have the option of following the terms and conditions | |
546 | either of that version or of any later version published by the Free | |
547 | Software Foundation. If the Program does not specify a version number of | |
548 | this License, you may choose any version ever published by the Free Software | |
549 | Foundation. | |
550 | ||
551 | @item | |
552 | If you wish to incorporate parts of the Program into other free | |
553 | programs whose distribution conditions are different, write to the author | |
554 | to ask for permission. For software which is copyrighted by the Free | |
555 | Software Foundation, write to the Free Software Foundation; we sometimes | |
556 | make exceptions for this. Our decision will be guided by the two goals | |
557 | of preserving the free status of all derivatives of our free software and | |
558 | of promoting the sharing and reuse of software generally. | |
559 | ||
560 | @iftex | |
561 | @heading NO WARRANTY | |
562 | @end iftex | |
563 | @ifinfo | |
564 | @center NO WARRANTY | |
565 | @end ifinfo | |
566 | ||
567 | @item | |
568 | BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY | |
569 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN | |
570 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES | |
571 | PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED | |
572 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF | |
573 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS | |
574 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE | |
575 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, | |
576 | REPAIR OR CORRECTION. | |
577 | ||
578 | @item | |
579 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING | |
580 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR | |
581 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, | |
582 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING | |
583 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED | |
584 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY | |
585 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER | |
586 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE | |
587 | POSSIBILITY OF SUCH DAMAGES. | |
588 | @end enumerate | |
589 | ||
590 | @iftex | |
591 | @heading END OF TERMS AND CONDITIONS | |
592 | @end iftex | |
593 | @ifinfo | |
594 | @center END OF TERMS AND CONDITIONS | |
595 | @end ifinfo | |
596 | ||
597 | @page | |
598 | @unnumberedsec How to Apply These Terms to Your New Programs | |
599 | ||
600 | If you develop a new program, and you want it to be of the greatest | |
601 | possible use to the public, the best way to achieve this is to make it | |
602 | free software which everyone can redistribute and change under these terms. | |
603 | ||
604 | To do so, attach the following notices to the program. It is safest | |
605 | to attach them to the start of each source file to most effectively | |
606 | convey the exclusion of warranty; and each file should have at least | |
607 | the ``copyright'' line and a pointer to where the full notice is found. | |
608 | ||
609 | @smallexample | |
610 | @var{one line to give the program's name and a brief idea of what it does.} | |
611 | Copyright (C) 19@var{yy} @var{name of author} | |
612 | ||
66d18ad7 UD |
613 | This program is free software; you can redistribute it and/or modify |
614 | it under the terms of the GNU General Public License as published by | |
615 | the Free Software Foundation; either version 2 of the License, or | |
5ff904cd JL |
616 | (at your option) any later version. |
617 | ||
618 | This program is distributed in the hope that it will be useful, | |
619 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
620 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
621 | GNU General Public License for more details. | |
622 | ||
623 | You should have received a copy of the GNU General Public License | |
624 | along with this program; if not, write to the Free Software | |
625 | Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. | |
626 | @end smallexample | |
627 | ||
628 | Also add information on how to contact you by electronic and paper mail. | |
629 | ||
630 | If the program is interactive, make it output a short notice like this | |
631 | when it starts in an interactive mode: | |
632 | ||
633 | @smallexample | |
634 | Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author} | |
635 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details | |
66d18ad7 UD |
636 | type `show w'. |
637 | This is free software, and you are welcome to redistribute it | |
5ff904cd JL |
638 | under certain conditions; type `show c' for details. |
639 | @end smallexample | |
640 | ||
641 | The hypothetical commands @samp{show w} and @samp{show c} should show | |
642 | the appropriate parts of the General Public License. Of course, the | |
643 | commands you use may be called something other than @samp{show w} and | |
644 | @samp{show c}; they could even be mouse-clicks or menu items---whatever | |
645 | suits your program. | |
646 | ||
647 | You should also get your employer (if you work as a programmer) or your | |
648 | school, if any, to sign a ``copyright disclaimer'' for the program, if | |
649 | necessary. Here is a sample; alter the names: | |
650 | ||
651 | @smallexample | |
652 | Yoyodyne, Inc., hereby disclaims all copyright interest in the program | |
653 | `Gnomovision' (which makes passes at compilers) written by James Hacker. | |
654 | ||
655 | @var{signature of Ty Coon}, 1 April 1989 | |
656 | Ty Coon, President of Vice | |
657 | @end smallexample | |
658 | ||
659 | This General Public License does not permit incorporating your program into | |
660 | proprietary programs. If your program is a subroutine library, you may | |
661 | consider it more useful to permit linking proprietary applications with the | |
662 | library. If this is what you want to do, use the GNU Library General | |
663 | Public License instead of this License. | |
664 | ||
665 | @node Contributors | |
666 | @unnumbered Contributors to GNU Fortran | |
667 | @cindex contributors | |
668 | @cindex credits | |
669 | ||
670 | In addition to James Craig Burley, who wrote the front end, | |
671 | many people have helped create and improve GNU Fortran. | |
672 | ||
673 | @itemize @bullet | |
674 | @item | |
675 | The packaging and compiler portions of GNU Fortran are based largely | |
676 | on the GNU CC compiler. | |
677 | @xref{Contributors,,Contributors to GNU CC,gcc,Using and Porting GNU CC}, | |
678 | for more information. | |
679 | ||
680 | @item | |
681 | The run-time library used by GNU Fortran is a repackaged version | |
682 | of the @code{libf2c} library (combined from the @code{libF77} and | |
683 | @code{libI77} libraries) provided as part of @code{f2c}, available for | |
684 | free from @code{netlib} sites on the Internet. | |
685 | ||
686 | @item | |
687 | Cygnus Support and The Free Software Foundation contributed | |
688 | significant money and/or equipment to Craig's efforts. | |
689 | ||
690 | @item | |
691 | The following individuals served as alpha testers prior to @code{g77}'s | |
692 | public release. This work consisted of testing, researching, sometimes | |
693 | debugging, and occasionally providing small amounts of code and fixes | |
694 | for @code{g77}, plus offering plenty of helpful advice to Craig: | |
695 | ||
696 | @itemize @w{} | |
697 | @item | |
698 | Jonathan Corbet | |
699 | @item | |
700 | Dr.@: Mark Fernyhough | |
701 | @item | |
0b31330e | 702 | Takafumi Hayashi (The University of Aizu)---@email{takafumi@@u-aizu.ac.jp} |
5ff904cd JL |
703 | @item |
704 | Kate Hedstrom | |
705 | @item | |
706 | Michel Kern (INRIA and Rice University)---@email{Michel.Kern@@inria.fr} | |
707 | @item | |
708 | Dr.@: A. O. V. Le Blanc | |
709 | @item | |
710 | Dave Love | |
711 | @item | |
712 | Rick Lutowski | |
713 | @item | |
714 | Toon Moene | |
715 | @item | |
716 | Rick Niles | |
717 | @item | |
718 | Derk Reefman | |
719 | @item | |
720 | Wayne K. Schroll | |
721 | @item | |
722 | Bill Thorson | |
723 | @item | |
724 | Pedro A. M. Vazquez | |
725 | @item | |
726 | Ian Watson | |
727 | @end itemize | |
728 | ||
729 | @item | |
730 | Scott Snyder (@email{snyder@@d0sgif.fnal.gov}) | |
731 | provided the patch to add rudimentary support | |
732 | for @code{INTEGER*1}, @code{INTEGER*2}, and | |
733 | @code{LOGICAL*1}. | |
734 | This inspired Craig to add further support, | |
735 | even though the resulting support | |
736 | would still be incomplete, because version 0.6 is still | |
737 | a ways off. | |
738 | ||
739 | @item | |
740 | David Ronis (@email{ronis@@onsager.chem.mcgill.ca}) inspired | |
741 | and encouraged Craig to rewrite the documentation in texinfo | |
742 | format by contributing a first pass at a translation of the | |
743 | old @file{g77-0.5.16/f/DOC} file. | |
744 | ||
745 | @item | |
746 | Toon Moene (@email{toon@@moene.indiv.nluug.nl}) performed | |
747 | some analysis of generated code as part of an overall project | |
748 | to improve @code{g77} code generation to at least be as good | |
749 | as @code{f2c} used in conjunction with @code{gcc}. | |
750 | So far, this has resulted in the three, somewhat | |
751 | experimental, options added by @code{g77} to the @code{gcc} | |
752 | compiler and its back end. | |
753 | ||
e72d9e6b DL |
754 | (These, in turn, have made their way into the @code{egcs} |
755 | version of the compiler, and do not exist in @code{gcc} | |
756 | version 2.8 or versions of @code{g77} based on that version | |
757 | of @code{gcc}.) | |
758 | ||
5ff904cd JL |
759 | @item |
760 | John Carr (@email{jfc@@mit.edu}) wrote the alias analysis improvements. | |
761 | ||
762 | @item | |
763 | Thanks to Mary Cortani and the staff at Craftwork Solutions | |
764 | (@email{support@@craftwork.com}) for all of their support. | |
765 | ||
766 | @item | |
767 | Many other individuals have helped debug, test, and improve @code{g77} | |
768 | over the past several years, and undoubtedly more people | |
769 | will be doing so in the future. | |
770 | If you have done so, and would like | |
771 | to see your name listed in the above list, please ask! | |
772 | The default is that people wish to remain anonymous. | |
773 | @end itemize | |
774 | ||
775 | @node Funding | |
776 | @chapter Funding Free Software | |
777 | ||
778 | If you want to have more free software a few years from now, it makes | |
779 | sense for you to help encourage people to contribute funds for its | |
780 | development. The most effective approach known is to encourage | |
781 | commercial redistributors to donate. | |
782 | ||
783 | Users of free software systems can boost the pace of development by | |
784 | encouraging for-a-fee distributors to donate part of their selling price | |
785 | to free software developers---the Free Software Foundation, and others. | |
786 | ||
787 | The way to convince distributors to do this is to demand it and expect | |
788 | it from them. So when you compare distributors, judge them partly by | |
789 | how much they give to free software development. Show distributors | |
790 | they must compete to be the one who gives the most. | |
791 | ||
792 | To make this approach work, you must insist on numbers that you can | |
793 | compare, such as, ``We will donate ten dollars to the Frobnitz project | |
794 | for each disk sold.'' Don't be satisfied with a vague promise, such as | |
795 | ``A portion of the profits are donated,'' since it doesn't give a basis | |
796 | for comparison. | |
797 | ||
798 | Even a precise fraction ``of the profits from this disk'' is not very | |
799 | meaningful, since creative accounting and unrelated business decisions | |
800 | can greatly alter what fraction of the sales price counts as profit. | |
801 | If the price you pay is $50, ten percent of the profit is probably | |
802 | less than a dollar; it might be a few cents, or nothing at all. | |
803 | ||
804 | Some redistributors do development work themselves. This is useful too; | |
805 | but to keep everyone honest, you need to inquire how much they do, and | |
806 | what kind. Some kinds of development make much more long-term | |
807 | difference than others. For example, maintaining a separate version of | |
808 | a program contributes very little; maintaining the standard version of a | |
809 | program for the whole community contributes much. Easy new ports | |
810 | contribute little, since someone else would surely do them; difficult | |
811 | ports such as adding a new CPU to the GNU C compiler contribute more; | |
812 | major new features or packages contribute the most. | |
813 | ||
814 | By establishing the idea that supporting further development is ``the | |
815 | proper thing to do'' when distributing free software for a fee, we can | |
816 | assure a steady flow of resources into making more free software. | |
817 | ||
818 | @display | |
819 | Copyright (C) 1994 Free Software Foundation, Inc. | |
820 | Verbatim copying and redistribution of this section is permitted | |
821 | without royalty; alteration is not permitted. | |
822 | @end display | |
823 | ||
824 | @node Funding GNU Fortran | |
825 | @chapter Funding GNU Fortran | |
826 | @cindex funding improvements | |
827 | @cindex improvements, funding | |
828 | ||
829 | Work on GNU Fortran is still being done mostly by its author, | |
d79904b8 | 830 | James Craig Burley (@email{@value{email-burley}}), who is a volunteer |
5ff904cd | 831 | for, not an employee of, the Free Software Foundation (FSF). |
68b14c71 CB |
832 | (He has a web page at @uref{@value{www-burley}}.) |
833 | ||
5ff904cd JL |
834 | As with other GNU software, funding is important because it can pay for |
835 | needed equipment, personnel, and so on. | |
836 | ||
837 | @cindex FSF, funding the | |
838 | @cindex funding the FSF | |
839 | The FSF provides information on the best way to fund ongoing | |
840 | development of GNU software (such as GNU Fortran) in documents | |
841 | such as the ``GNUS Bulletin''. | |
f2d76545 | 842 | Email @email{gnu@@gnu.org} for information on funding the FSF. |
5ff904cd JL |
843 | |
844 | To fund specific GNU Fortran work in particular, the FSF might | |
845 | provide a means for that, but the FSF does not provide direct funding | |
846 | to the author of GNU Fortran to continue his work. The FSF has | |
847 | employee salary restrictions that can be incompatible with the | |
848 | financial needs of some volunteers, who therefore choose to | |
849 | remain volunteers and thus be able to be free to do contract work | |
850 | and otherwise make their own schedules for doing GNU work. | |
851 | ||
852 | Still, funding the FSF at least indirectly benefits work | |
853 | on specific projects like GNU Fortran because it ensures the | |
854 | continuing operation of the FSF offices, their workstations, their | |
855 | network connections, and so on, which are invaluable to volunteers. | |
856 | (Similarly, hiring Cygnus Support can help a project like GNU | |
857 | Fortran---Cygnus has been a long-time donor of equipment usage to the author | |
858 | of GNU Fortran, and this too has been invaluable---@xref{Contributors}.) | |
859 | ||
860 | Currently, the only way to directly fund the author of GNU Fortran | |
861 | in his work on that project is to hire him for the work you want | |
862 | him to do, or donate money to him. | |
863 | Several people have done this | |
864 | already, with the result that he has not needed to immediately find | |
865 | contract work on a few occasions. | |
866 | If more people did this, he | |
867 | would be able to plan on not doing contract work for many months and | |
868 | could thus devote that time to work on projects (such as the planned | |
869 | changes for 0.6) that require longer timeframes to complete. | |
870 | For the latest information on the status of the author, do | |
f2d76545 | 871 | @kbd{finger -l burley@@gnu.org} on a UNIX system |
5ff904cd JL |
872 | (or any system with a command like UNIX @code{finger}). |
873 | ||
874 | Another important way to support work on GNU Fortran is to volunteer | |
875 | to help out. | |
876 | Work is needed on documentation, testing, porting | |
877 | to various machines, and in some cases, coding (although major | |
878 | changes planned for version 0.6 make it difficult to add manpower to this | |
879 | area). | |
9a59ff4f | 880 | Email @email{@value{email-general}} to volunteer for this work. |
5ff904cd JL |
881 | |
882 | @xref{Funding,,Funding Free Software}, for more information. | |
883 | ||
884 | @node Look and Feel | |
885 | @chapter Protect Your Freedom---Fight ``Look And Feel'' | |
66d18ad7 | 886 | @c the above chapter heading overflows onto the next line. --mew 1/26/93 |
5ff904cd JL |
887 | |
888 | To preserve the ability to write free software, including replacements | |
889 | for proprietary software, authors must be free to replicate the | |
890 | user interface to which users of existing software have become | |
891 | accustomed. | |
892 | ||
893 | @xref{Look and Feel,,Protect Your Freedom---Fight ``Look And Feel'', | |
894 | gcc,Using and Porting GNU CC}, for more information. | |
895 | ||
896 | @node Getting Started | |
897 | @chapter Getting Started | |
898 | @cindex getting started | |
899 | @cindex new users | |
900 | @cindex newbies | |
901 | @cindex beginners | |
902 | ||
903 | If you don't need help getting started reading the portions | |
904 | of this manual that are most important to you, you should skip | |
905 | this portion of the manual. | |
906 | ||
907 | If you are new to compilers, especially Fortran compilers, or | |
908 | new to how compilers are structured under UNIX and UNIX-like | |
909 | systems, you'll want to see @ref{What is GNU Fortran?}. | |
910 | ||
911 | If you are new to GNU compilers, or have used only one GNU | |
912 | compiler in the past and not had to delve into how it lets | |
913 | you manage various versions and configurations of @code{gcc}, | |
914 | you should see @ref{G77 and GCC}. | |
915 | ||
916 | Everyone except experienced @code{g77} users should | |
917 | see @ref{Invoking G77}. | |
918 | ||
919 | If you're acquainted with previous versions of @code{g77}, | |
5efcdab1 | 920 | you should see @ref{News,,News About GNU Fortran}. |
5ff904cd JL |
921 | Further, if you've actually used previous versions of @code{g77}, |
922 | especially if you've written or modified Fortran code to | |
923 | be compiled by previous versions of @code{g77}, you | |
924 | should see @ref{Changes}. | |
925 | ||
926 | If you intend to write or otherwise compile code that is | |
927 | not already strictly conforming ANSI FORTRAN 77---and this | |
928 | is probably everyone---you should see @ref{Language}. | |
929 | ||
930 | If you don't already have @code{g77} installed on your | |
931 | system, you must see @ref{Installation}. | |
932 | ||
933 | If you run into trouble getting Fortran code to compile, | |
934 | link, run, or work properly, you might find answers | |
935 | if you see @ref{Debugging and Interfacing}, | |
936 | see @ref{Collected Fortran Wisdom}, | |
937 | and see @ref{Trouble}. | |
938 | You might also find that the problems you are encountering | |
939 | are bugs in @code{g77}---see @ref{Bugs}, for information on | |
940 | reporting them, after reading the other material. | |
941 | ||
942 | If you need further help with @code{g77}, or with | |
943 | freely redistributable software in general, | |
944 | see @ref{Service}. | |
945 | ||
946 | If you would like to help the @code{g77} project, | |
947 | see @ref{Funding GNU Fortran}, for information on | |
948 | helping financially, and see @ref{Projects}, for information | |
949 | on helping in other ways. | |
950 | ||
951 | If you're generally curious about the future of | |
952 | @code{g77}, see @ref{Projects}. | |
953 | If you're curious about its past, | |
954 | see @ref{Contributors}, | |
955 | and see @ref{Funding GNU Fortran}. | |
956 | ||
957 | To see a few of the questions maintainers of @code{g77} have, | |
958 | and that you might be able to answer, | |
959 | see @ref{Open Questions}. | |
960 | ||
961 | @ifset USING | |
962 | @node What is GNU Fortran? | |
963 | @chapter What is GNU Fortran? | |
964 | @cindex concepts, basic | |
965 | @cindex basic concepts | |
966 | ||
967 | GNU Fortran, or @code{g77}, is designed initially as a free replacement | |
968 | for, or alternative to, the UNIX @code{f77} command. | |
969 | (Similarly, @code{gcc} is designed as a replacement | |
970 | for the UNIX @code{cc} command.) | |
971 | ||
972 | @code{g77} also is designed to fit in well with the other | |
973 | fine GNU compilers and tools. | |
974 | ||
975 | Sometimes these design goals conflict---in such cases, resolution | |
976 | often is made in favor of fitting in well with Project GNU. | |
977 | These cases are usually identified in the appropriate | |
978 | sections of this manual. | |
979 | ||
980 | @cindex compilers | |
981 | As compilers, @code{g77}, @code{gcc}, and @code{f77} | |
982 | share the following characteristics: | |
983 | ||
984 | @itemize @bullet | |
985 | @cindex source code | |
986 | @cindex file, source | |
987 | @cindex code, source | |
988 | @cindex source file | |
989 | @item | |
990 | They read a user's program, stored in a file and | |
991 | containing instructions written in the appropriate | |
992 | language (Fortran, C, and so on). | |
993 | This file contains @dfn{source code}. | |
994 | ||
995 | @cindex translation of user programs | |
996 | @cindex machine code | |
997 | @cindex code, machine | |
998 | @cindex mistakes | |
999 | @item | |
1000 | They translate the user's program into instructions | |
1001 | a computer can carry out more quickly than it takes | |
1002 | to translate the instructions in the first place. | |
1003 | These instructions are called @dfn{machine code}---code | |
1004 | designed to be efficiently translated and processed | |
1005 | by a machine such as a computer. | |
1006 | Humans usually aren't as good writing machine code | |
1007 | as they are at writing Fortran or C, because | |
1008 | it is easy to make tiny mistakes writing machine code. | |
1009 | When writing Fortran or C, it is easy | |
1010 | to make big mistakes. | |
1011 | ||
1012 | @cindex debugger | |
1013 | @cindex bugs, finding | |
26b9526e CB |
1014 | @cindex @code{gdb}, command |
1015 | @cindex commands, @code{gdb} | |
5ff904cd JL |
1016 | @item |
1017 | They provide information in the generated machine code | |
1018 | that can make it easier to find bugs in the program | |
1019 | (using a debugging tool, called a @dfn{debugger}, | |
1020 | such as @code{gdb}). | |
1021 | ||
1022 | @cindex libraries | |
1023 | @cindex linking | |
26b9526e CB |
1024 | @cindex @code{ld} command |
1025 | @cindex commands, @code{ld} | |
5ff904cd JL |
1026 | @item |
1027 | They locate and gather machine code already generated | |
1028 | to perform actions requested by statements in | |
1029 | the user's program. | |
1030 | This machine code is organized | |
1031 | into @dfn{libraries} and is located and gathered | |
1032 | during the @dfn{link} phase of the compilation | |
1033 | process. | |
1034 | (Linking often is thought of as a separate | |
1035 | step, because it can be directly invoked via the | |
1036 | @code{ld} command. | |
1037 | However, the @code{g77} and @code{gcc} | |
1038 | commands, as with most compiler commands, automatically | |
1039 | perform the linking step by calling on @code{ld} | |
1040 | directly, unless asked to not do so by the user.) | |
1041 | ||
1042 | @cindex language, incorrect use of | |
1043 | @cindex incorrect use of language | |
1044 | @item | |
1045 | They attempt to diagnose cases where the user's | |
1046 | program contains incorrect usages of the language. | |
1047 | The @dfn{diagnostics} produced by the compiler | |
1048 | indicate the problem and the location in the user's | |
1049 | source file where the problem was first noticed. | |
1050 | The user can use this information to locate and | |
1051 | fix the problem. | |
1052 | @cindex diagnostics, incorrect | |
1053 | @cindex incorrect diagnostics | |
1054 | @cindex error messages, incorrect | |
1055 | @cindex incorrect error messages | |
1056 | (Sometimes an incorrect usage | |
1057 | of the language leads to a situation where the | |
1058 | compiler can no longer make any sense of what | |
1059 | follows---while a human might be able to---and | |
1060 | thus ends up complaining about many ``problems'' | |
1061 | it encounters that, in fact, stem from just one | |
1062 | problem, usually the first one reported.) | |
1063 | ||
1064 | @cindex warnings | |
1065 | @cindex questionable instructions | |
1066 | @item | |
1067 | They attempt to diagnose cases where the user's | |
1068 | program contains a correct usage of the language, | |
1069 | but instructs the computer to do something questionable. | |
1070 | These diagnostics often are in the form of @dfn{warnings}, | |
1071 | instead of the @dfn{errors} that indicate incorrect | |
1072 | usage of the language. | |
1073 | @end itemize | |
1074 | ||
1075 | How these actions are performed is generally under the | |
1076 | control of the user. | |
1077 | Using command-line options, the user can specify | |
1078 | how persnickety the compiler is to be regarding | |
1079 | the program (whether to diagnose questionable usage | |
1080 | of the language), how much time to spend making | |
1081 | the generated machine code run faster, and so on. | |
1082 | ||
1083 | @cindex components of g77 | |
26b9526e | 1084 | @cindex @code{g77}, components of |
5ff904cd JL |
1085 | @code{g77} consists of several components: |
1086 | ||
26b9526e CB |
1087 | @cindex @code{gcc}, command |
1088 | @cindex commands, @code{gcc} | |
5ff904cd JL |
1089 | @itemize @bullet |
1090 | @item | |
1091 | A modified version of the @code{gcc} command, which also might be | |
1092 | installed as the system's @code{cc} command. | |
1093 | (In many cases, @code{cc} refers to the | |
1094 | system's ``native'' C compiler, which | |
1095 | might be a non-GNU compiler, or an older version | |
1096 | of @code{gcc} considered more stable or that is | |
1097 | used to build the operating system kernel.) | |
1098 | ||
26b9526e CB |
1099 | @cindex @code{g77}, command |
1100 | @cindex commands, @code{g77} | |
5ff904cd JL |
1101 | @item |
1102 | The @code{g77} command itself, which also might be installed as the | |
1103 | system's @code{f77} command. | |
1104 | ||
95a1b676 | 1105 | @cindex libg2c library |
5ff904cd JL |
1106 | @cindex libf2c library |
1107 | @cindex libraries, libf2c | |
95a1b676 | 1108 | @cindex libraries, libg2c |
26b9526e | 1109 | @cindex run-time, library |
5ff904cd | 1110 | @item |
95a1b676 | 1111 | The @code{libg2c} run-time library. |
5ff904cd JL |
1112 | This library contains the machine code needed to support |
1113 | capabilities of the Fortran language that are not directly | |
1114 | provided by the machine code generated by the @code{g77} | |
1115 | compilation phase. | |
1116 | ||
95a1b676 CB |
1117 | @code{libg2c} is just the unique name @code{g77} gives |
1118 | to its version of @code{libf2c} to distinguish it from | |
1119 | any copy of @code{libf2c} installed from @code{f2c} | |
1120 | (or versions of @code{g77} that built @code{libf2c} under | |
1121 | that same name) | |
1122 | on the system. | |
1123 | ||
1a057f3b DL |
1124 | The maintainer of @code{libf2c} currently is |
1125 | @email{dmg@@bell-labs.com}. | |
1126 | ||
26b9526e CB |
1127 | @cindex @code{f771}, program |
1128 | @cindex programs, @code{f771} | |
5ff904cd | 1129 | @cindex assembler |
26b9526e CB |
1130 | @cindex @code{as} command |
1131 | @cindex commands, @code{as} | |
5ff904cd JL |
1132 | @cindex assembly code |
1133 | @cindex code, assembly | |
1134 | @item | |
1135 | The compiler itself, internally named @code{f771}. | |
1136 | ||
1137 | Note that @code{f771} does not generate machine code directly---it | |
1138 | generates @dfn{assembly code} that is a more readable form | |
1139 | of machine code, leaving the conversion to actual machine code | |
1140 | to an @dfn{assembler}, usually named @code{as}. | |
1141 | @end itemize | |
1142 | ||
1143 | @code{gcc} is often thought of as ``the C compiler'' only, | |
1144 | but it does more than that. | |
1145 | Based on command-line options and the names given for files | |
1146 | on the command line, @code{gcc} determines which actions to perform, including | |
1147 | preprocessing, compiling (in a variety of possible languages), assembling, | |
1148 | and linking. | |
1149 | ||
1150 | @cindex driver, gcc command as | |
26b9526e | 1151 | @cindex @code{gcc}, command as driver |
5ff904cd JL |
1152 | @cindex executable file |
1153 | @cindex files, executable | |
1154 | @cindex cc1 program | |
1155 | @cindex programs, cc1 | |
1156 | @cindex preprocessor | |
1157 | @cindex cpp program | |
1158 | @cindex programs, cpp | |
1159 | For example, the command @samp{gcc foo.c} @dfn{drives} the file | |
1160 | @file{foo.c} through the preprocessor @code{cpp}, then | |
1161 | the C compiler (internally named | |
1162 | @code{cc1}), then the assembler (usually @code{as}), then the linker | |
1163 | (@code{ld}), producing an executable program named @file{a.out} (on | |
1164 | UNIX systems). | |
1165 | ||
1166 | @cindex cc1plus program | |
1167 | @cindex programs, cc1plus | |
1168 | As another example, the command @samp{gcc foo.cc} would do much the same as | |
1169 | @samp{gcc foo.c}, but instead of using the C compiler named @code{cc1}, | |
1170 | @code{gcc} would use the C++ compiler (named @code{cc1plus}). | |
1171 | ||
26b9526e CB |
1172 | @cindex @code{f771}, program |
1173 | @cindex programs, @code{f771} | |
5ff904cd JL |
1174 | In a GNU Fortran installation, @code{gcc} recognizes Fortran source |
1175 | files by name just like it does C and C++ source files. | |
1176 | It knows to use the Fortran compiler named @code{f771}, instead of | |
1177 | @code{cc1} or @code{cc1plus}, to compile Fortran files. | |
1178 | ||
26b9526e | 1179 | @cindex @code{gcc}, not recognizing Fortran source |
5ff904cd JL |
1180 | @cindex unrecognized file format |
1181 | @cindex file format not recognized | |
1182 | Non-Fortran-related operation of @code{gcc} is generally | |
1183 | unaffected by installing the GNU Fortran version of @code{gcc}. | |
1184 | However, without the installed version of @code{gcc} being the | |
1185 | GNU Fortran version, @code{gcc} will not be able to compile | |
1186 | and link Fortran programs---and since @code{g77} uses @code{gcc} | |
1187 | to do most of the actual work, neither will @code{g77}! | |
1188 | ||
26b9526e CB |
1189 | @cindex @code{g77}, command |
1190 | @cindex commands, @code{g77} | |
5ff904cd JL |
1191 | The @code{g77} command is essentially just a front-end for |
1192 | the @code{gcc} command. | |
1193 | Fortran users will normally use @code{g77} instead of @code{gcc}, | |
1194 | because @code{g77} | |
1195 | knows how to specify the libraries needed to link with Fortran programs | |
95a1b676 | 1196 | (@code{libg2c} and @code{lm}). |
5ff904cd JL |
1197 | @code{g77} can still compile and link programs and |
1198 | source files written in other languages, just like @code{gcc}. | |
1199 | ||
1200 | @cindex printing version information | |
1201 | @cindex version information, printing | |
1202 | The command @samp{g77 -v} is a quick | |
1203 | way to display lots of version information for the various programs | |
1204 | used to compile a typical preprocessed Fortran source file---this | |
1205 | produces much more output than @samp{gcc -v} currently does. | |
1206 | (If it produces an error message near the end of the output---diagnostics | |
1207 | from the linker, usually @code{ld}---you might | |
1208 | have an out-of-date @code{libf2c} that improperly handles | |
95a1b676 | 1209 | complex arithmetic.) |
5ff904cd JL |
1210 | In the output of this command, the line beginning @samp{GNU Fortran Front |
1211 | End} identifies the version number of GNU Fortran; immediately | |
1212 | preceding that line is a line identifying the version of @code{gcc} | |
1213 | with which that version of @code{g77} was built. | |
1214 | ||
1215 | @cindex libf2c library | |
1216 | @cindex libraries, libf2c | |
1217 | The @code{libf2c} library is distributed with GNU Fortran for | |
1218 | the convenience of its users, but is not part of GNU Fortran. | |
1219 | It contains the procedures | |
1220 | needed by Fortran programs while they are running. | |
1221 | ||
1222 | @cindex in-line code | |
1223 | @cindex code, in-line | |
1224 | For example, while code generated by @code{g77} is likely | |
1225 | to do additions, subtractions, and multiplications @dfn{in line}---in | |
1226 | the actual compiled code---it is not likely to do trigonometric | |
1227 | functions this way. | |
1228 | ||
1229 | Instead, operations like trigonometric | |
1230 | functions are compiled by the @code{f771} compiler | |
1231 | (invoked by @code{g77} when compiling Fortran code) into machine | |
95a1b676 CB |
1232 | code that, when run, calls on functions in @code{libg2c}, so |
1233 | @code{libg2c} must be linked with almost every useful program | |
5ff904cd JL |
1234 | having any component compiled by GNU Fortran. |
1235 | (As mentioned above, the @code{g77} command takes | |
1236 | care of all this for you.) | |
1237 | ||
1238 | The @code{f771} program represents most of what is unique to GNU Fortran. | |
95a1b676 CB |
1239 | While much of the @code{libg2c} component comes from |
1240 | the @code{libf2c} component of @code{f2c}, | |
5ff904cd JL |
1241 | a free Fortran-to-C converter distributed by Bellcore (AT&T), |
1242 | plus @code{libU77}, provided by Dave Love, | |
1243 | and the @code{g77} command is just a small front-end to @code{gcc}, | |
1244 | @code{f771} is a combination of two rather | |
1245 | large chunks of code. | |
1246 | ||
1247 | @cindex GNU Back End (GBE) | |
1248 | @cindex GBE | |
26b9526e | 1249 | @cindex @code{gcc}, back end |
5ff904cd JL |
1250 | @cindex back end, gcc |
1251 | @cindex code generator | |
1252 | One chunk is the so-called @dfn{GNU Back End}, or GBE, | |
1253 | which knows how to generate fast code for a wide variety of processors. | |
1254 | The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1}, | |
1255 | @code{cc1plus}, and @code{f771}, plus others. | |
1256 | Often the GBE is referred to as the ``gcc back end'' or | |
1257 | even just ``gcc''---in this manual, the term GBE is used | |
1258 | whenever the distinction is important. | |
1259 | ||
1260 | @cindex GNU Fortran Front End (FFE) | |
1261 | @cindex FFE | |
26b9526e | 1262 | @cindex @code{g77}, front end |
75e8000e | 1263 | @cindex front end, @code{g77} |
5ff904cd JL |
1264 | The other chunk of @code{f771} is the |
1265 | majority of what is unique about GNU Fortran---the code that knows how | |
1266 | to interpret Fortran programs to determine what they are intending to | |
1267 | do, and then communicate that knowledge to the GBE for actual compilation | |
1268 | of those programs. | |
1269 | This chunk is called the @dfn{Fortran Front End} (FFE). | |
1270 | The @code{cc1} and @code{cc1plus} programs have their own front ends, | |
1271 | for the C and C++ languages, respectively. | |
1272 | These fronts ends are responsible for diagnosing | |
1273 | incorrect usage of their respective languages by the | |
1274 | programs the process, and are responsible for most of | |
1275 | the warnings about questionable constructs as well. | |
1276 | (The GBE handles producing some warnings, like those | |
1277 | concerning possible references to undefined variables.) | |
1278 | ||
1279 | Because so much is shared among the compilers for various languages, | |
1280 | much of the behavior and many of the user-selectable options for these | |
1281 | compilers are similar. | |
1282 | For example, diagnostics (error messages and | |
1283 | warnings) are similar in appearance; command-line | |
1284 | options like @samp{-Wall} have generally similar effects; and the quality | |
1285 | of generated code (in terms of speed and size) is roughly similar | |
1286 | (since that work is done by the shared GBE). | |
1287 | ||
1288 | @node G77 and GCC | |
1289 | @chapter Compile Fortran, C, or Other Programs | |
1290 | @cindex compiling programs | |
1291 | @cindex programs, compiling | |
1292 | ||
26b9526e CB |
1293 | @cindex @code{gcc}, command |
1294 | @cindex commands, @code{gcc} | |
5ff904cd JL |
1295 | A GNU Fortran installation includes a modified version of the @code{gcc} |
1296 | command. | |
1297 | ||
1298 | In a non-Fortran installation, @code{gcc} recognizes C, C++, | |
1299 | and Objective-C source files. | |
1300 | ||
1301 | In a GNU Fortran installation, @code{gcc} also recognizes Fortran source | |
1302 | files and accepts Fortran-specific command-line options, plus some | |
1303 | command-line options that are designed to cater to Fortran users | |
1304 | but apply to other languages as well. | |
1305 | ||
1306 | @xref{G++ and GCC,,Compile C; C++; or Objective-C,gcc,Using and Porting GNU CC}, | |
1307 | for information on the way different languages are handled | |
1308 | by the GNU CC compiler (@code{gcc}). | |
1309 | ||
26b9526e CB |
1310 | @cindex @code{g77}, command |
1311 | @cindex commands, @code{g77} | |
5ff904cd JL |
1312 | Also provided as part of GNU Fortran is the @code{g77} command. |
1313 | The @code{g77} command is designed to make compiling and linking Fortran | |
1314 | programs somewhat easier than when using the @code{gcc} command for | |
1315 | these tasks. | |
1316 | It does this by analyzing the command line somewhat and changing it | |
1317 | appropriately before submitting it to the @code{gcc} command. | |
1318 | ||
1319 | @cindex -v option | |
26b9526e | 1320 | @cindex @code{g77} options, -v |
5ff904cd | 1321 | @cindex options, -v |
5ff904cd JL |
1322 | Use the @samp{-v} option with @code{g77} |
1323 | to see what is going on---the first line of output is the invocation | |
1324 | of the @code{gcc} command. | |
5ff904cd JL |
1325 | |
1326 | @node Invoking G77 | |
1327 | @chapter GNU Fortran Command Options | |
1328 | @cindex GNU Fortran command options | |
1329 | @cindex command options | |
1330 | @cindex options, GNU Fortran command | |
1331 | ||
1332 | The @code{g77} command supports all the options supported by the | |
1333 | @code{gcc} command. | |
1334 | @xref{Invoking GCC,,GNU CC Command Options,gcc,Using and Porting GNU CC}, | |
1335 | for information | |
1336 | on the non-Fortran-specific aspects of the @code{gcc} command (and, | |
1337 | therefore, the @code{g77} command). | |
1338 | ||
5ff904cd JL |
1339 | @cindex options, negative forms |
1340 | @cindex negative forms of options | |
95a1b676 CB |
1341 | All @code{gcc} and @code{g77} options |
1342 | are accepted both by @code{g77} and by @code{gcc} | |
1343 | (as well as any other drivers built at the same time, | |
1344 | such as @code{g++}), | |
1345 | since adding @code{g77} to the @code{gcc} distribution | |
1346 | enables acceptance of @code{g77}-specific options | |
1347 | by all of the relevant drivers. | |
1348 | ||
5ff904cd JL |
1349 | In some cases, options have positive and negative forms; |
1350 | the negative form of @samp{-ffoo} would be @samp{-fno-foo}. | |
1351 | This manual documents only one of these two forms, whichever | |
1352 | one is not the default. | |
1353 | ||
1354 | @menu | |
1355 | * Option Summary:: Brief list of all @code{g77} options, | |
1356 | without explanations. | |
1357 | * Overall Options:: Controlling the kind of output: | |
1358 | an executable, object files, assembler files, | |
1359 | or preprocessed source. | |
1360 | * Shorthand Options:: Options that are shorthand for other options. | |
1361 | * Fortran Dialect Options:: Controlling the variant of Fortran language | |
1362 | compiled. | |
1363 | * Warning Options:: How picky should the compiler be? | |
1364 | * Debugging Options:: Symbol tables, measurements, and debugging dumps. | |
1365 | * Optimize Options:: How much optimization? | |
1366 | * Preprocessor Options:: Controlling header files and macro definitions. | |
1367 | Also, getting dependency information for Make. | |
1368 | * Directory Options:: Where to find header files and libraries. | |
1369 | Where to find the compiler executable files. | |
1370 | * Code Gen Options:: Specifying conventions for function calls, data layout | |
1371 | and register usage. | |
1372 | * Environment Variables:: Env vars that affect GNU Fortran. | |
1373 | @end menu | |
1374 | ||
1375 | @node Option Summary | |
1376 | @section Option Summary | |
1377 | ||
1378 | Here is a summary of all the options specific to GNU Fortran, grouped | |
1379 | by type. Explanations are in the following sections. | |
1380 | ||
1381 | @table @emph | |
1382 | @item Overall Options | |
1383 | @xref{Overall Options,,Options Controlling the Kind of Output}. | |
1384 | @smallexample | |
95a1b676 | 1385 | -fversion -fset-g77-defaults -fno-silent |
5ff904cd JL |
1386 | @end smallexample |
1387 | ||
1388 | @item Shorthand Options | |
1389 | @xref{Shorthand Options}. | |
1390 | @smallexample | |
4e6a1440 | 1391 | -ff66 -fno-f66 -ff77 -fno-f77 -fno-ugly |
5ff904cd JL |
1392 | @end smallexample |
1393 | ||
1394 | @item Fortran Language Options | |
1395 | @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}. | |
1396 | @smallexample | |
1397 | -ffree-form -fno-fixed-form -ff90 | |
1398 | -fvxt -fdollar-ok -fno-backslash | |
1399 | -fno-ugly-args -fno-ugly-assign -fno-ugly-assumed | |
1400 | -fugly-comma -fugly-complex -fugly-init -fugly-logint | |
1401 | -fonetrip -ftypeless-boz | |
1402 | -fintrin-case-initcap -fintrin-case-upper | |
1403 | -fintrin-case-lower -fintrin-case-any | |
1404 | -fmatch-case-initcap -fmatch-case-upper | |
1405 | -fmatch-case-lower -fmatch-case-any | |
1406 | -fsource-case-upper -fsource-case-lower -fsource-case-preserve | |
1407 | -fsymbol-case-initcap -fsymbol-case-upper | |
1408 | -fsymbol-case-lower -fsymbol-case-any | |
1409 | -fcase-strict-upper -fcase-strict-lower | |
1410 | -fcase-initcap -fcase-upper -fcase-lower -fcase-preserve | |
1411 | -ff2c-intrinsics-delete -ff2c-intrinsics-hide | |
1412 | -ff2c-intrinsics-disable -ff2c-intrinsics-enable | |
56a0044b JL |
1413 | -fbadu77-intrinsics-delete -fbadu77-intrinsics-hide |
1414 | -fbadu77-intrinsics-disable -fbadu77-intrinsics-enable | |
5ff904cd JL |
1415 | -ff90-intrinsics-delete -ff90-intrinsics-hide |
1416 | -ff90-intrinsics-disable -ff90-intrinsics-enable | |
1417 | -fgnu-intrinsics-delete -fgnu-intrinsics-hide | |
1418 | -fgnu-intrinsics-disable -fgnu-intrinsics-enable | |
1419 | -fmil-intrinsics-delete -fmil-intrinsics-hide | |
1420 | -fmil-intrinsics-disable -fmil-intrinsics-enable | |
1421 | -funix-intrinsics-delete -funix-intrinsics-hide | |
1422 | -funix-intrinsics-disable -funix-intrinsics-enable | |
1423 | -fvxt-intrinsics-delete -fvxt-intrinsics-hide | |
1424 | -fvxt-intrinsics-disable -fvxt-intrinsics-enable | |
1425 | -ffixed-line-length-@var{n} -ffixed-line-length-none | |
1426 | @end smallexample | |
1427 | ||
1428 | @item Warning Options | |
1429 | @xref{Warning Options,,Options to Request or Suppress Warnings}. | |
1430 | @smallexample | |
1431 | -fsyntax-only -pedantic -pedantic-errors -fpedantic | |
1432 | -w -Wno-globals -Wimplicit -Wunused -Wuninitialized | |
1433 | -Wall -Wsurprising | |
1434 | -Werror -W | |
1435 | @end smallexample | |
1436 | ||
1437 | @item Debugging Options | |
1438 | @xref{Debugging Options,,Options for Debugging Your Program or GCC}. | |
1439 | @smallexample | |
1440 | -g | |
1441 | @end smallexample | |
1442 | ||
1443 | @item Optimization Options | |
1444 | @xref{Optimize Options,,Options that Control Optimization}. | |
1445 | @smallexample | |
1446 | -malign-double | |
1447 | -ffloat-store -fforce-mem -fforce-addr -fno-inline | |
1448 | -ffast-math -fstrength-reduce -frerun-cse-after-loop | |
1449 | -fexpensive-optimizations -fdelayed-branch | |
1450 | -fschedule-insns -fschedule-insn2 -fcaller-saves | |
1451 | -funroll-loops -funroll-all-loops | |
1452 | -fno-move-all-movables -fno-reduce-all-givs | |
1453 | -fno-rerun-loop-opt | |
1454 | @end smallexample | |
1455 | ||
1456 | @item Directory Options | |
1457 | @xref{Directory Options,,Options for Directory Search}. | |
1458 | @smallexample | |
1459 | -I@var{dir} -I- | |
1460 | @end smallexample | |
1461 | ||
1462 | @item Code Generation Options | |
1463 | @xref{Code Gen Options,,Options for Code Generation Conventions}. | |
1464 | @smallexample | |
1465 | -fno-automatic -finit-local-zero -fno-f2c | |
1466 | -ff2c-library -fno-underscoring -fno-ident | |
1467 | -fpcc-struct-return -freg-struct-return | |
1468 | -fshort-double -fno-common -fpack-struct | |
1469 | -fzeros -fno-second-underscore | |
d8955e17 | 1470 | -fdebug-kludge -femulate-complex |
5ff904cd JL |
1471 | -falias-check -fargument-alias |
1472 | -fargument-noalias -fno-argument-noalias-global | |
1473 | -fno-globals | |
6b55276e | 1474 | -fsubscript-check -ff2c-subscript-check |
5ff904cd JL |
1475 | @end smallexample |
1476 | @end table | |
1477 | ||
1478 | @menu | |
1479 | * Overall Options:: Controlling the kind of output: | |
1480 | an executable, object files, assembler files, | |
1481 | or preprocessed source. | |
1482 | * Shorthand Options:: Options that are shorthand for other options. | |
1483 | * Fortran Dialect Options:: Controlling the variant of Fortran language | |
1484 | compiled. | |
1485 | * Warning Options:: How picky should the compiler be? | |
1486 | * Debugging Options:: Symbol tables, measurements, and debugging dumps. | |
1487 | * Optimize Options:: How much optimization? | |
1488 | * Preprocessor Options:: Controlling header files and macro definitions. | |
1489 | Also, getting dependency information for Make. | |
1490 | * Directory Options:: Where to find header files and libraries. | |
1491 | Where to find the compiler executable files. | |
1492 | * Code Gen Options:: Specifying conventions for function calls, data layout | |
1493 | and register usage. | |
1494 | @end menu | |
1495 | ||
1496 | @node Overall Options | |
1497 | @section Options Controlling the Kind of Output | |
1498 | @cindex overall options | |
1499 | @cindex options, overall | |
1500 | ||
1501 | Compilation can involve as many as four stages: preprocessing, code | |
1502 | generation (often what is really meant by the term ``compilation''), | |
1503 | assembly, and linking, always in that order. The first three | |
1504 | stages apply to an individual source file, and end by producing an | |
1505 | object file; linking combines all the object files (those newly | |
1506 | compiled, and those specified as input) into an executable file. | |
1507 | ||
1508 | @cindex file name suffix | |
1509 | @cindex suffixes, file name | |
1510 | @cindex file name extension | |
1511 | @cindex extensions, file name | |
1512 | @cindex file type | |
1513 | @cindex types, file | |
1514 | For any given input file, the file name suffix determines what kind of | |
1515 | program is contained in the file---that is, the language in which the | |
1516 | program is written is generally indicated by the suffix. | |
1517 | Suffixes specific to GNU Fortran are listed below. | |
1518 | @xref{Overall Options,,gcc,Using and Porting GNU CC}, for | |
1519 | information on suffixes recognized by GNU CC. | |
1520 | ||
1521 | @table @code | |
d1d80a92 CB |
1522 | @cindex .f filename suffix |
1523 | @cindex .for filename suffix | |
1524 | @cindex .FOR filename suffix | |
5ff904cd JL |
1525 | @item @var{file}.f |
1526 | @item @var{file}.for | |
d1d80a92 | 1527 | @item @var{file}.FOR |
5ff904cd JL |
1528 | Fortran source code that should not be preprocessed. |
1529 | ||
1530 | Such source code cannot contain any preprocessor directives, such | |
1531 | as @code{#include}, @code{#define}, @code{#if}, and so on. | |
1532 | ||
4e6a1440 | 1533 | You can force @samp{.f} files to be preprocessed by @code{cpp} by using |
811cabee CB |
1534 | @samp{-x f77-cpp-input}. |
1535 | @xref{LEX}. | |
58dd1c34 | 1536 | |
5ff904cd JL |
1537 | @cindex preprocessor |
1538 | @cindex C preprocessor | |
1539 | @cindex cpp preprocessor | |
1540 | @cindex Fortran preprocessor | |
1541 | @cindex cpp program | |
1542 | @cindex programs, cpp | |
1543 | @cindex .F filename suffix | |
1544 | @cindex .fpp filename suffix | |
d1d80a92 | 1545 | @cindex .FPP filename suffix |
5ff904cd JL |
1546 | @item @var{file}.F |
1547 | @item @var{file}.fpp | |
d1d80a92 | 1548 | @item @var{file}.FPP |
5ff904cd JL |
1549 | Fortran source code that must be preprocessed (by the C preprocessor |
1550 | @code{cpp}, which is part of GNU CC). | |
1551 | ||
1552 | Note that preprocessing is not extended to the contents of | |
1553 | files included by the @code{INCLUDE} directive---the @code{#include} | |
1554 | preprocessor directive must be used instead. | |
1555 | ||
1556 | @cindex Ratfor preprocessor | |
26b9526e CB |
1557 | @cindex programs, @code{ratfor} |
1558 | @cindex @samp{.r} filename suffix | |
1559 | @cindex @code{ratfor} | |
5ff904cd JL |
1560 | @item @var{file}.r |
1561 | Ratfor source code, which must be preprocessed by the @code{ratfor} | |
58dd1c34 DL |
1562 | command, which is available separately (as it is not yet part of the GNU |
1563 | Fortran distribution). | |
1564 | One version in Fortran, adapted for use with @code{g77}, is at | |
1565 | @uref{ftp://members.aol.com/n8tm/rat7.uue} (of uncertain copyright | |
1566 | status). Another, public domain version in C is at | |
1567 | @uref{http://sepwww.stanford.edu/sep/prof/ratfor.shar.2}. | |
5ff904cd JL |
1568 | @end table |
1569 | ||
1570 | UNIX users typically use the @file{@var{file}.f} and @file{@var{file}.F} | |
1571 | nomenclature. | |
1572 | Users of other operating systems, especially those that cannot | |
1573 | distinguish upper-case | |
1574 | letters from lower-case letters in their file names, typically use | |
1575 | the @file{@var{file}.for} and @file{@var{file}.fpp} nomenclature. | |
1576 | ||
1577 | @cindex #define | |
1578 | @cindex #include | |
1579 | @cindex #if | |
1580 | Use of the preprocessor @code{cpp} allows use of C-like | |
1581 | constructs such as @code{#define} and @code{#include}, but can | |
1582 | lead to unexpected, even mistaken, results due to Fortran's source file | |
1583 | format. | |
1584 | It is recommended that use of the C preprocessor | |
1585 | be limited to @code{#include} and, in | |
1586 | conjunction with @code{#define}, only @code{#if} and related directives, | |
1587 | thus avoiding in-line macro expansion entirely. | |
1588 | This recommendation applies especially | |
1589 | when using the traditional fixed source form. | |
1590 | With free source form, | |
1591 | fewer unexpected transformations are likely to happen, but use of | |
1592 | constructs such as Hollerith and character constants can nevertheless | |
1593 | present problems, especially when these are continued across multiple | |
1594 | source lines. | |
1595 | These problems result, primarily, from differences between the way | |
1596 | such constants are interpreted by the C preprocessor and by a Fortran | |
1597 | compiler. | |
1598 | ||
795232f7 JL |
1599 | Another example of a problem that results from using the C preprocessor |
1600 | is that a Fortran comment line that happens to contain any | |
1601 | characters ``interesting'' to the C preprocessor, | |
1602 | such as a backslash at the end of the line, | |
1603 | is not recognized by the preprocessor as a comment line, | |
1604 | so instead of being passed through ``raw'', | |
1605 | the line is edited according to the rules for the preprocessor. | |
1606 | For example, the backslash at the end of the line is removed, | |
1607 | along with the subsequent newline, resulting in the next | |
1608 | line being effectively commented out---unfortunate if that | |
1609 | line is a non-comment line of important code! | |
1610 | ||
5ff904cd | 1611 | @emph{Note:} The @samp{-traditional} and @samp{-undef} flags are supplied |
c5a951a8 | 1612 | to @code{cpp} by default, to help avoid unpleasant surprises. |
5ff904cd JL |
1613 | @xref{Preprocessor Options,,Options Controlling the Preprocessor, |
1614 | gcc,Using and Porting GNU CC}. | |
1615 | This means that ANSI C preprocessor features (such as the @samp{#} | |
1616 | operator) aren't available, and only variables in the C reserved | |
1617 | namespace (generally, names with a leading underscore) are liable to | |
1618 | substitution by C predefines. | |
1619 | Thus, if you want to do system-specific | |
1620 | tests, use, for example, @samp{#ifdef __linux__} rather than @samp{#ifdef linux}. | |
1621 | Use the @samp{-v} option to see exactly how the preprocessor is invoked. | |
1622 | ||
c5a951a8 DL |
1623 | @cindex /* |
1624 | Unfortunately, the @samp{-traditional} flag will not avoid an error from | |
1625 | anything that @code{cpp} sees as an unterminated C comment, such as: | |
1626 | @smallexample | |
1627 | C Some Fortran compilers accept /* as starting | |
1628 | C an inline comment. | |
1629 | @end smallexample | |
1630 | @xref{Trailing Comment}. | |
1631 | ||
5ff904cd JL |
1632 | The following options that affect overall processing are recognized |
1633 | by the @code{g77} and @code{gcc} commands in a GNU Fortran installation: | |
1634 | ||
1635 | @table @code | |
5ff904cd JL |
1636 | @cindex -fversion option |
1637 | @cindex options, -fversion | |
1638 | @cindex printing version information | |
1639 | @cindex version information, printing | |
d1c32ce1 CB |
1640 | @cindex consistency checks |
1641 | @cindex internal consistency checks | |
1642 | @cindex checks, of internal consistency | |
5ff904cd JL |
1643 | @item -fversion |
1644 | Ensure that the @code{g77}-specific version of the compiler phase is reported, | |
d1c32ce1 CB |
1645 | if run, |
1646 | and, starting in @code{egcs} version 1.1, | |
1647 | that internal consistency checks in the @file{f771} program are run. | |
1648 | ||
1649 | This option is supplied automatically when @samp{-v} or @samp{--verbose} | |
5ff904cd | 1650 | is specified as a command-line option for @code{g77} or @code{gcc} |
d1c32ce1 | 1651 | and when the resulting commands compile Fortran source files. |
5ff904cd JL |
1652 | |
1653 | @cindex -fset-g77-defaults option | |
1654 | @cindex options, -fset-g77-defaults | |
1655 | @item -fset-g77-defaults | |
9a59ff4f CB |
1656 | @emph{Version info:} |
1657 | This option is obsolete in @code{egcs} | |
1658 | as of version 1.1. | |
d1c32ce1 | 1659 | The effect is instead achieved |
4e6a1440 | 1660 | by the @code{lang_init_options} routine |
d1c32ce1 | 1661 | in @file{egcs/gcc/f/com.c}. |
9a59ff4f | 1662 | |
d1c32ce1 CB |
1663 | @cindex consistency checks |
1664 | @cindex internal consistency checks | |
1665 | @cindex checks, of internal consistency | |
5ff904cd JL |
1666 | Set up whatever @code{gcc} options are to apply to Fortran |
1667 | compilations, and avoid running internal consistency checks | |
1668 | that might take some time. | |
1669 | ||
5ff904cd JL |
1670 | This option is supplied automatically when compiling Fortran code |
1671 | via the @code{g77} or @code{gcc} command. | |
1672 | The description of this option is provided so that users seeing | |
1673 | it in the output of, say, @samp{g77 -v} understand why it is | |
1674 | there. | |
1675 | ||
1676 | @cindex modifying g77 | |
1677 | @cindex code, modifying | |
1678 | Also, developers who run @code{f771} directly might want to specify it | |
1679 | by hand to get the same defaults as they would running @code{f771} | |
1680 | via @code{g77} or @code{gcc}. | |
1681 | However, such developers should, after linking a new @code{f771} | |
1682 | executable, invoke it without this option once, | |
1683 | e.g. via @kbd{./f771 -quiet < /dev/null}, | |
1684 | to ensure that they have not introduced any | |
1685 | internal inconsistencies (such as in the table of | |
1686 | intrinsics) before proceeding---@code{g77} will crash | |
1687 | with a diagnostic if it detects an inconsistency. | |
1688 | ||
1689 | @cindex -fno-silent option | |
1690 | @cindex options, -fno-silent | |
26b9526e CB |
1691 | @cindex f2c compatibility |
1692 | @cindex compatibility, f2c | |
5ff904cd | 1693 | @cindex status, compilation |
26b9526e | 1694 | @cindex compilation, status |
5ff904cd JL |
1695 | @cindex reporting compilation status |
1696 | @cindex printing compilation status | |
1697 | @item -fno-silent | |
1698 | Print (to @code{stderr}) the names of the program units as | |
1699 | they are compiled, in a form similar to that used by popular | |
1700 | UNIX @code{f77} implementations and @code{f2c}. | |
1701 | @end table | |
1702 | ||
1703 | @xref{Overall Options,,Options Controlling the Kind of Output, | |
1704 | gcc,Using and Porting GNU CC}, for information | |
1705 | on more options that control the overall operation of the @code{gcc} command | |
1706 | (and, by extension, the @code{g77} command). | |
1707 | ||
1708 | @node Shorthand Options | |
1709 | @section Shorthand Options | |
1710 | @cindex shorthand options | |
1711 | @cindex options, shorthand | |
1712 | @cindex macro options | |
1713 | @cindex options, macro | |
1714 | ||
1715 | The following options serve as ``shorthand'' | |
1716 | for other options accepted by the compiler: | |
1717 | ||
1718 | @table @code | |
1719 | @cindex -fugly option | |
1720 | @cindex options, -fugly | |
1721 | @item -fugly | |
1722 | @cindex ugly features | |
1723 | @cindex features, ugly | |
4e6a1440 CB |
1724 | @emph{Note:} This option is no longer supported. |
1725 | The information, below, is provided to aid | |
1726 | in the conversion of old scripts. | |
1727 | ||
5ff904cd JL |
1728 | Specify that certain ``ugly'' constructs are to be quietly accepted. |
1729 | Same as: | |
1730 | ||
1731 | @smallexample | |
1732 | -fugly-args -fugly-assign -fugly-assumed | |
1733 | -fugly-comma -fugly-complex -fugly-init | |
1734 | -fugly-logint | |
1735 | @end smallexample | |
1736 | ||
1737 | These constructs are considered inappropriate to use in new | |
1738 | or well-maintained portable Fortran code, but widely used | |
1739 | in old code. | |
1740 | @xref{Distensions}, for more information. | |
1741 | ||
5ff904cd JL |
1742 | @cindex -fno-ugly option |
1743 | @cindex options, -fno-ugly | |
1744 | @item -fno-ugly | |
1745 | @cindex ugly features | |
1746 | @cindex features, ugly | |
1747 | Specify that all ``ugly'' constructs are to be noisily rejected. | |
1748 | Same as: | |
1749 | ||
1750 | @smallexample | |
1751 | -fno-ugly-args -fno-ugly-assign -fno-ugly-assumed | |
1752 | -fno-ugly-comma -fno-ugly-complex -fno-ugly-init | |
1753 | -fno-ugly-logint | |
1754 | @end smallexample | |
1755 | ||
1756 | @xref{Distensions}, for more information. | |
1757 | ||
1758 | @cindex -ff66 option | |
1759 | @cindex options, -ff66 | |
1760 | @item -ff66 | |
1761 | @cindex FORTRAN 66 | |
1762 | @cindex compatibility, FORTRAN 66 | |
1763 | Specify that the program is written in idiomatic FORTRAN 66. | |
1764 | Same as @samp{-fonetrip -fugly-assumed}. | |
1765 | ||
1766 | The @samp{-fno-f66} option is the inverse of @samp{-ff66}. | |
1767 | As such, it is the same as @samp{-fno-onetrip -fno-ugly-assumed}. | |
1768 | ||
1769 | The meaning of this option is likely to be refined as future | |
1770 | versions of @code{g77} provide more compatibility with other | |
1771 | existing and obsolete Fortran implementations. | |
1772 | ||
1773 | @cindex -ff77 option | |
1774 | @cindex options, -ff77 | |
1775 | @item -ff77 | |
1776 | @cindex UNIX f77 | |
26b9526e CB |
1777 | @cindex f2c compatibility |
1778 | @cindex compatibility, f2c | |
1779 | @cindex f77 compatibility | |
1780 | @cindex compatibility, f77 | |
5ff904cd JL |
1781 | Specify that the program is written in idiomatic UNIX FORTRAN 77 |
1782 | and/or the dialect accepted by the @code{f2c} product. | |
1783 | Same as @samp{-fbackslash -fno-typeless-boz}. | |
1784 | ||
1785 | The meaning of this option is likely to be refined as future | |
1786 | versions of @code{g77} provide more compatibility with other | |
1787 | existing and obsolete Fortran implementations. | |
1788 | ||
1789 | @cindex -fno-f77 option | |
1790 | @cindex options, -fno-f77 | |
1791 | @item -fno-f77 | |
1792 | @cindex UNIX f77 | |
1793 | The @samp{-fno-f77} option is @emph{not} the inverse | |
1794 | of @samp{-ff77}. | |
1795 | It specifies that the program is not written in idiomatic UNIX | |
1796 | FORTRAN 77 or @code{f2c}, but in a more widely portable dialect. | |
1797 | @samp{-fno-f77} is the same as @samp{-fno-backslash}. | |
1798 | ||
1799 | The meaning of this option is likely to be refined as future | |
1800 | versions of @code{g77} provide more compatibility with other | |
1801 | existing and obsolete Fortran implementations. | |
1802 | @end table | |
1803 | ||
1804 | @node Fortran Dialect Options | |
1805 | @section Options Controlling Fortran Dialect | |
1806 | @cindex dialect options | |
26b9526e | 1807 | @cindex language, dialect options |
5ff904cd JL |
1808 | @cindex options, dialect |
1809 | ||
1810 | The following options control the dialect of Fortran | |
1811 | that the compiler accepts: | |
1812 | ||
1813 | @table @code | |
1814 | @cindex -ffree-form option | |
1815 | @cindex options, -ffree-form | |
1816 | @cindex -fno-fixed-form option | |
1817 | @cindex options, -fno-fixed-form | |
26b9526e | 1818 | @cindex source file format |
5ff904cd JL |
1819 | @cindex free form |
1820 | @cindex fixed form | |
26b9526e | 1821 | @cindex Fortran 90, features |
5ff904cd JL |
1822 | @item -ffree-form |
1823 | @item -fno-fixed-form | |
1824 | Specify that the source file is written in free form | |
1825 | (introduced in Fortran 90) instead of the more-traditional fixed form. | |
1826 | ||
1827 | @cindex -ff90 option | |
1828 | @cindex options, -ff90 | |
26b9526e | 1829 | @cindex Fortran 90, features |
5ff904cd JL |
1830 | @item -ff90 |
1831 | Allow certain Fortran-90 constructs. | |
1832 | ||
1833 | This option controls whether certain | |
1834 | Fortran 90 constructs are recognized. | |
1835 | (Other Fortran 90 constructs | |
1836 | might or might not be recognized depending on other options such as | |
1837 | @samp{-fvxt}, @samp{-ff90-intrinsics-enable}, and the | |
1838 | current level of support for Fortran 90.) | |
1839 | ||
1840 | @xref{Fortran 90}, for more information. | |
1841 | ||
1842 | @cindex -fvxt option | |
1843 | @cindex options, -fvxt | |
1844 | @item -fvxt | |
26b9526e CB |
1845 | @cindex Fortran 90, features |
1846 | @cindex VXT extensions | |
5ff904cd JL |
1847 | Specify the treatment of certain constructs that have different |
1848 | meanings depending on whether the code is written in | |
1849 | GNU Fortran (based on FORTRAN 77 and akin to Fortran 90) | |
1850 | or VXT Fortran (more like VAX FORTRAN). | |
1851 | ||
1852 | The default is @samp{-fno-vxt}. | |
1853 | @samp{-fvxt} specifies that the VXT Fortran interpretations | |
1854 | for those constructs are to be chosen. | |
1855 | ||
1856 | @xref{VXT Fortran}, for more information. | |
1857 | ||
1858 | @cindex -fdollar-ok option | |
1859 | @cindex options, -fdollar-ok | |
1860 | @item -fdollar-ok | |
1861 | @cindex dollar sign | |
1862 | @cindex symbol names | |
1863 | @cindex character set | |
1864 | Allow @samp{$} as a valid character in a symbol name. | |
1865 | ||
1866 | @cindex -fno-backslash option | |
1867 | @cindex options, -fno-backslash | |
1868 | @item -fno-backslash | |
1869 | @cindex backslash | |
1870 | @cindex character constants | |
1871 | @cindex Hollerith constants | |
1872 | Specify that @samp{\} is not to be specially interpreted in character | |
1873 | and Hollerith constants a la C and many UNIX Fortran compilers. | |
1874 | ||
1875 | For example, with @samp{-fbackslash} in effect, @samp{A\nB} specifies | |
1876 | three characters, with the second one being newline. | |
1877 | With @samp{-fno-backslash}, it specifies four characters, | |
1878 | @samp{A}, @samp{\}, @samp{n}, and @samp{B}. | |
1879 | ||
1880 | Note that @code{g77} implements a fairly general form of backslash | |
1881 | processing that is incompatible with the narrower forms supported | |
1882 | by some other compilers. | |
1883 | For example, @samp{'A\003B'} is a three-character string in @code{g77}, | |
1884 | whereas other compilers that support backslash might not support | |
1885 | the three-octal-digit form, and thus treat that string as longer | |
1886 | than three characters. | |
1887 | ||
1888 | @xref{Backslash in Constants}, for | |
1889 | information on why @samp{-fbackslash} is the default | |
1890 | instead of @samp{-fno-backslash}. | |
1891 | ||
1892 | @cindex -fno-ugly-args option | |
1893 | @cindex options, -fno-ugly-args | |
1894 | @item -fno-ugly-args | |
1895 | Disallow passing Hollerith and typeless constants as actual | |
1896 | arguments (for example, @samp{CALL FOO(4HABCD)}). | |
1897 | ||
1898 | @xref{Ugly Implicit Argument Conversion}, for more information. | |
1899 | ||
1900 | @cindex -fugly-assign option | |
1901 | @cindex options, -fugly-assign | |
1902 | @item -fugly-assign | |
1903 | Use the same storage for a given variable regardless of | |
1904 | whether it is used to hold an assigned-statement label | |
1905 | (as in @samp{ASSIGN 10 TO I}) or used to hold numeric data | |
1906 | (as in @samp{I = 3}). | |
1907 | ||
1908 | @xref{Ugly Assigned Labels}, for more information. | |
1909 | ||
1910 | @cindex -fugly-assumed option | |
1911 | @cindex options, -fugly-assumed | |
1912 | @item -fugly-assumed | |
1913 | Assume any dummy array with a final dimension specified as @samp{1} | |
1914 | is really an assumed-size array, as if @samp{*} had been specified | |
1915 | for the final dimension instead of @samp{1}. | |
1916 | ||
1917 | For example, @samp{DIMENSION X(1)} is treated as if it | |
1918 | had read @samp{DIMENSION X(*)}. | |
1919 | ||
1920 | @xref{Ugly Assumed-Size Arrays}, for more information. | |
1921 | ||
1922 | @cindex -fugly-comma option | |
1923 | @cindex options, -fugly-comma | |
1924 | @item -fugly-comma | |
56a0044b JL |
1925 | In an external-procedure invocation, |
1926 | treat a trailing comma in the argument list | |
1927 | as specification of a trailing null argument, | |
1928 | and treat an empty argument list | |
1929 | as specification of a single null argument. | |
5ff904cd JL |
1930 | |
1931 | For example, @samp{CALL FOO(,)} is treated as | |
1932 | @samp{CALL FOO(%VAL(0), %VAL(0))}. | |
1933 | That is, @emph{two} null arguments are specified | |
1934 | by the procedure call when @samp{-fugly-comma} is in force. | |
1935 | And @samp{F = FUNC()} is treated as @samp{F = FUNC(%VAL(0))}. | |
1936 | ||
1937 | The default behavior, @samp{-fno-ugly-comma}, is to ignore | |
1938 | a single trailing comma in an argument list. | |
56a0044b JL |
1939 | So, by default, @samp{CALL FOO(X,)} is treated |
1940 | exactly the same as @samp{CALL FOO(X)}. | |
5ff904cd JL |
1941 | |
1942 | @xref{Ugly Null Arguments}, for more information. | |
1943 | ||
1944 | @cindex -fugly-complex option | |
1945 | @cindex options, -fugly-complex | |
1946 | @item -fugly-complex | |
1947 | Do not complain about @samp{REAL(@var{expr})} or | |
1948 | @samp{AIMAG(@var{expr})} when @var{expr} is a @code{COMPLEX} | |
1949 | type other than @code{COMPLEX(KIND=1)}---usually | |
1950 | this is used to permit @code{COMPLEX(KIND=2)} | |
1951 | (@code{DOUBLE COMPLEX}) operands. | |
1952 | ||
1953 | The @samp{-ff90} option controls the interpretation | |
1954 | of this construct. | |
1955 | ||
1956 | @xref{Ugly Complex Part Extraction}, for more information. | |
1957 | ||
1958 | @cindex -fno-ugly-init option | |
1959 | @cindex options, -fno-ugly-init | |
1960 | @item -fno-ugly-init | |
1961 | Disallow use of Hollerith and typeless constants as initial | |
1962 | values (in @code{PARAMETER} and @code{DATA} statements), and | |
1963 | use of character constants to | |
1964 | initialize numeric types and vice versa. | |
1965 | ||
1966 | For example, @samp{DATA I/'F'/, CHRVAR/65/, J/4HABCD/} is disallowed by | |
1967 | @samp{-fno-ugly-init}. | |
1968 | ||
1969 | @xref{Ugly Conversion of Initializers}, for more information. | |
1970 | ||
1971 | @cindex -fugly-logint option | |
1972 | @cindex options, -fugly-logint | |
1973 | @item -fugly-logint | |
1974 | Treat @code{INTEGER} and @code{LOGICAL} variables and | |
1975 | expressions as potential stand-ins for each other. | |
1976 | ||
1977 | For example, automatic conversion between @code{INTEGER} and | |
1978 | @code{LOGICAL} is enabled, for many contexts, via this option. | |
1979 | ||
1980 | @xref{Ugly Integer Conversions}, for more information. | |
1981 | ||
1982 | @cindex -fonetrip option | |
1983 | @cindex options, -fonetrip | |
1984 | @item -fonetrip | |
1985 | @cindex FORTRAN 66 | |
26b9526e CB |
1986 | @cindex @code{DO} loops, one-trip |
1987 | @cindex one-trip @code{DO} loops | |
1988 | @cindex @code{DO} loops, zero-trip | |
1989 | @cindex zero-trip @code{DO} loops | |
5ff904cd | 1990 | @cindex compatibility, FORTRAN 66 |
26b9526e | 1991 | Executable iterative @code{DO} loops are to be executed at |
5ff904cd JL |
1992 | least once each time they are reached. |
1993 | ||
1994 | ANSI FORTRAN 77 and more recent versions of the Fortran standard | |
26b9526e | 1995 | specify that the body of an iterative @code{DO} loop is not executed |
5ff904cd JL |
1996 | if the number of iterations calculated from the parameters of the |
1997 | loop is less than 1. | |
95a1b676 | 1998 | (For example, @samp{DO 10 I = 1, 0}.) |
5ff904cd JL |
1999 | Such a loop is called a @dfn{zero-trip loop}. |
2000 | ||
2001 | Prior to ANSI FORTRAN 77, many compilers implemented @code{DO} loops | |
2002 | such that the body of a loop would be executed at least once, even | |
2003 | if the iteration count was zero. | |
2004 | Fortran code written assuming this behavior is said to require | |
2005 | @dfn{one-trip loops}. | |
2006 | For example, some code written to the FORTRAN 66 standard | |
2007 | expects this behavior from its @code{DO} loops, although that | |
2008 | standard did not specify this behavior. | |
2009 | ||
2010 | The @samp{-fonetrip} option specifies that the source file(s) being | |
2011 | compiled require one-trip loops. | |
2012 | ||
26b9526e | 2013 | This option affects only those loops specified by the (iterative) @code{DO} |
5ff904cd JL |
2014 | statement and by implied-@code{DO} lists in I/O statements. |
2015 | Loops specified by implied-@code{DO} lists in @code{DATA} and | |
2016 | specification (non-executable) statements are not affected. | |
2017 | ||
2018 | @cindex -ftypeless-boz option | |
2019 | @cindex options, -ftypeless-boz | |
2020 | @cindex prefix-radix constants | |
2021 | @cindex constants, prefix-radix | |
2022 | @cindex constants, types | |
2023 | @cindex types, constants | |
2024 | @item -ftypeless-boz | |
2025 | Specifies that prefix-radix non-decimal constants, such as | |
2026 | @samp{Z'ABCD'}, are typeless instead of @code{INTEGER(KIND=1)}. | |
2027 | ||
2028 | You can test for yourself whether a particular compiler treats | |
2029 | the prefix form as @code{INTEGER(KIND=1)} or typeless by running the | |
2030 | following program: | |
2031 | ||
2032 | @smallexample | |
2033 | EQUIVALENCE (I, R) | |
2034 | R = Z'ABCD1234' | |
2035 | J = Z'ABCD1234' | |
2036 | IF (J .EQ. I) PRINT *, 'Prefix form is TYPELESS' | |
2037 | IF (J .NE. I) PRINT *, 'Prefix form is INTEGER' | |
2038 | END | |
2039 | @end smallexample | |
2040 | ||
2041 | Reports indicate that many compilers process this form as | |
2042 | @code{INTEGER(KIND=1)}, though a few as typeless, and at least one | |
2043 | based on a command-line option specifying some kind of | |
2044 | compatibility. | |
2045 | ||
2046 | @cindex -fintrin-case-initcap option | |
2047 | @cindex options, -fintrin-case-initcap | |
2048 | @item -fintrin-case-initcap | |
2049 | @cindex -fintrin-case-upper option | |
2050 | @cindex options, -fintrin-case-upper | |
2051 | @item -fintrin-case-upper | |
2052 | @cindex -fintrin-case-lower option | |
2053 | @cindex options, -fintrin-case-lower | |
2054 | @item -fintrin-case-lower | |
2055 | @cindex -fintrin-case-any option | |
2056 | @cindex options, -fintrin-case-any | |
2057 | @item -fintrin-case-any | |
2058 | Specify expected case for intrinsic names. | |
2059 | @samp{-fintrin-case-lower} is the default. | |
2060 | ||
2061 | @cindex -fmatch-case-initcap option | |
2062 | @cindex options, -fmatch-case-initcap | |
2063 | @item -fmatch-case-initcap | |
2064 | @cindex -fmatch-case-upper option | |
2065 | @cindex options, -fmatch-case-upper | |
2066 | @item -fmatch-case-upper | |
2067 | @cindex -fmatch-case-lower option | |
2068 | @cindex options, -fmatch-case-lower | |
2069 | @item -fmatch-case-lower | |
2070 | @cindex -fmatch-case-any option | |
2071 | @cindex options, -fmatch-case-any | |
2072 | @item -fmatch-case-any | |
2073 | Specify expected case for keywords. | |
2074 | @samp{-fmatch-case-lower} is the default. | |
2075 | ||
2076 | @cindex -fsource-case-upper option | |
2077 | @cindex options, -fsource-case-upper | |
2078 | @item -fsource-case-upper | |
2079 | @cindex -fsource-case-lower option | |
2080 | @cindex options, -fsource-case-lower | |
2081 | @item -fsource-case-lower | |
2082 | @cindex -fsource-case-preserve option | |
2083 | @cindex options, -fsource-case-preserve | |
2084 | @item -fsource-case-preserve | |
2085 | Specify whether source text other than character and Hollerith constants | |
2086 | is to be translated to uppercase, to lowercase, or preserved as is. | |
2087 | @samp{-fsource-case-lower} is the default. | |
2088 | ||
2089 | @cindex -fsymbol-case-initcap option | |
2090 | @cindex options, -fsymbol-case-initcap | |
2091 | @item -fsymbol-case-initcap | |
2092 | @cindex -fsymbol-case-upper option | |
2093 | @cindex options, -fsymbol-case-upper | |
2094 | @item -fsymbol-case-upper | |
2095 | @cindex -fsymbol-case-lower option | |
2096 | @cindex options, -fsymbol-case-lower | |
2097 | @item -fsymbol-case-lower | |
2098 | @cindex -fsymbol-case-any option | |
2099 | @cindex options, -fsymbol-case-any | |
2100 | @item -fsymbol-case-any | |
2101 | Specify valid cases for user-defined symbol names. | |
2102 | @samp{-fsymbol-case-any} is the default. | |
2103 | ||
2104 | @cindex -fcase-strict-upper option | |
2105 | @cindex options, -fcase-strict-upper | |
2106 | @item -fcase-strict-upper | |
2107 | Same as @samp{-fintrin-case-upper -fmatch-case-upper -fsource-case-preserve | |
2108 | -fsymbol-case-upper}. | |
2109 | (Requires all pertinent source to be in uppercase.) | |
2110 | ||
2111 | @cindex -fcase-strict-lower option | |
2112 | @cindex options, -fcase-strict-lower | |
2113 | @item -fcase-strict-lower | |
2114 | Same as @samp{-fintrin-case-lower -fmatch-case-lower -fsource-case-preserve | |
2115 | -fsymbol-case-lower}. | |
2116 | (Requires all pertinent source to be in lowercase.) | |
2117 | ||
2118 | @cindex -fcase-initcap option | |
2119 | @cindex options, -fcase-initcap | |
2120 | @item -fcase-initcap | |
2121 | Same as @samp{-fintrin-case-initcap -fmatch-case-initcap -fsource-case-preserve | |
2122 | -fsymbol-case-initcap}. | |
2123 | (Requires all pertinent source to be in initial capitals, | |
2124 | as in @samp{Print *,SqRt(Value)}.) | |
2125 | ||
2126 | @cindex -fcase-upper option | |
2127 | @cindex options, -fcase-upper | |
2128 | @item -fcase-upper | |
2129 | Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-upper | |
2130 | -fsymbol-case-any}. | |
2131 | (Maps all pertinent source to uppercase.) | |
2132 | ||
2133 | @cindex -fcase-lower option | |
2134 | @cindex options, -fcase-lower | |
2135 | @item -fcase-lower | |
2136 | Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-lower | |
2137 | -fsymbol-case-any}. | |
2138 | (Maps all pertinent source to lowercase.) | |
2139 | ||
2140 | @cindex -fcase-preserve option | |
2141 | @cindex options, -fcase-preserve | |
2142 | @item -fcase-preserve | |
2143 | Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-preserve | |
2144 | -fsymbol-case-any}. | |
2145 | (Preserves all case in user-defined symbols, | |
2146 | while allowing any-case matching of intrinsics and keywords. | |
2147 | For example, @samp{call Foo(i,I)} would pass two @emph{different} | |
2148 | variables named @samp{i} and @samp{I} to a procedure named @samp{Foo}.) | |
2149 | ||
56a0044b JL |
2150 | @cindex -fbadu77-intrinsics-delete option |
2151 | @cindex options, -fbadu77-intrinsics-delete | |
2152 | @item -fbadu77-intrinsics-delete | |
2153 | @cindex -fbadu77-intrinsics-hide option | |
2154 | @cindex options, -fbadu77-intrinsics-hide | |
2155 | @item -fbadu77-intrinsics-hide | |
2156 | @cindex -fbadu77-intrinsics-disable option | |
2157 | @cindex options, -fbadu77-intrinsics-disable | |
2158 | @item -fbadu77-intrinsics-disable | |
2159 | @cindex -fbadu77-intrinsics-enable option | |
2160 | @cindex options, -fbadu77-intrinsics-enable | |
2161 | @item -fbadu77-intrinsics-enable | |
26b9526e CB |
2162 | @cindex @code{badu77} intrinsics |
2163 | @cindex intrinsics, @code{badu77} | |
56a0044b JL |
2164 | Specify status of UNIX intrinsics having inappropriate forms. |
2165 | @samp{-fbadu77-intrinsics-enable} is the default. | |
2166 | @xref{Intrinsic Groups}. | |
2167 | ||
5ff904cd JL |
2168 | @cindex -ff2c-intrinsics-delete option |
2169 | @cindex options, -ff2c-intrinsics-delete | |
2170 | @item -ff2c-intrinsics-delete | |
2171 | @cindex -ff2c-intrinsics-hide option | |
2172 | @cindex options, -ff2c-intrinsics-hide | |
2173 | @item -ff2c-intrinsics-hide | |
2174 | @cindex -ff2c-intrinsics-disable option | |
2175 | @cindex options, -ff2c-intrinsics-disable | |
2176 | @item -ff2c-intrinsics-disable | |
2177 | @cindex -ff2c-intrinsics-enable option | |
2178 | @cindex options, -ff2c-intrinsics-enable | |
2179 | @item -ff2c-intrinsics-enable | |
26b9526e CB |
2180 | @cindex @code{f2c} intrinsics |
2181 | @cindex intrinsics, @code{f2c} | |
5ff904cd JL |
2182 | Specify status of f2c-specific intrinsics. |
2183 | @samp{-ff2c-intrinsics-enable} is the default. | |
56a0044b | 2184 | @xref{Intrinsic Groups}. |
5ff904cd JL |
2185 | |
2186 | @cindex -ff90-intrinsics-delete option | |
2187 | @cindex options, -ff90-intrinsics-delete | |
2188 | @item -ff90-intrinsics-delete | |
2189 | @cindex -ff90-intrinsics-hide option | |
2190 | @cindex options, -ff90-intrinsics-hide | |
2191 | @item -ff90-intrinsics-hide | |
2192 | @cindex -ff90-intrinsics-disable option | |
2193 | @cindex options, -ff90-intrinsics-disable | |
2194 | @item -ff90-intrinsics-disable | |
2195 | @cindex -ff90-intrinsics-enable option | |
2196 | @cindex options, -ff90-intrinsics-enable | |
2197 | @item -ff90-intrinsics-enable | |
26b9526e | 2198 | @cindex Fortran 90, intrinsics |
5ff904cd JL |
2199 | @cindex intrinsics, Fortran 90 |
2200 | Specify status of F90-specific intrinsics. | |
2201 | @samp{-ff90-intrinsics-enable} is the default. | |
56a0044b | 2202 | @xref{Intrinsic Groups}. |
5ff904cd JL |
2203 | |
2204 | @cindex -fgnu-intrinsics-delete option | |
2205 | @cindex options, -fgnu-intrinsics-delete | |
2206 | @item -fgnu-intrinsics-delete | |
2207 | @cindex -fgnu-intrinsics-hide option | |
2208 | @cindex options, -fgnu-intrinsics-hide | |
2209 | @item -fgnu-intrinsics-hide | |
2210 | @cindex -fgnu-intrinsics-disable option | |
2211 | @cindex options, -fgnu-intrinsics-disable | |
2212 | @item -fgnu-intrinsics-disable | |
2213 | @cindex -fgnu-intrinsics-enable option | |
2214 | @cindex options, -fgnu-intrinsics-enable | |
2215 | @item -fgnu-intrinsics-enable | |
2216 | @cindex Digital Fortran features | |
26b9526e CB |
2217 | @cindex @code{COMPLEX} intrinsics |
2218 | @cindex intrinsics, @code{COMPLEX} | |
5ff904cd JL |
2219 | Specify status of Digital's COMPLEX-related intrinsics. |
2220 | @samp{-fgnu-intrinsics-enable} is the default. | |
56a0044b | 2221 | @xref{Intrinsic Groups}. |
5ff904cd JL |
2222 | |
2223 | @cindex -fmil-intrinsics-delete option | |
2224 | @cindex options, -fmil-intrinsics-delete | |
2225 | @item -fmil-intrinsics-delete | |
2226 | @cindex -fmil-intrinsics-hide option | |
2227 | @cindex options, -fmil-intrinsics-hide | |
2228 | @item -fmil-intrinsics-hide | |
2229 | @cindex -fmil-intrinsics-disable option | |
2230 | @cindex options, -fmil-intrinsics-disable | |
2231 | @item -fmil-intrinsics-disable | |
2232 | @cindex -fmil-intrinsics-enable option | |
2233 | @cindex options, -fmil-intrinsics-enable | |
2234 | @item -fmil-intrinsics-enable | |
2235 | @cindex MIL-STD 1753 | |
2236 | @cindex intrinsics, MIL-STD 1753 | |
2237 | Specify status of MIL-STD-1753-specific intrinsics. | |
2238 | @samp{-fmil-intrinsics-enable} is the default. | |
56a0044b | 2239 | @xref{Intrinsic Groups}. |
5ff904cd JL |
2240 | |
2241 | @cindex -funix-intrinsics-delete option | |
2242 | @cindex options, -funix-intrinsics-delete | |
2243 | @item -funix-intrinsics-delete | |
2244 | @cindex -funix-intrinsics-hide option | |
2245 | @cindex options, -funix-intrinsics-hide | |
2246 | @item -funix-intrinsics-hide | |
2247 | @cindex -funix-intrinsics-disable option | |
2248 | @cindex options, -funix-intrinsics-disable | |
2249 | @item -funix-intrinsics-disable | |
2250 | @cindex -funix-intrinsics-enable option | |
2251 | @cindex options, -funix-intrinsics-enable | |
2252 | @item -funix-intrinsics-enable | |
2253 | @cindex UNIX intrinsics | |
2254 | @cindex intrinsics, UNIX | |
2255 | Specify status of UNIX intrinsics. | |
2256 | @samp{-funix-intrinsics-enable} is the default. | |
56a0044b | 2257 | @xref{Intrinsic Groups}. |
5ff904cd JL |
2258 | |
2259 | @cindex -fvxt-intrinsics-delete option | |
2260 | @cindex options, -fvxt-intrinsics-delete | |
2261 | @item -fvxt-intrinsics-delete | |
2262 | @cindex -fvxt-intrinsics-hide option | |
2263 | @cindex options, -fvxt-intrinsics-hide | |
2264 | @item -fvxt-intrinsics-hide | |
2265 | @cindex -fvxt-intrinsics-disable option | |
2266 | @cindex options, -fvxt-intrinsics-disable | |
2267 | @item -fvxt-intrinsics-disable | |
2268 | @cindex -fvxt-intrinsics-enable option | |
2269 | @cindex options, -fvxt-intrinsics-enable | |
2270 | @item -fvxt-intrinsics-enable | |
2271 | @cindex VXT intrinsics | |
2272 | @cindex intrinsics, VXT | |
2273 | Specify status of VXT intrinsics. | |
2274 | @samp{-fvxt-intrinsics-enable} is the default. | |
56a0044b | 2275 | @xref{Intrinsic Groups}. |
5ff904cd JL |
2276 | |
2277 | @cindex -ffixed-line-length-@var{n} option | |
2278 | @cindex options, -ffixed-line-length-@var{n} | |
2279 | @item -ffixed-line-length-@var{n} | |
2280 | @cindex source file format | |
26b9526e | 2281 | @cindex lines, length |
5ff904cd | 2282 | @cindex length of source lines |
26b9526e | 2283 | @cindex fixed form |
d79904b8 | 2284 | @cindex limits, lengths of source lines |
5ff904cd JL |
2285 | Set column after which characters are ignored in typical fixed-form |
2286 | lines in the source file, and through which spaces are assumed (as | |
2287 | if padded to that length) after the ends of short fixed-form lines. | |
2288 | ||
2289 | @cindex card image | |
2290 | @cindex extended-source option | |
2291 | Popular values for @var{n} include 72 (the | |
2292 | standard and the default), 80 (card image), and 132 (corresponds | |
2293 | to ``extended-source'' options in some popular compilers). | |
2294 | @var{n} may be @samp{none}, meaning that the entire line is meaningful | |
2295 | and that continued character constants never have implicit spaces appended | |
2296 | to them to fill out the line. | |
2297 | @samp{-ffixed-line-length-0} means the same thing as | |
2298 | @samp{-ffixed-line-length-none}. | |
2299 | ||
2300 | @xref{Source Form}, for more information. | |
2301 | @end table | |
2302 | ||
2303 | @node Warning Options | |
2304 | @section Options to Request or Suppress Warnings | |
26b9526e CB |
2305 | @cindex options, warnings |
2306 | @cindex warnings, suppressing | |
5ff904cd JL |
2307 | @cindex messages, warning |
2308 | @cindex suppressing warnings | |
2309 | ||
2310 | Warnings are diagnostic messages that report constructions which | |
2311 | are not inherently erroneous but which are risky or suggest there | |
2312 | might have been an error. | |
2313 | ||
2314 | You can request many specific warnings with options beginning @samp{-W}, | |
2315 | for example @samp{-Wimplicit} to request warnings on implicit | |
2316 | declarations. Each of these specific warning options also has a | |
2317 | negative form beginning @samp{-Wno-} to turn off warnings; | |
2318 | for example, @samp{-Wno-implicit}. This manual lists only one of the | |
2319 | two forms, whichever is not the default. | |
2320 | ||
2321 | These options control the amount and kinds of warnings produced by GNU | |
2322 | Fortran: | |
2323 | ||
2324 | @table @code | |
2325 | @cindex syntax checking | |
2326 | @cindex -fsyntax-only option | |
2327 | @cindex options, -fsyntax-only | |
2328 | @item -fsyntax-only | |
2329 | Check the code for syntax errors, but don't do anything beyond that. | |
2330 | ||
2331 | @cindex -pedantic option | |
2332 | @cindex options, -pedantic | |
2333 | @item -pedantic | |
2334 | Issue warnings for uses of extensions to ANSI FORTRAN 77. | |
2335 | @samp{-pedantic} also applies to C-language constructs where they | |
2336 | occur in GNU Fortran source files, such as use of @samp{\e} in a | |
2337 | character constant within a directive like @samp{#include}. | |
2338 | ||
2339 | Valid ANSI FORTRAN 77 programs should compile properly with or without | |
2340 | this option. | |
2341 | However, without this option, certain GNU extensions and traditional | |
2342 | Fortran features are supported as well. | |
2343 | With this option, many of them are rejected. | |
2344 | ||
2345 | Some users try to use @samp{-pedantic} to check programs for strict ANSI | |
2346 | conformance. | |
2347 | They soon find that it does not do quite what they want---it finds some | |
2348 | non-ANSI practices, but not all. | |
2349 | However, improvements to @code{g77} in this area are welcome. | |
2350 | ||
2351 | @cindex -pedantic-errors option | |
2352 | @cindex options, -pedantic-errors | |
2353 | @item -pedantic-errors | |
2354 | Like @samp{-pedantic}, except that errors are produced rather than | |
2355 | warnings. | |
2356 | ||
2357 | @cindex -fpedantic option | |
2358 | @cindex options, -fpedantic | |
2359 | @item -fpedantic | |
2360 | Like @samp{-pedantic}, but applies only to Fortran constructs. | |
2361 | ||
2362 | @cindex -w option | |
2363 | @cindex options, -w | |
2364 | @item -w | |
2365 | Inhibit all warning messages. | |
2366 | ||
2367 | @cindex -Wno-globals option | |
2368 | @cindex options, -Wno-globals | |
2369 | @item -Wno-globals | |
2370 | @cindex global names, warning | |
2371 | @cindex warnings, global names | |
2372 | Inhibit warnings about use of a name as both a global name | |
2373 | (a subroutine, function, or block data program unit, or a | |
2374 | common block) and implicitly as the name of an intrinsic | |
2375 | in a source file. | |
2376 | ||
2377 | Also inhibit warnings about inconsistent invocations and/or | |
2378 | definitions of global procedures (function and subroutines). | |
2379 | Such inconsistencies include different numbers of arguments | |
2380 | and different types of arguments. | |
2381 | ||
2382 | @cindex -Wimplicit option | |
2383 | @cindex options, -Wimplicit | |
2384 | @item -Wimplicit | |
2385 | @cindex implicit declaration, warning | |
2386 | @cindex warnings, implicit declaration | |
2387 | @cindex -u option | |
2388 | @cindex /WARNINGS=DECLARATIONS switch | |
2389 | @cindex IMPLICIT NONE, similar effect | |
2390 | @cindex effecting IMPLICIT NONE | |
2391 | Warn whenever a variable, array, or function is implicitly | |
2392 | declared. | |
2393 | Has an effect similar to using the @code{IMPLICIT NONE} statement | |
2394 | in every program unit. | |
2395 | (Some Fortran compilers provide this feature by an option | |
2396 | named @samp{-u} or @samp{/WARNINGS=DECLARATIONS}.) | |
2397 | ||
2398 | @cindex -Wunused option | |
2399 | @cindex options, -Wunused | |
2400 | @item -Wunused | |
2401 | @cindex unused variables | |
2402 | @cindex variables, unused | |
2403 | Warn whenever a variable is unused aside from its declaration. | |
2404 | ||
2405 | @cindex -Wuninitialized option | |
2406 | @cindex options, -Wuninitialized | |
2407 | @item -Wuninitialized | |
2408 | @cindex uninitialized variables | |
2409 | @cindex variables, uninitialized | |
2410 | Warn whenever an automatic variable is used without first being initialized. | |
2411 | ||
2412 | These warnings are possible only in optimizing compilation, | |
2413 | because they require data-flow information that is computed only | |
2414 | when optimizing. If you don't specify @samp{-O}, you simply won't | |
2415 | get these warnings. | |
2416 | ||
2417 | These warnings occur only for variables that are candidates for | |
2418 | register allocation. Therefore, they do not occur for a variable | |
2419 | @c that is declared @code{VOLATILE}, or | |
2420 | whose address is taken, or whose size | |
2421 | is other than 1, 2, 4 or 8 bytes. Also, they do not occur for | |
2422 | arrays, even when they are in registers. | |
2423 | ||
2424 | Note that there might be no warning about a variable that is used only | |
2425 | to compute a value that itself is never used, because such | |
2426 | computations may be deleted by data-flow analysis before the warnings | |
2427 | are printed. | |
2428 | ||
2429 | These warnings are made optional because GNU Fortran is not smart | |
2430 | enough to see all the reasons why the code might be correct | |
2431 | despite appearing to have an error. Here is one example of how | |
2432 | this can happen: | |
2433 | ||
2434 | @example | |
2435 | SUBROUTINE DISPAT(J) | |
2436 | IF (J.EQ.1) I=1 | |
2437 | IF (J.EQ.2) I=4 | |
2438 | IF (J.EQ.3) I=5 | |
2439 | CALL FOO(I) | |
2440 | END | |
2441 | @end example | |
2442 | ||
2443 | @noindent | |
2444 | If the value of @code{J} is always 1, 2 or 3, then @code{I} is | |
2445 | always initialized, but GNU Fortran doesn't know this. Here is | |
2446 | another common case: | |
2447 | ||
2448 | @example | |
2449 | SUBROUTINE MAYBE(FLAG) | |
2450 | LOGICAL FLAG | |
2451 | IF (FLAG) VALUE = 9.4 | |
2452 | @dots{} | |
2453 | IF (FLAG) PRINT *, VALUE | |
2454 | END | |
2455 | @end example | |
2456 | ||
2457 | @noindent | |
2458 | This has no bug because @code{VALUE} is used only if it is set. | |
2459 | ||
2460 | @cindex -Wall option | |
2461 | @cindex options, -Wall | |
2462 | @item -Wall | |
2463 | @cindex all warnings | |
2464 | @cindex warnings, all | |
2465 | The @samp{-Wunused} and @samp{-Wuninitialized} options combined. | |
2466 | These are all the | |
2467 | options which pertain to usage that we recommend avoiding and that we | |
2468 | believe is easy to avoid. | |
2469 | (As more warnings are added to @code{g77}, some might | |
2470 | be added to the list enabled by @samp{-Wall}.) | |
2471 | @end table | |
2472 | ||
2473 | The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall} | |
2474 | because they warn about constructions that we consider reasonable to | |
2475 | use, on occasion, in clean programs. | |
2476 | ||
2477 | @table @code | |
2478 | @c @item -W | |
2479 | @c Print extra warning messages for these events: | |
66d18ad7 | 2480 | @c |
5ff904cd JL |
2481 | @c @itemize @bullet |
2482 | @c @item | |
2483 | @c If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused | |
2484 | @c arguments. | |
66d18ad7 | 2485 | @c |
5ff904cd JL |
2486 | @c @end itemize |
2487 | @c | |
2488 | @cindex -Wsurprising option | |
2489 | @cindex options, -Wsurprising | |
2490 | @item -Wsurprising | |
2491 | Warn about ``suspicious'' constructs that are interpreted | |
2492 | by the compiler in a way that might well be surprising to | |
2493 | someone reading the code. | |
2494 | These differences can result in subtle, compiler-dependent | |
2495 | (even machine-dependent) behavioral differences. | |
2496 | The constructs warned about include: | |
2497 | ||
2498 | @itemize @bullet | |
2499 | @item | |
2500 | Expressions having two arithmetic operators in a row, such | |
2501 | as @samp{X*-Y}. | |
2502 | Such a construct is nonstandard, and can produce | |
2503 | unexpected results in more complicated situations such | |
2504 | as @samp{X**-Y*Z}. | |
2505 | @code{g77}, along with many other compilers, interprets | |
2506 | this example differently than many programmers, and a few | |
2507 | other compilers. | |
2508 | Specifically, @code{g77} interprets @samp{X**-Y*Z} as | |
2509 | @samp{(X**(-Y))*Z}, while others might think it should | |
2510 | be interpreted as @samp{X**(-(Y*Z))}. | |
2511 | ||
2512 | A revealing example is the constant expression @samp{2**-2*1.}, | |
2513 | which @code{g77} evaluates to .25, while others might evaluate | |
2514 | it to 0., the difference resulting from the way precedence affects | |
2515 | type promotion. | |
2516 | ||
2517 | (The @samp{-fpedantic} option also warns about expressions | |
2518 | having two arithmetic operators in a row.) | |
2519 | ||
2520 | @item | |
2521 | Expressions with a unary minus followed by an operand and then | |
2522 | a binary operator other than plus or minus. | |
2523 | For example, @samp{-2**2} produces a warning, because | |
2524 | the precedence is @samp{-(2**2)}, yielding -4, not | |
2525 | @samp{(-2)**2}, which yields 4, and which might represent | |
2526 | what a programmer expects. | |
2527 | ||
2528 | An example of an expression producing different results | |
2529 | in a surprising way is @samp{-I*S}, where @var{I} holds | |
2530 | the value @samp{-2147483648} and @var{S} holds @samp{0.5}. | |
2531 | On many systems, negating @var{I} results in the same | |
2532 | value, not a positive number, because it is already the | |
2533 | lower bound of what an @code{INTEGER(KIND=1)} variable can hold. | |
2534 | So, the expression evaluates to a positive number, while | |
2535 | the ``expected'' interpretation, @samp{(-I)*S}, would | |
2536 | evaluate to a negative number. | |
2537 | ||
2538 | Even cases such as @samp{-I*J} produce warnings, | |
2539 | even though, in most configurations and situations, | |
2540 | there is no computational difference between the | |
2541 | results of the two interpretations---the purpose | |
2542 | of this warning is to warn about differing interpretations | |
2543 | and encourage a better style of coding, not to identify | |
2544 | only those places where bugs might exist in the user's | |
2545 | code. | |
2546 | ||
2547 | @cindex DO statement | |
2548 | @cindex statements, DO | |
2549 | @item | |
2550 | @code{DO} loops with @code{DO} variables that are not | |
2551 | of integral type---that is, using @code{REAL} | |
2552 | variables as loop control variables. | |
2553 | Although such loops can be written to work in the | |
2554 | ``obvious'' way, the way @code{g77} is required by the | |
2555 | Fortran standard to interpret such code is likely to | |
2556 | be quite different from the way many programmers expect. | |
2557 | (This is true of all @code{DO} loops, but the differences | |
2558 | are pronounced for non-integral loop control variables.) | |
2559 | ||
2560 | @xref{Loops}, for more information. | |
2561 | @end itemize | |
2562 | ||
2563 | @cindex -Werror option | |
2564 | @cindex options, -Werror | |
2565 | @item -Werror | |
2566 | Make all warnings into errors. | |
2567 | ||
2568 | @cindex -W option | |
2569 | @cindex options, -W | |
2570 | @item -W | |
2571 | @cindex extra warnings | |
2572 | @cindex warnings, extra | |
2573 | Turns on ``extra warnings'' and, if optimization is specified | |
2574 | via @samp{-O}, the @samp{-Wuninitialized} option. | |
2575 | (This might change in future versions of @code{g77}.) | |
2576 | ||
2577 | ``Extra warnings'' are issued for: | |
2578 | ||
2579 | @itemize @bullet | |
2580 | @item | |
2581 | @cindex unused parameters | |
2582 | @cindex parameters, unused | |
2583 | @cindex unused arguments | |
2584 | @cindex arguments, unused | |
2585 | @cindex unused dummies | |
2586 | @cindex dummies, unused | |
2587 | Unused parameters to a procedure (when @samp{-Wunused} also is | |
2588 | specified). | |
2589 | ||
2590 | @item | |
2591 | @cindex overflow | |
2592 | Overflows involving floating-point constants (not available | |
2593 | for certain configurations). | |
2594 | @end itemize | |
2595 | @end table | |
2596 | ||
2597 | @xref{Warning Options,,Options to Request or Suppress Warnings, | |
2598 | gcc,Using and Porting GNU CC}, for information on more options offered | |
2599 | by the GBE shared by @code{g77}, @code{gcc}, and other GNU compilers. | |
2600 | ||
2601 | Some of these have no effect when compiling programs written in Fortran: | |
2602 | ||
2603 | @table @code | |
2604 | @cindex -Wcomment option | |
2605 | @cindex options, -Wcomment | |
2606 | @item -Wcomment | |
2607 | @cindex -Wformat option | |
2608 | @cindex options, -Wformat | |
2609 | @item -Wformat | |
2610 | @cindex -Wparentheses option | |
2611 | @cindex options, -Wparentheses | |
2612 | @item -Wparentheses | |
2613 | @cindex -Wswitch option | |
2614 | @cindex options, -Wswitch | |
2615 | @item -Wswitch | |
2616 | @cindex -Wtraditional option | |
2617 | @cindex options, -Wtraditional | |
2618 | @item -Wtraditional | |
2619 | @cindex -Wshadow option | |
2620 | @cindex options, -Wshadow | |
2621 | @item -Wshadow | |
2622 | @cindex -Wid-clash-@var{len} option | |
2623 | @cindex options, -Wid-clash-@var{len} | |
2624 | @item -Wid-clash-@var{len} | |
2625 | @cindex -Wlarger-than-@var{len} option | |
2626 | @cindex options, -Wlarger-than-@var{len} | |
2627 | @item -Wlarger-than-@var{len} | |
2628 | @cindex -Wconversion option | |
2629 | @cindex options, -Wconversion | |
2630 | @item -Wconversion | |
2631 | @cindex -Waggregate-return option | |
2632 | @cindex options, -Waggregate-return | |
2633 | @item -Waggregate-return | |
2634 | @cindex -Wredundant-decls option | |
2635 | @cindex options, -Wredundant-decls | |
2636 | @item -Wredundant-decls | |
2637 | @cindex unsupported warnings | |
2638 | @cindex warnings, unsupported | |
2639 | These options all could have some relevant meaning for | |
2640 | GNU Fortran programs, but are not yet supported. | |
2641 | @end table | |
2642 | ||
2643 | @node Debugging Options | |
2644 | @section Options for Debugging Your Program or GNU Fortran | |
2645 | @cindex options, debugging | |
2646 | @cindex debugging information options | |
2647 | ||
2648 | GNU Fortran has various special options that are used for debugging | |
2649 | either your program or @code{g77}. | |
2650 | ||
2651 | @table @code | |
2652 | @cindex -g option | |
2653 | @cindex options, -g | |
2654 | @item -g | |
2655 | Produce debugging information in the operating system's native format | |
2656 | (stabs, COFF, XCOFF, or DWARF). GDB can work with this debugging | |
2657 | information. | |
2658 | ||
2659 | @cindex common blocks | |
2660 | @cindex equivalence areas | |
2661 | @cindex missing debug features | |
2662 | Support for this option in Fortran programs is incomplete. | |
2663 | In particular, names of variables and arrays in common blocks | |
2664 | or that are storage-associated via @code{EQUIVALENCE} are | |
2665 | unavailable to the debugger. | |
2666 | ||
2667 | However, version 0.5.19 of @code{g77} does provide this information | |
2668 | in a rudimentary way, as controlled by the | |
2669 | @samp{-fdebug-kludge} option. | |
2670 | ||
2671 | @xref{Code Gen Options,,Options for Code Generation Conventions}, | |
2672 | for more information. | |
2673 | @end table | |
2674 | ||
2675 | @xref{Debugging Options,,Options for Debugging Your Program or GNU CC, | |
2676 | gcc,Using and Porting GNU CC}, for more information on debugging options. | |
2677 | ||
2678 | @node Optimize Options | |
2679 | @section Options That Control Optimization | |
2680 | @cindex optimize options | |
2681 | @cindex options, optimization | |
2682 | ||
2683 | Most Fortran users will want to use no optimization when | |
2684 | developing and testing programs, and use @samp{-O} or @samp{-O2} when | |
2685 | compiling programs for late-cycle testing and for production use. | |
95a1b676 CB |
2686 | However, note that certain diagnostics---such as for uninitialized |
2687 | variables---depend on the flow analysis done by @samp{-O}, i.e.@: you | |
2688 | must use @samp{-O} or @samp{-O2} to get such diagnostics. | |
5ff904cd JL |
2689 | |
2690 | The following flags have particular applicability when | |
2691 | compiling Fortran programs: | |
2692 | ||
2693 | @table @code | |
2694 | @cindex -malign-double option | |
2695 | @cindex options, -malign-double | |
2696 | @item -malign-double | |
95a1b676 | 2697 | (Intel x86 architecture only.) |
5ff904cd JL |
2698 | |
2699 | Noticeably improves performance of @code{g77} programs making | |
2700 | heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) data | |
2701 | on some systems. | |
2702 | In particular, systems using Pentium, Pentium Pro, 586, and | |
2703 | 686 implementations | |
2704 | of the i386 architecture execute programs faster when | |
2705 | @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) data are | |
2706 | aligned on 64-bit boundaries | |
2707 | in memory. | |
2708 | ||
2709 | This option can, at least, make benchmark results more consistent | |
2710 | across various system configurations, versions of the program, | |
2711 | and data sets. | |
2712 | ||
2713 | @emph{Note:} The warning in the @code{gcc} documentation about | |
2714 | this option does not apply, generally speaking, to Fortran | |
2715 | code compiled by @code{g77}. | |
2716 | ||
7cceca32 | 2717 | @xref{Aligned Data}, for more information on alignment issues. |
5ff904cd JL |
2718 | |
2719 | @emph{Also also note:} The negative form of @samp{-malign-double} | |
2720 | is @samp{-mno-align-double}, not @samp{-benign-double}. | |
2721 | ||
2722 | @cindex -ffloat-store option | |
2723 | @cindex options, -ffloat-store | |
2724 | @item -ffloat-store | |
26b9526e CB |
2725 | @cindex IEEE 754 conformance |
2726 | @cindex conformance, IEEE 754 | |
2727 | @cindex floating-point, precision | |
0b31330e DL |
2728 | Might help a Fortran program that depends on exact IEEE conformance on |
2729 | some machines, but might slow down a program that doesn't. | |
2730 | ||
26b9526e | 2731 | This option is effective when the floating-point unit is set to work in |
0b31330e | 2732 | IEEE 854 `extended precision'---as it typically is on x86 and m68k GNU |
4e6a1440 | 2733 | systems---rather than IEEE 754 double precision. @samp{-ffloat-store} |
26b9526e | 2734 | tries to remove the extra precision by spilling data from floating-point |
0b31330e DL |
2735 | registers into memory and this typically involves a big performance |
2736 | hit. However, it doesn't affect intermediate results, so that it is | |
2737 | only partially effective. `Excess precision' is avoided in code like: | |
2738 | @smallexample | |
2739 | a = b + c | |
2740 | d = a * e | |
2741 | @end smallexample | |
2742 | but not in code like: | |
2743 | @smallexample | |
2744 | d = (b + c) * e | |
2745 | @end smallexample | |
2746 | ||
811cabee CB |
2747 | For another, potentially better, way of controlling the precision, |
2748 | see @ref{Floating-point precision}. | |
5ff904cd JL |
2749 | |
2750 | @cindex -fforce-mem option | |
2751 | @cindex options, -fforce-mem | |
2752 | @item -fforce-mem | |
2753 | @cindex -fforce-addr option | |
2754 | @cindex options, -fforce-addr | |
2755 | @item -fforce-addr | |
2756 | @cindex loops, speeding up | |
26b9526e | 2757 | @cindex speed, of loops |
5ff904cd JL |
2758 | Might improve optimization of loops. |
2759 | ||
2760 | @cindex -fno-inline option | |
2761 | @cindex options, -fno-inline | |
2762 | @item -fno-inline | |
26b9526e | 2763 | @cindex in-line code |
5ff904cd | 2764 | @cindex compilation, in-line |
95a1b676 | 2765 | @c DL: Only relevant for -O3? |
5ff904cd JL |
2766 | Don't compile statement functions inline. |
2767 | Might reduce the size of a program unit---which might be at | |
2768 | expense of some speed (though it should compile faster). | |
2769 | Note that if you are not optimizing, no functions can be expanded inline. | |
2770 | ||
2771 | @cindex -ffast-math option | |
2772 | @cindex options, -ffast-math | |
2773 | @item -ffast-math | |
26b9526e CB |
2774 | @cindex IEEE 754 conformance |
2775 | @cindex conformance, IEEE 754 | |
5ff904cd JL |
2776 | Might allow some programs designed to not be too dependent |
2777 | on IEEE behavior for floating-point to run faster, or die trying. | |
2778 | ||
2779 | @cindex -fstrength-reduce option | |
2780 | @cindex options, -fstrength-reduce | |
2781 | @item -fstrength-reduce | |
2782 | @cindex loops, speeding up | |
26b9526e | 2783 | @cindex speed, of loops |
95a1b676 | 2784 | @c DL: normally defaulted? |
5ff904cd JL |
2785 | Might make some loops run faster. |
2786 | ||
2787 | @cindex -frerun-cse-after-loop option | |
2788 | @cindex options, -frerun-cse-after-loop | |
2789 | @item -frerun-cse-after-loop | |
2790 | @cindex -fexpensive-optimizations option | |
2791 | @cindex options, -fexpensive-optimizations | |
95a1b676 | 2792 | @c DL: This is -O2? |
5ff904cd JL |
2793 | @item -fexpensive-optimizations |
2794 | @cindex -fdelayed-branch option | |
2795 | @cindex options, -fdelayed-branch | |
2796 | @item -fdelayed-branch | |
2797 | @cindex -fschedule-insns option | |
2798 | @cindex options, -fschedule-insns | |
2799 | @item -fschedule-insns | |
2800 | @cindex -fschedule-insns2 option | |
2801 | @cindex options, -fschedule-insns2 | |
2802 | @item -fschedule-insns2 | |
2803 | @cindex -fcaller-saves option | |
2804 | @cindex options, -fcaller-saves | |
2805 | @item -fcaller-saves | |
2806 | Might improve performance on some code. | |
2807 | ||
2808 | @cindex -funroll-loops option | |
2809 | @cindex options, -funroll-loops | |
2810 | @item -funroll-loops | |
2811 | @cindex loops, unrolling | |
2812 | @cindex unrolling loops | |
26b9526e CB |
2813 | @cindex loops, optimizing |
2814 | @cindex indexed (iterative) @code{DO} | |
2815 | @cindex iterative @code{DO} | |
0b31330e DL |
2816 | @c DL: fixme: Craig doesn't like `indexed' but f95 doesn't seem to |
2817 | @c provide a suitable term | |
26b9526e CB |
2818 | @c CB: I've decided on `iterative', for the time being, and changed |
2819 | @c my previous, rather bizarre, use of `imperative' to that | |
2820 | @c (though `precomputed-trip' would be a more precise adjective) | |
2821 | Typically improves performance on code using iterative @code{DO} loops by | |
0b31330e | 2822 | unrolling them and is probably generally appropriate for Fortran, though |
66d18ad7 | 2823 | it is not turned on at any optimization level. |
0b31330e | 2824 | Note that outer loop unrolling isn't done specifically; decisions about |
66d18ad7 | 2825 | whether to unroll a loop are made on the basis of its instruction count. |
0b31330e DL |
2826 | |
2827 | @c DL: Fixme: This should obviously go somewhere else... | |
2828 | Also, no `loop discovery'@footnote{@dfn{loop discovery} refers to the | |
2829 | process by which a compiler, or indeed any reader of a program, | |
2830 | determines which portions of the program are more likely to be executed | |
2831 | repeatedly as it is being run. Such discovery typically is done early | |
2832 | when compiling using optimization techniques, so the ``discovered'' | |
2833 | loops get more attention---and more run-time resources, such as | |
2834 | registers---from the compiler. It is easy to ``discover'' loops that are | |
2835 | constructed out of looping constructs in the language | |
2836 | (such as Fortran's @code{DO}). For some programs, ``discovering'' loops | |
2837 | constructed out of lower-level constructs (such as @code{IF} and | |
2838 | @code{GOTO}) can lead to generation of more optimal code | |
2839 | than otherwise.} is done, so only loops written with @code{DO} | |
2840 | benefit from loop optimizations, including---but not limited | |
26b9526e CB |
2841 | to---unrolling. Loops written with @code{IF} and @code{GOTO} are not |
2842 | currently recognized as such. This option unrolls only iterative | |
2843 | @code{DO} loops, not @code{DO WHILE} loops. | |
5ff904cd JL |
2844 | |
2845 | @cindex -funroll-all-loops option | |
2846 | @cindex options, -funroll-all-loops | |
26b9526e | 2847 | @cindex DO WHILE |
5ff904cd | 2848 | @item -funroll-all-loops |
0b31330e DL |
2849 | @c DL: Check my understanding of -funroll-all-loops v. -funroll-loops is correct. |
2850 | Probably improves performance on code using @code{DO WHILE} loops by | |
26b9526e | 2851 | unrolling them in addition to iterative @code{DO} loops. In the absence |
4e6a1440 | 2852 | of @code{DO WHILE}, this option is equivalent to @samp{-funroll-loops} |
0b31330e | 2853 | but possibly slower. |
5ff904cd JL |
2854 | |
2855 | @item -fno-move-all-movables | |
2856 | @cindex -fno-move-all-movables option | |
2857 | @cindex options, -fno-move-all-movables | |
2858 | @item -fno-reduce-all-givs | |
2859 | @cindex -fno-reduce-all-givs option | |
2860 | @cindex options, -fno-reduce-all-givs | |
2861 | @item -fno-rerun-loop-opt | |
2862 | @cindex -fno-rerun-loop-opt option | |
2863 | @cindex options, -fno-rerun-loop-opt | |
9a59ff4f CB |
2864 | @emph{Version info:} |
2865 | These options are not supported by | |
2866 | versions of @code{g77} based on @code{gcc} version 2.8. | |
2867 | ||
5ff904cd JL |
2868 | Each of these might improve performance on some code. |
2869 | ||
2870 | Analysis of Fortran code optimization and the resulting | |
2871 | optimizations triggered by the above options were | |
2872 | contributed by Toon Moene (@email{toon@@moene.indiv.nluug.nl}). | |
2873 | ||
2874 | These three options are intended to be removed someday, once | |
2875 | they have helped determine the efficacy of various | |
2876 | approaches to improving the performance of Fortran code. | |
2877 | ||
2878 | Please let us know how use of these options affects | |
2879 | the performance of your production code. | |
2880 | We're particularly interested in code that runs faster | |
2881 | when these options are @emph{disabled}, and in | |
2882 | non-Fortran code that benefits when they are | |
2883 | @emph{enabled} via the above @code{gcc} command-line options. | |
2884 | @end table | |
2885 | ||
2886 | @xref{Optimize Options,,Options That Control Optimization, | |
2887 | gcc,Using and Porting GNU CC}, for more information on options | |
2888 | to optimize the generated machine code. | |
2889 | ||
2890 | @node Preprocessor Options | |
2891 | @section Options Controlling the Preprocessor | |
2892 | @cindex preprocessor options | |
2893 | @cindex options, preprocessor | |
2894 | @cindex cpp program | |
2895 | @cindex programs, cpp | |
2896 | ||
2897 | These options control the C preprocessor, which is run on each C source | |
2898 | file before actual compilation. | |
2899 | ||
2900 | @xref{Preprocessor Options,,Options Controlling the Preprocessor, | |
2901 | gcc,Using and Porting GNU CC}, for information on C preprocessor options. | |
2902 | ||
2903 | @cindex INCLUDE directive | |
2904 | @cindex directive, INCLUDE | |
2905 | Some of these options also affect how @code{g77} processes the | |
2906 | @code{INCLUDE} directive. | |
2907 | Since this directive is processed even when preprocessing | |
2908 | is not requested, it is not described in this section. | |
2909 | @xref{Directory Options,,Options for Directory Search}, for | |
2910 | information on how @code{g77} processes the @code{INCLUDE} directive. | |
2911 | ||
2912 | However, the @code{INCLUDE} directive does not apply | |
2913 | preprocessing to the contents of the included file itself. | |
2914 | ||
2915 | Therefore, any file that contains preprocessor directives | |
2916 | (such as @code{#include}, @code{#define}, and @code{#if}) | |
2917 | must be included via the @code{#include} directive, not | |
2918 | via the @code{INCLUDE} directive. | |
2919 | Therefore, any file containing preprocessor directives, | |
2920 | if included, is necessarily included by a file that itself | |
2921 | contains preprocessor directives. | |
2922 | ||
2923 | @node Directory Options | |
2924 | @section Options for Directory Search | |
26b9526e | 2925 | @cindex directory, options |
5ff904cd JL |
2926 | @cindex options, directory search |
2927 | @cindex search path | |
2928 | ||
2929 | These options affect how the @code{cpp} preprocessor searches | |
2930 | for files specified via the @code{#include} directive. | |
2931 | Therefore, when compiling Fortran programs, they are meaningful | |
46511dd5 | 2932 | when the preprocessor is used. |
5ff904cd JL |
2933 | |
2934 | @cindex INCLUDE directive | |
2935 | @cindex directive, INCLUDE | |
2936 | Some of these options also affect how @code{g77} searches | |
2937 | for files specified via the @code{INCLUDE} directive, | |
2938 | although files included by that directive are not, | |
2939 | themselves, preprocessed. | |
2940 | These options are: | |
2941 | ||
2942 | @table @code | |
2943 | @cindex -I- option | |
2944 | @cindex options, -I- | |
2945 | @item -I- | |
2946 | @cindex -Idir option | |
2947 | @cindex options, -Idir | |
2948 | @item -I@var{dir} | |
26b9526e | 2949 | @cindex directory, search paths for inclusion |
5ff904cd | 2950 | @cindex inclusion, directory search paths for |
26b9526e CB |
2951 | @cindex search paths, for included files |
2952 | @cindex paths, search | |
5ff904cd JL |
2953 | These affect interpretation of the @code{INCLUDE} directive |
2954 | (as well as of the @code{#include} directive of the @code{cpp} | |
2955 | preprocessor). | |
2956 | ||
2957 | Note that @samp{-I@var{dir}} must be specified @emph{without} any | |
2958 | spaces between @samp{-I} and the directory name---that is, | |
2959 | @samp{-Ifoo/bar} is valid, but @samp{-I foo/bar} | |
2960 | is rejected by the @code{g77} compiler (though the preprocessor supports | |
2961 | the latter form). | |
2962 | @c this is due to toplev.c's inflexible option processing | |
2963 | Also note that the general behavior of @samp{-I} and | |
2964 | @code{INCLUDE} is pretty much the same as of @samp{-I} with | |
2965 | @code{#include} in the @code{cpp} preprocessor, with regard to | |
2966 | looking for @file{header.gcc} files and other such things. | |
2967 | ||
2968 | @xref{Directory Options,,Options for Directory Search, | |
2969 | gcc,Using and Porting GNU CC}, for information on the @samp{-I} option. | |
2970 | @end table | |
2971 | ||
2972 | @node Code Gen Options | |
2973 | @section Options for Code Generation Conventions | |
26b9526e | 2974 | @cindex code generation, conventions |
66d18ad7 | 2975 | @cindex options, code generation |
26b9526e | 2976 | @cindex run-time, options |
5ff904cd JL |
2977 | |
2978 | These machine-independent options control the interface conventions | |
2979 | used in code generation. | |
2980 | ||
2981 | Most of them have both positive and negative forms; the negative form | |
2982 | of @samp{-ffoo} would be @samp{-fno-foo}. In the table below, only | |
2983 | one of the forms is listed---the one which is not the default. You | |
2984 | can figure out the other form by either removing @samp{no-} or adding | |
2985 | it. | |
2986 | ||
2987 | @table @code | |
2988 | @cindex -fno-automatic option | |
2989 | @cindex options, -fno-automatic | |
2990 | @item -fno-automatic | |
2991 | @cindex SAVE statement | |
2992 | @cindex statements, SAVE | |
2993 | Treat each program unit as if the @code{SAVE} statement was specified | |
2994 | for every local variable and array referenced in it. | |
2995 | Does not affect common blocks. | |
2996 | (Some Fortran compilers provide this option under | |
2997 | the name @samp{-static}.) | |
2998 | ||
2999 | @cindex -finit-local-zero option | |
3000 | @cindex options, -finit-local-zero | |
3001 | @item -finit-local-zero | |
3002 | @cindex DATA statement | |
3003 | @cindex statements, DATA | |
26b9526e | 3004 | @cindex initialization, of local variables |
5ff904cd JL |
3005 | @cindex variables, initialization of |
3006 | @cindex uninitialized variables | |
3007 | @cindex variables, uninitialized | |
3008 | Specify that variables and arrays that are local to a program unit | |
3009 | (not in a common block and not passed as an argument) are to be initialized | |
3010 | to binary zeros. | |
3011 | ||
3012 | Since there is a run-time penalty for initialization of variables | |
3013 | that are not given the @code{SAVE} attribute, it might be a | |
3014 | good idea to also use @samp{-fno-automatic} with @samp{-finit-local-zero}. | |
3015 | ||
3016 | @cindex -fno-f2c option | |
3017 | @cindex options, -fno-f2c | |
3018 | @item -fno-f2c | |
3019 | @cindex @code{f2c} compatibility | |
3020 | @cindex compatibility, @code{f2c} | |
3021 | Do not generate code designed to be compatible with code generated | |
3022 | by @code{f2c}; use the GNU calling conventions instead. | |
3023 | ||
3024 | The @code{f2c} calling conventions require functions that return | |
3025 | type @code{REAL(KIND=1)} to actually return the C type @code{double}, | |
3026 | and functions that return type @code{COMPLEX} to return the | |
3027 | values via an extra argument in the calling sequence that points | |
3028 | to where to store the return value. | |
3029 | Under the GNU calling conventions, such functions simply return | |
3030 | their results as they would in GNU C---@code{REAL(KIND=1)} functions | |
3031 | return the C type @code{float}, and @code{COMPLEX} functions | |
3032 | return the GNU C type @code{complex} (or its @code{struct} | |
3033 | equivalent). | |
3034 | ||
3035 | This does not affect the generation of code that interfaces with the | |
95a1b676 | 3036 | @code{libg2c} library. |
5ff904cd | 3037 | |
95a1b676 | 3038 | However, because the @code{libg2c} library uses @code{f2c} |
5ff904cd JL |
3039 | calling conventions, @code{g77} rejects attempts to pass |
3040 | intrinsics implemented by routines in this library as actual | |
3041 | arguments when @samp{-fno-f2c} is used, to avoid bugs when | |
3042 | they are actually called by code expecting the GNU calling | |
3043 | conventions to work. | |
3044 | ||
3045 | For example, @samp{INTRINSIC ABS;CALL FOO(ABS)} is | |
3046 | rejected when @samp{-fno-f2c} is in force. | |
3047 | (Future versions of the @code{g77} run-time library might | |
3048 | offer routines that provide GNU-callable versions of the | |
3049 | routines that implement the @code{f2c}-callable intrinsics | |
3050 | that may be passed as actual arguments, so that | |
3051 | valid programs need not be rejected when @samp{-fno-f2c} | |
3052 | is used.) | |
3053 | ||
3054 | @strong{Caution:} If @samp{-fno-f2c} is used when compiling any | |
3055 | source file used in a program, it must be used when compiling | |
3056 | @emph{all} Fortran source files used in that program. | |
3057 | ||
3058 | @c seems kinda dumb to tell people about an option they can't use -- jcb | |
3059 | @c then again, we want users building future-compatible libraries with it. | |
3060 | @cindex -ff2c-library option | |
3061 | @cindex options, -ff2c-library | |
3062 | @item -ff2c-library | |
95a1b676 CB |
3063 | Specify that use of @code{libg2c} (or the original @code{libf2c}) |
3064 | is required. | |
5ff904cd JL |
3065 | This is the default for the current version of @code{g77}. |
3066 | ||
3067 | Currently it is not | |
3068 | valid to specify @samp{-fno-f2c-library}. | |
3069 | This option is provided so users can specify it in shell | |
3070 | scripts that build programs and libraries that require the | |
3071 | @code{libf2c} library, even when being compiled by future | |
3072 | versions of @code{g77} that might otherwise default to | |
3073 | generating code for an incompatible library. | |
3074 | ||
3075 | @cindex -fno-underscoring option | |
3076 | @cindex options, -fno-underscoring | |
3077 | @item -fno-underscoring | |
26b9526e | 3078 | @cindex underscore |
5ff904cd JL |
3079 | @cindex symbol names, underscores |
3080 | @cindex transforming symbol names | |
3081 | @cindex symbol names, transforming | |
3082 | Do not transform names of entities specified in the Fortran | |
3083 | source file by appending underscores to them. | |
3084 | ||
3085 | With @samp{-funderscoring} in effect, @code{g77} appends two underscores | |
3086 | to names with underscores and one underscore to external names with | |
3087 | no underscores. (@code{g77} also appends two underscores to internal | |
3088 | names with underscores to avoid naming collisions with external names. | |
3089 | The @samp{-fno-second-underscore} option disables appending of the | |
3090 | second underscore in all cases.) | |
3091 | ||
3092 | This is done to ensure compatibility with code produced by many | |
3093 | UNIX Fortran compilers, including @code{f2c}, which perform the | |
3094 | same transformations. | |
3095 | ||
3096 | Use of @samp{-fno-underscoring} is not recommended unless you are | |
3097 | experimenting with issues such as integration of (GNU) Fortran into | |
3098 | existing system environments (vis-a-vis existing libraries, tools, and | |
3099 | so on). | |
3100 | ||
3101 | For example, with @samp{-funderscoring}, and assuming other defaults like | |
3102 | @samp{-fcase-lower} and that @samp{j()} and @samp{max_count()} are | |
3103 | external functions while @samp{my_var} and @samp{lvar} are local variables, | |
3104 | a statement like | |
3105 | ||
3106 | @smallexample | |
3107 | I = J() + MAX_COUNT (MY_VAR, LVAR) | |
3108 | @end smallexample | |
3109 | ||
3110 | @noindent | |
3111 | is implemented as something akin to: | |
3112 | ||
3113 | @smallexample | |
3114 | i = j_() + max_count__(&my_var__, &lvar); | |
3115 | @end smallexample | |
3116 | ||
3117 | With @samp{-fno-underscoring}, the same statement is implemented as: | |
3118 | ||
3119 | @smallexample | |
3120 | i = j() + max_count(&my_var, &lvar); | |
3121 | @end smallexample | |
3122 | ||
3123 | Use of @samp{-fno-underscoring} allows direct specification of | |
3124 | user-defined names while debugging and when interfacing @code{g77}-compiled | |
3125 | code with other languages. | |
3126 | ||
3127 | Note that just because the names match does @emph{not} mean that the | |
3128 | interface implemented by @code{g77} for an external name matches the | |
3129 | interface implemented by some other language for that same name. | |
3130 | That is, getting code produced by @code{g77} to link to code produced | |
3131 | by some other compiler using this or any other method can be only a | |
3132 | small part of the overall solution---getting the code generated by | |
3133 | both compilers to agree on issues other than naming can require | |
3134 | significant effort, and, unlike naming disagreements, linkers normally | |
3135 | cannot detect disagreements in these other areas. | |
3136 | ||
3137 | Also, note that with @samp{-fno-underscoring}, the lack of appended | |
3138 | underscores introduces the very real possibility that a user-defined | |
3139 | external name will conflict with a name in a system library, which | |
3140 | could make finding unresolved-reference bugs quite difficult in some | |
3141 | cases---they might occur at program run time, and show up only as | |
3142 | buggy behavior at run time. | |
3143 | ||
3144 | In future versions of @code{g77}, we hope to improve naming and linking | |
3145 | issues so that debugging always involves using the names as they appear | |
3146 | in the source, even if the names as seen by the linker are mangled to | |
3147 | prevent accidental linking between procedures with incompatible | |
3148 | interfaces. | |
3149 | ||
3150 | @cindex -fno-second-underscore option | |
3151 | @cindex options, -fno-second-underscore | |
3152 | @item -fno-second-underscore | |
26b9526e | 3153 | @cindex underscore |
5ff904cd JL |
3154 | @cindex symbol names, underscores |
3155 | @cindex transforming symbol names | |
3156 | @cindex symbol names, transforming | |
3157 | Do not append a second underscore to names of entities specified | |
3158 | in the Fortran source file. | |
3159 | ||
3160 | This option has no effect if @samp{-fno-underscoring} is | |
3161 | in effect. | |
3162 | ||
3163 | Otherwise, with this option, an external name such as @samp{MAX_COUNT} | |
3164 | is implemented as a reference to the link-time external symbol | |
3165 | @samp{max_count_}, instead of @samp{max_count__}. | |
3166 | ||
3167 | @cindex -fno-ident option | |
3168 | @cindex options, -fno-ident | |
3169 | @item -fno-ident | |
3170 | Ignore the @samp{#ident} directive. | |
3171 | ||
3172 | @cindex -fzeros option | |
3173 | @cindex options, -fzeros | |
3174 | @item -fzeros | |
3175 | Treat initial values of zero as if they were any other value. | |
3176 | ||
3177 | As of version 0.5.18, @code{g77} normally treats @code{DATA} and | |
3178 | other statements that are used to specify initial values of zero | |
3179 | for variables and arrays as if no values were actually specified, | |
3180 | in the sense that no diagnostics regarding multiple initializations | |
3181 | are produced. | |
3182 | ||
3183 | This is done to speed up compiling of programs that initialize | |
3184 | large arrays to zeros. | |
3185 | ||
3186 | Use @samp{-fzeros} to revert to the simpler, slower behavior | |
3187 | that can catch multiple initializations by keeping track of | |
3188 | all initializations, zero or otherwise. | |
3189 | ||
3190 | @emph{Caution:} Future versions of @code{g77} might disregard this option | |
3191 | (and its negative form, the default) or interpret it somewhat | |
3192 | differently. | |
3193 | The interpretation changes will affect only non-standard | |
3194 | programs; standard-conforming programs should not be affected. | |
3195 | ||
3196 | @cindex -fdebug-kludge option | |
3197 | @cindex options, -fdebug-kludge | |
3198 | @item -fdebug-kludge | |
3199 | Emit information on @code{COMMON} and @code{EQUIVALENCE} members | |
3200 | that might help users of debuggers work around lack of proper debugging | |
3201 | information on such members. | |
3202 | ||
3203 | As of version 0.5.19, @code{g77} offers this option to emit | |
3204 | information on members of aggregate areas to help users while debugging. | |
3205 | This information consists of establishing the type and contents of each | |
3206 | such member so that, when a debugger is asked to print the contents, | |
3207 | the printed information provides rudimentary debugging information. | |
3208 | This information identifies the name of the aggregate area (either the | |
3209 | @code{COMMON} block name, or the @code{g77}-assigned name for the | |
3210 | @code{EQUIVALENCE} name) and the offset, in bytes, of the member from | |
3211 | the beginning of the area. | |
3212 | ||
3213 | Using @code{gdb}, this information is not coherently displayed in the Fortran | |
3214 | language mode, so temporarily switching to the C language mode to display the | |
3215 | information is suggested. | |
3216 | Use @samp{set language c} and @samp{set language fortran} to accomplish this. | |
3217 | ||
3218 | For example: | |
3219 | ||
3220 | @smallexample | |
3221 | COMMON /X/A,B | |
3222 | EQUIVALENCE (C,D) | |
3223 | CHARACTER XX*50 | |
3224 | EQUIVALENCE (I,XX(20:20)) | |
3225 | END | |
3226 | ||
3227 | GDB is free software and you are welcome to distribute copies of it | |
3228 | under certain conditions; type "show copying" to see the conditions. | |
3229 | There is absolutely no warranty for GDB; type "show warranty" for details. | |
3230 | GDB 4.16 (lm-gnits-dwim), Copyright 1996 Free Software Foundation, Inc... | |
3231 | (gdb) b MAIN__ | |
3232 | Breakpoint 1 at 0t1200000201120112: file cd.f, line 5. | |
3233 | (gdb) r | |
3234 | Starting program: /home/user/a.out | |
3235 | ||
3236 | Breakpoint 1, MAIN__ () at cd.f:5 | |
3237 | Current language: auto; currently fortran | |
3238 | (gdb) set language c | |
3239 | Warning: the current language does not match this frame. | |
3240 | (gdb) p a | |
3241 | $2 = "At (COMMON) `x_' plus 0 bytes" | |
3242 | (gdb) p b | |
3243 | $3 = "At (COMMON) `x_' plus 4 bytes" | |
3244 | (gdb) p c | |
3245 | $4 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes" | |
3246 | (gdb) p d | |
3247 | $5 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes" | |
3248 | (gdb) p i | |
3249 | $6 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 20 bytes" | |
3250 | (gdb) p xx | |
3251 | $7 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 1 bytes" | |
3252 | (gdb) set language fortran | |
66d18ad7 | 3253 | (gdb) |
5ff904cd JL |
3254 | @end smallexample |
3255 | ||
3256 | @noindent | |
3257 | Use @samp{-fdebug-kludge} to generate this information, | |
3258 | which might make some programs noticeably larger. | |
3259 | ||
3260 | @emph{Caution:} Future versions of @code{g77} might disregard this option | |
3261 | (and its negative form). | |
3262 | Current plans call for this to happen when published versions of @code{g77} | |
3263 | and @code{gdb} exist that provide proper access to debugging information on | |
3264 | @code{COMMON} and @code{EQUIVALENCE} members. | |
3265 | ||
d8955e17 CB |
3266 | @cindex -femulate-complex option |
3267 | @cindex options, -femulate-complex | |
3268 | @item -femulate-complex | |
3269 | Implement @code{COMPLEX} arithmetic via emulation, | |
3270 | instead of using the facilities of | |
5ff904cd | 3271 | the @code{gcc} back end that provide direct support of |
d8955e17 | 3272 | @code{complex} arithmetic. |
5ff904cd | 3273 | |
d8955e17 | 3274 | (@code{gcc} had some bugs in its back-end support |
5ff904cd | 3275 | for @code{complex} arithmetic, due primarily to the support not being |
d8955e17 CB |
3276 | completed as of version 2.8.1 and @code{egcs} 1.1.2.) |
3277 | ||
3278 | Use @samp{-femulate-complex} if you suspect code-generation bugs, | |
3279 | or experience compiler crashes, | |
3280 | that might result from @code{g77} using the @code{COMPLEX} support | |
3281 | in the @code{gcc} back end. | |
3282 | If using that option fixes the bugs or crashes you are seeing, | |
3283 | that indicates a likely @code{g77} bugs | |
3284 | (though, all compiler crashes are considered bugs), | |
3285 | so, please report it. | |
3286 | (Note that the known bugs, now believed fixed, produced compiler crashes | |
3287 | rather than causing the generation of incorrect code.) | |
5ff904cd JL |
3288 | |
3289 | Use of this option should not affect how Fortran code compiled | |
3290 | by @code{g77} works in terms of its interfaces to other code, | |
3291 | e.g. that compiled by @code{f2c}. | |
3292 | ||
d8955e17 | 3293 | @emph{Caution:} Future versions of @code{g77} might ignore both forms |
5ff904cd JL |
3294 | of this option. |
3295 | ||
5ff904cd JL |
3296 | @cindex -falias-check option |
3297 | @cindex options, -falias-check | |
3298 | @cindex -fargument-alias option | |
3299 | @cindex options, -fargument-alias | |
3300 | @cindex -fargument-noalias option | |
3301 | @cindex options, -fargument-noalias | |
3302 | @cindex -fno-argument-noalias-global option | |
3303 | @cindex options, -fno-argument-noalias-global | |
3304 | @item -falias-check | |
3305 | @item -fargument-alias | |
3306 | @item -fargument-noalias | |
3307 | @item -fno-argument-noalias-global | |
9a59ff4f CB |
3308 | @emph{Version info:} |
3309 | These options are not supported by | |
3310 | versions of @code{g77} based on @code{gcc} version 2.8. | |
3311 | ||
5ff904cd JL |
3312 | These options specify to what degree aliasing |
3313 | (overlap) | |
3314 | is permitted between | |
3315 | arguments (passed as pointers) and @code{COMMON} (external, or | |
3316 | public) storage. | |
3317 | ||
3318 | The default for Fortran code, as mandated by the FORTRAN 77 and | |
3319 | Fortran 90 standards, is @samp{-fargument-noalias-global}. | |
3320 | The default for code written in the C language family is | |
3321 | @samp{-fargument-alias}. | |
3322 | ||
3323 | Note that, on some systems, compiling with @samp{-fforce-addr} in | |
3324 | effect can produce more optimal code when the default aliasing | |
3325 | options are in effect (and when optimization is enabled). | |
3326 | ||
3327 | @xref{Aliasing Assumed To Work}, for detailed information on the implications | |
3328 | of compiling Fortran code that depends on the ability to alias dummy | |
3329 | arguments. | |
3330 | ||
3331 | @cindex -fno-globals option | |
3332 | @cindex options, -fno-globals | |
3333 | @item -fno-globals | |
3334 | @cindex global names, warning | |
3335 | @cindex warnings, global names | |
c89524a8 CB |
3336 | @cindex in-line code |
3337 | @cindex compilation, in-line | |
5ff904cd JL |
3338 | Disable diagnostics about inter-procedural |
3339 | analysis problems, such as disagreements about the | |
3340 | type of a function or a procedure's argument, | |
3341 | that might cause a compiler crash when attempting | |
3342 | to inline a reference to a procedure within a | |
3343 | program unit. | |
3344 | (The diagnostics themselves are still produced, but | |
3345 | as warnings, unless @samp{-Wno-globals} is specified, | |
3346 | in which case no relevant diagnostics are produced.) | |
3347 | ||
3348 | Further, this option disables such inlining, to | |
3349 | avoid compiler crashes resulting from incorrect | |
3350 | code that would otherwise be diagnosed. | |
3351 | ||
3352 | As such, this option might be quite useful when | |
3353 | compiling existing, ``working'' code that happens | |
c89524a8 CB |
3354 | to have a few bugs that do not generally show themselves, |
3355 | but which @code{g77} diagnoses. | |
5ff904cd JL |
3356 | |
3357 | Use of this option therefore has the effect of | |
3358 | instructing @code{g77} to behave more like it did | |
3359 | up through version 0.5.19.1, when it paid little or | |
3360 | no attention to disagreements between program units | |
3361 | about a procedure's type and argument information, | |
3362 | and when it performed no inlining of procedures | |
3363 | (except statement functions). | |
3364 | ||
3365 | Without this option, @code{g77} defaults to performing | |
3366 | the potentially inlining procedures as it started doing | |
3367 | in version 0.5.20, but as of version 0.5.21, it also | |
3368 | diagnoses disagreements that might cause such inlining | |
c89524a8 CB |
3369 | to crash the compiler as (fatal) errors, |
3370 | and warns about similar disagreements | |
3371 | that are currently believed to not | |
3372 | likely to result in the compiler later crashing | |
3373 | or producing incorrect code. | |
6b55276e CB |
3374 | |
3375 | @cindex -fsubscript-check option | |
3376 | @cindex -ff2c-subscript-check option | |
3377 | @item -fsubscript-check | |
3378 | @itemx -ff2c-subscript-check | |
3379 | @cindex bounds checking | |
3380 | @cindex range checking | |
3381 | @cindex array bounds checking | |
3382 | @cindex subscript checking | |
3383 | @cindex substring checking | |
3384 | @cindex checking subscripts | |
3385 | @cindex checking substrings | |
3386 | Enable generation of run-time checks for array subscripts | |
3387 | and substring start and end points | |
3388 | against the (locally) declared minimum and maximum values. | |
3389 | ||
3390 | The current implementation uses the @code{libf2c} | |
3391 | library routine @code{s_rnge} to print the diagnostic. | |
3392 | ||
3393 | However, whereas @code{f2c} generates a single check per | |
3394 | reference for a multi-dimensional array, of the computed | |
3395 | offset against the valid offset range (0 through the size of the array), | |
3396 | @code{g77} generates a single check per @emph{subscript} expression. | |
3397 | This catches some cases of potential bugs that @code{f2c} does not, | |
3398 | such as references to below the beginning of an assumed-size array. | |
3399 | ||
3400 | @code{g77} also generates checks for @code{CHARACTER} substring references, | |
3401 | something @code{f2c} currently does not do. | |
3402 | ||
3403 | Since a future version of @code{g77} might use a different implementation, | |
3404 | use the new @samp{-ff2c-subscript-check} option | |
3405 | if your application requires use of @code{s_rnge} or a compile-time diagnostic. | |
3406 | ||
3407 | @emph{Note:} To provide more detailed information on the offending subscript, | |
3408 | @code{g77} provides @code{s_rnge} | |
3409 | with somewhat differently-formatted information. | |
3410 | Here's a sample diagnostic: | |
3411 | ||
3412 | @smallexample | |
3413 | Subscript out of range on file line 4, procedure rnge.f/bf. | |
3414 | Attempt to access the -6-th element of variable b[subscript-2-of-2]. | |
3415 | Aborted | |
3416 | @end smallexample | |
3417 | ||
3418 | The above message indicates that the offending source line is | |
3419 | line 4 of the file @file{rnge.f}, | |
3420 | within the program unit (or statement function) named @samp{bf}. | |
3421 | The offended array is named @samp{b}. | |
3422 | The offended array dimension is the second for a two-dimensional array, | |
3423 | and the offending, computed subscript expression was @samp{-6}. | |
3424 | ||
3425 | For a @code{CHARACTER} substring reference, the second line has | |
3426 | this appearance: | |
3427 | ||
3428 | @smallexample | |
3429 | Attempt to access the 11-th element of variable a[start-substring]. | |
3430 | @end smallexample | |
3431 | ||
3432 | This indicates that the offended @code{CHARACTER} variable or array | |
3433 | is named @samp{a}, | |
3434 | the offended substring position is the starting (leftmost) position, | |
3435 | and the offending substring expression is @samp{11}. | |
3436 | ||
3437 | (Though the verbage of @code{s_rnge} is not ideal | |
3438 | for the purpose of the @code{g77} compiler, | |
3439 | the above information should provide adequate diagnostic abilities | |
3440 | to it users.) | |
5ff904cd JL |
3441 | @end table |
3442 | ||
3443 | @xref{Code Gen Options,,Options for Code Generation Conventions, | |
3444 | gcc,Using and Porting GNU CC}, for information on more options | |
3445 | offered by the GBE | |
3446 | shared by @code{g77}, @code{gcc}, and other GNU compilers. | |
3447 | ||
3448 | Some of these do @emph{not} work when compiling programs written in Fortran: | |
3449 | ||
3450 | @table @code | |
3451 | @cindex -fpcc-struct-return option | |
3452 | @cindex options, -fpcc-struct-return | |
3453 | @item -fpcc-struct-return | |
3454 | @cindex -freg-struct-return option | |
3455 | @cindex options, -freg-struct-return | |
3456 | @item -freg-struct-return | |
3457 | You should not use these except strictly the same way as you | |
95a1b676 | 3458 | used them to build the version of @code{libg2c} with which |
5ff904cd JL |
3459 | you will be linking all code compiled by @code{g77} with the |
3460 | same option. | |
3461 | ||
3462 | @cindex -fshort-double option | |
3463 | @cindex options, -fshort-double | |
3464 | @item -fshort-double | |
3465 | This probably either has no effect on Fortran programs, or | |
3466 | makes them act loopy. | |
3467 | ||
3468 | @cindex -fno-common option | |
3469 | @cindex options, -fno-common | |
3470 | @item -fno-common | |
3471 | Do not use this when compiling Fortran programs, | |
3472 | or there will be Trouble. | |
3473 | ||
3474 | @cindex -fpack-struct option | |
3475 | @cindex options, -fpack-struct | |
3476 | @item -fpack-struct | |
95a1b676 | 3477 | This probably will break any calls to the @code{libg2c} library, |
5ff904cd JL |
3478 | at the very least, even if it is built with the same option. |
3479 | @end table | |
3480 | ||
3481 | @node Environment Variables | |
3482 | @section Environment Variables Affecting GNU Fortran | |
3483 | @cindex environment variables | |
3484 | ||
3485 | GNU Fortran currently does not make use of any environment | |
3486 | variables to control its operation above and beyond those | |
3487 | that affect the operation of @code{gcc}. | |
3488 | ||
3489 | @xref{Environment Variables,,Environment Variables Affecting GNU CC, | |
3490 | gcc,Using and Porting GNU CC}, for information on environment | |
3491 | variables. | |
3492 | ||
3493 | @include news.texi | |
3494 | ||
51efa892 CB |
3495 | @set USERVISONLY |
3496 | @include news.texi | |
3497 | @clear USERVISONLY | |
5ff904cd JL |
3498 | |
3499 | @node Language | |
3500 | @chapter The GNU Fortran Language | |
3501 | ||
3502 | @cindex standard, ANSI FORTRAN 77 | |
3503 | @cindex ANSI FORTRAN 77 standard | |
3504 | @cindex reference works | |
3505 | GNU Fortran supports a variety of extensions to, and dialects | |
3506 | of, the Fortran language. | |
3507 | Its primary base is the ANSI FORTRAN 77 standard, currently available on | |
95a1b676 CB |
3508 | the network at |
3509 | @uref{http://www.fortran.com/fortran/F77_std/rjcnf0001.html} | |
3510 | or as monolithic text at | |
3511 | @uref{http://www.fortran.com/fortran/F77_std/f77_std.html}. | |
5ff904cd JL |
3512 | It offers some extensions that are popular among users |
3513 | of UNIX @code{f77} and @code{f2c} compilers, some that | |
3514 | are popular among users of other compilers (such as Digital | |
3515 | products), some that are popular among users of the | |
3516 | newer Fortran 90 standard, and some that are introduced | |
3517 | by GNU Fortran. | |
3518 | ||
3519 | @cindex textbooks | |
3520 | (If you need a text on Fortran, | |
3521 | a few freely available electronic references have pointers from | |
58dd1c34 DL |
3522 | @uref{http://www.fortran.com/fortran/Books/}. There is a `cooperative |
3523 | net project', @cite{User Notes on Fortran Programming} at | |
3524 | @uref{ftp://vms.huji.ac.il/fortran/} and mirrors elsewhere; some of this | |
3525 | material might not apply specifically to @code{g77}.) | |
5ff904cd JL |
3526 | |
3527 | Part of what defines a particular implementation of a Fortran | |
3528 | system, such as @code{g77}, is the particular characteristics | |
3529 | of how it supports types, constants, and so on. | |
3530 | Much of this is left up to the implementation by the various | |
3531 | Fortran standards and accepted practice in the industry. | |
3532 | ||
3533 | The GNU Fortran @emph{language} is described below. | |
3534 | Much of the material is organized along the same lines | |
3535 | as the ANSI FORTRAN 77 standard itself. | |
3536 | ||
3537 | @xref{Other Dialects}, for information on features @code{g77} supports | |
3538 | that are not part of the GNU Fortran language. | |
3539 | ||
3540 | @emph{Note}: This portion of the documentation definitely needs a lot | |
3541 | of work! | |
3542 | ||
3543 | @menu | |
3544 | Relationship to the ANSI FORTRAN 77 standard: | |
3545 | * Direction of Language Development:: Where GNU Fortran is headed. | |
3546 | * Standard Support:: Degree of support for the standard. | |
3547 | ||
3548 | Extensions to the ANSI FORTRAN 77 standard: | |
3549 | * Conformance:: | |
3550 | * Notation Used:: | |
3551 | * Terms and Concepts:: | |
3552 | * Characters Lines Sequence:: | |
3553 | * Data Types and Constants:: | |
3554 | * Expressions:: | |
3555 | * Specification Statements:: | |
3556 | * Control Statements:: | |
3557 | * Functions and Subroutines:: | |
3558 | * Scope and Classes of Names:: | |
0b31330e DL |
3559 | * I/O:: |
3560 | * Fortran 90 Features:: | |
5ff904cd JL |
3561 | @end menu |
3562 | ||
3563 | @node Direction of Language Development | |
3564 | @section Direction of Language Development | |
3565 | @cindex direction of language development | |
3566 | @cindex features, language | |
26b9526e | 3567 | @cindex language, features |
5ff904cd JL |
3568 | |
3569 | The purpose of the following description of the GNU Fortran | |
3570 | language is to promote wide portability of GNU Fortran programs. | |
3571 | ||
3572 | GNU Fortran is an evolving language, due to the | |
3573 | fact that @code{g77} itself is in beta test. | |
3574 | Some current features of the language might later | |
3575 | be redefined as dialects of Fortran supported by @code{g77} | |
3576 | when better ways to express these features are added to @code{g77}, | |
3577 | for example. | |
3578 | Such features would still be supported by | |
3579 | @code{g77}, but would be available only when | |
3580 | one or more command-line options were used. | |
3581 | ||
3582 | The GNU Fortran @emph{language} is distinct from the | |
3583 | GNU Fortran @emph{compilation system} (@code{g77}). | |
3584 | ||
3585 | For example, @code{g77} supports various dialects of | |
3586 | Fortran---in a sense, these are languages other than | |
3587 | GNU Fortran---though its primary | |
3588 | purpose is to support the GNU Fortran language, which also is | |
3589 | described in its documentation and by its implementation. | |
3590 | ||
3591 | On the other hand, non-GNU compilers might offer | |
3592 | support for the GNU Fortran language, and are encouraged | |
3593 | to do so. | |
3594 | ||
3595 | Currently, the GNU Fortran language is a fairly fuzzy object. | |
3596 | It represents something of a cross between what @code{g77} accepts | |
3597 | when compiling using the prevailing defaults and what this | |
3598 | document describes as being part of the language. | |
3599 | ||
3600 | Future versions of @code{g77} are expected to clarify the | |
3601 | definition of the language in the documentation. | |
3602 | Often, this will mean adding new features to the language, in the form | |
3603 | of both new documentation and new support in @code{g77}. | |
3604 | However, it might occasionally mean removing a feature | |
3605 | from the language itself to ``dialect'' status. | |
3606 | In such a case, the documentation would be adjusted | |
3607 | to reflect the change, and @code{g77} itself would likely be changed | |
3608 | to require one or more command-line options to continue supporting | |
3609 | the feature. | |
3610 | ||
3611 | The development of the GNU Fortran language is intended to strike | |
3612 | a balance between: | |
3613 | ||
3614 | @itemize @bullet | |
3615 | @item | |
3616 | Serving as a mostly-upwards-compatible language from the | |
3617 | de facto UNIX Fortran dialect as supported by @code{f77}. | |
3618 | ||
3619 | @item | |
3620 | Offering new, well-designed language features. | |
3621 | Attributes of such features include | |
3622 | not making existing code any harder to read | |
3623 | (for those who might be unaware that the new | |
3624 | features are not in use) and | |
3625 | not making state-of-the-art | |
3626 | compilers take longer to issue diagnostics, | |
3627 | among others. | |
3628 | ||
3629 | @item | |
3630 | Supporting existing, well-written code without gratuitously | |
3631 | rejecting non-standard constructs, regardless of the origin | |
3632 | of the code (its dialect). | |
3633 | ||
3634 | @item | |
3635 | Offering default behavior and command-line options to reduce | |
3636 | and, where reasonable, eliminate the need for programmers to make | |
3637 | any modifications to code that already works in existing | |
3638 | production environments. | |
3639 | ||
3640 | @item | |
3641 | Diagnosing constructs that have different meanings in different | |
3642 | systems, languages, and dialects, while offering clear, | |
3643 | less ambiguous ways to express each of the different meanings | |
3644 | so programmers can change their code appropriately. | |
3645 | @end itemize | |
3646 | ||
3647 | One of the biggest practical challenges for the developers of the | |
3648 | GNU Fortran language is meeting the sometimes contradictory demands | |
3649 | of the above items. | |
3650 | ||
3651 | For example, a feature might be widely used in one popular environment, | |
3652 | but the exact same code that utilizes that feature might not work | |
3653 | as expected---perhaps it might mean something entirely different---in | |
3654 | another popular environment. | |
3655 | ||
3656 | Traditionally, Fortran compilers---even portable ones---have solved this | |
3657 | problem by simply offering the appropriate feature to users of | |
3658 | the respective systems. | |
3659 | This approach treats users of various Fortran systems and dialects | |
3660 | as remote ``islands'', or camps, of programmers, and assume that these | |
3661 | camps rarely come into contact with each other (or, | |
3662 | especially, with each other's code). | |
3663 | ||
3664 | Project GNU takes a radically different approach to software and language | |
3665 | design, in that it assumes that users of GNU software do not necessarily | |
3666 | care what kind of underlying system they are using, regardless | |
3667 | of whether they are using software (at the user-interface | |
3668 | level) or writing it (for example, writing Fortran or C code). | |
3669 | ||
3670 | As such, GNU users rarely need consider just what kind of underlying | |
3671 | hardware (or, in many cases, operating system) they are using at any | |
3672 | particular time. | |
3673 | They can use and write software designed for a general-purpose, | |
46511dd5 | 3674 | widely portable, heterogenous environment---the GNU environment. |
5ff904cd JL |
3675 | |
3676 | In line with this philosophy, GNU Fortran must evolve into a product | |
3677 | that is widely ported and portable not only in the sense that it can | |
3678 | be successfully built, installed, and run by users, but in the larger | |
3679 | sense that its users can use it in the same way, and expect largely the | |
3680 | same behaviors from it, regardless of the kind of system they are using | |
3681 | at any particular time. | |
3682 | ||
3683 | This approach constrains the solutions @code{g77} can use to resolve | |
3684 | conflicts between various camps of Fortran users. | |
3685 | If these two camps disagree about what a particular construct should | |
3686 | mean, @code{g77} cannot simply be changed to treat that particular construct as | |
3687 | having one meaning without comment (such as a warning), lest the users | |
3688 | expecting it to have the other meaning are unpleasantly surprised that | |
3689 | their code misbehaves when executed. | |
3690 | ||
3691 | The use of the ASCII backslash character in character constants is | |
3692 | an excellent (and still somewhat unresolved) example of this kind of | |
3693 | controversy. | |
3694 | @xref{Backslash in Constants}. | |
3695 | Other examples are likely to arise in the future, as @code{g77} developers | |
3696 | strive to improve its ability to accept an ever-wider variety of existing | |
3697 | Fortran code without requiring significant modifications to said code. | |
3698 | ||
3699 | Development of GNU Fortran is further constrained by the desire | |
3700 | to avoid requiring programmers to change their code. | |
3701 | This is important because it allows programmers, administrators, | |
3702 | and others to more faithfully evaluate and validate @code{g77} | |
3703 | (as an overall product and as new versions are distributed) | |
3704 | without having to support multiple versions of their programs | |
3705 | so that they continue to work the same way on their existing | |
3706 | systems (non-GNU perhaps, but possibly also earlier versions | |
3707 | of @code{g77}). | |
3708 | ||
3709 | @node Standard Support | |
3710 | @section ANSI FORTRAN 77 Standard Support | |
3711 | @cindex ANSI FORTRAN 77 support | |
26b9526e CB |
3712 | @cindex standard, support for |
3713 | @cindex support, FORTRAN 77 | |
5ff904cd JL |
3714 | @cindex compatibility, FORTRAN 77 |
3715 | @cindex FORTRAN 77 compatibility | |
3716 | ||
3717 | GNU Fortran supports ANSI FORTRAN 77 with the following caveats. | |
3718 | In summary, the only ANSI FORTRAN 77 features @code{g77} doesn't | |
3719 | support are those that are probably rarely used in actual code, | |
3720 | some of which are explicitly disallowed by the Fortran 90 standard. | |
3721 | ||
3722 | @menu | |
3723 | * No Passing External Assumed-length:: CHAR*(*) CFUNC restriction. | |
3724 | * No Passing Dummy Assumed-length:: CHAR*(*) CFUNC restriction. | |
3725 | * No Pathological Implied-DO:: No @samp{((@dots{}, I=@dots{}), I=@dots{})}. | |
3726 | * No Useless Implied-DO:: No @samp{(A, I=1, 1)}. | |
3727 | @end menu | |
3728 | ||
3729 | @node No Passing External Assumed-length | |
3730 | @subsection No Passing External Assumed-length | |
3731 | ||
3732 | @code{g77} disallows passing of an external procedure | |
3733 | as an actual argument if the procedure's | |
3734 | type is declared @code{CHARACTER*(*)}. For example: | |
3735 | ||
3736 | @example | |
3737 | CHARACTER*(*) CFUNC | |
3738 | EXTERNAL CFUNC | |
3739 | CALL FOO(CFUNC) | |
3740 | END | |
3741 | @end example | |
3742 | ||
3743 | @noindent | |
3744 | It isn't clear whether the standard considers this conforming. | |
3745 | ||
3746 | @node No Passing Dummy Assumed-length | |
3747 | @subsection No Passing Dummy Assumed-length | |
3748 | ||
3749 | @code{g77} disallows passing of a dummy procedure | |
3750 | as an actual argument if the procedure's | |
3751 | type is declared @code{CHARACTER*(*)}. | |
3752 | ||
3753 | @example | |
3754 | SUBROUTINE BAR(CFUNC) | |
3755 | CHARACTER*(*) CFUNC | |
3756 | EXTERNAL CFUNC | |
3757 | CALL FOO(CFUNC) | |
3758 | END | |
3759 | @end example | |
3760 | ||
3761 | @noindent | |
3762 | It isn't clear whether the standard considers this conforming. | |
3763 | ||
3764 | @node No Pathological Implied-DO | |
3765 | @subsection No Pathological Implied-DO | |
3766 | ||
3767 | The @code{DO} variable for an implied-@code{DO} construct in a | |
3768 | @code{DATA} statement may not be used as the @code{DO} variable | |
3769 | for an outer implied-@code{DO} construct. For example, this | |
3770 | fragment is disallowed by @code{g77}: | |
3771 | ||
3772 | @smallexample | |
3773 | DATA ((A(I, I), I= 1, 10), I= 1, 10) /@dots{}/ | |
3774 | @end smallexample | |
3775 | ||
3776 | @noindent | |
3777 | This also is disallowed by Fortran 90, as it offers no additional | |
3778 | capabilities and would have a variety of possible meanings. | |
3779 | ||
3780 | Note that it is @emph{very} unlikely that any production Fortran code | |
3781 | tries to use this unsupported construct. | |
3782 | ||
3783 | @node No Useless Implied-DO | |
3784 | @subsection No Useless Implied-DO | |
3785 | ||
3786 | An array element initializer in an implied-@code{DO} construct in a | |
3787 | @code{DATA} statement must contain at least one reference to the @code{DO} | |
3788 | variables of each outer implied-@code{DO} construct. For example, | |
3789 | this fragment is disallowed by @code{g77}: | |
3790 | ||
3791 | @smallexample | |
3792 | DATA (A, I= 1, 1) /1./ | |
3793 | @end smallexample | |
3794 | ||
3795 | @noindent | |
3796 | This also is disallowed by Fortran 90, as FORTRAN 77's more permissive | |
3797 | requirements offer no additional capabilities. | |
3798 | However, @code{g77} doesn't necessarily diagnose all cases | |
3799 | where this requirement is not met. | |
3800 | ||
3801 | Note that it is @emph{very} unlikely that any production Fortran code | |
3802 | tries to use this unsupported construct. | |
3803 | ||
3804 | @node Conformance | |
3805 | @section Conformance | |
3806 | ||
3807 | (The following information augments or overrides the information in | |
3808 | Section 1.4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
3809 | language. | |
3810 | Chapter 1 of that document otherwise serves as the basis | |
3811 | for the relevant aspects of GNU Fortran.) | |
3812 | ||
3813 | The definition of the GNU Fortran language is akin to that of | |
3814 | the ANSI FORTRAN 77 language in that it does not generally require | |
3815 | conforming implementations to diagnose cases where programs do | |
3816 | not conform to the language. | |
3817 | ||
3818 | However, @code{g77} as a compiler is being developed in a way that | |
3819 | is intended to enable it to diagnose such cases in an easy-to-understand | |
3820 | manner. | |
3821 | ||
3822 | A program that conforms to the GNU Fortran language should, when | |
3823 | compiled, linked, and executed using a properly installed @code{g77} | |
3824 | system, perform as described by the GNU Fortran language definition. | |
3825 | Reasons for different behavior include, among others: | |
3826 | ||
3827 | @itemize @bullet | |
3828 | @item | |
3829 | Use of resources (memory---heap, stack, and so on; disk space; CPU | |
3830 | time; etc.) exceeds those of the system. | |
3831 | ||
3832 | @item | |
3833 | Range and/or precision of calculations required by the program | |
3834 | exceeds that of the system. | |
3835 | ||
3836 | @item | |
3837 | Excessive reliance on behaviors that are system-dependent | |
3838 | (non-portable Fortran code). | |
3839 | ||
3840 | @item | |
3841 | Bugs in the program. | |
3842 | ||
3843 | @item | |
3844 | Bug in @code{g77}. | |
3845 | ||
3846 | @item | |
3847 | Bugs in the system. | |
3848 | @end itemize | |
3849 | ||
3850 | Despite these ``loopholes'', the availability of a clear specification | |
3851 | of the language of programs submitted to @code{g77}, as this document | |
3852 | is intended to provide, is considered an important aspect of providing | |
3853 | a robust, clean, predictable Fortran implementation. | |
3854 | ||
3855 | The definition of the GNU Fortran language, while having no special | |
3856 | legal status, can therefore be viewed as a sort of contract, or agreement. | |
3857 | This agreement says, in essence, ``if you write a program in this language, | |
3858 | and run it in an environment (such as a @code{g77} system) that supports | |
3859 | this language, the program should behave in a largely predictable way''. | |
3860 | ||
3861 | @node Notation Used | |
3862 | @section Notation Used in This Chapter | |
3863 | ||
3864 | (The following information augments or overrides the information in | |
3865 | Section 1.5 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
3866 | language. | |
3867 | Chapter 1 of that document otherwise serves as the basis | |
3868 | for the relevant aspects of GNU Fortran.) | |
3869 | ||
3870 | In this chapter, ``must'' denotes a requirement, ``may'' denotes permission, | |
3871 | and ``must not'' and ``may not'' denote prohibition. | |
3872 | Terms such as ``might'', ``should'', and ``can'' generally add little or | |
3873 | nothing in the way of weight to the GNU Fortran language itself, | |
3874 | but are used to explain or illustrate the language. | |
3875 | ||
3876 | For example: | |
3877 | ||
3878 | @display | |
3879 | ``The @code{FROBNITZ} statement must precede all executable | |
3880 | statements in a program unit, and may not specify any dummy | |
3881 | arguments. It may specify local or common variables and arrays. | |
3882 | Its use should be limited to portions of the program designed to | |
3883 | be non-portable and system-specific, because it might cause the | |
3884 | containing program unit to behave quite differently on different | |
3885 | systems.'' | |
3886 | @end display | |
3887 | ||
3888 | Insofar as the GNU Fortran language is specified, | |
3889 | the requirements and permissions denoted by the above sample statement | |
3890 | are limited to the placement of the statement and the kinds of | |
3891 | things it may specify. | |
3892 | The rest of the statement---the content regarding non-portable portions | |
3893 | of the program and the differing behavior of program units containing | |
3894 | the @code{FROBNITZ} statement---does not pertain the GNU Fortran | |
3895 | language itself. | |
3896 | That content offers advice and warnings about the @code{FROBNITZ} | |
3897 | statement. | |
3898 | ||
3899 | @emph{Remember:} The GNU Fortran language definition specifies | |
3900 | both what constitutes a valid GNU Fortran program and how, | |
3901 | given such a program, a valid GNU Fortran implementation is | |
3902 | to interpret that program. | |
3903 | ||
3904 | It is @emph{not} incumbent upon a valid GNU Fortran implementation | |
3905 | to behave in any particular way, any consistent way, or any | |
3906 | predictable way when it is asked to interpret input that is | |
3907 | @emph{not} a valid GNU Fortran program. | |
3908 | ||
3909 | Such input is said to have @dfn{undefined} behavior when | |
3910 | interpreted by a valid GNU Fortran implementation, though | |
3911 | an implementation may choose to specify behaviors for some | |
3912 | cases of inputs that are not valid GNU Fortran programs. | |
3913 | ||
3914 | Other notation used herein is that of the GNU texinfo format, | |
3915 | which is used to generate printed hardcopy, on-line hypertext | |
3916 | (Info), and on-line HTML versions, all from a single source | |
3917 | document. | |
3918 | This notation is used as follows: | |
3919 | ||
3920 | @itemize @bullet | |
3921 | @item | |
3922 | Keywords defined by the GNU Fortran language are shown | |
3923 | in uppercase, as in: @code{COMMON}, @code{INTEGER}, and | |
3924 | @code{BLOCK DATA}. | |
3925 | ||
3926 | Note that, in practice, many Fortran programs are written | |
3927 | in lowercase---uppercase is used in this manual as a | |
3928 | means to readily distinguish keywords and sample Fortran-related | |
3929 | text from the prose in this document. | |
3930 | ||
3931 | @item | |
3932 | Portions of actual sample program, input, or output text | |
3933 | look like this: @samp{Actual program text}. | |
3934 | ||
3935 | Generally, uppercase is used for all Fortran-specific and | |
3936 | Fortran-related text, though this does not always include | |
3937 | literal text within Fortran code. | |
3938 | ||
3939 | For example: @samp{PRINT *, 'My name is Bob'}. | |
3940 | ||
3941 | @item | |
3942 | A metasyntactic variable---that is, a name used in this document | |
3943 | to serve as a placeholder for whatever text is used by the | |
4e6a1440 | 3944 | user or programmer---appears as shown in the following example: |
5ff904cd JL |
3945 | |
3946 | ``The @code{INTEGER @var{ivar}} statement specifies that | |
3947 | @var{ivar} is a variable or array of type @code{INTEGER}.'' | |
3948 | ||
3949 | In the above example, any valid text may be substituted for | |
3950 | the metasyntactic variable @var{ivar} to make the statement | |
3951 | apply to a specific instance, as long as the same text is | |
3952 | substituted for @emph{both} occurrences of @var{ivar}. | |
3953 | ||
3954 | @item | |
3955 | Ellipses (``@dots{}'') are used to indicate further text that | |
3956 | is either unimportant or expanded upon further, elsewhere. | |
3957 | ||
3958 | @item | |
3959 | Names of data types are in the style of Fortran 90, in most | |
3960 | cases. | |
3961 | ||
3962 | @xref{Kind Notation}, for information on the relationship | |
3963 | between Fortran 90 nomenclature (such as @code{INTEGER(KIND=1)}) | |
3964 | and the more traditional, less portably concise nomenclature | |
3965 | (such as @code{INTEGER*4}). | |
3966 | @end itemize | |
3967 | ||
3968 | @node Terms and Concepts | |
3969 | @section Fortran Terms and Concepts | |
3970 | ||
3971 | (The following information augments or overrides the information in | |
3972 | Chapter 2 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
3973 | language. | |
3974 | Chapter 2 of that document otherwise serves as the basis | |
3975 | for the relevant aspects of GNU Fortran.) | |
3976 | ||
3977 | @menu | |
3978 | * Syntactic Items:: | |
3979 | * Statements Comments Lines:: | |
3980 | * Scope of Names and Labels:: | |
3981 | @end menu | |
3982 | ||
3983 | @node Syntactic Items | |
3984 | @subsection Syntactic Items | |
3985 | ||
3986 | (Corresponds to Section 2.2 of ANSI X3.9-1978 FORTRAN 77.) | |
3987 | ||
d79904b8 | 3988 | @cindex limits, lengths of names |
5ff904cd JL |
3989 | In GNU Fortran, a symbolic name is at least one character long, |
3990 | and has no arbitrary upper limit on length. | |
3991 | However, names of entities requiring external linkage (such as | |
3992 | external functions, external subroutines, and @code{COMMON} areas) | |
3993 | might be restricted to some arbitrary length by the system. | |
3994 | Such a restriction is no more constrained than that of one | |
3995 | through six characters. | |
3996 | ||
3997 | Underscores (@samp{_}) are accepted in symbol names after the first | |
3998 | character (which must be a letter). | |
3999 | ||
4000 | @node Statements Comments Lines | |
4001 | @subsection Statements, Comments, and Lines | |
4002 | ||
4003 | (Corresponds to Section 2.3 of ANSI X3.9-1978 FORTRAN 77.) | |
4004 | ||
26b9526e CB |
4005 | @cindex trailing comment |
4006 | @cindex comment | |
4007 | @cindex characters, comment | |
4008 | @cindex ! | |
4009 | @cindex exclamation point | |
4010 | @cindex continuation character | |
4011 | @cindex characters, continuation | |
5ff904cd JL |
4012 | Use of an exclamation point (@samp{!}) to begin a |
4013 | trailing comment (a comment that extends to the end of the same | |
4014 | source line) is permitted under the following conditions: | |
4015 | ||
4016 | @itemize @bullet | |
4017 | @item | |
4018 | The exclamation point does not appear in column 6. | |
4019 | Otherwise, it is treated as an indicator of a continuation | |
4020 | line. | |
4021 | ||
4022 | @item | |
0b31330e | 4023 | The exclamation point appears outside a character or Hollerith |
5ff904cd JL |
4024 | constant. |
4025 | Otherwise, the exclamation point is considered part of the | |
4026 | constant. | |
4027 | ||
4028 | @item | |
4029 | The exclamation point appears to the left of any other possible | |
4030 | trailing comment. | |
4031 | That is, a trailing comment may contain exclamation points | |
4032 | in their commentary text. | |
4033 | @end itemize | |
4034 | ||
26b9526e CB |
4035 | @cindex ; |
4036 | @cindex semicolon | |
5ff904cd JL |
4037 | @cindex statements, separated by semicolon |
4038 | Use of a semicolon (@samp{;}) as a statement separator | |
4039 | is permitted under the following conditions: | |
4040 | ||
4041 | @itemize @bullet | |
4042 | @item | |
0b31330e | 4043 | The semicolon appears outside a character or Hollerith |
5ff904cd JL |
4044 | constant. |
4045 | Otherwise, the semicolon is considered part of the | |
4046 | constant. | |
4047 | ||
4048 | @item | |
4049 | The semicolon appears to the left of a trailing comment. | |
4050 | Otherwise, the semicolon is considered part of that | |
4051 | comment. | |
4052 | ||
4053 | @item | |
4054 | Neither a logical @code{IF} statement nor a non-construct | |
4055 | @code{WHERE} statement (a Fortran 90 feature) may be | |
4056 | followed (in the same, possibly continued, line) by | |
4057 | a semicolon used as a statement separator. | |
4058 | ||
4059 | This restriction avoids the confusion | |
4060 | that can result when reading a line such as: | |
4061 | ||
4062 | @smallexample | |
4063 | IF (VALIDP) CALL FOO; CALL BAR | |
4064 | @end smallexample | |
4065 | ||
4066 | @noindent | |
4067 | Some readers might think the @samp{CALL BAR} is executed | |
4068 | only if @samp{VALIDP} is @code{.TRUE.}, while others might | |
4069 | assume its execution is unconditional. | |
4070 | ||
4071 | (At present, @code{g77} does not diagnose code that | |
4072 | violates this restriction.) | |
4073 | @end itemize | |
4074 | ||
4075 | @node Scope of Names and Labels | |
4076 | @subsection Scope of Symbolic Names and Statement Labels | |
4077 | @cindex scope | |
4078 | ||
4079 | (Corresponds to Section 2.9 of ANSI X3.9-1978 FORTRAN 77.) | |
4080 | ||
4081 | Included in the list of entities that have a scope of a | |
4082 | program unit are construct names (a Fortran 90 feature). | |
4083 | @xref{Construct Names}, for more information. | |
4084 | ||
4085 | @node Characters Lines Sequence | |
4086 | @section Characters, Lines, and Execution Sequence | |
4087 | ||
4088 | (The following information augments or overrides the information in | |
4089 | Chapter 3 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
4090 | language. | |
4091 | Chapter 3 of that document otherwise serves as the basis | |
4092 | for the relevant aspects of GNU Fortran.) | |
4093 | ||
4094 | @menu | |
4095 | * Character Set:: | |
4096 | * Lines:: | |
4097 | * Continuation Line:: | |
4098 | * Statements:: | |
4099 | * Statement Labels:: | |
4100 | * Order:: | |
4101 | * INCLUDE:: | |
0b31330e | 4102 | * Cpp-style directives:: |
5ff904cd JL |
4103 | @end menu |
4104 | ||
4105 | @node Character Set | |
4106 | @subsection GNU Fortran Character Set | |
4107 | @cindex characters | |
4108 | ||
4109 | (Corresponds to Section 3.1 of ANSI X3.9-1978 FORTRAN 77.) | |
4110 | ||
4111 | Letters include uppercase letters (the twenty-six characters | |
4112 | of the English alphabet) and lowercase letters (their lowercase | |
4113 | equivalent). | |
4114 | Generally, lowercase letters may be used in place of uppercase | |
0b31330e | 4115 | letters, though in character and Hollerith constants, they |
5ff904cd JL |
4116 | are distinct. |
4117 | ||
4118 | Special characters include: | |
4119 | ||
4120 | @itemize @bullet | |
4121 | @item | |
26b9526e CB |
4122 | @cindex ; |
4123 | @cindex semicolon | |
5ff904cd JL |
4124 | Semicolon (@samp{;}) |
4125 | ||
4126 | @item | |
26b9526e CB |
4127 | @cindex ! |
4128 | @cindex exclamation point | |
5ff904cd JL |
4129 | Exclamation point (@samp{!}) |
4130 | ||
4131 | @item | |
26b9526e CB |
4132 | @cindex " |
4133 | @cindex double quote | |
5ff904cd JL |
4134 | Double quote (@samp{"}) |
4135 | ||
4136 | @item | |
26b9526e CB |
4137 | @cindex \ |
4138 | @cindex backslash | |
5ff904cd JL |
4139 | Backslash (@samp{\}) |
4140 | ||
4141 | @item | |
26b9526e CB |
4142 | @cindex ? |
4143 | @cindex question mark | |
5ff904cd JL |
4144 | Question mark (@samp{?}) |
4145 | ||
4146 | @item | |
26b9526e CB |
4147 | @cindex # |
4148 | @cindex hash mark | |
4149 | @cindex pound sign | |
5ff904cd JL |
4150 | Hash mark (@samp{#}) |
4151 | ||
4152 | @item | |
26b9526e CB |
4153 | @cindex & |
4154 | @cindex ampersand | |
5ff904cd JL |
4155 | Ampersand (@samp{&}) |
4156 | ||
4157 | @item | |
26b9526e CB |
4158 | @cindex % |
4159 | @cindex percent sign | |
5ff904cd JL |
4160 | Percent sign (@samp{%}) |
4161 | ||
4162 | @item | |
26b9526e CB |
4163 | @cindex _ |
4164 | @cindex underscore | |
5ff904cd JL |
4165 | Underscore (@samp{_}) |
4166 | ||
4167 | @item | |
26b9526e CB |
4168 | @cindex < |
4169 | @cindex open angle | |
4170 | @cindex left angle | |
4171 | @cindex open bracket | |
4172 | @cindex left bracket | |
5ff904cd JL |
4173 | Open angle (@samp{<}) |
4174 | ||
4175 | @item | |
26b9526e CB |
4176 | @cindex > |
4177 | @cindex close angle | |
4178 | @cindex right angle | |
4179 | @cindex close bracket | |
4180 | @cindex right bracket | |
5ff904cd JL |
4181 | Close angle (@samp{>}) |
4182 | ||
4183 | @item | |
4184 | The FORTRAN 77 special characters (@key{SPC}, @samp{=}, | |
4185 | @samp{+}, @samp{-}, @samp{*}, @samp{/}, @samp{(}, | |
4186 | @samp{)}, @samp{,}, @samp{.}, @samp{$}, @samp{'}, | |
4187 | and @samp{:}) | |
4188 | @end itemize | |
4189 | ||
26b9526e CB |
4190 | @cindex blank |
4191 | @cindex space | |
4192 | @cindex SPC | |
5ff904cd JL |
4193 | Note that this document refers to @key{SPC} as @dfn{space}, |
4194 | while X3.9-1978 FORTRAN 77 refers to it as @dfn{blank}. | |
4195 | ||
4196 | @node Lines | |
4197 | @subsection Lines | |
4198 | @cindex lines | |
4199 | @cindex source file format | |
26b9526e CB |
4200 | @cindex source format |
4201 | @cindex file, source | |
5ff904cd JL |
4202 | @cindex source code |
4203 | @cindex code, source | |
4204 | @cindex fixed form | |
4205 | @cindex free form | |
4206 | ||
4207 | (Corresponds to Section 3.2 of ANSI X3.9-1978 FORTRAN 77.) | |
4208 | ||
4209 | The way a Fortran compiler views source files depends entirely on the | |
4210 | implementation choices made for the compiler, since those choices | |
4211 | are explicitly left to the implementation by the published Fortran | |
4212 | standards. | |
4213 | ||
4214 | The GNU Fortran language mandates a view applicable to UNIX-like | |
4215 | text files---files that are made up of an arbitrary number of lines, | |
4216 | each with an arbitrary number of characters (sometimes called stream-based | |
4217 | files). | |
4218 | ||
4219 | This view does not apply to types of files that are specified as | |
4220 | having a particular number of characters on every single line (sometimes | |
4221 | referred to as record-based files). | |
4222 | ||
4223 | Because a ``line in a program unit is a sequence of 72 characters'', | |
4224 | to quote X3.9-1978, the GNU Fortran language specifies that a | |
4225 | stream-based text file is translated to GNU Fortran lines as follows: | |
4226 | ||
4227 | @itemize @bullet | |
4228 | @item | |
4229 | A newline in the file is the character that represents the end of | |
4230 | a line of text to the underlying system. | |
4231 | For example, on ASCII-based systems, a newline is the @key{NL} | |
4232 | character, which has ASCII value 12 (decimal). | |
4233 | ||
4234 | @item | |
4235 | Each newline in the file serves to end the line of text that precedes | |
4236 | it (and that does not contain a newline). | |
4237 | ||
4238 | @item | |
4239 | The end-of-file marker (@code{EOF}) also serves to end the line | |
4240 | of text that precedes it (and that does not contain a newline). | |
4241 | ||
4242 | @item | |
26b9526e CB |
4243 | @cindex blank |
4244 | @cindex space | |
4245 | @cindex SPC | |
5ff904cd JL |
4246 | Any line of text that is shorter than 72 characters is padded to that length |
4247 | with spaces (called ``blanks'' in the standard). | |
4248 | ||
4249 | @item | |
4250 | Any line of text that is longer than 72 characters is truncated to that | |
4251 | length, but the truncated remainder must consist entirely of spaces. | |
4252 | ||
4253 | @item | |
4254 | Characters other than newline and the GNU Fortran character set | |
4255 | are invalid. | |
4256 | @end itemize | |
4257 | ||
4258 | For the purposes of the remainder of this description of the GNU | |
4259 | Fortran language, the translation described above has already | |
4260 | taken place, unless otherwise specified. | |
4261 | ||
4262 | The result of the above translation is that the source file appears, | |
4263 | in terms of the remainder of this description of the GNU Fortran language, | |
4264 | as if it had an arbitrary | |
4265 | number of 72-character lines, each character being among the GNU Fortran | |
4266 | character set. | |
4267 | ||
4268 | For example, if the source file itself has two newlines in a row, | |
4269 | the second newline becomes, after the above translation, a single | |
4270 | line containing 72 spaces. | |
4271 | ||
4272 | @node Continuation Line | |
4273 | @subsection Continuation Line | |
26b9526e | 4274 | @cindex continuation line, number of |
5ff904cd JL |
4275 | @cindex lines, continuation |
4276 | @cindex number of continuation lines | |
26b9526e | 4277 | @cindex limits, continuation lines |
5ff904cd JL |
4278 | |
4279 | (Corresponds to Section 3.2.3 of ANSI X3.9-1978 FORTRAN 77.) | |
4280 | ||
4281 | A continuation line is any line that both | |
4282 | ||
4283 | @itemize @bullet | |
4284 | @item | |
4285 | Contains a continuation character, and | |
4286 | ||
4287 | @item | |
4288 | Contains only spaces in columns 1 through 5 | |
4289 | @end itemize | |
4290 | ||
4291 | A continuation character is any character of the GNU Fortran character set | |
4292 | other than space (@key{SPC}) or zero (@samp{0}) | |
4293 | in column 6, or a digit (@samp{0} through @samp{9}) in column | |
4294 | 7 through 72 of a line that has only spaces to the left of that | |
4295 | digit. | |
4296 | ||
4297 | The continuation character is ignored as far as the content of | |
4298 | the statement is concerned. | |
4299 | ||
4300 | The GNU Fortran language places no limit on the number of | |
4301 | continuation lines in a statement. | |
4302 | In practice, the limit depends on a variety of factors, such as | |
4303 | available memory, statement content, and so on, but no | |
4304 | GNU Fortran system may impose an arbitrary limit. | |
4305 | ||
4306 | @node Statements | |
4307 | @subsection Statements | |
4308 | ||
4309 | (Corresponds to Section 3.3 of ANSI X3.9-1978 FORTRAN 77.) | |
4310 | ||
4311 | Statements may be written using an arbitrary number of continuation | |
4312 | lines. | |
4313 | ||
4314 | Statements may be separated using the semicolon (@samp{;}), except | |
4315 | that the logical @code{IF} and non-construct @code{WHERE} statements | |
4316 | may not be separated from subsequent statements using only a semicolon | |
4317 | as statement separator. | |
4318 | ||
4319 | The @code{END PROGRAM}, @code{END SUBROUTINE}, @code{END FUNCTION}, | |
4320 | and @code{END BLOCK DATA} statements are alternatives to the @code{END} | |
4321 | statement. | |
4322 | These alternatives may be written as normal statements---they are not | |
4323 | subject to the restrictions of the @code{END} statement. | |
4324 | ||
4325 | However, no statement other than @code{END} may have an initial line | |
4326 | that appears to be an @code{END} statement---even @code{END PROGRAM}, | |
4327 | for example, must not be written as: | |
4328 | ||
4329 | @example | |
4330 | END | |
4331 | &PROGRAM | |
4332 | @end example | |
4333 | ||
4334 | @node Statement Labels | |
4335 | @subsection Statement Labels | |
4336 | ||
4337 | (Corresponds to Section 3.4 of ANSI X3.9-1978 FORTRAN 77.) | |
4338 | ||
4339 | A statement separated from its predecessor via a semicolon may be | |
4340 | labeled as follows: | |
4341 | ||
4342 | @itemize @bullet | |
4343 | @item | |
4344 | The semicolon is followed by the label for the statement, | |
4345 | which in turn follows the label. | |
4346 | ||
4347 | @item | |
4348 | The label must be no more than five digits in length. | |
4349 | ||
4350 | @item | |
4351 | The first digit of the label for the statement is not | |
4352 | the first non-space character on a line. | |
4353 | Otherwise, that character is treated as a continuation | |
4354 | character. | |
4355 | @end itemize | |
4356 | ||
4357 | A statement may have only one label defined for it. | |
4358 | ||
4359 | @node Order | |
4360 | @subsection Order of Statements and Lines | |
4361 | ||
4362 | (Corresponds to Section 3.5 of ANSI X3.9-1978 FORTRAN 77.) | |
4363 | ||
4364 | Generally, @code{DATA} statements may precede executable statements. | |
4365 | However, specification statements pertaining to any entities | |
4366 | initialized by a @code{DATA} statement must precede that @code{DATA} | |
4367 | statement. | |
4368 | For example, | |
4369 | after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but | |
4370 | @samp{INTEGER J} is permitted. | |
4371 | ||
4372 | The last line of a program unit may be an @code{END} statement, | |
4373 | or may be: | |
4374 | ||
4375 | @itemize @bullet | |
4376 | @item | |
4377 | An @code{END PROGRAM} statement, if the program unit is a main program. | |
4378 | ||
4379 | @item | |
4380 | An @code{END SUBROUTINE} statement, if the program unit is a subroutine. | |
4381 | ||
4382 | @item | |
4383 | An @code{END FUNCTION} statement, if the program unit is a function. | |
4384 | ||
4385 | @item | |
4386 | An @code{END BLOCK DATA} statement, if the program unit is a block data. | |
4387 | @end itemize | |
4388 | ||
4389 | @node INCLUDE | |
4390 | @subsection Including Source Text | |
26b9526e | 4391 | @cindex INCLUDE directive |
5ff904cd JL |
4392 | |
4393 | Additional source text may be included in the processing of | |
4394 | the source file via the @code{INCLUDE} directive: | |
4395 | ||
4396 | @example | |
4397 | INCLUDE @var{filename} | |
4398 | @end example | |
4399 | ||
4400 | @noindent | |
4401 | The source text to be included is identified by @var{filename}, | |
4402 | which is a literal GNU Fortran character constant. | |
4403 | The meaning and interpretation of @var{filename} depends on the | |
4404 | implementation, but typically is a filename. | |
4405 | ||
4406 | (@code{g77} treats it as a filename that it searches for | |
4407 | in the current directory and/or directories specified | |
4408 | via the @samp{-I} command-line option.) | |
4409 | ||
4410 | The effect of the @code{INCLUDE} directive is as if the | |
4411 | included text directly replaced the directive in the source | |
4412 | file prior to interpretation of the program. | |
4413 | Included text may itself use @code{INCLUDE}. | |
4414 | The depth of nested @code{INCLUDE} references depends on | |
4415 | the implementation, but typically is a positive integer. | |
4416 | ||
4417 | This virtual replacement treats the statements and @code{INCLUDE} | |
4418 | directives in the included text as syntactically distinct from | |
4419 | those in the including text. | |
4420 | ||
4421 | Therefore, the first non-comment line of the included text | |
4422 | must not be a continuation line. | |
4423 | The included text must therefore have, after the non-comment | |
4424 | lines, either an initial line (statement), an @code{INCLUDE} | |
4425 | directive, or nothing (the end of the included text). | |
4426 | ||
4427 | Similarly, the including text may end the @code{INCLUDE} | |
4428 | directive with a semicolon or the end of the line, but it | |
4429 | cannot follow an @code{INCLUDE} directive at the end of its | |
4430 | line with a continuation line. | |
4431 | Thus, the last statement in an included text may not be | |
4432 | continued. | |
4433 | ||
4434 | Any statements between two @code{INCLUDE} directives on the | |
4435 | same line are treated as if they appeared in between the | |
4436 | respective included texts. | |
4437 | For example: | |
4438 | ||
4439 | @smallexample | |
4440 | INCLUDE 'A'; PRINT *, 'B'; INCLUDE 'C'; END PROGRAM | |
4441 | @end smallexample | |
4442 | ||
4443 | @noindent | |
4444 | If the text included by @samp{INCLUDE 'A'} constitutes | |
4445 | a @samp{PRINT *, 'A'} statement and the text included by | |
4446 | @samp{INCLUDE 'C'} constitutes a @samp{PRINT *, 'C'} statement, | |
4447 | then the output of the above sample program would be | |
4448 | ||
4449 | @example | |
4450 | A | |
4451 | B | |
4452 | C | |
4453 | @end example | |
4454 | ||
4455 | @noindent | |
4456 | (with suitable allowances for how an implementation defines | |
4457 | its handling of output). | |
4458 | ||
4459 | Included text must not include itself directly or indirectly, | |
4460 | regardless of whether the @var{filename} used to reference | |
4461 | the text is the same. | |
4462 | ||
4463 | Note that @code{INCLUDE} is @emph{not} a statement. | |
4464 | As such, it is neither a non-executable or executable | |
4465 | statement. | |
4466 | However, if the text it includes constitutes one or more | |
4467 | executable statements, then the placement of @code{INCLUDE} | |
4468 | is subject to effectively the same restrictions as those | |
4469 | on executable statements. | |
4470 | ||
4471 | An @code{INCLUDE} directive may be continued across multiple | |
4472 | lines as if it were a statement. | |
4473 | This permits long names to be used for @var{filename}. | |
4474 | ||
0b31330e DL |
4475 | @node Cpp-style directives |
4476 | @subsection Cpp-style directives | |
4477 | @cindex # | |
4478 | @cindex preprocessor | |
4479 | ||
4480 | @code{cpp} output-style @code{#} directives @xref{C Preprocessor | |
4481 | Output,,, cpp, The C Preprocessor}, are recognized by the compiler even | |
4482 | when the preprocessor isn't run on the input (as it is when compiling | |
4483 | @samp{.F} files). (Note the distinction between these @code{cpp} | |
4484 | @code{#} @emph{output} directives and @code{#line} @emph{input} | |
4485 | directives.) | |
4486 | ||
5ff904cd JL |
4487 | @node Data Types and Constants |
4488 | @section Data Types and Constants | |
4489 | ||
4490 | (The following information augments or overrides the information in | |
4491 | Chapter 4 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
4492 | language. | |
4493 | Chapter 4 of that document otherwise serves as the basis | |
4494 | for the relevant aspects of GNU Fortran.) | |
4495 | ||
4496 | To more concisely express the appropriate types for | |
4497 | entities, this document uses the more concise | |
4498 | Fortran 90 nomenclature such as @code{INTEGER(KIND=1)} | |
4499 | instead of the more traditional, but less portably concise, | |
4500 | byte-size-based nomenclature such as @code{INTEGER*4}, | |
4501 | wherever reasonable. | |
4502 | ||
4503 | When referring to generic types---in contexts where the | |
4504 | specific precision and range of a type are not important---this | |
4505 | document uses the generic type names @code{INTEGER}, @code{LOGICAL}, | |
4506 | @code{REAL}, @code{COMPLEX}, and @code{CHARACTER}. | |
4507 | ||
4508 | In some cases, the context requires specification of a | |
4509 | particular type. | |
4510 | This document uses the @samp{KIND=} notation to accomplish | |
4511 | this throughout, sometimes supplying the more traditional | |
4512 | notation for clarification, though the traditional notation | |
4513 | might not work the same way on all GNU Fortran implementations. | |
4514 | ||
4515 | Use of @samp{KIND=} makes this document more concise because | |
4516 | @code{g77} is able to define values for @samp{KIND=} that | |
4517 | have the same meanings on all systems, due to the way the | |
4518 | Fortran 90 standard specifies these values are to be used. | |
4519 | ||
4520 | (In particular, that standard permits an implementation to | |
4521 | arbitrarily assign nonnegative values. | |
4522 | There are four distinct sets of assignments: one to the @code{CHARACTER} | |
4523 | type; one to the @code{INTEGER} type; one to the @code{LOGICAL} type; | |
4524 | and the fourth to both the @code{REAL} and @code{COMPLEX} types. | |
4525 | Implementations are free to assign these values in any order, | |
4526 | leave gaps in the ordering of assignments, and assign more than | |
4527 | one value to a representation.) | |
4528 | ||
4529 | This makes @samp{KIND=} values superior to the values used | |
4530 | in non-standard statements such as @samp{INTEGER*4}, because | |
4531 | the meanings of the values in those statements vary from machine | |
4532 | to machine, compiler to compiler, even operating system to | |
4533 | operating system. | |
4534 | ||
4535 | However, use of @samp{KIND=} is @emph{not} generally recommended | |
4536 | when writing portable code (unless, for example, the code is | |
4537 | going to be compiled only via @code{g77}, which is a widely | |
4538 | ported compiler). | |
4539 | GNU Fortran does not yet have adequate language constructs to | |
4540 | permit use of @samp{KIND=} in a fashion that would make the | |
4541 | code portable to Fortran 90 implementations; and, this construct | |
4542 | is known to @emph{not} be accepted by many popular FORTRAN 77 | |
4543 | implementations, so it cannot be used in code that is to be ported | |
4544 | to those. | |
4545 | ||
4546 | The distinction here is that this document is able to use | |
4547 | specific values for @samp{KIND=} to concisely document the | |
4548 | types of various operations and operands. | |
4549 | ||
4550 | A Fortran program should use the FORTRAN 77 designations for the | |
4551 | appropriate GNU Fortran types---such as @code{INTEGER} for | |
4552 | @code{INTEGER(KIND=1)}, @code{REAL} for @code{REAL(KIND=1)}, | |
4553 | and @code{DOUBLE COMPLEX} for @code{COMPLEX(KIND=2)}---and, | |
4554 | where no such designations exist, make use of appropriate | |
4555 | techniques (preprocessor macros, parameters, and so on) | |
4556 | to specify the types in a fashion that may be easily adjusted | |
4557 | to suit each particular implementation to which the program | |
4558 | is ported. | |
4559 | (These types generally won't need to be adjusted for ports of | |
4560 | @code{g77}.) | |
4561 | ||
4562 | Further details regarding GNU Fortran data types and constants | |
4563 | are provided below. | |
4564 | ||
4565 | @menu | |
4566 | * Types:: | |
4567 | * Constants:: | |
4568 | * Integer Type:: | |
4569 | * Character Type:: | |
4570 | @end menu | |
4571 | ||
4572 | @node Types | |
4573 | @subsection Data Types | |
4574 | ||
4575 | (Corresponds to Section 4.1 of ANSI X3.9-1978 FORTRAN 77.) | |
4576 | ||
4577 | GNU Fortran supports these types: | |
4578 | ||
4579 | @enumerate | |
4580 | @item | |
4581 | Integer (generic type @code{INTEGER}) | |
4582 | ||
4583 | @item | |
4584 | Real (generic type @code{REAL}) | |
4585 | ||
4586 | @item | |
4587 | Double precision | |
4588 | ||
4589 | @item | |
4590 | Complex (generic type @code{COMPLEX}) | |
4591 | ||
4592 | @item | |
4593 | Logical (generic type @code{LOGICAL}) | |
4594 | ||
4595 | @item | |
4596 | Character (generic type @code{CHARACTER}) | |
4597 | ||
4598 | @item | |
4599 | Double Complex | |
4600 | @end enumerate | |
4601 | ||
4602 | (The types numbered 1 through 6 above are standard FORTRAN 77 types.) | |
4603 | ||
4604 | The generic types shown above are referred to in this document | |
4605 | using only their generic type names. | |
4606 | Such references usually indicate that any specific type (kind) | |
4607 | of that generic type is valid. | |
4608 | ||
4609 | For example, a context described in this document as accepting | |
4610 | the @code{COMPLEX} type also is likely to accept the | |
4611 | @code{DOUBLE COMPLEX} type. | |
4612 | ||
4613 | The GNU Fortran language supports three ways to specify | |
4614 | a specific kind of a generic type. | |
4615 | ||
4616 | @menu | |
4617 | * Double Notation:: As in @code{DOUBLE COMPLEX}. | |
4618 | * Star Notation:: As in @code{INTEGER*4}. | |
4619 | * Kind Notation:: As in @code{INTEGER(KIND=1)}. | |
4620 | @end menu | |
4621 | ||
4622 | @node Double Notation | |
4623 | @subsubsection Double Notation | |
4624 | ||
4625 | The GNU Fortran language supports two uses of the keyword | |
4626 | @code{DOUBLE} to specify a specific kind of type: | |
4627 | ||
4628 | @itemize @bullet | |
4629 | @item | |
4630 | @code{DOUBLE PRECISION}, equivalent to @code{REAL(KIND=2)} | |
4631 | ||
4632 | @item | |
4633 | @code{DOUBLE COMPLEX}, equivalent to @code{COMPLEX(KIND=2)} | |
4634 | @end itemize | |
4635 | ||
4636 | Use one of the above forms where a type name is valid. | |
4637 | ||
4638 | While use of this notation is popular, it doesn't scale | |
4639 | well in a language or dialect rich in intrinsic types, | |
4640 | as is the case for the GNU Fortran language (especially | |
4641 | planned future versions of it). | |
4642 | ||
4643 | After all, one rarely sees type names such as @samp{DOUBLE INTEGER}, | |
4644 | @samp{QUADRUPLE REAL}, or @samp{QUARTER INTEGER}. | |
4645 | Instead, @code{INTEGER*8}, @code{REAL*16}, and @code{INTEGER*1} | |
4646 | often are substituted for these, respectively, even though they | |
4647 | do not always have the same meanings on all systems. | |
4648 | (And, the fact that @samp{DOUBLE REAL} does not exist as such | |
4649 | is an inconsistency.) | |
4650 | ||
4651 | Therefore, this document uses ``double notation'' only on occasion | |
4652 | for the benefit of those readers who are accustomed to it. | |
4653 | ||
4654 | @node Star Notation | |
4655 | @subsubsection Star Notation | |
4656 | @cindex *@var{n} notation | |
4657 | ||
4658 | The following notation specifies the storage size for a type: | |
4659 | ||
4660 | @smallexample | |
4661 | @var{generic-type}*@var{n} | |
4662 | @end smallexample | |
4663 | ||
4664 | @noindent | |
4665 | @var{generic-type} must be a generic type---one of | |
4666 | @code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL}, | |
4667 | or @code{CHARACTER}. | |
4668 | @var{n} must be one or more digits comprising a decimal | |
4669 | integer number greater than zero. | |
4670 | ||
4671 | Use the above form where a type name is valid. | |
4672 | ||
4673 | The @samp{*@var{n}} notation specifies that the amount of storage | |
4674 | occupied by variables and array elements of that type is @var{n} | |
4675 | times the storage occupied by a @code{CHARACTER*1} variable. | |
4676 | ||
4677 | This notation might indicate a different degree of precision and/or | |
4678 | range for such variables and array elements, and the functions that | |
4679 | return values of types using this notation. | |
4680 | It does not limit the precision or range of values of that type | |
4681 | in any particular way---use explicit code to do that. | |
4682 | ||
4683 | Further, the GNU Fortran language requires no particular values | |
4684 | for @var{n} to be supported by an implementation via the @samp{*@var{n}} | |
4685 | notation. | |
4686 | @code{g77} supports @code{INTEGER*1} (as @code{INTEGER(KIND=3)}) | |
4687 | on all systems, for example, | |
4688 | but not all implementations are required to do so, and @code{g77} | |
4689 | is known to not support @code{REAL*1} on most (or all) systems. | |
4690 | ||
4691 | As a result, except for @var{generic-type} of @code{CHARACTER}, | |
4692 | uses of this notation should be limited to isolated | |
4693 | portions of a program that are intended to handle system-specific | |
4694 | tasks and are expected to be non-portable. | |
4695 | ||
4696 | (Standard FORTRAN 77 supports the @samp{*@var{n}} notation for | |
4697 | only @code{CHARACTER}, where it signifies not only the amount | |
4698 | of storage occupied, but the number of characters in entities | |
4699 | of that type. | |
4700 | However, almost all Fortran compilers have supported this | |
4701 | notation for generic types, though with a variety of meanings | |
4702 | for @var{n}.) | |
4703 | ||
4704 | Specifications of types using the @samp{*@var{n}} notation | |
4705 | always are interpreted as specifications of the appropriate | |
4706 | types described in this document using the @samp{KIND=@var{n}} | |
4707 | notation, described below. | |
4708 | ||
4709 | While use of this notation is popular, it doesn't serve well | |
4710 | in the context of a widely portable dialect of Fortran, such as | |
4711 | the GNU Fortran language. | |
4712 | ||
4713 | For example, even on one particular machine, two or more popular | |
4714 | Fortran compilers might well disagree on the size of a type | |
4715 | declared @code{INTEGER*2} or @code{REAL*16}. | |
4716 | Certainly there | |
4717 | is known to be disagreement over such things among Fortran | |
4718 | compilers on @emph{different} systems. | |
4719 | ||
4720 | Further, this notation offers no elegant way to specify sizes | |
4721 | that are not even multiples of the ``byte size'' typically | |
4722 | designated by @code{INTEGER*1}. | |
4723 | Use of ``absurd'' values (such as @code{INTEGER*1000}) would | |
4724 | certainly be possible, but would perhaps be stretching the original | |
4725 | intent of this notation beyond the breaking point in terms | |
4726 | of widespread readability of documentation and code making use | |
4727 | of it. | |
4728 | ||
4729 | Therefore, this document uses ``star notation'' only on occasion | |
4730 | for the benefit of those readers who are accustomed to it. | |
4731 | ||
4732 | @node Kind Notation | |
4733 | @subsubsection Kind Notation | |
4734 | @cindex KIND= notation | |
4735 | ||
4736 | The following notation specifies the kind-type selector of a type: | |
4737 | ||
4738 | @smallexample | |
4739 | @var{generic-type}(KIND=@var{n}) | |
4740 | @end smallexample | |
4741 | ||
4742 | @noindent | |
4743 | Use the above form where a type name is valid. | |
4744 | ||
4745 | @var{generic-type} must be a generic type---one of | |
4746 | @code{INTEGER}, @code{REAL}, @code{COMPLEX}, @code{LOGICAL}, | |
4747 | or @code{CHARACTER}. | |
4748 | @var{n} must be an integer initialization expression that | |
4749 | is a positive, nonzero value. | |
4750 | ||
4751 | Programmers are discouraged from writing these values directly | |
4752 | into their code. | |
4753 | Future versions of the GNU Fortran language will offer | |
4754 | facilities that will make the writing of code portable | |
4755 | to @code{g77} @emph{and} Fortran 90 implementations simpler. | |
4756 | ||
4757 | However, writing code that ports to existing FORTRAN 77 | |
4758 | implementations depends on avoiding the @samp{KIND=} construct. | |
4759 | ||
4760 | The @samp{KIND=} construct is thus useful in the context | |
4761 | of GNU Fortran for two reasons: | |
4762 | ||
4763 | @itemize @bullet | |
4764 | @item | |
4765 | It provides a means to specify a type in a fashion that | |
4766 | is portable across all GNU Fortran implementations (though | |
4767 | not other FORTRAN 77 and Fortran 90 implementations). | |
4768 | ||
4769 | @item | |
4770 | It provides a sort of Rosetta stone for this document to use | |
4771 | to concisely describe the types of various operations and | |
4772 | operands. | |
4773 | @end itemize | |
4774 | ||
4775 | The values of @var{n} in the GNU Fortran language are | |
4776 | assigned using a scheme that: | |
4777 | ||
4778 | @itemize @bullet | |
4779 | @item | |
4780 | Attempts to maximize the ability of readers | |
4781 | of this document to quickly familiarize themselves | |
4782 | with assignments for popular types | |
4783 | ||
4784 | @item | |
4785 | Provides a unique value for each specific desired | |
4786 | meaning | |
4787 | ||
4788 | @item | |
4789 | Provides a means to automatically assign new values so | |
4790 | they have a ``natural'' relationship to existing values, | |
4791 | if appropriate, or, if no such relationship exists, will | |
4792 | not interfere with future values assigned on the basis | |
4793 | of such relationships | |
4794 | ||
4795 | @item | |
4796 | Avoids using values that are similar to values used | |
4797 | in the existing, popular @samp{*@var{n}} notation, | |
4798 | to prevent readers from expecting that these implied | |
4799 | correspondences work on all GNU Fortran implementations | |
4800 | @end itemize | |
4801 | ||
4802 | The assignment system accomplishes this by assigning | |
4803 | to each ``fundamental meaning'' of a specific type a | |
4804 | unique prime number. | |
4805 | Combinations of fundamental meanings---for example, a type | |
4806 | that is two times the size of some other type---are assigned | |
4807 | values of @var{n} that are the products of the values for | |
4808 | those fundamental meanings. | |
4809 | ||
4810 | A prime value of @var{n} is never given more than one fundamental | |
4811 | meaning, to avoid situations where some code or system | |
4812 | cannot reasonably provide those meanings in the form of a | |
4813 | single type. | |
4814 | ||
4815 | The values of @var{n} assigned so far are: | |
4816 | ||
4817 | @table @code | |
4818 | @item KIND=0 | |
4819 | This value is reserved for future use. | |
4820 | ||
4821 | The planned future use is for this value to designate, | |
4822 | explicitly, context-sensitive kind-type selection. | |
4823 | For example, the expression @samp{1D0 * 0.1_0} would | |
4824 | be equivalent to @samp{1D0 * 0.1D0}. | |
4825 | ||
4826 | @item KIND=1 | |
4827 | This corresponds to the default types for | |
4828 | @code{REAL}, @code{INTEGER}, @code{LOGICAL}, @code{COMPLEX}, | |
4829 | and @code{CHARACTER}, as appropriate. | |
4830 | ||
4831 | These are the ``default'' types described in the Fortran 90 standard, | |
4832 | though that standard does not assign any particular @samp{KIND=} | |
4833 | value to these types. | |
4834 | ||
4835 | (Typically, these are @code{REAL*4}, @code{INTEGER*4}, | |
4836 | @code{LOGICAL*4}, and @code{COMPLEX*8}.) | |
4837 | ||
4838 | @item KIND=2 | |
4839 | This corresponds to types that occupy twice as much | |
4840 | storage as the default types. | |
4841 | @code{REAL(KIND=2)} is @code{DOUBLE PRECISION} (typically @code{REAL*8}), | |
4842 | @code{COMPLEX(KIND=2)} is @code{DOUBLE COMPLEX} (typically @code{COMPLEX*16}), | |
4843 | ||
4844 | These are the ``double precision'' types described in the Fortran 90 | |
4845 | standard, | |
4846 | though that standard does not assign any particular @samp{KIND=} | |
4847 | value to these types. | |
4848 | ||
4849 | @var{n} of 4 thus corresponds to types that occupy four times | |
4850 | as much storage as the default types, @var{n} of 8 to types that | |
4851 | occupy eight times as much storage, and so on. | |
4852 | ||
4853 | The @code{INTEGER(KIND=2)} and @code{LOGICAL(KIND=2)} types | |
4854 | are not necessarily supported by every GNU Fortran implementation. | |
4855 | ||
4856 | @item KIND=3 | |
4857 | This corresponds to types that occupy as much | |
4858 | storage as the default @code{CHARACTER} type, | |
4859 | which is the same effective type as @code{CHARACTER(KIND=1)} | |
4860 | (making that type effectively the same as @code{CHARACTER(KIND=3)}). | |
4861 | ||
4862 | (Typically, these are @code{INTEGER*1} and @code{LOGICAL*1}.) | |
4863 | ||
4864 | @var{n} of 6 thus corresponds to types that occupy twice as | |
4865 | much storage as the @var{n}=3 types, @var{n} of 12 to types | |
4866 | that occupy four times as much storage, and so on. | |
4867 | ||
4868 | These are not necessarily supported by every GNU Fortran | |
4869 | implementation. | |
4870 | ||
4871 | @item KIND=5 | |
4872 | This corresponds to types that occupy half the | |
4873 | storage as the default (@var{n}=1) types. | |
4874 | ||
4875 | (Typically, these are @code{INTEGER*2} and @code{LOGICAL*2}.) | |
4876 | ||
4877 | @var{n} of 25 thus corresponds to types that occupy one-quarter | |
4878 | as much storage as the default types. | |
4879 | ||
4880 | These are not necessarily supported by every GNU Fortran | |
4881 | implementation. | |
4882 | ||
4883 | @item KIND=7 | |
795232f7 | 4884 | @cindex pointers |
5ff904cd JL |
4885 | This is valid only as @code{INTEGER(KIND=7)} and |
4886 | denotes the @code{INTEGER} type that has the smallest | |
4887 | storage size that holds a pointer on the system. | |
4888 | ||
4889 | A pointer representable by this type is capable of uniquely | |
4890 | addressing a @code{CHARACTER*1} variable, array, array element, | |
4891 | or substring. | |
4892 | ||
4893 | (Typically this is equivalent to @code{INTEGER*4} or, | |
4894 | on 64-bit systems, @code{INTEGER*8}. | |
4895 | In a compatible C implementation, it typically would | |
4896 | be the same size and semantics of the C type @code{void *}.) | |
4897 | @end table | |
4898 | ||
4899 | Note that these are @emph{proposed} correspondences and might change | |
4900 | in future versions of @code{g77}---avoid writing code depending | |
4901 | on them while @code{g77}, and therefore the GNU Fortran language | |
4902 | it defines, is in beta testing. | |
4903 | ||
4904 | Values not specified in the above list are reserved to | |
4905 | future versions of the GNU Fortran language. | |
4906 | ||
4907 | Implementation-dependent meanings will be assigned new, | |
4908 | unique prime numbers so as to not interfere with other | |
4909 | implementation-dependent meanings, and offer the possibility | |
4910 | of increasing the portability of code depending on such | |
4911 | types by offering support for them in other GNU Fortran | |
4912 | implementations. | |
4913 | ||
4914 | Other meanings that might be given unique values are: | |
4915 | ||
4916 | @itemize @bullet | |
4917 | @item | |
4918 | Types that make use of only half their storage size for | |
4919 | representing precision and range. | |
4920 | ||
4921 | For example, some compilers offer options that cause | |
4922 | @code{INTEGER} types to occupy the amount of storage | |
4923 | that would be needed for @code{INTEGER(KIND=2)} types, but the | |
4924 | range remains that of @code{INTEGER(KIND=1)}. | |
4925 | ||
4926 | @item | |
4927 | The IEEE single floating-point type. | |
4928 | ||
4929 | @item | |
4930 | Types with a specific bit pattern (endianness), such as the | |
4931 | little-endian form of @code{INTEGER(KIND=1)}. | |
4932 | These could permit, conceptually, use of portable code and | |
4933 | implementations on data files written by existing systems. | |
4934 | @end itemize | |
4935 | ||
4936 | Future @emph{prime} numbers should be given meanings in as incremental | |
4937 | a fashion as possible, to allow for flexibility and | |
4938 | expressiveness in combining types. | |
4939 | ||
4940 | For example, instead of defining a prime number for little-endian | |
4941 | IEEE doubles, one prime number might be assigned the meaning | |
4942 | ``little-endian'', another the meaning ``IEEE double'', and the | |
4943 | value of @var{n} for a little-endian IEEE double would thus | |
4944 | naturally be the product of those two respective assigned values. | |
4945 | (It could even be reasonable to have IEEE values result from the | |
4946 | products of prime values denoting exponent and fraction sizes | |
4947 | and meanings, hidden bit usage, availability and representations | |
4948 | of special values such as subnormals, infinities, and Not-A-Numbers | |
4949 | (NaNs), and so on.) | |
4950 | ||
4951 | This assignment mechanism, while not inherently required for | |
4952 | future versions of the GNU Fortran language, is worth using | |
4953 | because it could ease management of the ``space'' of supported | |
4954 | types much easier in the long run. | |
4955 | ||
4956 | The above approach suggests a mechanism for specifying inheritance | |
4957 | of intrinsic (built-in) types for an entire, widely portable | |
4958 | product line. | |
4959 | It is certainly reasonable that, unlike programmers of other languages | |
4960 | offering inheritance mechanisms that employ verbose names for classes | |
4961 | and subclasses, along with graphical browsers to elucidate the | |
4962 | relationships, Fortran programmers would employ | |
4963 | a mechanism that works by multiplying prime numbers together | |
4964 | and finding the prime factors of such products. | |
4965 | ||
4966 | Most of the advantages for the above scheme have been explained | |
4967 | above. | |
4968 | One disadvantage is that it could lead to the defining, | |
4969 | by the GNU Fortran language, of some fairly large prime numbers. | |
4970 | This could lead to the GNU Fortran language being declared | |
4971 | ``munitions'' by the United States Department of Defense. | |
4972 | ||
4973 | @node Constants | |
4974 | @subsection Constants | |
4975 | @cindex constants | |
4976 | @cindex types, constants | |
4977 | ||
4978 | (Corresponds to Section 4.2 of ANSI X3.9-1978 FORTRAN 77.) | |
4979 | ||
4980 | A @dfn{typeless constant} has one of the following forms: | |
4981 | ||
4982 | @smallexample | |
4983 | '@var{binary-digits}'B | |
4984 | '@var{octal-digits}'O | |
4985 | '@var{hexadecimal-digits}'Z | |
4986 | '@var{hexadecimal-digits}'X | |
4987 | @end smallexample | |
4988 | ||
4989 | @noindent | |
4990 | @var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits} | |
4991 | are nonempty strings of characters in the set @samp{01}, @samp{01234567}, | |
4992 | and @samp{0123456789ABCDEFabcdef}, respectively. | |
4993 | (The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b} | |
4994 | is 11, and so on.) | |
4995 | ||
58dd1c34 DL |
4996 | A prefix-radix constant, such as @samp{Z'ABCD'}, can optionally be |
4997 | treated as typeless. @xref{Fortran Dialect Options,, Options | |
4998 | Controlling Fortran Dialect}, for information on the | |
4999 | @samp{-ftypeless-boz} option. | |
5000 | ||
5ff904cd JL |
5001 | Typeless constants have values that depend on the context in which |
5002 | they are used. | |
5003 | ||
5004 | All other constants, called @dfn{typed constants}, are interpreted---converted | |
5005 | to internal form---according to their inherent type. | |
5006 | Thus, context is @emph{never} a determining factor for the type, and hence | |
5007 | the interpretation, of a typed constant. | |
5008 | (All constants in the ANSI FORTRAN 77 language are typed constants.) | |
5009 | ||
5010 | For example, @samp{1} is always type @code{INTEGER(KIND=1)} in GNU | |
5011 | Fortran (called default INTEGER in Fortran 90), | |
5012 | @samp{9.435784839284958} is always type @code{REAL(KIND=1)} (even if the | |
5013 | additional precision specified is lost, and even when used in a | |
5014 | @code{REAL(KIND=2)} context), @samp{1E0} is always type @code{REAL(KIND=2)}, | |
5015 | and @samp{1D0} is always type @code{REAL(KIND=2)}. | |
5016 | ||
5017 | @node Integer Type | |
5018 | @subsection Integer Type | |
5019 | ||
5020 | (Corresponds to Section 4.3 of ANSI X3.9-1978 FORTRAN 77.) | |
5021 | ||
5022 | An integer constant also may have one of the following forms: | |
5023 | ||
5024 | @smallexample | |
5025 | B'@var{binary-digits}' | |
5026 | O'@var{octal-digits}' | |
5027 | Z'@var{hexadecimal-digits}' | |
5028 | X'@var{hexadecimal-digits}' | |
5029 | @end smallexample | |
5030 | ||
5031 | @noindent | |
5032 | @var{binary-digits}, @var{octal-digits}, and @var{hexadecimal-digits} | |
5033 | are nonempty strings of characters in the set @samp{01}, @samp{01234567}, | |
5034 | and @samp{0123456789ABCDEFabcdef}, respectively. | |
5035 | (The value for @samp{A} (and @samp{a}) is 10, for @samp{B} and @samp{b} | |
5036 | is 11, and so on.) | |
5037 | ||
5038 | @node Character Type | |
5039 | @subsection Character Type | |
5040 | ||
5041 | (Corresponds to Section 4.8 of ANSI X3.9-1978 FORTRAN 77.) | |
5042 | ||
0b31330e | 5043 | @cindex double quoted character constants |
5ff904cd JL |
5044 | A character constant may be delimited by a pair of double quotes |
5045 | (@samp{"}) instead of apostrophes. | |
5046 | In this case, an apostrophe within the constant represents | |
5047 | a single apostrophe, while a double quote is represented in | |
5048 | the source text of the constant by two consecutive double | |
5049 | quotes with no intervening spaces. | |
5050 | ||
5051 | @cindex zero-length CHARACTER | |
5052 | @cindex null CHARACTER strings | |
5053 | @cindex empty CHARACTER strings | |
5054 | @cindex strings, empty | |
5055 | @cindex CHARACTER, null | |
5056 | A character constant may be empty (have a length of zero). | |
5057 | ||
5058 | A character constant may include a substring specification, | |
5059 | The value of such a constant is the value of the substring---for | |
5060 | example, the value of @samp{'hello'(3:5)} is the same | |
5061 | as the value of @samp{'llo'}. | |
5062 | ||
5063 | @node Expressions | |
5064 | @section Expressions | |
5065 | ||
5066 | (The following information augments or overrides the information in | |
5067 | Chapter 6 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
5068 | language. | |
5069 | Chapter 6 of that document otherwise serves as the basis | |
5070 | for the relevant aspects of GNU Fortran.) | |
5071 | ||
5072 | @menu | |
5073 | * %LOC():: | |
5074 | @end menu | |
5075 | ||
5076 | @node %LOC() | |
5077 | @subsection The @code{%LOC()} Construct | |
5078 | @cindex %LOC() construct | |
5079 | ||
5080 | @example | |
5081 | %LOC(@var{arg}) | |
5082 | @end example | |
5083 | ||
5084 | The @code{%LOC()} construct is an expression | |
5085 | that yields the value of the location of its argument, | |
5086 | @var{arg}, in memory. | |
5087 | The size of the type of the expression depends on the system---typically, | |
5088 | it is equivalent to either @code{INTEGER(KIND=1)} or @code{INTEGER(KIND=2)}, | |
5089 | though it is actually type @code{INTEGER(KIND=7)}. | |
5090 | ||
5091 | The argument to @code{%LOC()} must be suitable as the | |
5092 | left-hand side of an assignment statement. | |
5093 | That is, it may not be a general expression involving | |
5094 | operators such as addition, subtraction, and so on, | |
5095 | nor may it be a constant. | |
5096 | ||
5097 | Use of @code{%LOC()} is recommended only for code that | |
5098 | is accessing facilities outside of GNU Fortran, such as | |
5099 | operating system or windowing facilities. | |
5100 | It is best to constrain such uses to isolated portions of | |
5101 | a program---portions that deal specifically and exclusively | |
5102 | with low-level, system-dependent facilities. | |
5103 | Such portions might well provide a portable interface for | |
5104 | use by the program as a whole, but are themselves not | |
5105 | portable, and should be thoroughly tested each time they | |
5106 | are rebuilt using a new compiler or version of a compiler. | |
5107 | ||
5108 | Do not depend on @code{%LOC()} returning a pointer that | |
5109 | can be safely used to @emph{define} (change) the argument. | |
5110 | While this might work in some circumstances, it is hard | |
5111 | to predict whether it will continue to work when a program | |
5112 | (that works using this unsafe behavior) | |
5113 | is recompiled using different command-line options or | |
5114 | a different version of @code{g77}. | |
5115 | ||
5116 | Generally, @code{%LOC()} is safe when used as an argument | |
5117 | to a procedure that makes use of the value of the corresponding | |
5118 | dummy argument only during its activation, and only when | |
5119 | such use is restricted to referencing (reading) the value | |
5120 | of the argument to @code{%LOC()}. | |
5121 | ||
5122 | @emph{Implementation Note:} Currently, @code{g77} passes | |
5123 | arguments (those not passed using a construct such as @code{%VAL()}) | |
5124 | by reference or descriptor, depending on the type of | |
5125 | the actual argument. | |
5126 | Thus, given @samp{INTEGER I}, @samp{CALL FOO(I)} would | |
a835e351 | 5127 | seem to mean the same thing as @samp{CALL FOO(%VAL(%LOC(I)))}, and |
5ff904cd JL |
5128 | in fact might compile to identical code. |
5129 | ||
a835e351 CB |
5130 | However, @samp{CALL FOO(%VAL(%LOC(I)))} emphatically means |
5131 | ``pass, by value, the address of @samp{I} in memory''. | |
5ff904cd JL |
5132 | While @samp{CALL FOO(I)} might use that same approach in a |
5133 | particular version of @code{g77}, another version or compiler | |
5134 | might choose a different implementation, such as copy-in/copy-out, | |
5135 | to effect the desired behavior---and which will therefore not | |
a835e351 CB |
5136 | necessarily compile to the same code as would |
5137 | @samp{CALL FOO(%VAL(%LOC(I)))} | |
5ff904cd JL |
5138 | using the same version or compiler. |
5139 | ||
5140 | @xref{Debugging and Interfacing}, for detailed information on | |
5141 | how this particular version of @code{g77} implements various | |
5142 | constructs. | |
5143 | ||
5144 | @node Specification Statements | |
5145 | @section Specification Statements | |
5146 | ||
5147 | (The following information augments or overrides the information in | |
5148 | Chapter 8 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
5149 | language. | |
5150 | Chapter 8 of that document otherwise serves as the basis | |
5151 | for the relevant aspects of GNU Fortran.) | |
5152 | ||
5153 | @menu | |
5154 | * NAMELIST:: | |
5155 | * DOUBLE COMPLEX:: | |
5156 | @end menu | |
5157 | ||
5158 | @node NAMELIST | |
5159 | @subsection @code{NAMELIST} Statement | |
5160 | @cindex NAMELIST statement | |
5161 | @cindex statements, NAMELIST | |
5162 | ||
5163 | The @code{NAMELIST} statement, and related I/O constructs, are | |
5164 | supported by the GNU Fortran language in essentially the same | |
5165 | way as they are by @code{f2c}. | |
5166 | ||
0b31330e DL |
5167 | This follows Fortran 90 with the restriction that on @code{NAMELIST} |
5168 | input, subscripts must have the form | |
5169 | @smallexample | |
5170 | @var{subscript} [ @code{:} @var{subscript} [ @code{:} @var{stride}]] | |
5171 | @end smallexample | |
5172 | i.e.@: | |
5173 | @smallexample | |
5174 | &xx x(1:3,8:10:2)=1,2,3,4,5,6/ | |
5175 | @end smallexample | |
5176 | is allowed, but not, say, | |
5177 | @smallexample | |
5178 | &xx x(:3,8::2)=1,2,3,4,5,6/ | |
5179 | @end smallexample | |
5180 | ||
5181 | As an extension of the Fortran 90 form, @code{$} and @code{$END} may be | |
5182 | used in place of @code{&} and @code{/} in @code{NAMELIST} input, so that | |
5183 | @smallexample | |
5184 | $&xx x(1:3,8:10:2)=1,2,3,4,5,6 $end | |
5185 | @end smallexample | |
5186 | could be used instead of the example above. | |
5187 | ||
5ff904cd JL |
5188 | @node DOUBLE COMPLEX |
5189 | @subsection @code{DOUBLE COMPLEX} Statement | |
5190 | @cindex DOUBLE COMPLEX | |
5191 | ||
5192 | @code{DOUBLE COMPLEX} is a type-statement (and type) that | |
5193 | specifies the type @code{COMPLEX(KIND=2)} in GNU Fortran. | |
5194 | ||
5195 | @node Control Statements | |
5196 | @section Control Statements | |
5197 | ||
5198 | (The following information augments or overrides the information in | |
5199 | Chapter 11 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
5200 | language. | |
5201 | Chapter 11 of that document otherwise serves as the basis | |
5202 | for the relevant aspects of GNU Fortran.) | |
5203 | ||
5204 | @menu | |
5205 | * DO WHILE:: | |
5206 | * END DO:: | |
5207 | * Construct Names:: | |
5208 | * CYCLE and EXIT:: | |
5209 | @end menu | |
5210 | ||
5211 | @node DO WHILE | |
5212 | @subsection DO WHILE | |
5213 | @cindex DO WHILE | |
0b31330e | 5214 | @cindex DO |
5ff904cd JL |
5215 | @cindex MIL-STD 1753 |
5216 | ||
5217 | The @code{DO WHILE} statement, a feature of both the MIL-STD 1753 and | |
5218 | Fortran 90 standards, is provided by the GNU Fortran language. | |
0b31330e DL |
5219 | The Fortran 90 ``do forever'' statement comprising just @code{DO} is |
5220 | also supported. | |
5ff904cd JL |
5221 | |
5222 | @node END DO | |
5223 | @subsection END DO | |
5224 | @cindex END DO | |
5225 | @cindex MIL-STD 1753 | |
5226 | ||
5227 | The @code{END DO} statement is provided by the GNU Fortran language. | |
5228 | ||
5229 | This statement is used in one of two ways: | |
5230 | ||
5231 | @itemize @bullet | |
5232 | @item | |
5233 | The Fortran 90 meaning, in which it specifies the termination | |
5234 | point of a single @code{DO} loop started with a @code{DO} statement | |
5235 | that specifies no termination label. | |
5236 | ||
5237 | @item | |
5238 | The MIL-STD 1753 meaning, in which it specifies the termination | |
5239 | point of one or more @code{DO} loops, all of which start with a | |
5240 | @code{DO} statement that specify the label defined for the | |
5241 | @code{END DO} statement. | |
5242 | ||
5243 | This kind of @code{END DO} statement is merely a synonym for | |
5244 | @code{CONTINUE}, except it is permitted only when the statement | |
5245 | is labeled and a target of one or more labeled @code{DO} loops. | |
5246 | ||
5247 | It is expected that this use of @code{END DO} will be removed from | |
5248 | the GNU Fortran language in the future, though it is likely that | |
5249 | it will long be supported by @code{g77} as a dialect form. | |
5250 | @end itemize | |
5251 | ||
5252 | @node Construct Names | |
5253 | @subsection Construct Names | |
5254 | @cindex construct names | |
5255 | ||
5256 | The GNU Fortran language supports construct names as defined | |
5257 | by the Fortran 90 standard. | |
5258 | These names are local to the program unit and are defined | |
5259 | as follows: | |
5260 | ||
5261 | @smallexample | |
5262 | @var{construct-name}: @var{block-statement} | |
5263 | @end smallexample | |
5264 | ||
5265 | @noindent | |
5266 | Here, @var{construct-name} is the construct name itself; | |
5267 | its definition is connoted by the single colon (@samp{:}); and | |
5268 | @var{block-statement} is an @code{IF}, @code{DO}, | |
5269 | or @code{SELECT CASE} statement that begins a block. | |
5270 | ||
5271 | A block that is given a construct name must also specify the | |
5272 | same construct name in its termination statement: | |
5273 | ||
5274 | @example | |
5275 | END @var{block} @var{construct-name} | |
5276 | @end example | |
5277 | ||
5278 | @noindent | |
5279 | Here, @var{block} must be @code{IF}, @code{DO}, or @code{SELECT}, | |
5280 | as appropriate. | |
5281 | ||
5282 | @node CYCLE and EXIT | |
5283 | @subsection The @code{CYCLE} and @code{EXIT} Statements | |
5284 | ||
a20f31a0 DL |
5285 | @cindex CYCLE statement |
5286 | @cindex EXIT statement | |
5287 | @cindex statements, CYCLE | |
5288 | @cindex statements, EXIT | |
5ff904cd JL |
5289 | The @code{CYCLE} and @code{EXIT} statements specify that |
5290 | the remaining statements in the current iteration of a | |
5291 | particular active (enclosing) @code{DO} loop are to be skipped. | |
5292 | ||
5293 | @code{CYCLE} specifies that these statements are skipped, | |
5294 | but the @code{END DO} statement that marks the end of the | |
5295 | @code{DO} loop be executed---that is, the next iteration, | |
5296 | if any, is to be started. | |
5297 | If the statement marking the end of the @code{DO} loop is | |
5298 | not @code{END DO}---in other words, if the loop is not | |
5299 | a block @code{DO}---the @code{CYCLE} statement does not | |
5300 | execute that statement, but does start the next iteration (if any). | |
5301 | ||
5302 | @code{EXIT} specifies that the loop specified by the | |
5303 | @code{DO} construct is terminated. | |
5304 | ||
5305 | The @code{DO} loop affected by @code{CYCLE} and @code{EXIT} | |
5306 | is the innermost enclosing @code{DO} loop when the following | |
5307 | forms are used: | |
5308 | ||
5309 | @example | |
5310 | CYCLE | |
5311 | EXIT | |
5312 | @end example | |
5313 | ||
5314 | Otherwise, the following forms specify the construct name | |
5315 | of the pertinent @code{DO} loop: | |
5316 | ||
5317 | @example | |
5318 | CYCLE @var{construct-name} | |
5319 | EXIT @var{construct-name} | |
5320 | @end example | |
5321 | ||
5322 | @code{CYCLE} and @code{EXIT} can be viewed as glorified @code{GO TO} | |
5323 | statements. | |
5324 | However, they cannot be easily thought of as @code{GO TO} statements | |
5325 | in obscure cases involving FORTRAN 77 loops. | |
5326 | For example: | |
5327 | ||
5328 | @smallexample | |
5329 | DO 10 I = 1, 5 | |
5330 | DO 10 J = 1, 5 | |
5331 | IF (J .EQ. 5) EXIT | |
5332 | DO 10 K = 1, 5 | |
5333 | IF (K .EQ. 3) CYCLE | |
5334 | 10 PRINT *, 'I=', I, ' J=', J, ' K=', K | |
5335 | 20 CONTINUE | |
5336 | @end smallexample | |
5337 | ||
5338 | @noindent | |
5339 | In particular, neither the @code{EXIT} nor @code{CYCLE} statements | |
5340 | above are equivalent to a @code{GO TO} statement to either label | |
5341 | @samp{10} or @samp{20}. | |
5342 | ||
5343 | To understand the effect of @code{CYCLE} and @code{EXIT} in the | |
5344 | above fragment, it is helpful to first translate it to its equivalent | |
5345 | using only block @code{DO} loops: | |
5346 | ||
5347 | @smallexample | |
5348 | DO I = 1, 5 | |
5349 | DO J = 1, 5 | |
5350 | IF (J .EQ. 5) EXIT | |
5351 | DO K = 1, 5 | |
5352 | IF (K .EQ. 3) CYCLE | |
5353 | 10 PRINT *, 'I=', I, ' J=', J, ' K=', K | |
5354 | END DO | |
5355 | END DO | |
5356 | END DO | |
5357 | 20 CONTINUE | |
5358 | @end smallexample | |
5359 | ||
5360 | Adding new labels allows translation of @code{CYCLE} and @code{EXIT} | |
5361 | to @code{GO TO} so they may be more easily understood by programmers | |
5362 | accustomed to FORTRAN coding: | |
5363 | ||
5364 | @smallexample | |
5365 | DO I = 1, 5 | |
5366 | DO J = 1, 5 | |
5367 | IF (J .EQ. 5) GOTO 18 | |
5368 | DO K = 1, 5 | |
5369 | IF (K .EQ. 3) GO TO 12 | |
5370 | 10 PRINT *, 'I=', I, ' J=', J, ' K=', K | |
5371 | 12 END DO | |
5372 | END DO | |
5373 | 18 END DO | |
5374 | 20 CONTINUE | |
5375 | @end smallexample | |
5376 | ||
5377 | @noindent | |
5378 | Thus, the @code{CYCLE} statement in the innermost loop skips over | |
5379 | the @code{PRINT} statement as it begins the next iteration of the | |
5380 | loop, while the @code{EXIT} statement in the middle loop ends that | |
5381 | loop but @emph{not} the outermost loop. | |
5382 | ||
5383 | @node Functions and Subroutines | |
5384 | @section Functions and Subroutines | |
5385 | ||
5386 | (The following information augments or overrides the information in | |
5387 | Chapter 15 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
5388 | language. | |
5389 | Chapter 15 of that document otherwise serves as the basis | |
5390 | for the relevant aspects of GNU Fortran.) | |
5391 | ||
5392 | @menu | |
5393 | * %VAL():: | |
5394 | * %REF():: | |
5395 | * %DESCR():: | |
5396 | * Generics and Specifics:: | |
5397 | * REAL() and AIMAG() of Complex:: | |
5398 | * CMPLX() of DOUBLE PRECISION:: | |
5399 | * MIL-STD 1753:: | |
5400 | * f77/f2c Intrinsics:: | |
5401 | * Table of Intrinsic Functions:: | |
5402 | @end menu | |
5403 | ||
5404 | @node %VAL() | |
5405 | @subsection The @code{%VAL()} Construct | |
5406 | @cindex %VAL() construct | |
5407 | ||
5408 | @example | |
5409 | %VAL(@var{arg}) | |
5410 | @end example | |
5411 | ||
5412 | The @code{%VAL()} construct specifies that an argument, | |
5413 | @var{arg}, is to be passed by value, instead of by reference | |
5414 | or descriptor. | |
5415 | ||
5416 | @code{%VAL()} is restricted to actual arguments in | |
5417 | invocations of external procedures. | |
5418 | ||
5419 | Use of @code{%VAL()} is recommended only for code that | |
5420 | is accessing facilities outside of GNU Fortran, such as | |
5421 | operating system or windowing facilities. | |
5422 | It is best to constrain such uses to isolated portions of | |
5423 | a program---portions the deal specifically and exclusively | |
5424 | with low-level, system-dependent facilities. | |
5425 | Such portions might well provide a portable interface for | |
5426 | use by the program as a whole, but are themselves not | |
5427 | portable, and should be thoroughly tested each time they | |
5428 | are rebuilt using a new compiler or version of a compiler. | |
5429 | ||
5430 | @emph{Implementation Note:} Currently, @code{g77} passes | |
5431 | all arguments either by reference or by descriptor. | |
5432 | ||
5433 | Thus, use of @code{%VAL()} tends to be restricted to cases | |
5434 | where the called procedure is written in a language other | |
5435 | than Fortran that supports call-by-value semantics. | |
5436 | (C is an example of such a language.) | |
5437 | ||
5438 | @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, | |
5439 | for detailed information on | |
5440 | how this particular version of @code{g77} passes arguments | |
5441 | to procedures. | |
5442 | ||
5443 | @node %REF() | |
5444 | @subsection The @code{%REF()} Construct | |
5445 | @cindex %REF() construct | |
5446 | ||
5447 | @example | |
5448 | %REF(@var{arg}) | |
5449 | @end example | |
5450 | ||
5451 | The @code{%REF()} construct specifies that an argument, | |
5452 | @var{arg}, is to be passed by reference, instead of by | |
5453 | value or descriptor. | |
5454 | ||
5455 | @code{%REF()} is restricted to actual arguments in | |
5456 | invocations of external procedures. | |
5457 | ||
5458 | Use of @code{%REF()} is recommended only for code that | |
5459 | is accessing facilities outside of GNU Fortran, such as | |
5460 | operating system or windowing facilities. | |
5461 | It is best to constrain such uses to isolated portions of | |
5462 | a program---portions the deal specifically and exclusively | |
5463 | with low-level, system-dependent facilities. | |
5464 | Such portions might well provide a portable interface for | |
5465 | use by the program as a whole, but are themselves not | |
5466 | portable, and should be thoroughly tested each time they | |
5467 | are rebuilt using a new compiler or version of a compiler. | |
5468 | ||
5469 | Do not depend on @code{%REF()} supplying a pointer to the | |
5470 | procedure being invoked. | |
5471 | While that is a likely implementation choice, other | |
5472 | implementation choices are available that preserve Fortran | |
5473 | pass-by-reference semantics without passing a pointer to | |
5474 | the argument, @var{arg}. | |
5475 | (For example, a copy-in/copy-out implementation.) | |
5476 | ||
5477 | @emph{Implementation Note:} Currently, @code{g77} passes | |
5478 | all arguments | |
5479 | (other than variables and arrays of type @code{CHARACTER}) | |
5480 | by reference. | |
5481 | Future versions of, or dialects supported by, @code{g77} might | |
5482 | not pass @code{CHARACTER} functions by reference. | |
5483 | ||
5484 | Thus, use of @code{%REF()} tends to be restricted to cases | |
5485 | where @var{arg} is type @code{CHARACTER} but the called | |
5486 | procedure accesses it via a means other than the method | |
5487 | used for Fortran @code{CHARACTER} arguments. | |
5488 | ||
5489 | @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on | |
5490 | how this particular version of @code{g77} passes arguments | |
5491 | to procedures. | |
5492 | ||
5493 | @node %DESCR() | |
5494 | @subsection The @code{%DESCR()} Construct | |
5495 | @cindex %DESCR() construct | |
5496 | ||
5497 | @example | |
5498 | %DESCR(@var{arg}) | |
5499 | @end example | |
5500 | ||
5501 | The @code{%DESCR()} construct specifies that an argument, | |
5502 | @var{arg}, is to be passed by descriptor, instead of by | |
5503 | value or reference. | |
5504 | ||
5505 | @code{%DESCR()} is restricted to actual arguments in | |
5506 | invocations of external procedures. | |
5507 | ||
5508 | Use of @code{%DESCR()} is recommended only for code that | |
5509 | is accessing facilities outside of GNU Fortran, such as | |
5510 | operating system or windowing facilities. | |
5511 | It is best to constrain such uses to isolated portions of | |
5512 | a program---portions the deal specifically and exclusively | |
5513 | with low-level, system-dependent facilities. | |
5514 | Such portions might well provide a portable interface for | |
5515 | use by the program as a whole, but are themselves not | |
5516 | portable, and should be thoroughly tested each time they | |
5517 | are rebuilt using a new compiler or version of a compiler. | |
5518 | ||
5519 | Do not depend on @code{%DESCR()} supplying a pointer | |
5520 | and/or a length passed by value | |
5521 | to the procedure being invoked. | |
5522 | While that is a likely implementation choice, other | |
5523 | implementation choices are available that preserve the | |
5524 | pass-by-reference semantics without passing a pointer to | |
5525 | the argument, @var{arg}. | |
95a1b676 | 5526 | (For example, a copy-in/copy-out implementation.) |
5ff904cd JL |
5527 | And, future versions of @code{g77} might change the |
5528 | way descriptors are implemented, such as passing a | |
5529 | single argument pointing to a record containing the | |
5530 | pointer/length information instead of passing that same | |
5531 | information via two arguments as it currently does. | |
5532 | ||
5533 | @emph{Implementation Note:} Currently, @code{g77} passes | |
5534 | all variables and arrays of type @code{CHARACTER} | |
5535 | by descriptor. | |
5536 | Future versions of, or dialects supported by, @code{g77} might | |
5537 | pass @code{CHARACTER} functions by descriptor as well. | |
5538 | ||
5539 | Thus, use of @code{%DESCR()} tends to be restricted to cases | |
5540 | where @var{arg} is not type @code{CHARACTER} but the called | |
5541 | procedure accesses it via a means similar to the method | |
5542 | used for Fortran @code{CHARACTER} arguments. | |
5543 | ||
5544 | @xref{Procedures,,Procedures (SUBROUTINE and FUNCTION)}, for detailed information on | |
5545 | how this particular version of @code{g77} passes arguments | |
5546 | to procedures. | |
5547 | ||
5548 | @node Generics and Specifics | |
5549 | @subsection Generics and Specifics | |
5550 | @cindex generic intrinsics | |
5551 | @cindex intrinsics, generic | |
5552 | ||
5553 | The ANSI FORTRAN 77 language defines generic and specific | |
5554 | intrinsics. | |
5555 | In short, the distinctions are: | |
5556 | ||
5557 | @itemize @bullet | |
5558 | @item | |
5559 | @emph{Specific} intrinsics have | |
5560 | specific types for their arguments and a specific return | |
5561 | type. | |
5562 | ||
5563 | @item | |
5564 | @emph{Generic} intrinsics are treated, | |
5565 | on a case-by-case basis in the program's source code, | |
5566 | as one of several possible specific intrinsics. | |
5567 | ||
5568 | Typically, a generic intrinsic has a return type that | |
5569 | is determined by the type of one or more of its arguments. | |
5570 | @end itemize | |
5571 | ||
5572 | The GNU Fortran language generalizes these concepts somewhat, | |
5573 | especially by providing intrinsic subroutines and generic | |
5574 | intrinsics that are treated as either a specific intrinsic subroutine | |
5575 | or a specific intrinsic function (e.g. @code{SECOND}). | |
5576 | ||
5577 | However, GNU Fortran avoids generalizing this concept to | |
5578 | the point where existing code would be accepted as meaning | |
5579 | something possibly different than what was intended. | |
5580 | ||
5581 | For example, @code{ABS} is a generic intrinsic, so all working | |
5582 | code written using @code{ABS} of an @code{INTEGER} argument | |
5583 | expects an @code{INTEGER} return value. | |
5584 | Similarly, all such code expects that @code{ABS} of an @code{INTEGER*2} | |
5585 | argument returns an @code{INTEGER*2} return value. | |
5586 | ||
5587 | Yet, @code{IABS} is a @emph{specific} intrinsic that accepts only | |
5588 | an @code{INTEGER(KIND=1)} argument. | |
5589 | Code that passes something other than an @code{INTEGER(KIND=1)} | |
5590 | argument to @code{IABS} is not valid GNU Fortran code, because | |
5591 | it is not clear what the author intended. | |
5592 | ||
5593 | For example, if @samp{J} is @code{INTEGER(KIND=6)}, @samp{IABS(J)} | |
5594 | is not defined by the GNU Fortran language, because the programmer | |
5595 | might have used that construct to mean any of the following, subtly | |
5596 | different, things: | |
5597 | ||
5598 | @itemize @bullet | |
5599 | @item | |
5600 | Convert @samp{J} to @code{INTEGER(KIND=1)} first | |
5601 | (as if @samp{IABS(INT(J))} had been written). | |
5602 | ||
5603 | @item | |
5604 | Convert the result of the intrinsic to @code{INTEGER(KIND=1)} | |
5605 | (as if @samp{INT(ABS(J))} had been written). | |
5606 | ||
5607 | @item | |
5608 | No conversion (as if @samp{ABS(J)} had been written). | |
5609 | @end itemize | |
5610 | ||
5611 | The distinctions matter especially when types and values wider than | |
5612 | @code{INTEGER(KIND=1)} (such as @code{INTEGER(KIND=2)}), or when | |
5613 | operations performing more ``arithmetic'' than absolute-value, are involved. | |
5614 | ||
5615 | The following sample program is not a valid GNU Fortran program, but | |
5616 | might be accepted by other compilers. | |
5617 | If so, the output is likely to be revealing in terms of how a given | |
5618 | compiler treats intrinsics (that normally are specific) when they | |
5619 | are given arguments that do not conform to their stated requirements: | |
5620 | ||
5621 | @cindex JCB002 program | |
5622 | @smallexample | |
5623 | PROGRAM JCB002 | |
5624 | C Version 1: | |
25d7717e | 5625 | C Modified 1999-02-15 (Burley) to delete my email address. |
5ff904cd JL |
5626 | C Modified 1997-05-21 (Burley) to accommodate compilers that implement |
5627 | C INT(I1-I2) as INT(I1)-INT(I2) given INTEGER*2 I1,I2. | |
5628 | C | |
5629 | C Version 0: | |
5630 | C Written by James Craig Burley 1997-02-20. | |
5ff904cd JL |
5631 | C |
5632 | C Purpose: | |
5633 | C Determine how compilers handle non-standard IDIM | |
5634 | C on INTEGER*2 operands, which presumably can be | |
5635 | C extrapolated into understanding how the compiler | |
5636 | C generally treats specific intrinsics that are passed | |
5637 | C arguments not of the correct types. | |
5638 | C | |
5639 | C If your compiler implements INTEGER*2 and INTEGER | |
5640 | C as the same type, change all INTEGER*2 below to | |
5641 | C INTEGER*1. | |
5642 | C | |
5643 | INTEGER*2 I0, I4 | |
5644 | INTEGER I1, I2, I3 | |
5645 | INTEGER*2 ISMALL, ILARGE | |
5646 | INTEGER*2 ITOOLG, ITWO | |
5647 | INTEGER*2 ITMP | |
5648 | LOGICAL L2, L3, L4 | |
5649 | C | |
5650 | C Find smallest INTEGER*2 number. | |
5651 | C | |
5652 | ISMALL=0 | |
5653 | 10 I0 = ISMALL-1 | |
5654 | IF ((I0 .GE. ISMALL) .OR. (I0+1 .NE. ISMALL)) GOTO 20 | |
5655 | ISMALL = I0 | |
5656 | GOTO 10 | |
5657 | 20 CONTINUE | |
5658 | C | |
5659 | C Find largest INTEGER*2 number. | |
5660 | C | |
5661 | ILARGE=0 | |
5662 | 30 I0 = ILARGE+1 | |
5663 | IF ((I0 .LE. ILARGE) .OR. (I0-1 .NE. ILARGE)) GOTO 40 | |
5664 | ILARGE = I0 | |
5665 | GOTO 30 | |
5666 | 40 CONTINUE | |
5667 | C | |
5668 | C Multiplying by two adds stress to the situation. | |
5669 | C | |
5670 | ITWO = 2 | |
5671 | C | |
5672 | C Need a number that, added to -2, is too wide to fit in I*2. | |
5673 | C | |
5674 | ITOOLG = ISMALL | |
5675 | C | |
5676 | C Use IDIM the straightforward way. | |
5677 | C | |
5678 | I1 = IDIM (ILARGE, ISMALL) * ITWO + ITOOLG | |
5679 | C | |
5680 | C Calculate result for first interpretation. | |
5681 | C | |
5682 | I2 = (INT (ILARGE) - INT (ISMALL)) * ITWO + ITOOLG | |
5683 | C | |
5684 | C Calculate result for second interpretation. | |
5685 | C | |
5686 | ITMP = ILARGE - ISMALL | |
5687 | I3 = (INT (ITMP)) * ITWO + ITOOLG | |
5688 | C | |
5689 | C Calculate result for third interpretation. | |
5690 | C | |
5691 | I4 = (ILARGE - ISMALL) * ITWO + ITOOLG | |
5692 | C | |
5693 | C Print results. | |
5694 | C | |
5695 | PRINT *, 'ILARGE=', ILARGE | |
5696 | PRINT *, 'ITWO=', ITWO | |
5697 | PRINT *, 'ITOOLG=', ITOOLG | |
5698 | PRINT *, 'ISMALL=', ISMALL | |
5699 | PRINT *, 'I1=', I1 | |
5700 | PRINT *, 'I2=', I2 | |
5701 | PRINT *, 'I3=', I3 | |
5702 | PRINT *, 'I4=', I4 | |
5703 | PRINT * | |
5704 | L2 = (I1 .EQ. I2) | |
5705 | L3 = (I1 .EQ. I3) | |
5706 | L4 = (I1 .EQ. I4) | |
5707 | IF (L2 .AND. .NOT.L3 .AND. .NOT.L4) THEN | |
5708 | PRINT *, 'Interp 1: IDIM(I*2,I*2) => IDIM(INT(I*2),INT(I*2))' | |
5709 | STOP | |
5710 | END IF | |
5711 | IF (L3 .AND. .NOT.L2 .AND. .NOT.L4) THEN | |
5712 | PRINT *, 'Interp 2: IDIM(I*2,I*2) => INT(DIM(I*2,I*2))' | |
5713 | STOP | |
5714 | END IF | |
5715 | IF (L4 .AND. .NOT.L2 .AND. .NOT.L3) THEN | |
5716 | PRINT *, 'Interp 3: IDIM(I*2,I*2) => DIM(I*2,I*2)' | |
5717 | STOP | |
5718 | END IF | |
5719 | PRINT *, 'Results need careful analysis.' | |
5720 | END | |
5721 | @end smallexample | |
5722 | ||
5723 | No future version of the GNU Fortran language | |
5724 | will likely permit specific intrinsic invocations with wrong-typed | |
5725 | arguments (such as @code{IDIM} in the above example), since | |
5726 | it has been determined that disagreements exist among | |
5727 | many production compilers on the interpretation of | |
5728 | such invocations. | |
5729 | These disagreements strongly suggest that Fortran programmers, | |
5730 | and certainly existing Fortran programs, disagree about the | |
5731 | meaning of such invocations. | |
5732 | ||
4e6a1440 | 5733 | The first version of @code{JCB002} didn't accommodate some compilers' |
5ff904cd JL |
5734 | treatment of @samp{INT(I1-I2)} where @samp{I1} and @samp{I2} are |
5735 | @code{INTEGER*2}. | |
5736 | In such a case, these compilers apparently convert both | |
5737 | operands to @code{INTEGER*4} and then do an @code{INTEGER*4} subtraction, | |
5738 | instead of doing an @code{INTEGER*2} subtraction on the | |
5739 | original values in @samp{I1} and @samp{I2}. | |
5740 | ||
5741 | However, the results of the careful analyses done on the outputs | |
5742 | of programs compiled by these various compilers show that they | |
5743 | all implement either @samp{Interp 1} or @samp{Interp 2} above. | |
5744 | ||
4e6a1440 | 5745 | Specifically, it is believed that the new version of @code{JCB002} |
5ff904cd JL |
5746 | above will confirm that: |
5747 | ||
5748 | @itemize @bullet | |
5749 | @item | |
5750 | Digital Semiconductor (``DEC'') Alpha OSF/1, HP-UX 10.0.1, AIX 3.2.5 | |
5751 | @code{f77} compilers all implement @samp{Interp 1}. | |
5752 | ||
5753 | @item | |
5754 | IRIX 5.3 @code{f77} compiler implements @samp{Interp 2}. | |
5755 | ||
5756 | @item | |
5757 | Solaris 2.5, SunOS 4.1.3, DECstation ULTRIX 4.3, | |
5758 | and IRIX 6.1 @code{f77} compilers all implement @samp{Interp 3}. | |
5759 | @end itemize | |
5760 | ||
5761 | If you get different results than the above for the stated | |
5762 | compilers, or have results for other compilers that might be | |
5763 | worth adding to the above list, please let us know the details | |
5764 | (compiler product, version, machine, results, and so on). | |
5765 | ||
5766 | @node REAL() and AIMAG() of Complex | |
5767 | @subsection @code{REAL()} and @code{AIMAG()} of Complex | |
26b9526e CB |
5768 | @cindex @code{Real} intrinsic |
5769 | @cindex intrinsics, @code{Real} | |
5770 | @cindex @code{AImag} intrinsic | |
5771 | @cindex intrinsics, @code{AImag} | |
5ff904cd JL |
5772 | |
5773 | The GNU Fortran language disallows @code{REAL(@var{expr})} | |
5774 | and @code{AIMAG(@var{expr})}, | |
5775 | where @var{expr} is any @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}, | |
5776 | except when they are used in the following way: | |
5777 | ||
5778 | @example | |
5779 | REAL(REAL(@var{expr})) | |
5780 | REAL(AIMAG(@var{expr})) | |
5781 | @end example | |
5782 | ||
5783 | @noindent | |
5784 | The above forms explicitly specify that the desired effect | |
5785 | is to convert the real or imaginary part of @var{expr}, which might | |
5786 | be some @code{REAL} type other than @code{REAL(KIND=1)}, | |
5787 | to type @code{REAL(KIND=1)}, | |
5788 | and have that serve as the value of the expression. | |
5789 | ||
5790 | The GNU Fortran language offers clearly named intrinsics to extract the | |
5791 | real and imaginary parts of a complex entity without any | |
5792 | conversion: | |
5793 | ||
5794 | @example | |
5795 | REALPART(@var{expr}) | |
5796 | IMAGPART(@var{expr}) | |
5797 | @end example | |
5798 | ||
5799 | To express the above using typical extended FORTRAN 77, | |
5800 | use the following constructs | |
5801 | (when @var{expr} is @code{COMPLEX(KIND=2)}): | |
5802 | ||
5803 | @example | |
5804 | DBLE(@var{expr}) | |
5805 | DIMAG(@var{expr}) | |
5806 | @end example | |
5807 | ||
5808 | The FORTRAN 77 language offers no way | |
5809 | to explicitly specify the real and imaginary parts of a complex expression of | |
5810 | arbitrary type, apparently as a result of requiring support for | |
5811 | only one @code{COMPLEX} type (@code{COMPLEX(KIND=1)}). | |
5812 | The concepts of converting an expression to type @code{REAL(KIND=1)} and | |
5813 | of extracting the real part of a complex expression were | |
5814 | thus ``smooshed'' by FORTRAN 77 into a single intrinsic, since | |
5815 | they happened to have the exact same effect in that language | |
5816 | (due to having only one @code{COMPLEX} type). | |
5817 | ||
5818 | @emph{Note:} When @samp{-ff90} is in effect, | |
5819 | @code{g77} treats @samp{REAL(@var{expr})}, where @var{expr} is of | |
5820 | type @code{COMPLEX}, as @samp{REALPART(@var{expr})}, | |
5821 | whereas with @samp{-fugly-complex -fno-f90} in effect, it is | |
5822 | treated as @samp{REAL(REALPART(@var{expr}))}. | |
5823 | ||
5824 | @xref{Ugly Complex Part Extraction}, for more information. | |
5825 | ||
5826 | @node CMPLX() of DOUBLE PRECISION | |
5827 | @subsection @code{CMPLX()} of @code{DOUBLE PRECISION} | |
26b9526e CB |
5828 | @cindex @code{Cmplx} intrinsic |
5829 | @cindex intrinsics, @code{Cmplx} | |
5ff904cd JL |
5830 | |
5831 | In accordance with Fortran 90 and at least some (perhaps all) | |
5832 | other compilers, the GNU Fortran language defines @code{CMPLX()} | |
5833 | as always returning a result that is type @code{COMPLEX(KIND=1)}. | |
5834 | ||
5835 | This means @samp{CMPLX(D1,D2)}, where @samp{D1} and @samp{D2} | |
5836 | are @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}), is treated as: | |
5837 | ||
5838 | @example | |
5839 | CMPLX(SNGL(D1), SNGL(D2)) | |
5840 | @end example | |
5841 | ||
5842 | (It was necessary for Fortran 90 to specify this behavior | |
5843 | for @code{DOUBLE PRECISION} arguments, since that is | |
5844 | the behavior mandated by FORTRAN 77.) | |
5845 | ||
5846 | The GNU Fortran language also provides the @code{DCMPLX()} intrinsic, | |
5847 | which is provided by some FORTRAN 77 compilers to construct | |
5848 | a @code{DOUBLE COMPLEX} entity from of @code{DOUBLE PRECISION} | |
5849 | operands. | |
5850 | However, this solution does not scale well when more @code{COMPLEX} types | |
5851 | (having various precisions and ranges) are offered by Fortran implementations. | |
5852 | ||
5853 | Fortran 90 extends the @code{CMPLX()} intrinsic by adding | |
5854 | an extra argument used to specify the desired kind of complex | |
5855 | result. | |
5856 | However, this solution is somewhat awkward to use, and | |
5857 | @code{g77} currently does not support it. | |
5858 | ||
5859 | The GNU Fortran language provides a simple way to build a complex | |
5860 | value out of two numbers, with the precise type of the value | |
5861 | determined by the types of the two numbers (via the usual | |
5862 | type-promotion mechanism): | |
5863 | ||
5864 | @example | |
5865 | COMPLEX(@var{real}, @var{imag}) | |
5866 | @end example | |
5867 | ||
5868 | When @var{real} and @var{imag} are the same @code{REAL} types, @code{COMPLEX()} | |
5869 | performs no conversion other than to put them together to form a | |
5870 | complex result of the same (complex version of real) type. | |
5871 | ||
5872 | @xref{Complex Intrinsic}, for more information. | |
5873 | ||
5874 | @node MIL-STD 1753 | |
5875 | @subsection MIL-STD 1753 Support | |
5876 | @cindex MIL-STD 1753 | |
5877 | ||
5878 | The GNU Fortran language includes the MIL-STD 1753 intrinsics | |
5879 | @code{BTEST}, @code{IAND}, @code{IBCLR}, @code{IBITS}, | |
5880 | @code{IBSET}, @code{IEOR}, @code{IOR}, @code{ISHFT}, | |
5881 | @code{ISHFTC}, @code{MVBITS}, and @code{NOT}. | |
5882 | ||
5883 | @node f77/f2c Intrinsics | |
5884 | @subsection @code{f77}/@code{f2c} Intrinsics | |
5885 | ||
5886 | The bit-manipulation intrinsics supported by traditional | |
5887 | @code{f77} and by @code{f2c} are available in the GNU Fortran language. | |
5888 | These include @code{AND}, @code{LSHIFT}, @code{OR}, @code{RSHIFT}, | |
5889 | and @code{XOR}. | |
5890 | ||
5891 | Also supported are the intrinsics @code{CDABS}, | |
5892 | @code{CDCOS}, @code{CDEXP}, @code{CDLOG}, @code{CDSIN}, | |
5893 | @code{CDSQRT}, @code{DCMPLX}, @code{DCONJG}, @code{DFLOAT}, | |
5894 | @code{DIMAG}, @code{DREAL}, and @code{IMAG}, | |
5895 | @code{ZABS}, @code{ZCOS}, @code{ZEXP}, @code{ZLOG}, @code{ZSIN}, | |
5896 | and @code{ZSQRT}. | |
5897 | ||
5898 | @node Table of Intrinsic Functions | |
5899 | @subsection Table of Intrinsic Functions | |
5900 | @cindex intrinsics, table of | |
5901 | @cindex table of intrinsics | |
5902 | ||
5903 | (Corresponds to Section 15.10 of ANSI X3.9-1978 FORTRAN 77.) | |
5904 | ||
5905 | The GNU Fortran language adds various functions, subroutines, types, | |
5906 | and arguments to the set of intrinsic functions in ANSI FORTRAN 77. | |
5907 | The complete set of intrinsics supported by the GNU Fortran language | |
5908 | is described below. | |
5909 | ||
5910 | Note that a name is not treated as that of an intrinsic if it is | |
5911 | specified in an @code{EXTERNAL} statement in the same program unit; | |
5912 | if a command-line option is used to disable the groups to which | |
5913 | the intrinsic belongs; or if the intrinsic is not named in an | |
5914 | @code{INTRINSIC} statement and a command-line option is used to | |
5915 | hide the groups to which the intrinsic belongs. | |
5916 | ||
5917 | So, it is recommended that any reference in a program unit to | |
5918 | an intrinsic procedure that is not a standard FORTRAN 77 | |
5919 | intrinsic be accompanied by an appropriate @code{INTRINSIC} | |
5920 | statement in that program unit. | |
5921 | This sort of defensive programming makes it more | |
5922 | likely that an implementation will issue a diagnostic rather | |
5923 | than generate incorrect code for such a reference. | |
5924 | ||
5925 | The terminology used below is based on that of the Fortran 90 | |
5926 | standard, so that the text may be more concise and accurate: | |
5927 | ||
5928 | @itemize @bullet | |
5929 | @item | |
5930 | @code{OPTIONAL} means the argument may be omitted. | |
5931 | ||
5932 | @item | |
5933 | @samp{A-1, A-2, @dots{}, A-n} means more than one argument | |
5934 | (generally named @samp{A}) may be specified. | |
5935 | ||
5936 | @item | |
5937 | @samp{scalar} means the argument must not be an array (must | |
5938 | be a variable or array element, or perhaps a constant if expressions | |
5939 | are permitted). | |
5940 | ||
5941 | @item | |
5942 | @samp{DIMENSION(4)} means the argument must be an array having 4 elements. | |
5943 | ||
5944 | @item | |
5945 | @code{INTENT(IN)} means the argument must be an expression | |
5946 | (such as a constant or a variable that is defined upon invocation | |
5947 | of the intrinsic). | |
5948 | ||
5949 | @item | |
5950 | @code{INTENT(OUT)} means the argument must be definable by the | |
5951 | invocation of the intrinsic (that is, must not be a constant nor | |
5952 | an expression involving operators other than array reference and | |
5953 | substring reference). | |
5954 | ||
5955 | @item | |
5956 | @code{INTENT(INOUT)} means the argument must be defined prior to, | |
5957 | and definable by, invocation of the intrinsic (a combination of | |
5958 | the requirements of @code{INTENT(IN)} and @code{INTENT(OUT)}. | |
5959 | ||
5960 | @item | |
58dd1c34 | 5961 | @xref{Kind Notation}, for an explanation of @code{KIND}. |
5ff904cd JL |
5962 | @end itemize |
5963 | ||
5964 | @ifinfo | |
5965 | (Note that the empty lines appearing in the menu below | |
5966 | are not intentional---they result from a bug in the | |
5967 | GNU @code{makeinfo} program@dots{}a program that, if it | |
5968 | did not exist, would leave this document in far worse shape!) | |
5969 | @end ifinfo | |
5970 | ||
5971 | @c The actual documentation for intrinsics comes from | |
5972 | @c intdoc.texi, which in turn is automatically generated | |
5973 | @c from the internal g77 tables in intrin.def _and_ the | |
5974 | @c largely hand-written text in intdoc.h. So, if you want | |
5975 | @c to change or add to existing documentation on intrinsics, | |
5976 | @c you probably want to edit intdoc.h. | |
5977 | @c | |
5978 | @set familyF77 | |
5979 | @set familyGNU | |
5980 | @set familyASC | |
5981 | @set familyMIL | |
5982 | @set familyF90 | |
5983 | @clear familyVXT | |
5984 | @clear familyFVZ | |
5985 | @set familyF2C | |
5986 | @set familyF2U | |
5987 | @clear familyBADU77 | |
5988 | @include intdoc.texi | |
5989 | ||
5990 | @node Scope and Classes of Names | |
5991 | @section Scope and Classes of Symbolic Names | |
26b9526e | 5992 | @cindex symbol names, scope and classes |
5ff904cd JL |
5993 | @cindex scope |
5994 | ||
5995 | (The following information augments or overrides the information in | |
5996 | Chapter 18 of ANSI X3.9-1978 FORTRAN 77 in specifying the GNU Fortran | |
5997 | language. | |
5998 | Chapter 18 of that document otherwise serves as the basis | |
5999 | for the relevant aspects of GNU Fortran.) | |
6000 | ||
6001 | @menu | |
6002 | * Underscores in Symbol Names:: | |
6003 | @end menu | |
6004 | ||
6005 | @node Underscores in Symbol Names | |
6006 | @subsection Underscores in Symbol Names | |
26b9526e | 6007 | @cindex underscore |
5ff904cd JL |
6008 | |
6009 | Underscores (@samp{_}) are accepted in symbol names after the first | |
6010 | character (which must be a letter). | |
6011 | ||
0b31330e DL |
6012 | @node I/O |
6013 | @section I/O | |
6014 | ||
6015 | @cindex dollar sign | |
6016 | A dollar sign at the end of an output format specification suppresses | |
6017 | the newline at the end of the output. | |
6018 | ||
6019 | @cindex <> edit descriptor | |
6020 | @cindex edit descriptor, <> | |
6021 | Edit descriptors in @code{FORMAT} statements may contain compile-time | |
6022 | @code{INTEGER} constant expressions in angle brackets, such as | |
6023 | @smallexample | |
6024 | 10 FORMAT (I<WIDTH>) | |
6025 | @end smallexample | |
6026 | ||
6027 | The @code{OPEN} specifier @code{NAME=} is equivalent to @code{FILE=}. | |
6028 | ||
66d18ad7 | 6029 | These Fortran 90 features are supported: |
0b31330e DL |
6030 | @itemize @bullet |
6031 | @item | |
26b9526e | 6032 | @cindex FORMAT descriptors |
0b31330e DL |
6033 | @cindex Z edit descriptor |
6034 | @cindex edit descriptor, Z | |
c12c792d CB |
6035 | @cindex O edit descriptor |
6036 | @cindex edit descriptor, O | |
6037 | The @code{O} and @code{Z} edit descriptors are supported for I/O of | |
6038 | integers in octal and hexadecimal formats, respectively. | |
0b31330e DL |
6039 | @item |
6040 | The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if | |
6041 | @code{STATUS='SCRATCH'} is supplied. The @code{STATUS='REPLACE'} | |
6042 | specifier is supported. | |
6043 | @end itemize | |
6044 | ||
6045 | @node Fortran 90 Features | |
6046 | @section Fortran 90 Features | |
6047 | @cindex Fortran 90 | |
26b9526e | 6048 | @cindex extensions, from Fortran 90 |
0b31330e DL |
6049 | |
6050 | For convenience this section collects a list (probably incomplete) of | |
6051 | the Fortran 90 features supported by the GNU Fortran language, even if | |
6052 | they are documented elsewhere. | |
6053 | @c makeinfo 1.68 objects to the nested parens | |
6054 | @ifnotinfo | |
6055 | @xref{Characters Lines Sequence,,{Characters, Lines, and Execution Sequence}}, | |
6056 | @end ifnotinfo | |
6057 | @ifinfo | |
6058 | @xref{Characters Lines Sequence}, | |
6059 | @end ifinfo | |
811cabee | 6060 | for information on additional fixed source form lexical issues. |
0b31330e | 6061 | @cindex @samp{-ffree-form} |
811cabee CB |
6062 | Further, the free source form is supported through the |
6063 | @samp{-ffree-form} option. | |
0b31330e | 6064 | @cindex @samp{-ff90} |
811cabee CB |
6065 | Other Fortran 90 features can be turned on by the @samp{-ff90} option; |
6066 | see @ref{Fortran 90}. | |
6067 | For information on the Fortran 90 intrinsics available, | |
6068 | see @ref{Table of Intrinsic Functions}. | |
0b31330e DL |
6069 | |
6070 | @table @asis | |
6071 | @item Automatic arrays in procedures | |
6072 | @item Character assignments | |
6073 | @cindex character assignments | |
6074 | In character assignments, the variable being assigned may occur on the | |
6075 | right hand side of the assignment. | |
6076 | @item Character strings | |
6077 | @cindex double quoted character constants | |
6078 | Strings may have zero length and substrings of character constants are | |
6079 | permitted. Character constants may be enclosed in double quotes | |
6080 | (@code{"}) as well as single quotes. @xref{Character Type}. | |
6081 | @item Construct names | |
6082 | (Symbolic tags on blocks.) @xref{Construct Names }. | |
6083 | @item @code{CYCLE} and @code{EXIT} | |
6084 | @xref{CYCLE and EXIT,,The @code{CYCLE} and @code{EXIT} Statements}. | |
6085 | @item @code{DOUBLE COMPLEX} | |
6086 | @xref{DOUBLE COMPLEX,,@code{DOUBLE COMPLEX} Statement | |
6087 | }. | |
6088 | @item @code{DO WHILE} | |
6089 | @xref{DO WHILE}. | |
6090 | @item @code{END} decoration | |
6091 | @xref{Statements}. | |
6092 | @item @code{END DO} | |
6093 | @xref{END DO}. | |
6094 | @item @code{KIND} | |
6095 | @item @code{IMPLICIT NONE} | |
6096 | @item @code{INCLUDE} statements | |
6097 | @xref{INCLUDE}. | |
26b9526e | 6098 | @item List-directed and namelist I/O on internal files |
0b31330e DL |
6099 | @item Binary, octal and hexadecimal constants |
6100 | These are supported more generally than required by Fortran 90. | |
6101 | @xref{Integer Type}. | |
c12c792d | 6102 | @item @samp{O} and @samp{Z} edit descriptors |
0b31330e DL |
6103 | @item @code{NAMELIST} |
6104 | @xref{NAMELIST}. | |
6105 | @item @code{OPEN} specifiers | |
6106 | @code{STATUS='REPLACE'} is supported. | |
26b9526e CB |
6107 | The @code{FILE=} specifier may be omitted in an @code{OPEN} statement if |
6108 | @code{STATUS='SCRATCH'} is supplied. | |
6109 | @item @code{FORMAT} edit descriptors | |
6110 | @cindex FORMAT descriptors | |
6111 | @cindex Z edit descriptor | |
6112 | @cindex edit descriptor, Z | |
6113 | The @code{Z} edit descriptor is supported. | |
0b31330e DL |
6114 | @item Relational operators |
6115 | The operators @code{<}, @code{<=}, @code{==}, @code{/=}, @code{>} and | |
6116 | @code{>=} may be used instead of @code{.LT.}, @code{.LE.}, @code{.EQ.}, | |
6117 | @code{.NE.}, @code{.GT.} and @code{.GE.} respectively. | |
6118 | @item @code{SELECT CASE} | |
6119 | Not fully implemented. @xref{SELECT CASE on CHARACTER Type,, | |
6120 | @code{SELECT CASE} on @code{CHARACTER} Type}. | |
6121 | @item Specification statements | |
6122 | A limited subset of the Fortran 90 syntax and semantics for variable | |
6123 | declarations is supported, including @code{KIND}. @xref{Kind Notation}. | |
6124 | (@code{KIND} is of limited usefulness in the absence of the | |
6125 | @code{KIND}-related intrinsics, since these intrinsics permit writing | |
6126 | more widely portable code.) An example of supported @code{KIND} usage | |
6127 | is: | |
6128 | @smallexample | |
6129 | INTEGER (KIND=1) :: FOO=1, BAR=2 | |
6130 | CHARACTER (LEN=3) FOO | |
6131 | @end smallexample | |
6132 | @code{PARAMETER} and @code{DIMENSION} attributes aren't supported. | |
6133 | @end table | |
6134 | ||
5ff904cd JL |
6135 | @node Other Dialects |
6136 | @chapter Other Dialects | |
6137 | ||
6138 | GNU Fortran supports a variety of features that are not | |
6139 | considered part of the GNU Fortran language itself, but | |
6140 | are representative of various dialects of Fortran that | |
6141 | @code{g77} supports in whole or in part. | |
6142 | ||
6143 | Any of the features listed below might be disallowed by | |
6144 | @code{g77} unless some command-line option is specified. | |
6145 | Currently, some of the features are accepted using the | |
6146 | default invocation of @code{g77}, but that might change | |
6147 | in the future. | |
6148 | ||
6149 | @emph{Note: This portion of the documentation definitely needs a lot | |
6150 | of work!} | |
6151 | ||
6152 | @menu | |
6153 | * Source Form:: Details of fixed-form and free-form source. | |
6154 | * Trailing Comment:: Use of @samp{/*} to start a comment. | |
6155 | * Debug Line:: Use of @samp{D} in column 1. | |
6156 | * Dollar Signs:: Use of @samp{$} in symbolic names. | |
6157 | * Case Sensitivity:: Uppercase and lowercase in source files. | |
6158 | * VXT Fortran:: @dots{}versus the GNU Fortran language. | |
6159 | * Fortran 90:: @dots{}versus the GNU Fortran language. | |
6160 | * Pedantic Compilation:: Enforcing the standard. | |
6161 | * Distensions:: Misfeatures supported by GNU Fortran. | |
6162 | @end menu | |
6163 | ||
6164 | @node Source Form | |
6165 | @section Source Form | |
6166 | @cindex source file format | |
26b9526e CB |
6167 | @cindex source format |
6168 | @cindex file, source | |
5ff904cd JL |
6169 | @cindex source code |
6170 | @cindex code, source | |
6171 | @cindex fixed form | |
6172 | @cindex free form | |
6173 | ||
6174 | GNU Fortran accepts programs written in either fixed form or | |
6175 | free form. | |
6176 | ||
6177 | Fixed form | |
6178 | corresponds to ANSI FORTRAN 77 (plus popular extensions, such as | |
6179 | allowing tabs) and Fortran 90's fixed form. | |
6180 | ||
6181 | Free form corresponds to | |
6182 | Fortran 90's free form (though possibly not entirely up-to-date, and | |
6183 | without complaining about some things that for which Fortran 90 requires | |
6184 | diagnostics, such as the spaces in the constant in @samp{R = 3 . 1}). | |
6185 | ||
6186 | The way a Fortran compiler views source files depends entirely on the | |
6187 | implementation choices made for the compiler, since those choices | |
6188 | are explicitly left to the implementation by the published Fortran | |
6189 | standards. | |
6190 | GNU Fortran currently tries to be somewhat like a few popular compilers | |
6191 | (@code{f2c}, Digital (``DEC'') Fortran, and so on), though a cleaner default | |
6192 | definition along with more | |
6193 | flexibility offered by command-line options is likely to be offered | |
6194 | in version 0.6. | |
6195 | ||
6196 | This section describes how @code{g77} interprets source lines. | |
6197 | ||
6198 | @menu | |
6199 | * Carriage Returns:: Carriage returns ignored. | |
6200 | * Tabs:: Tabs converted to spaces. | |
6201 | * Short Lines:: Short lines padded with spaces (fixed-form only). | |
6202 | * Long Lines:: Long lines truncated. | |
6203 | * Ampersands:: Special Continuation Lines. | |
6204 | @end menu | |
6205 | ||
6206 | @node Carriage Returns | |
6207 | @subsection Carriage Returns | |
6208 | @cindex carriage returns | |
6209 | ||
6210 | Carriage returns (@samp{\r}) in source lines are ignored. | |
6211 | This is somewhat different from @code{f2c}, which seems to treat them as | |
6212 | spaces outside character/Hollerith constants, and encodes them as @samp{\r} | |
6213 | inside such constants. | |
6214 | ||
6215 | @node Tabs | |
6216 | @subsection Tabs | |
26b9526e CB |
6217 | @cindex tab character |
6218 | @cindex horizontal tab | |
5ff904cd JL |
6219 | |
6220 | A source line with a @key{TAB} character anywhere in it is treated as | |
6221 | entirely significant---however long it is---instead of ending in | |
6222 | column 72 (for fixed-form source) or 132 (for free-form source). | |
6223 | This also is different from @code{f2c}, which encodes tabs as | |
6224 | @samp{\t} (the ASCII @key{TAB} character) inside character | |
6225 | and Hollerith constants, but nevertheless seems to treat the column | |
6226 | position as if it had been affected by the canonical tab positioning. | |
6227 | ||
6228 | @code{g77} effectively | |
6229 | translates tabs to the appropriate number of spaces (a la the default | |
6230 | for the UNIX @code{expand} command) before doing any other processing, other | |
6231 | than (currently) noting whether a tab was found on a line and using this | |
6232 | information to decide how to interpret the length of the line and continued | |
6233 | constants. | |
6234 | ||
6235 | Note that this default behavior probably will change for version 0.6, | |
6236 | when it will presumably be available via a command-line option. | |
6237 | The default as of version 0.6 is planned to be a ``pure visual'' | |
6238 | model, where tabs are immediately | |
6239 | converted to spaces and otherwise have no effect, so the way a typical | |
6240 | user sees source lines produces a consistent result no matter how the | |
6241 | spacing in those source lines is actually implemented via tabs, spaces, | |
6242 | and trailing tabs/spaces before newline. | |
6243 | Command-line options are likely to be added to specify whether all or | |
6244 | just-tabbed lines are to be extended to 132 or full input-line length, | |
6245 | and perhaps even an option will be added to specify the truncated-line | |
6246 | behavior to which some Digital compilers default (and which affects | |
6247 | the way continued character/Hollerith constants are interpreted). | |
6248 | ||
6249 | @node Short Lines | |
6250 | @subsection Short Lines | |
6251 | @cindex short source lines | |
26b9526e | 6252 | @cindex space, padding with |
5ff904cd JL |
6253 | @cindex source lines, short |
6254 | @cindex lines, short | |
6255 | ||
6256 | Source lines shorter than the applicable fixed-form length are treated as | |
6257 | if they were padded with spaces to that length. | |
6258 | (None of this is relevant to source files written in free form.) | |
6259 | ||
6260 | This affects only | |
6261 | continued character and Hollerith constants, and is a different | |
6262 | interpretation than provided by some other popular compilers | |
6263 | (although a bit more consistent with the traditional punched-card | |
6264 | basis of Fortran and the way the Fortran standard expressed fixed | |
6265 | source form). | |
6266 | ||
6267 | @code{g77} might someday offer an option to warn about cases where differences | |
6268 | might be seen as a result of this treatment, and perhaps an option to | |
6269 | specify the alternate behavior as well. | |
6270 | ||
6271 | Note that this padding cannot apply to lines that are effectively of | |
6272 | infinite length---such lines are specified using command-line options | |
6273 | like @samp{-ffixed-line-length-none}, for example. | |
6274 | ||
6275 | @node Long Lines | |
6276 | @subsection Long Lines | |
6277 | @cindex long source lines | |
26b9526e | 6278 | @cindex truncation, of long lines |
5ff904cd JL |
6279 | @cindex lines, long |
6280 | @cindex source lines, long | |
6281 | ||
6282 | Source lines longer than the applicable length are truncated to that | |
6283 | length. | |
6284 | Currently, @code{g77} does not warn if the truncated characters are | |
6285 | not spaces, to accommodate existing code written for systems that | |
6286 | treated truncated text as commentary (especially in columns 73 through 80). | |
6287 | ||
6288 | @xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}, | |
6289 | for information on the @samp{-ffixed-line-length-@var{n}} option, | |
6290 | which can be used to set the line length applicable to fixed-form | |
6291 | source files. | |
6292 | ||
6293 | @node Ampersands | |
6294 | @subsection Ampersand Continuation Line | |
6295 | @cindex ampersand continuation line | |
6296 | @cindex continuation line, ampersand | |
6297 | ||
6298 | A @samp{&} in column 1 of fixed-form source denotes an arbitrary-length | |
6299 | continuation line, imitating the behavior of @code{f2c}. | |
6300 | ||
6301 | @node Trailing Comment | |
6302 | @section Trailing Comment | |
6303 | ||
c5a951a8 | 6304 | @cindex trailing comment |
26b9526e CB |
6305 | @cindex comment |
6306 | @cindex characters, comment | |
c5a951a8 | 6307 | @cindex /* |
26b9526e CB |
6308 | @cindex ! |
6309 | @cindex exclamation point | |
5ff904cd JL |
6310 | @code{g77} supports use of @samp{/*} to start a trailing |
6311 | comment. | |
6312 | In the GNU Fortran language, @samp{!} is used for this purpose. | |
6313 | ||
6314 | @samp{/*} is not in the GNU Fortran language | |
6315 | because the use of @samp{/*} in a program might | |
6316 | suggest to some readers that a block, not trailing, comment is | |
6317 | started (and thus ended by @samp{*/}, not end of line), | |
6318 | since that is the meaning of @samp{/*} in C. | |
6319 | ||
6320 | Also, such readers might think they can use @samp{//} to start | |
6321 | a trailing comment as an alternative to @samp{/*}, but | |
6322 | @samp{//} already denotes concatenation, and such a ``comment'' | |
6323 | might actually result in a program that compiles without | |
6324 | error (though it would likely behave incorrectly). | |
6325 | ||
6326 | @node Debug Line | |
6327 | @section Debug Line | |
6328 | @cindex debug line | |
c5a951a8 | 6329 | @cindex comment line, debug |
5ff904cd JL |
6330 | |
6331 | Use of @samp{D} or @samp{d} as the first character (column 1) of | |
6332 | a source line denotes a debug line. | |
6333 | ||
6334 | In turn, a debug line is treated as either a comment line | |
6335 | or a normal line, depending on whether debug lines are enabled. | |
6336 | ||
6337 | When treated as a comment line, a line beginning with @samp{D} or | |
6338 | @samp{d} is treated as if it the first character was @samp{C} or @samp{c}, respectively. | |
6339 | When treated as a normal line, such a line is treated as if | |
6340 | the first character was @key{SPC} (space). | |
6341 | ||
6342 | (Currently, @code{g77} provides no means for treating debug | |
6343 | lines as normal lines.) | |
6344 | ||
6345 | @node Dollar Signs | |
6346 | @section Dollar Signs in Symbol Names | |
6347 | @cindex dollar sign | |
6348 | @cindex $ | |
6349 | ||
6350 | Dollar signs (@samp{$}) are allowed in symbol names (after the first character) | |
6351 | when the @samp{-fdollar-ok} option is specified. | |
6352 | ||
6353 | @node Case Sensitivity | |
6354 | @section Case Sensitivity | |
6355 | @cindex case sensitivity | |
6356 | @cindex source file format | |
6357 | @cindex code, source | |
6358 | @cindex source code | |
6359 | @cindex uppercase letters | |
6360 | @cindex lowercase letters | |
6361 | @cindex letters, uppercase | |
6362 | @cindex letters, lowercase | |
6363 | ||
6364 | GNU Fortran offers the programmer way too much flexibility in deciding | |
6365 | how source files are to be treated vis-a-vis uppercase and lowercase | |
6366 | characters. | |
6367 | There are 66 useful settings that affect case sensitivity, plus 10 | |
6368 | settings that are nearly useless, with the remaining 116 settings | |
6369 | being either redundant or useless. | |
6370 | ||
6371 | None of these settings have any effect on the contents of comments | |
6372 | (the text after a @samp{c} or @samp{C} in Column 1, for example) | |
6373 | or of character or Hollerith constants. | |
6374 | Note that things like the @samp{E} in the statement | |
6375 | @samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB} | |
6376 | are considered built-in keywords, and so are affected by | |
6377 | these settings. | |
6378 | ||
6379 | Low-level switches are identified in this section as follows: | |
6380 | ||
6381 | @itemize @w{} | |
6382 | @item A | |
6383 | Source Case Conversion: | |
6384 | ||
6385 | @itemize @w{} | |
6386 | @item 0 | |
6387 | Preserve (see Note 1) | |
6388 | @item 1 | |
6389 | Convert to Upper Case | |
6390 | @item 2 | |
6391 | Convert to Lower Case | |
6392 | @end itemize | |
6393 | ||
6394 | @item B | |
6395 | Built-in Keyword Matching: | |
6396 | ||
6397 | @itemize @w{} | |
6398 | @item 0 | |
6399 | Match Any Case (per-character basis) | |
6400 | @item 1 | |
6401 | Match Upper Case Only | |
6402 | @item 2 | |
6403 | Match Lower Case Only | |
6404 | @item 3 | |
6405 | Match InitialCaps Only (see tables for spellings) | |
6406 | @end itemize | |
6407 | ||
6408 | @item C | |
6409 | Built-in Intrinsic Matching: | |
6410 | ||
6411 | @itemize @w{} | |
6412 | @item 0 | |
6413 | Match Any Case (per-character basis) | |
6414 | @item 1 | |
6415 | Match Upper Case Only | |
6416 | @item 2 | |
6417 | Match Lower Case Only | |
6418 | @item 3 | |
6419 | Match InitialCaps Only (see tables for spellings) | |
6420 | @end itemize | |
6421 | ||
6422 | @item D | |
6423 | User-defined Symbol Possibilities (warnings only): | |
6424 | ||
6425 | @itemize @w{} | |
6426 | @item 0 | |
6427 | Allow Any Case (per-character basis) | |
6428 | @item 1 | |
6429 | Allow Upper Case Only | |
6430 | @item 2 | |
6431 | Allow Lower Case Only | |
6432 | @item 3 | |
6433 | Allow InitialCaps Only (see Note 2) | |
6434 | @end itemize | |
6435 | @end itemize | |
6436 | ||
6437 | Note 1: @code{g77} eventually will support @code{NAMELIST} in a manner that is | |
6438 | consistent with these source switches---in the sense that input will be | |
6439 | expected to meet the same requirements as source code in terms | |
6440 | of matching symbol names and keywords (for the exponent letters). | |
6441 | ||
95a1b676 | 6442 | Currently, however, @code{NAMELIST} is supported by @code{libg2c}, |
5ff904cd JL |
6443 | which uppercases @code{NAMELIST} input and symbol names for matching. |
6444 | This means not only that @code{NAMELIST} output currently shows symbol | |
6445 | (and keyword) names in uppercase even if lower-case source | |
6446 | conversion (option A2) is selected, but that @code{NAMELIST} cannot be | |
6447 | adequately supported when source case preservation (option A0) | |
6448 | is selected. | |
6449 | ||
6450 | If A0 is selected, a warning message will be | |
6451 | output for each @code{NAMELIST} statement to this effect. | |
6452 | The behavior | |
6453 | of the program is undefined at run time if two or more symbol names | |
6454 | appear in a given @code{NAMELIST} such that the names are identical | |
6455 | when converted to upper case (e.g. @samp{NAMELIST /X/ VAR, Var, var}). | |
6456 | For complete and total elegance, perhaps there should be a warning | |
6457 | when option A2 is selected, since the output of NAMELIST is currently | |
6458 | in uppercase but will someday be lowercase (when a @code{libg77} is written), | |
6459 | but that seems to be overkill for a product in beta test. | |
6460 | ||
6461 | Note 2: Rules for InitialCaps names are: | |
6462 | ||
4e6a1440 | 6463 | @itemize @minus |
5ff904cd JL |
6464 | @item |
6465 | Must be a single uppercase letter, @strong{or} | |
6466 | @item | |
6467 | Must start with an uppercase letter and contain at least one | |
6468 | lowercase letter. | |
6469 | @end itemize | |
6470 | ||
6471 | So @samp{A}, @samp{Ab}, @samp{ABc}, @samp{AbC}, and @samp{Abc} are | |
6472 | valid InitialCaps names, but @samp{AB}, @samp{A2}, and @samp{ABC} are | |
6473 | not. | |
6474 | Note that most, but not all, built-in names meet these | |
6475 | requirements---the exceptions are some of the two-letter format | |
4e6a1440 | 6476 | specifiers, such as @code{BN} and @code{BZ}. |
5ff904cd JL |
6477 | |
6478 | Here are the names of the corresponding command-line options: | |
6479 | ||
6480 | @smallexample | |
6481 | A0: -fsource-case-preserve | |
6482 | A1: -fsource-case-upper | |
6483 | A2: -fsource-case-lower | |
6484 | ||
6485 | B0: -fmatch-case-any | |
6486 | B1: -fmatch-case-upper | |
6487 | B2: -fmatch-case-lower | |
6488 | B3: -fmatch-case-initcap | |
6489 | ||
6490 | C0: -fintrin-case-any | |
6491 | C1: -fintrin-case-upper | |
6492 | C2: -fintrin-case-lower | |
6493 | C3: -fintrin-case-initcap | |
6494 | ||
6495 | D0: -fsymbol-case-any | |
6496 | D1: -fsymbol-case-upper | |
6497 | D2: -fsymbol-case-lower | |
6498 | D3: -fsymbol-case-initcap | |
6499 | @end smallexample | |
6500 | ||
6501 | Useful combinations of the above settings, along with abbreviated | |
6502 | option names that set some of these combinations all at once: | |
6503 | ||
6504 | @smallexample | |
6505 | 1: A0-- B0--- C0--- D0--- -fcase-preserve | |
6506 | 2: A0-- B0--- C0--- D-1-- | |
6507 | 3: A0-- B0--- C0--- D--2- | |
6508 | 4: A0-- B0--- C0--- D---3 | |
6509 | 5: A0-- B0--- C-1-- D0--- | |
6510 | 6: A0-- B0--- C-1-- D-1-- | |
6511 | 7: A0-- B0--- C-1-- D--2- | |
6512 | 8: A0-- B0--- C-1-- D---3 | |
6513 | 9: A0-- B0--- C--2- D0--- | |
6514 | 10: A0-- B0--- C--2- D-1-- | |
6515 | 11: A0-- B0--- C--2- D--2- | |
6516 | 12: A0-- B0--- C--2- D---3 | |
6517 | 13: A0-- B0--- C---3 D0--- | |
6518 | 14: A0-- B0--- C---3 D-1-- | |
6519 | 15: A0-- B0--- C---3 D--2- | |
6520 | 16: A0-- B0--- C---3 D---3 | |
6521 | 17: A0-- B-1-- C0--- D0--- | |
6522 | 18: A0-- B-1-- C0--- D-1-- | |
6523 | 19: A0-- B-1-- C0--- D--2- | |
6524 | 20: A0-- B-1-- C0--- D---3 | |
6525 | 21: A0-- B-1-- C-1-- D0--- | |
6526 | 22: A0-- B-1-- C-1-- D-1-- -fcase-strict-upper | |
6527 | 23: A0-- B-1-- C-1-- D--2- | |
6528 | 24: A0-- B-1-- C-1-- D---3 | |
6529 | 25: A0-- B-1-- C--2- D0--- | |
6530 | 26: A0-- B-1-- C--2- D-1-- | |
6531 | 27: A0-- B-1-- C--2- D--2- | |
6532 | 28: A0-- B-1-- C--2- D---3 | |
6533 | 29: A0-- B-1-- C---3 D0--- | |
6534 | 30: A0-- B-1-- C---3 D-1-- | |
6535 | 31: A0-- B-1-- C---3 D--2- | |
6536 | 32: A0-- B-1-- C---3 D---3 | |
6537 | 33: A0-- B--2- C0--- D0--- | |
6538 | 34: A0-- B--2- C0--- D-1-- | |
6539 | 35: A0-- B--2- C0--- D--2- | |
6540 | 36: A0-- B--2- C0--- D---3 | |
6541 | 37: A0-- B--2- C-1-- D0--- | |
6542 | 38: A0-- B--2- C-1-- D-1-- | |
6543 | 39: A0-- B--2- C-1-- D--2- | |
6544 | 40: A0-- B--2- C-1-- D---3 | |
6545 | 41: A0-- B--2- C--2- D0--- | |
6546 | 42: A0-- B--2- C--2- D-1-- | |
6547 | 43: A0-- B--2- C--2- D--2- -fcase-strict-lower | |
6548 | 44: A0-- B--2- C--2- D---3 | |
6549 | 45: A0-- B--2- C---3 D0--- | |
6550 | 46: A0-- B--2- C---3 D-1-- | |
6551 | 47: A0-- B--2- C---3 D--2- | |
6552 | 48: A0-- B--2- C---3 D---3 | |
6553 | 49: A0-- B---3 C0--- D0--- | |
6554 | 50: A0-- B---3 C0--- D-1-- | |
6555 | 51: A0-- B---3 C0--- D--2- | |
6556 | 52: A0-- B---3 C0--- D---3 | |
6557 | 53: A0-- B---3 C-1-- D0--- | |
6558 | 54: A0-- B---3 C-1-- D-1-- | |
6559 | 55: A0-- B---3 C-1-- D--2- | |
6560 | 56: A0-- B---3 C-1-- D---3 | |
6561 | 57: A0-- B---3 C--2- D0--- | |
6562 | 58: A0-- B---3 C--2- D-1-- | |
6563 | 59: A0-- B---3 C--2- D--2- | |
6564 | 60: A0-- B---3 C--2- D---3 | |
6565 | 61: A0-- B---3 C---3 D0--- | |
6566 | 62: A0-- B---3 C---3 D-1-- | |
6567 | 63: A0-- B---3 C---3 D--2- | |
6568 | 64: A0-- B---3 C---3 D---3 -fcase-initcap | |
6569 | 65: A-1- B01-- C01-- D01-- -fcase-upper | |
6570 | 66: A--2 B0-2- C0-2- D0-2- -fcase-lower | |
6571 | @end smallexample | |
6572 | ||
6573 | Number 22 is the ``strict'' ANSI FORTRAN 77 model wherein all input | |
6574 | (except comments, character constants, and Hollerith strings) must | |
6575 | be entered in uppercase. | |
6576 | Use @samp{-fcase-strict-upper} to specify this | |
6577 | combination. | |
6578 | ||
6579 | Number 43 is like Number 22 except all input must be lowercase. Use | |
6580 | @samp{-fcase-strict-lower} to specify this combination. | |
6581 | ||
6582 | Number 65 is the ``classic'' ANSI FORTRAN 77 model as implemented on many | |
6583 | non-UNIX machines whereby all the source is translated to uppercase. | |
6584 | Use @samp{-fcase-upper} to specify this combination. | |
6585 | ||
6586 | Number 66 is the ``canonical'' UNIX model whereby all the source is | |
6587 | translated to lowercase. | |
6588 | Use @samp{-fcase-lower} to specify this combination. | |
6589 | ||
6590 | There are a few nearly useless combinations: | |
6591 | ||
6592 | @smallexample | |
6593 | 67: A-1- B01-- C01-- D--2- | |
6594 | 68: A-1- B01-- C01-- D---3 | |
6595 | 69: A-1- B01-- C--23 D01-- | |
6596 | 70: A-1- B01-- C--23 D--2- | |
6597 | 71: A-1- B01-- C--23 D---3 | |
6598 | 72: A--2 B01-- C0-2- D-1-- | |
6599 | 73: A--2 B01-- C0-2- D---3 | |
6600 | 74: A--2 B01-- C-1-3 D0-2- | |
6601 | 75: A--2 B01-- C-1-3 D-1-- | |
6602 | 76: A--2 B01-- C-1-3 D---3 | |
6603 | @end smallexample | |
6604 | ||
6605 | The above allow some programs to be compiled but with restrictions that | |
6606 | make most useful programs impossible: Numbers 67 and 72 warn about | |
6607 | @emph{any} user-defined symbol names (such as @samp{SUBROUTINE FOO}); | |
6608 | Numbers | |
6609 | 68 and 73 warn about any user-defined symbol names longer than one | |
6610 | character that don't have at least one non-alphabetic character after | |
6611 | the first; | |
6612 | Numbers 69 and 74 disallow any references to intrinsics; | |
6613 | and Numbers 70, 71, 75, and 76 are combinations of the restrictions in | |
6614 | 67+69, 68+69, 72+74, and 73+74, respectively. | |
6615 | ||
6616 | All redundant combinations are shown in the above tables anyplace | |
6617 | where more than one setting is shown for a low-level switch. | |
6618 | For example, @samp{B0-2-} means either setting 0 or 2 is valid for switch B. | |
6619 | The ``proper'' setting in such a case is the one that copies the setting | |
6620 | of switch A---any other setting might slightly reduce the speed of | |
6621 | the compiler, though possibly to an unmeasurable extent. | |
6622 | ||
6623 | All remaining combinations are useless in that they prevent successful | |
6624 | compilation of non-null source files (source files with something other | |
6625 | than comments). | |
6626 | ||
6627 | @node VXT Fortran | |
6628 | @section VXT Fortran | |
6629 | ||
6630 | @cindex VXT extensions | |
6631 | @cindex extensions, VXT | |
6632 | @code{g77} supports certain constructs that | |
6633 | have different meanings in VXT Fortran than they | |
6634 | do in the GNU Fortran language. | |
6635 | ||
6636 | Generally, this manual uses the invented term VXT Fortran to refer | |
6637 | VAX FORTRAN (circa v4). | |
6638 | That compiler offered many popular features, though not necessarily | |
6639 | those that are specific to the VAX processor architecture, | |
6640 | the VMS operating system, | |
6641 | or Digital Equipment Corporation's Fortran product line. | |
6642 | (VAX and VMS probably are trademarks of Digital Equipment | |
6643 | Corporation.) | |
6644 | ||
6645 | An extension offered by a Digital Fortran product that also is | |
6646 | offered by several other Fortran products for different kinds of | |
6647 | systems is probably going to be considered for inclusion in @code{g77} | |
6648 | someday, and is considered a VXT Fortran feature. | |
6649 | ||
6650 | The @samp{-fvxt} option generally specifies that, where | |
6651 | the meaning of a construct is ambiguous (means one thing | |
6652 | in GNU Fortran and another in VXT Fortran), the VXT Fortran | |
6653 | meaning is to be assumed. | |
6654 | ||
6655 | @menu | |
6656 | * Double Quote Meaning:: @samp{"2000} as octal constant. | |
6657 | * Exclamation Point:: @samp{!} in column 6. | |
6658 | @end menu | |
6659 | ||
6660 | @node Double Quote Meaning | |
6661 | @subsection Meaning of Double Quote | |
6662 | @cindex double quotes | |
6663 | @cindex character constants | |
6664 | @cindex constants, character | |
6665 | @cindex octal constants | |
6666 | @cindex constants, octal | |
6667 | ||
6668 | @code{g77} treats double-quote (@samp{"}) | |
6669 | as beginning an octal constant of @code{INTEGER(KIND=1)} type | |
4e6a1440 | 6670 | when the @samp{-fvxt} option is specified. |
5ff904cd JL |
6671 | The form of this octal constant is |
6672 | ||
6673 | @example | |
6674 | "@var{octal-digits} | |
6675 | @end example | |
6676 | ||
6677 | @noindent | |
6678 | where @var{octal-digits} is a nonempty string of characters in | |
6679 | the set @samp{01234567}. | |
6680 | ||
4e6a1440 | 6681 | For example, the @samp{-fvxt} option permits this: |
5ff904cd JL |
6682 | |
6683 | @example | |
6684 | PRINT *, "20 | |
6685 | END | |
6686 | @end example | |
6687 | ||
6688 | @noindent | |
6689 | The above program would print the value @samp{16}. | |
6690 | ||
6691 | @xref{Integer Type}, for information on the preferred construct | |
6692 | for integer constants specified using GNU Fortran's octal notation. | |
6693 | ||
6694 | (In the GNU Fortran language, the double-quote character (@samp{"}) | |
6695 | delimits a character constant just as does apostrophe (@samp{'}). | |
6696 | There is no way to allow | |
6697 | both constructs in the general case, since statements like | |
6698 | @samp{PRINT *,"2000 !comment?"} would be ambiguous.) | |
6699 | ||
6700 | @node Exclamation Point | |
6701 | @subsection Meaning of Exclamation Point in Column 6 | |
26b9526e CB |
6702 | @cindex ! |
6703 | @cindex exclamation point | |
5ff904cd JL |
6704 | @cindex continuation character |
6705 | @cindex characters, continuation | |
6706 | @cindex comment character | |
6707 | @cindex characters, comment | |
6708 | ||
6709 | @code{g77} treats an exclamation point (@samp{!}) in column 6 of | |
6710 | a fixed-form source file | |
6711 | as a continuation character rather than | |
6712 | as the beginning of a comment | |
6713 | (as it does in any other column) | |
4e6a1440 | 6714 | when the @samp{-fvxt} option is specified. |
5ff904cd JL |
6715 | |
6716 | The following program, when run, prints a message indicating | |
6717 | whether it is interpreted according to GNU Fortran (and Fortran 90) | |
6718 | rules or VXT Fortran rules: | |
6719 | ||
6720 | @smallexample | |
6721 | C234567 (This line begins in column 1.) | |
6722 | I = 0 | |
6723 | !1 | |
6724 | IF (I.EQ.0) PRINT *, ' I am a VXT Fortran program' | |
6725 | IF (I.EQ.1) PRINT *, ' I am a Fortran 90 program' | |
6726 | IF (I.LT.0 .OR. I.GT.1) PRINT *, ' I am a HAL 9000 computer' | |
6727 | END | |
6728 | @end smallexample | |
6729 | ||
6730 | (In the GNU Fortran and Fortran 90 languages, exclamation point is | |
6731 | a valid character and, unlike space (@key{SPC}) or zero (@samp{0}), | |
6732 | marks a line as a continuation line when it appears in column 6.) | |
6733 | ||
6734 | @node Fortran 90 | |
6735 | @section Fortran 90 | |
6736 | @cindex compatibility, Fortran 90 | |
26b9526e | 6737 | @cindex Fortran 90, compatibility |
5ff904cd JL |
6738 | |
6739 | The GNU Fortran language includes a number of features that are | |
6740 | part of Fortran 90, even when the @samp{-ff90} option is not specified. | |
6741 | The features enabled by @samp{-ff90} are intended to be those that, | |
6742 | when @samp{-ff90} is not specified, would have another | |
6743 | meaning to @code{g77}---usually meaning something invalid in the | |
6744 | GNU Fortran language. | |
6745 | ||
6746 | So, the purpose of @samp{-ff90} is not to specify whether @code{g77} is | |
6747 | to gratuitously reject Fortran 90 constructs. | |
6748 | The @samp{-pedantic} option specified with @samp{-fno-f90} is intended | |
6749 | to do that, although its implementation is certainly incomplete at | |
6750 | this point. | |
6751 | ||
6752 | When @samp{-ff90} is specified: | |
6753 | ||
6754 | @itemize @bullet | |
6755 | @item | |
6756 | The type of @samp{REAL(@var{expr})} and @samp{AIMAG(@var{expr})}, | |
6757 | where @var{expr} is @code{COMPLEX} type, | |
6758 | is the same type as the real part of @var{expr}. | |
6759 | ||
6760 | For example, assuming @samp{Z} is type @code{COMPLEX(KIND=2)}, | |
6761 | @samp{REAL(Z)} would return a value of type @code{REAL(KIND=2)}, | |
6762 | not of type @code{REAL(KIND=1)}, since @samp{-ff90} is specified. | |
6763 | @end itemize | |
6764 | ||
6765 | @node Pedantic Compilation | |
6766 | @section Pedantic Compilation | |
6767 | @cindex pedantic compilation | |
6768 | @cindex compilation, pedantic | |
6769 | ||
6770 | The @samp{-fpedantic} command-line option specifies that @code{g77} | |
6771 | is to warn about code that is not standard-conforming. | |
6772 | This is useful for finding | |
6773 | some extensions @code{g77} accepts that other compilers might not accept. | |
6774 | (Note that the @samp{-pedantic} and @samp{-pedantic-errors} options | |
6775 | always imply @samp{-fpedantic}.) | |
6776 | ||
6777 | With @samp{-fno-f90} in force, ANSI FORTRAN 77 is used as the standard | |
6778 | for conforming code. | |
6779 | With @samp{-ff90} in force, Fortran 90 is used. | |
6780 | ||
6781 | The constructs for which @code{g77} issues diagnostics when @samp{-fpedantic} | |
6782 | and @samp{-fno-f90} are in force are: | |
6783 | ||
6784 | @itemize @bullet | |
6785 | @item | |
6786 | Automatic arrays, as in | |
6787 | ||
6788 | @example | |
6789 | SUBROUTINE X(N) | |
6790 | REAL A(N) | |
6791 | @dots{} | |
6792 | @end example | |
6793 | ||
6794 | @noindent | |
6795 | where @samp{A} is not listed in any @code{ENTRY} statement, | |
6796 | and thus is not a dummy argument. | |
6797 | ||
6798 | @item | |
6799 | The commas in @samp{READ (5), I} and @samp{WRITE (10), J}. | |
6800 | ||
6801 | These commas are disallowed by FORTRAN 77, but, while strictly | |
6802 | superfluous, are syntactically elegant, | |
6803 | especially given that commas are required in statements such | |
6804 | as @samp{READ 99, I} and @samp{PRINT *, J}. | |
6805 | Many compilers permit the superfluous commas for this reason. | |
6806 | ||
6807 | @item | |
6808 | @code{DOUBLE COMPLEX}, either explicitly or implicitly. | |
6809 | ||
6810 | An explicit use of this type is via a @code{DOUBLE COMPLEX} or | |
6811 | @code{IMPLICIT DOUBLE COMPLEX} statement, for examples. | |
6812 | ||
6813 | An example of an implicit use is the expression @samp{C*D}, | |
6814 | where @samp{C} is @code{COMPLEX(KIND=1)} | |
6815 | and @samp{D} is @code{DOUBLE PRECISION}. | |
6816 | This expression is prohibited by ANSI FORTRAN 77 | |
6817 | because the rules of promotion would suggest that it | |
6818 | produce a @code{DOUBLE COMPLEX} result---a type not | |
6819 | provided for by that standard. | |
6820 | ||
6821 | @item | |
6822 | Automatic conversion of numeric | |
6823 | expressions to @code{INTEGER(KIND=1)} in contexts such as: | |
6824 | ||
4e6a1440 | 6825 | @itemize @minus |
5ff904cd JL |
6826 | @item |
6827 | Array-reference indexes. | |
6828 | @item | |
6829 | Alternate-return values. | |
6830 | @item | |
6831 | Computed @code{GOTO}. | |
6832 | @item | |
6833 | @code{FORMAT} run-time expressions (not yet supported). | |
6834 | @item | |
6835 | Dimension lists in specification statements. | |
6836 | @item | |
6837 | Numbers for I/O statements (such as @samp{READ (UNIT=3.2), I}) | |
6838 | @item | |
6839 | Sizes of @code{CHARACTER} entities in specification statements. | |
6840 | @item | |
6841 | Kind types in specification entities (a Fortran 90 feature). | |
6842 | @item | |
6843 | Initial, terminal, and incrementation parameters for implied-@code{DO} | |
6844 | constructs in @code{DATA} statements. | |
6845 | @end itemize | |
6846 | ||
6847 | @item | |
6848 | Automatic conversion of @code{LOGICAL} expressions to @code{INTEGER} | |
6849 | in contexts such as arithmetic @code{IF} (where @code{COMPLEX} | |
6850 | expressions are disallowed anyway). | |
6851 | ||
6852 | @item | |
6853 | Zero-size array dimensions, as in: | |
6854 | ||
6855 | @example | |
6856 | INTEGER I(10,20,4:2) | |
6857 | @end example | |
6858 | ||
6859 | @item | |
6860 | Zero-length @code{CHARACTER} entities, as in: | |
6861 | ||
6862 | @example | |
6863 | PRINT *, '' | |
6864 | @end example | |
6865 | ||
6866 | @item | |
6867 | Substring operators applied to character constants and named | |
6868 | constants, as in: | |
6869 | ||
6870 | @example | |
6871 | PRINT *, 'hello'(3:5) | |
6872 | @end example | |
6873 | ||
6874 | @item | |
6875 | Null arguments passed to statement function, as in: | |
6876 | ||
6877 | @example | |
6878 | PRINT *, FOO(,3) | |
6879 | @end example | |
6880 | ||
6881 | @item | |
6882 | Disagreement among program units regarding whether a given @code{COMMON} | |
6883 | area is @code{SAVE}d (for targets where program units in a single source | |
6884 | file are ``glued'' together as they typically are for UNIX development | |
6885 | environments). | |
6886 | ||
6887 | @item | |
6888 | Disagreement among program units regarding the size of a | |
6889 | named @code{COMMON} block. | |
6890 | ||
6891 | @item | |
6892 | Specification statements following first @code{DATA} statement. | |
6893 | ||
6894 | (In the GNU Fortran language, @samp{DATA I/1/} may be followed by @samp{INTEGER J}, | |
6895 | but not @samp{INTEGER I}. | |
6896 | The @samp{-fpedantic} option disallows both of these.) | |
6897 | ||
6898 | @item | |
6899 | Semicolon as statement separator, as in: | |
6900 | ||
6901 | @example | |
6902 | CALL FOO; CALL BAR | |
6903 | @end example | |
6904 | @c | |
6905 | @c @item | |
6906 | @c Comma before list of I/O items in @code{WRITE} | |
6907 | @c @c, @code{ENCODE}, @code{DECODE}, and @code{REWRITE} | |
6908 | @c statements, as with @code{READ} (as explained above). | |
6909 | ||
6910 | @item | |
6911 | Use of @samp{&} in column 1 of fixed-form source (to indicate continuation). | |
6912 | ||
6913 | @item | |
6914 | Use of @code{CHARACTER} constants to initialize numeric entities, and vice | |
6915 | versa. | |
6916 | ||
6917 | @item | |
6918 | Expressions having two arithmetic operators in a row, such | |
6919 | as @samp{X*-Y}. | |
6920 | @end itemize | |
6921 | ||
6922 | If @samp{-fpedantic} is specified along with @samp{-ff90}, the | |
6923 | following constructs result in diagnostics: | |
6924 | ||
6925 | @itemize @bullet | |
6926 | @item | |
6927 | Use of semicolon as a statement separator on a line | |
6928 | that has an @code{INCLUDE} directive. | |
6929 | @end itemize | |
6930 | ||
6931 | @node Distensions | |
6932 | @section Distensions | |
6933 | @cindex distensions | |
6934 | @cindex ugly features | |
6935 | @cindex features, ugly | |
6936 | ||
6937 | The @samp{-fugly-*} command-line options determine whether certain | |
6938 | features supported by VAX FORTRAN and other such compilers, but considered | |
6939 | too ugly to be in code that can be changed to use safer and/or more | |
6940 | portable constructs, are accepted. | |
6941 | These are humorously referred to as ``distensions'', | |
6942 | extensions that just plain look ugly in the harsh light of day. | |
6943 | ||
5ff904cd JL |
6944 | @menu |
6945 | * Ugly Implicit Argument Conversion:: Disabled via @samp{-fno-ugly-args}. | |
6946 | * Ugly Assumed-Size Arrays:: Enabled via @samp{-fugly-assumed}. | |
6947 | * Ugly Null Arguments:: Enabled via @samp{-fugly-comma}. | |
6948 | * Ugly Complex Part Extraction:: Enabled via @samp{-fugly-complex}. | |
6949 | * Ugly Conversion of Initializers:: Disabled via @samp{-fno-ugly-init}. | |
6950 | * Ugly Integer Conversions:: Enabled via @samp{-fugly-logint}. | |
6951 | * Ugly Assigned Labels:: Enabled via @samp{-fugly-assign}. | |
6952 | @end menu | |
6953 | ||
6954 | @node Ugly Implicit Argument Conversion | |
6955 | @subsection Implicit Argument Conversion | |
6956 | @cindex Hollerith constants | |
6957 | @cindex constants, Hollerith | |
6958 | ||
6959 | The @samp{-fno-ugly-args} option disables | |
6960 | passing typeless and Hollerith constants as actual arguments | |
6961 | in procedure invocations. | |
6962 | For example: | |
6963 | ||
6964 | @example | |
6965 | CALL FOO(4HABCD) | |
6966 | CALL BAR('123'O) | |
6967 | @end example | |
6968 | ||
6969 | @noindent | |
6970 | These constructs can be too easily used to create non-portable | |
6971 | code, but are not considered as ``ugly'' as others. | |
6972 | Further, they are widely used in existing Fortran source code | |
6973 | in ways that often are quite portable. | |
6974 | Therefore, they are enabled by default. | |
6975 | ||
6976 | @node Ugly Assumed-Size Arrays | |
6977 | @subsection Ugly Assumed-Size Arrays | |
6978 | @cindex arrays, assumed-size | |
6979 | @cindex assumed-size arrays | |
6980 | @cindex DIMENSION X(1) | |
6981 | ||
6982 | The @samp{-fugly-assumed} option enables | |
6983 | the treatment of any array with a final dimension specified as @samp{1} | |
6984 | as an assumed-size array, as if @samp{*} had been specified | |
6985 | instead. | |
6986 | ||
6987 | For example, @samp{DIMENSION X(1)} is treated as if it | |
6988 | had read @samp{DIMENSION X(*)} if @samp{X} is listed as | |
6989 | a dummy argument in a preceding @code{SUBROUTINE}, @code{FUNCTION}, | |
6990 | or @code{ENTRY} statement in the same program unit. | |
6991 | ||
6992 | Use an explicit lower bound to avoid this interpretation. | |
6993 | For example, @samp{DIMENSION X(1:1)} is never treated as if | |
6994 | it had read @samp{DIMENSION X(*)} or @samp{DIMENSION X(1:*)}. | |
6995 | Nor is @samp{DIMENSION X(2-1)} affected by this option, | |
6996 | since that kind of expression is unlikely to have been | |
6997 | intended to designate an assumed-size array. | |
6998 | ||
6999 | This option is used to prevent warnings being issued about apparent | |
7000 | out-of-bounds reference such as @samp{X(2) = 99}. | |
7001 | ||
7002 | It also prevents the array from being used in contexts that | |
7003 | disallow assumed-size arrays, such as @samp{PRINT *,X}. | |
7004 | In such cases, a diagnostic is generated and the source file is | |
7005 | not compiled. | |
7006 | ||
7007 | The construct affected by this option is used only in old code | |
7008 | that pre-exists the widespread acceptance of adjustable and assumed-size | |
7009 | arrays in the Fortran community. | |
7010 | ||
7011 | @emph{Note:} This option does not affect how @samp{DIMENSION X(1)} is | |
7012 | treated if @samp{X} is listed as a dummy argument only | |
7013 | @emph{after} the @code{DIMENSION} statement (presumably in | |
7014 | an @code{ENTRY} statement). | |
7015 | For example, @samp{-fugly-assumed} has no effect on the | |
7016 | following program unit: | |
7017 | ||
7018 | @example | |
7019 | SUBROUTINE X | |
7020 | REAL A(1) | |
7021 | RETURN | |
7022 | ENTRY Y(A) | |
7023 | PRINT *, A | |
7024 | END | |
7025 | @end example | |
7026 | ||
7027 | @node Ugly Complex Part Extraction | |
7028 | @subsection Ugly Complex Part Extraction | |
7029 | @cindex complex values | |
7030 | @cindex real part | |
7031 | @cindex imaginary part | |
7032 | ||
7033 | The @samp{-fugly-complex} option enables | |
7034 | use of the @code{REAL()} and @code{AIMAG()} | |
7035 | intrinsics with arguments that are | |
7036 | @code{COMPLEX} types other than @code{COMPLEX(KIND=1)}. | |
7037 | ||
7038 | With @samp{-ff90} in effect, these intrinsics return | |
7039 | the unconverted real and imaginary parts (respectively) | |
7040 | of their argument. | |
7041 | ||
7042 | With @samp{-fno-f90} in effect, these intrinsics convert | |
7043 | the real and imaginary parts to @code{REAL(KIND=1)}, and return | |
7044 | the result of that conversion. | |
7045 | ||
7046 | Due to this ambiguity, the GNU Fortran language defines | |
7047 | these constructs as invalid, except in the specific | |
7048 | case where they are entirely and solely passed as an | |
7049 | argument to an invocation of the @code{REAL()} intrinsic. | |
7050 | For example, | |
7051 | ||
7052 | @example | |
7053 | REAL(REAL(Z)) | |
7054 | @end example | |
7055 | ||
7056 | @noindent | |
7057 | is permitted even when @samp{Z} is @code{COMPLEX(KIND=2)} | |
7058 | and @samp{-fno-ugly-complex} is in effect, because the | |
7059 | meaning is clear. | |
7060 | ||
7061 | @code{g77} enforces this restriction, unless @samp{-fugly-complex} | |
7062 | is specified, in which case the appropriate interpretation is | |
7063 | chosen and no diagnostic is issued. | |
7064 | ||
7065 | @xref{CMPAMBIG}, for information on how to cope with existing | |
7066 | code with unclear expectations of @code{REAL()} and @code{AIMAG()} | |
7067 | with @code{COMPLEX(KIND=2)} arguments. | |
7068 | ||
7069 | @xref{RealPart Intrinsic}, for information on the @code{REALPART()} | |
7070 | intrinsic, used to extract the real part of a complex expression | |
7071 | without conversion. | |
7072 | @xref{ImagPart Intrinsic}, for information on the @code{IMAGPART()} | |
7073 | intrinsic, used to extract the imaginary part of a complex expression | |
7074 | without conversion. | |
7075 | ||
7076 | @node Ugly Null Arguments | |
7077 | @subsection Ugly Null Arguments | |
26b9526e CB |
7078 | @cindex trailing comma |
7079 | @cindex comma, trailing | |
7080 | @cindex characters, comma | |
5ff904cd JL |
7081 | @cindex null arguments |
7082 | @cindex arguments, null | |
7083 | ||
56a0044b JL |
7084 | The @samp{-fugly-comma} option enables use of a single trailing comma |
7085 | to mean ``pass an extra trailing null argument'' | |
7086 | in a list of actual arguments to an external procedure, | |
7087 | and use of an empty list of arguments to such a procedure | |
7088 | to mean ``pass a single null argument''. | |
5ff904cd JL |
7089 | |
7090 | @cindex omitting arguments | |
7091 | @cindex arguments, omitting | |
7092 | (Null arguments often are used in some procedure-calling | |
7093 | schemes to indicate omitted arguments.) | |
7094 | ||
7095 | For example, @samp{CALL FOO(,)} means ``pass | |
7096 | two null arguments'', rather than ``pass one null argument''. | |
7097 | Also, @samp{CALL BAR()} means ``pass one null argument''. | |
7098 | ||
7099 | This construct is considered ``ugly'' because it does not | |
7100 | provide an elegant way to pass a single null argument | |
7101 | that is syntactically distinct from passing no arguments. | |
7102 | That is, this construct changes the meaning of code that | |
7103 | makes no use of the construct. | |
7104 | ||
7105 | So, with @samp{-fugly-comma} in force, @samp{CALL FOO()} | |
7106 | and @samp{I = JFUNC()} pass a single null argument, instead | |
7107 | of passing no arguments as required by the Fortran 77 and | |
7108 | 90 standards. | |
7109 | ||
7110 | @emph{Note:} Many systems gracefully allow the case | |
7111 | where a procedure call passes one extra argument that the | |
7112 | called procedure does not expect. | |
7113 | ||
7114 | So, in practice, there might be no difference in | |
7115 | the behavior of a program that does @samp{CALL FOO()} | |
7116 | or @samp{I = JFUNC()} and is compiled with @samp{-fugly-comma} | |
7117 | in force as compared to its behavior when compiled | |
7118 | with the default, @samp{-fno-ugly-comma}, in force, | |
7119 | assuming @samp{FOO} and @samp{JFUNC} do not expect any | |
7120 | arguments to be passed. | |
7121 | ||
7122 | @node Ugly Conversion of Initializers | |
7123 | @subsection Ugly Conversion of Initializers | |
7124 | ||
7125 | The constructs disabled by @samp{-fno-ugly-init} are: | |
7126 | ||
7127 | @itemize @bullet | |
7128 | @cindex Hollerith constants | |
7129 | @cindex constants, Hollerith | |
7130 | @item | |
7131 | Use of Hollerith and typeless constants in contexts where they set | |
7132 | initial (compile-time) values for variables, arrays, and named | |
7133 | constants---that is, @code{DATA} and @code{PARAMETER} statements, plus | |
7134 | type-declaration statements specifying initial values. | |
7135 | ||
7136 | Here are some sample initializations that are disabled by the | |
7137 | @samp{-fno-ugly-init} option: | |
7138 | ||
7139 | @example | |
7140 | PARAMETER (VAL='9A304FFE'X) | |
7141 | REAL*8 STRING/8HOUTPUT00/ | |
7142 | DATA VAR/4HABCD/ | |
7143 | @end example | |
7144 | ||
7145 | @cindex character constants | |
7146 | @cindex constants, character | |
7147 | @item | |
7148 | In the same contexts as above, use of character constants to initialize | |
7149 | numeric items and vice versa (one constant per item). | |
7150 | ||
7151 | Here are more sample initializations that are disabled by the | |
7152 | @samp{-fno-ugly-init} option: | |
7153 | ||
7154 | @example | |
7155 | INTEGER IA | |
7156 | CHARACTER BELL | |
7157 | PARAMETER (IA = 'A') | |
7158 | PARAMETER (BELL = 7) | |
7159 | @end example | |
7160 | ||
7161 | @item | |
7162 | Use of Hollerith and typeless constants on the right-hand side | |
7163 | of assignment statements to numeric types, and in other | |
7164 | contexts (such as passing arguments in invocations of | |
7165 | intrinsic procedures and statement functions) that | |
7166 | are treated as assignments to known types (the dummy | |
7167 | arguments, in these cases). | |
7168 | ||
7169 | Here are sample statements that are disabled by the | |
7170 | @samp{-fno-ugly-init} option: | |
7171 | ||
7172 | @example | |
7173 | IVAR = 4HABCD | |
7174 | PRINT *, IMAX0(2HAB, 2HBA) | |
7175 | @end example | |
7176 | @end itemize | |
7177 | ||
7178 | The above constructs, when used, | |
7179 | can tend to result in non-portable code. | |
7180 | But, they are widely used in existing Fortran code in ways | |
7181 | that often are quite portable. | |
7182 | Therefore, they are enabled by default. | |
7183 | ||
7184 | @node Ugly Integer Conversions | |
7185 | @subsection Ugly Integer Conversions | |
7186 | ||
7187 | The constructs enabled via @samp{-fugly-logint} are: | |
7188 | ||
7189 | @itemize @bullet | |
7190 | @item | |
7191 | Automatic conversion between @code{INTEGER} and @code{LOGICAL} as | |
7192 | dictated by | |
7193 | context (typically implies nonportable dependencies on how a | |
7194 | particular implementation encodes @code{.TRUE.} and @code{.FALSE.}). | |
7195 | ||
7196 | @item | |
7197 | Use of a @code{LOGICAL} variable in @code{ASSIGN} and assigned-@code{GOTO} | |
7198 | statements. | |
7199 | @end itemize | |
7200 | ||
7201 | The above constructs are disabled by default because use | |
7202 | of them tends to lead to non-portable code. | |
7203 | Even existing Fortran code that uses that often turns out | |
7204 | to be non-portable, if not outright buggy. | |
7205 | ||
7206 | Some of this is due to differences among implementations as | |
7207 | far as how @code{.TRUE.} and @code{.FALSE.} are encoded as | |
7208 | @code{INTEGER} values---Fortran code that assumes a particular | |
7209 | coding is likely to use one of the above constructs, and is | |
7210 | also likely to not work correctly on implementations using | |
7211 | different encodings. | |
7212 | ||
7213 | @xref{Equivalence Versus Equality}, for more information. | |
7214 | ||
7215 | @node Ugly Assigned Labels | |
7216 | @subsection Ugly Assigned Labels | |
7217 | @cindex ASSIGN statement | |
7218 | @cindex statements, ASSIGN | |
7219 | @cindex assigned labels | |
7220 | @cindex pointers | |
7221 | ||
7222 | The @samp{-fugly-assign} option forces @code{g77} to use the | |
7223 | same storage for assigned labels as it would for a normal | |
7224 | assignment to the same variable. | |
7225 | ||
7226 | For example, consider the following code fragment: | |
7227 | ||
7228 | @example | |
7229 | I = 3 | |
7230 | ASSIGN 10 TO I | |
7231 | @end example | |
7232 | ||
7233 | @noindent | |
7234 | Normally, for portability and improved diagnostics, @code{g77} | |
7235 | reserves distinct storage for a ``sibling'' of @samp{I}, used | |
7236 | only for @code{ASSIGN} statements to that variable (along with | |
4e6a1440 | 7237 | the corresponding assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O |
5ff904cd JL |
7238 | statements that reference the variable). |
7239 | ||
7240 | However, some code (that violates the ANSI FORTRAN 77 standard) | |
7241 | attempts to copy assigned labels among variables involved with | |
7242 | @code{ASSIGN} statements, as in: | |
7243 | ||
7244 | @example | |
7245 | ASSIGN 10 TO I | |
7246 | ISTATE(5) = I | |
7247 | @dots{} | |
7248 | J = ISTATE(ICUR) | |
7249 | GOTO J | |
7250 | @end example | |
7251 | ||
7252 | @noindent | |
7253 | Such code doesn't work under @code{g77} unless @samp{-fugly-assign} | |
7254 | is specified on the command-line, ensuring that the value of @code{I} | |
7255 | referenced in the second line is whatever value @code{g77} uses | |
7256 | to designate statement label @samp{10}, so the value may be | |
7257 | copied into the @samp{ISTATE} array, later retrieved into a | |
7258 | variable of the appropriate type (@samp{J}), and used as the target of | |
7259 | an assigned-@code{GOTO} statement. | |
7260 | ||
7261 | @emph{Note:} To avoid subtle program bugs, | |
7262 | when @samp{-fugly-assign} is specified, | |
7263 | @code{g77} requires the type of variables | |
7264 | specified in assigned-label contexts | |
7265 | @emph{must} be the same type returned by @code{%LOC()}. | |
7266 | On many systems, this type is effectively the same | |
7267 | as @code{INTEGER(KIND=1)}, while, on others, it is | |
7268 | effectively the same as @code{INTEGER(KIND=2)}. | |
7269 | ||
7270 | Do @emph{not} depend on @code{g77} actually writing valid pointers | |
7271 | to these variables, however. | |
7272 | While @code{g77} currently chooses that implementation, it might | |
7273 | be changed in the future. | |
7274 | ||
7275 | @xref{Assigned Statement Labels,,Assigned Statement Labels (ASSIGN and GOTO)}, | |
7276 | for implementation details on assigned-statement labels. | |
7277 | ||
7278 | @node Compiler | |
7279 | @chapter The GNU Fortran Compiler | |
7280 | ||
7281 | The GNU Fortran compiler, @code{g77}, supports programs written | |
7282 | in the GNU Fortran language and in some other dialects of Fortran. | |
7283 | ||
7284 | Some aspects of how @code{g77} works are universal regardless | |
7285 | of dialect, and yet are not properly part of the GNU Fortran | |
7286 | language itself. | |
7287 | These are described below. | |
7288 | ||
7289 | @emph{Note: This portion of the documentation definitely needs a lot | |
7290 | of work!} | |
7291 | ||
7292 | @menu | |
7293 | * Compiler Limits:: | |
d79904b8 | 7294 | * Run-time Environment Limits:: |
5ff904cd JL |
7295 | * Compiler Types:: |
7296 | * Compiler Constants:: | |
7297 | * Compiler Intrinsics:: | |
7298 | @end menu | |
7299 | ||
7300 | @node Compiler Limits | |
7301 | @section Compiler Limits | |
7302 | @cindex limits, compiler | |
7303 | @cindex compiler limits | |
7304 | ||
7305 | @code{g77}, as with GNU tools in general, imposes few arbitrary restrictions | |
7306 | on lengths of identifiers, number of continuation lines, number of external | |
7307 | symbols in a program, and so on. | |
7308 | ||
7309 | @cindex options, -Nl | |
7310 | @cindex -Nl option | |
7311 | @cindex options, -Nx | |
7312 | @cindex -Nx option | |
d79904b8 CB |
7313 | @cindex limits, continuation lines |
7314 | @cindex limits, lengths of names | |
5ff904cd JL |
7315 | For example, some other Fortran compiler have an option |
7316 | (such as @samp{-Nl@var{x}}) to increase the limit on the | |
7317 | number of continuation lines. | |
7318 | Also, some Fortran compilation systems have an option | |
7319 | (such as @samp{-Nx@var{x}}) to increase the limit on the | |
7320 | number of external symbols. | |
7321 | ||
7322 | @code{g77}, @code{gcc}, and GNU @code{ld} (the GNU linker) have | |
7323 | no equivalent options, since they do not impose arbitrary | |
7324 | limits in these areas. | |
7325 | ||
7326 | @cindex rank, maximum | |
7327 | @cindex maximum rank | |
7328 | @cindex number of dimensions, maximum | |
7329 | @cindex maximum number of dimensions | |
d79904b8 CB |
7330 | @cindex limits, rank |
7331 | @cindex limits, array dimensions | |
5ff904cd JL |
7332 | @code{g77} does currently limit the number of dimensions in an array |
7333 | to the same degree as do the Fortran standards---seven (7). | |
d79904b8 CB |
7334 | This restriction might be lifted in a future version. |
7335 | ||
7336 | @node Run-time Environment Limits | |
7337 | @section Run-time Environment Limits | |
7338 | @cindex limits, run-time library | |
7339 | @cindex wraparound | |
7340 | ||
7341 | As a portable Fortran implementation, | |
7342 | @code{g77} offers its users direct access to, | |
7343 | and otherwise depends upon, | |
7344 | the underlying facilities of the system | |
7345 | used to build @code{g77}, | |
7346 | the system on which @code{g77} itself is used to compile programs, | |
7347 | and the system on which the @code{g77}-compiled program is actually run. | |
7348 | (For most users, the three systems are of the same | |
7349 | type---combination of operating environment and hardware---often | |
7350 | the same physical system.) | |
7351 | ||
7352 | The run-time environment for a particular system | |
7353 | inevitably imposes some limits on a program's use | |
7354 | of various system facilities. | |
7355 | These limits vary from system to system. | |
7356 | ||
7357 | Even when such limits might be well beyond the | |
7358 | possibility of being encountered on a particular system, | |
7359 | the @code{g77} run-time environment | |
7360 | has certain built-in limits, | |
7361 | usually, but not always, stemming from intrinsics | |
7362 | with inherently limited interfaces. | |
7363 | ||
7364 | Currently, the @code{g77} run-time environment | |
7365 | does not generally offer a less-limiting environment | |
7366 | by augmenting the underlying system's own environment. | |
7367 | ||
7368 | Therefore, code written in the GNU Fortran language, | |
7369 | while syntactically and semantically portable, | |
7370 | might nevertheless make non-portable assumptions | |
7371 | about the run-time environment---assumptions that | |
7372 | prove to be false for some particular environments. | |
7373 | ||
7374 | The GNU Fortran language, | |
7375 | the @code{g77} compiler and run-time environment, | |
7376 | and the @code{g77} documentation | |
7377 | do not yet offer comprehensive portable work-arounds for such limits, | |
7378 | though programmers should be able to | |
7379 | find their own in specific instances. | |
7380 | ||
7381 | Not all of the limitations are described in this document. | |
7382 | Some of the known limitations include: | |
7383 | ||
7384 | @menu | |
7385 | * Timer Wraparounds:: | |
7386 | * Year 2000 (Y2K) Problems:: | |
7387 | * Array Size:: | |
7388 | * Character-variable Length:: | |
7389 | * Year 10000 (Y10K) Problems:: | |
7390 | @end menu | |
7391 | ||
7392 | @node Timer Wraparounds | |
7393 | @subsection Timer Wraparounds | |
7394 | ||
7395 | Intrinsics that return values computed from system timers, | |
7396 | whether elapsed (wall-clock) timers, | |
7397 | process CPU timers, | |
7398 | or other kinds of timers, | |
7399 | are prone to experiencing wrap-around errors | |
7400 | (or returning wrapped-around values from successive calls) | |
7401 | due to insufficient ranges | |
7402 | offered by the underlying system's timers. | |
7403 | ||
7404 | @cindex negative time | |
7405 | @cindex short time | |
7406 | @cindex long time | |
7407 | Some of the symptoms of such behaviors include | |
7408 | apparently negative time being computed for a duration, | |
7409 | an extremely short amount of time being computed for a long duration, | |
7410 | and an extremely long amount of time being computed for a short duration. | |
7411 | ||
7412 | See the following for intrinsics | |
7413 | known to have potential problems in these areas | |
7414 | on at least some systems: | |
7415 | @ref{CPU_Time Intrinsic}, | |
7416 | @ref{DTime Intrinsic (function)}, @ref{DTime Intrinsic (subroutine)}, | |
7417 | @ref{ETime Intrinsic (function)}, @ref{ETime Intrinsic (subroutine)}, | |
7418 | @ref{MClock Intrinsic}, @ref{MClock8 Intrinsic}, | |
7419 | @ref{Secnds Intrinsic}, | |
7420 | @ref{Second Intrinsic (function)}, @ref{Second Intrinsic (subroutine)}, | |
7421 | @ref{System_Clock Intrinsic}, | |
7422 | @ref{Time Intrinsic (UNIX)}, @ref{Time Intrinsic (VXT)}, | |
7423 | @ref{Time8 Intrinsic}. | |
7424 | ||
7425 | @node Year 2000 (Y2K) Problems | |
7426 | @subsection Year 2000 (Y2K) Problems | |
7427 | @cindex Y2K compliance | |
7428 | @cindex Year 2000 compliance | |
7429 | ||
7430 | While the @code{g77} compiler itself is believed to | |
7431 | be Year-2000 (Y2K) compliant, | |
7432 | some intrinsics are not, | |
7433 | and, potentially, some underlying systems are not, | |
7434 | perhaps rendering some Y2K-compliant intrinsics | |
7435 | non-compliant when used on those particular systems. | |
7436 | ||
7437 | Fortran code that uses non-Y2K-compliant intrinsics | |
7438 | (listed below) | |
7439 | is, itself, almost certainly not compliant, | |
7440 | and should be modified to use Y2K-compliant intrinsics instead. | |
7441 | ||
7442 | Fortran code that uses no non-Y2K-compliant intrinsics, | |
7443 | but which currently is running on a non-Y2K-compliant system, | |
7444 | can be made more Y2K compliant by compiling and | |
7445 | linking it for use on a new Y2K-compliant system, | |
7446 | such as a new version of an old, non-Y2K-compliant, system. | |
7447 | ||
7448 | Currently, information on Y2K and related issues | |
7449 | is being maintained at | |
7450 | @uref{http://www.gnu.org/software/year2000-list.html}. | |
7451 | ||
7452 | See the following for intrinsics | |
7453 | known to have potential problems in these areas | |
7454 | on at least some systems: | |
7455 | @ref{Date Intrinsic}, | |
7456 | @ref{IDate Intrinsic (VXT)}. | |
7457 | ||
411d4e28 CB |
7458 | @cindex y2kbuggy |
7459 | @cindex date_y2kbuggy_0 | |
7460 | @cindex vxtidate_y2kbuggy_0 | |
7461 | @cindex G77_date_y2kbuggy_0 | |
7462 | @cindex G77_vxtidate_y2kbuggy_0 | |
7463 | The @code{libg2c} library | |
7464 | shipped with any @code{g77} that warns | |
7465 | about invocation of a non-Y2K-compliant intrinsic | |
4e6a1440 | 7466 | has renamed the @code{EXTERNAL} procedure names |
411d4e28 CB |
7467 | of those intrinsics. |
7468 | This is done so that | |
7469 | the @code{libg2c} implementations of these intrinsics | |
7470 | cannot be directly linked to | |
4e6a1440 | 7471 | as @code{EXTERNAL} names |
411d4e28 CB |
7472 | (which normally would avoid the non-Y2K-intrinsic warning). |
7473 | ||
4e6a1440 | 7474 | The renamed forms of the @code{EXTERNAL} names |
411d4e28 CB |
7475 | of these renamed procedures |
7476 | may be linked to | |
7477 | by appending the string @samp{_y2kbug} | |
7478 | to the name of the procedure | |
7479 | in the source code. | |
7480 | For example: | |
7481 | ||
7482 | @smallexample | |
7483 | CHARACTER*20 STR | |
7484 | INTEGER YY, MM, DD | |
7485 | EXTERNAL DATE_Y2KBUG, VXTIDATE_Y2KBUG | |
7486 | CALL DATE_Y2KBUG (STR) | |
7487 | CALL VXTIDATE_Y2KBUG (MM, DD, YY) | |
7488 | @end smallexample | |
7489 | ||
4e6a1440 | 7490 | (Note that the @code{EXTERNAL} statement |
411d4e28 CB |
7491 | is not actually required, |
7492 | since the modified names are not recognized as intrinsics | |
7493 | by the current version of @code{g77}. | |
7494 | But it is shown in this specific case, | |
7495 | for purposes of illustration.) | |
7496 | ||
4e6a1440 | 7497 | The renaming of @code{EXTERNAL} procedure names of these intrinsics |
411d4e28 CB |
7498 | causes unresolved references at link time. |
7499 | For example, @samp{EXTERNAL DATE; CALL DATE(STR)} | |
7500 | is normally compiled by @code{g77} | |
7501 | as, in C, @samp{date_(&str, 20);}. | |
4e6a1440 CB |
7502 | This, in turn, links to the @code{date_} procedure |
7503 | in the @code{libE77} portion of @code{libg2c}, | |
411d4e28 | 7504 | which purposely calls a nonexistent procedure |
4e6a1440 | 7505 | named @code{G77_date_y2kbuggy_0}. |
411d4e28 CB |
7506 | The resulting link-time error is designed, via this name, |
7507 | to encourage the programmer to look up the | |
7508 | index entries to this portion of the @code{g77} documentation. | |
7509 | ||
4e6a1440 | 7510 | Generally, we recommend that the @code{EXTERNAL} method |
411d4e28 CB |
7511 | of invoking procedures in @code{libg2c} |
7512 | @emph{not} be used. | |
7513 | When used, some of the correctness checking | |
7514 | normally performed by @code{g77} | |
7515 | is skipped. | |
7516 | ||
7517 | In particular, it is probably better to use the | |
4e6a1440 | 7518 | @code{INTRINSIC} method of invoking |
411d4e28 CB |
7519 | non-Y2K-compliant procedures, |
7520 | so anyone compiling the code | |
7521 | can quickly notice the potential Y2K problems | |
7522 | (via the warnings printing by @code{g77}) | |
7523 | without having to even look at the code itself. | |
7524 | ||
7525 | If there are problems linking @code{libg2c} | |
7526 | to code compiled by @code{g77} | |
7527 | that involve the string @samp{y2kbug}, | |
7528 | and these are not explained above, | |
7529 | that probably indicates | |
7530 | that a version of @code{libg2c} | |
7531 | older than @code{g77} | |
7532 | is being linked to, | |
7533 | or that the new library is being linked | |
7534 | to code compiled by an older version of @code{g77}. | |
7535 | ||
7536 | That's because, as of the version that warns about | |
7537 | non-Y2K-compliant intrinsic invocation, | |
7538 | @code{g77} references the @code{libg2c} implementations | |
7539 | of those intrinsics | |
7540 | using new names, containing the string @samp{y2kbug}. | |
7541 | ||
7542 | So, linking newly-compiled code | |
7543 | (invoking one of the intrinsics in question) | |
7544 | to an old library | |
7545 | might yield an unresolved reference | |
4e6a1440 CB |
7546 | to @code{G77_date_y2kbug_0}. |
7547 | (The old library calls it @code{G77_date_0}.) | |
411d4e28 CB |
7548 | |
7549 | Similarly, linking previously-compiled code | |
7550 | to a new library | |
7551 | might yield an unresolved reference | |
4e6a1440 CB |
7552 | to @code{G77_vxtidate_0}. |
7553 | (The new library calls it @code{G77_vxtidate_y2kbug_0}.) | |
411d4e28 CB |
7554 | |
7555 | The proper fix for the above problems | |
7556 | is to obtain the latest release of @code{g77} | |
7557 | and related products | |
7558 | (including @code{libg2c}) | |
7559 | and install them on all systems, | |
7560 | then recompile, relink, and install | |
7561 | (as appropriate) | |
7562 | all existing Fortran programs. | |
7563 | ||
7564 | (Normally, this sort of renaming is steadfastly avoided. | |
7565 | In this case, however, it seems more important to highlight | |
7566 | potential Y2K problems | |
7567 | than to ease the transition | |
7568 | of potentially non-Y2K-compliant code | |
7569 | to new versions of @code{g77} and @code{libg2c}.) | |
7570 | ||
d79904b8 CB |
7571 | @node Array Size |
7572 | @subsection Array Size | |
7573 | @cindex limits, array size | |
7574 | @cindex array size | |
7575 | ||
7576 | Currently, @code{g77} uses the default @code{INTEGER} type | |
7577 | for array indexes, | |
7578 | which limits the sizes of single-dimension arrays | |
7579 | on systems offering a larger address space | |
7580 | than can be addressed by that type. | |
7581 | (That @code{g77} puts all arrays in memory | |
7582 | could be considered another limitation---it | |
7583 | could use large temporary files---but that decision | |
7584 | is left to the programmer as an implementation choice | |
7585 | by most Fortran implementations.) | |
7586 | ||
7587 | @c ??? Investigate this, to offer a more clear statement | |
7588 | @c than the following paragraphs do. -- burley 1999-02-17 | |
7589 | It is not yet clear whether this limitation | |
7590 | never, sometimes, or always applies to the | |
7591 | sizes of multiple-dimension arrays as a whole. | |
7592 | ||
7593 | For example, on a system with 64-bit addresses | |
7594 | and 32-bit default @code{INTEGER}, | |
7595 | an array with a size greater than can be addressed | |
7596 | by a 32-bit offset | |
7597 | can be declared using multiple dimensions. | |
7598 | Such an array is therefore larger | |
7599 | than a single-dimension array can be, | |
7600 | on the same system. | |
7601 | ||
7602 | @cindex limits, multi-dimension arrays | |
7603 | @cindex multi-dimension arrays | |
7604 | @cindex arrays, dimensioning | |
7605 | Whether large multiple-dimension arrays are reliably supported | |
7606 | depends mostly on the @code{gcc} back end (code generator) | |
7607 | used by @code{g77}, and has not yet been fully investigated. | |
7608 | ||
7609 | @node Character-variable Length | |
7610 | @subsection Character-variable Length | |
7611 | @cindex limits, on character-variable length | |
7612 | @cindex character-variable length | |
7613 | ||
7614 | Currently, @code{g77} uses the default @code{INTEGER} type | |
7615 | for the lengths of @code{CHARACTER} variables | |
7616 | and array elements. | |
7617 | ||
7618 | This means that, for example, | |
7619 | a system with a 64-bit address space | |
7620 | and a 32-bit default @code{INTEGER} type | |
7621 | does not, under @code{g77}, | |
7622 | support a @code{CHARACTER*@var{n}} declaration | |
7623 | where @var{n} is greater than 2147483647. | |
7624 | ||
7625 | @node Year 10000 (Y10K) Problems | |
7626 | @subsection Year 10000 (Y10K) Problems | |
7627 | @cindex Y10K compliance | |
7628 | @cindex Year 10000 compliance | |
7629 | ||
7630 | Most intrinsics returning, or computing values based on, | |
7631 | date information are prone to Year-10000 (Y10K) problems, | |
7632 | due to supporting only 4 digits for the year. | |
7633 | ||
7634 | See the following for examples: | |
7635 | @ref{FDate Intrinsic (function)}, @ref{FDate Intrinsic (subroutine)}, | |
7636 | @ref{IDate Intrinsic (UNIX)}, | |
7637 | @ref{Time Intrinsic (VXT)}, | |
7638 | @ref{Date_and_Time Intrinsic}. | |
5ff904cd JL |
7639 | |
7640 | @node Compiler Types | |
7641 | @section Compiler Types | |
7642 | @cindex types, of data | |
7643 | @cindex data types | |
7644 | ||
7645 | Fortran implementations have a fair amount of freedom given them by the | |
7646 | standard as far as how much storage space is used and how much precision | |
7647 | and range is offered by the various types such as @code{LOGICAL(KIND=1)}, | |
7648 | @code{INTEGER(KIND=1)}, @code{REAL(KIND=1)}, @code{REAL(KIND=2)}, | |
7649 | @code{COMPLEX(KIND=1)}, and @code{CHARACTER}. | |
7650 | Further, many compilers offer so-called @samp{*@var{n}} notation, but | |
7651 | the interpretation of @var{n} varies across compilers and target architectures. | |
7652 | ||
7653 | The standard requires that @code{LOGICAL(KIND=1)}, @code{INTEGER(KIND=1)}, | |
7654 | and @code{REAL(KIND=1)} | |
7655 | occupy the same amount of storage space, and that @code{COMPLEX(KIND=1)} | |
7656 | and @code{REAL(KIND=2)} take twice as much storage space as @code{REAL(KIND=1)}. | |
7657 | Further, it requires that @code{COMPLEX(KIND=1)} | |
7658 | entities be ordered such that when a @code{COMPLEX(KIND=1)} variable is | |
7659 | storage-associated (such as via @code{EQUIVALENCE}) | |
7660 | with a two-element @code{REAL(KIND=1)} array named @samp{R}, @samp{R(1)} | |
7661 | corresponds to the real element and @samp{R(2)} to the imaginary | |
7662 | element of the @code{COMPLEX(KIND=1)} variable. | |
7663 | ||
7664 | (Few requirements as to precision or ranges of any of these are | |
7665 | placed on the implementation, nor is the relationship of storage sizes of | |
7666 | these types to the @code{CHARACTER} type specified, by the standard.) | |
7667 | ||
7668 | @code{g77} follows the above requirements, warning when compiling | |
7669 | a program requires placement of items in memory that contradict the | |
7670 | requirements of the target architecture. | |
7671 | (For example, a program can require placement of a @code{REAL(KIND=2)} | |
7672 | on a boundary that is not an even multiple of its size, but still an | |
7673 | even multiple of the size of a @code{REAL(KIND=1)} variable. | |
7674 | On some target architectures, using the canonical | |
7675 | mapping of Fortran types to underlying architectural types, such | |
7676 | placement is prohibited by the machine definition or | |
7677 | the Application Binary Interface (ABI) in force for | |
7678 | the configuration defined for building @code{gcc} and @code{g77}. | |
7679 | @code{g77} warns about such | |
7680 | situations when it encounters them.) | |
7681 | ||
7682 | @code{g77} follows consistent rules for configuring the mapping between Fortran | |
7683 | types, including the @samp{*@var{n}} notation, and the underlying architectural | |
7684 | types as accessed by a similarly-configured applicable version of the | |
7685 | @code{gcc} compiler. | |
7686 | These rules offer a widely portable, consistent Fortran/C | |
7687 | environment, although they might well conflict with the expectations of | |
7688 | users of Fortran compilers designed and written for particular | |
7689 | architectures. | |
7690 | ||
7691 | These rules are based on the configuration that is in force for the | |
7692 | version of @code{gcc} built in the same release as @code{g77} (and | |
7693 | which was therefore used to build both the @code{g77} compiler | |
95a1b676 | 7694 | components and the @code{libg2c} run-time library): |
5ff904cd JL |
7695 | |
7696 | @table @code | |
7697 | @cindex REAL(KIND=1) type | |
7698 | @cindex types, REAL(KIND=1) | |
7699 | @item REAL(KIND=1) | |
7700 | Same as @code{float} type. | |
7701 | ||
7702 | @cindex REAL(KIND=2) type | |
7703 | @cindex types, REAL(KIND=2) | |
7704 | @item REAL(KIND=2) | |
7705 | Same as whatever floating-point type that is twice the size | |
7706 | of a @code{float}---usually, this is a @code{double}. | |
7707 | ||
7708 | @cindex INTEGER(KIND=1) type | |
7709 | @cindex types, INTEGER(KIND=1) | |
7710 | @item INTEGER(KIND=1) | |
7711 | Same as an integral type that is occupies the same amount | |
7712 | of memory storage as @code{float}---usually, this is either | |
7713 | an @code{int} or a @code{long int}. | |
7714 | ||
7715 | @cindex LOGICAL(KIND=1) type | |
7716 | @cindex types, LOGICAL(KIND=1) | |
7717 | @item LOGICAL(KIND=1) | |
7718 | Same @code{gcc} type as @code{INTEGER(KIND=1)}. | |
7719 | ||
7720 | @cindex INTEGER(KIND=2) type | |
7721 | @cindex types, INTEGER(KIND=2) | |
7722 | @item INTEGER(KIND=2) | |
7723 | Twice the size, and usually nearly twice the range, | |
7724 | as @code{INTEGER(KIND=1)}---usually, this is either | |
7725 | a @code{long int} or a @code{long long int}. | |
7726 | ||
7727 | @cindex LOGICAL(KIND=2) type | |
7728 | @cindex types, LOGICAL(KIND=2) | |
7729 | @item LOGICAL(KIND=2) | |
7730 | Same @code{gcc} type as @code{INTEGER(KIND=2)}. | |
7731 | ||
7732 | @cindex INTEGER(KIND=3) type | |
7733 | @cindex types, INTEGER(KIND=3) | |
7734 | @item INTEGER(KIND=3) | |
7735 | Same @code{gcc} type as signed @code{char}. | |
7736 | ||
7737 | @cindex LOGICAL(KIND=3) type | |
7738 | @cindex types, LOGICAL(KIND=3) | |
7739 | @item LOGICAL(KIND=3) | |
7740 | Same @code{gcc} type as @code{INTEGER(KIND=3)}. | |
7741 | ||
7742 | @cindex INTEGER(KIND=6) type | |
7743 | @cindex types, INTEGER(KIND=6) | |
7744 | @item INTEGER(KIND=6) | |
7745 | Twice the size, and usually nearly twice the range, | |
7746 | as @code{INTEGER(KIND=3)}---usually, this is | |
7747 | a @code{short}. | |
7748 | ||
7749 | @cindex LOGICAL(KIND=6) type | |
7750 | @cindex types, LOGICAL(KIND=6) | |
7751 | @item LOGICAL(KIND=6) | |
7752 | Same @code{gcc} type as @code{INTEGER(KIND=6)}. | |
7753 | ||
7754 | @cindex COMPLEX(KIND=1) type | |
7755 | @cindex types, COMPLEX(KIND=1) | |
7756 | @item COMPLEX(KIND=1) | |
7757 | Two @code{REAL(KIND=1)} scalars (one for the real part followed by | |
7758 | one for the imaginary part). | |
7759 | ||
7760 | @cindex COMPLEX(KIND=2) type | |
7761 | @cindex types, COMPLEX(KIND=2) | |
7762 | @item COMPLEX(KIND=2) | |
7763 | Two @code{REAL(KIND=2)} scalars. | |
7764 | ||
7765 | @cindex *@var{n} notation | |
7766 | @item @var{numeric-type}*@var{n} | |
95a1b676 | 7767 | (Where @var{numeric-type} is any type other than @code{CHARACTER}.) |
5ff904cd JL |
7768 | Same as whatever @code{gcc} type occupies @var{n} times the storage |
7769 | space of a @code{gcc} @code{char} item. | |
7770 | ||
7771 | @cindex DOUBLE PRECISION type | |
7772 | @cindex types, DOUBLE PRECISION | |
7773 | @item DOUBLE PRECISION | |
7774 | Same as @code{REAL(KIND=2)}. | |
7775 | ||
7776 | @cindex DOUBLE COMPLEX type | |
7777 | @cindex types, DOUBLE COMPLEX | |
7778 | @item DOUBLE COMPLEX | |
7779 | Same as @code{COMPLEX(KIND=2)}. | |
7780 | @end table | |
7781 | ||
7782 | Note that the above are proposed correspondences and might change | |
7783 | in future versions of @code{g77}---avoid writing code depending | |
7784 | on them. | |
7785 | ||
7786 | Other types supported by @code{g77} | |
7787 | are derived from gcc types such as @code{char}, @code{short}, | |
7788 | @code{int}, @code{long int}, @code{long long int}, @code{long double}, | |
7789 | and so on. | |
7790 | That is, whatever types @code{gcc} already supports, @code{g77} supports | |
7791 | now or probably will support in a future version. | |
7792 | The rules for the @samp{@var{numeric-type}*@var{n}} notation | |
7793 | apply to these types, | |
7794 | and new values for @samp{@var{numeric-type}(KIND=@var{n})} will be | |
7795 | assigned in a way that encourages clarity, consistency, and portability. | |
7796 | ||
7797 | @node Compiler Constants | |
7798 | @section Compiler Constants | |
7799 | @cindex constants | |
7800 | @cindex types, constants | |
7801 | ||
7802 | @code{g77} strictly assigns types to @emph{all} constants not | |
7803 | documented as ``typeless'' (typeless constants including @samp{'1'Z}, | |
7804 | for example). | |
7805 | Many other Fortran compilers attempt to assign types to typed constants | |
7806 | based on their context. | |
7807 | This results in hard-to-find bugs, nonportable | |
7808 | code, and is not in the spirit (though it strictly follows the letter) | |
7809 | of the 77 and 90 standards. | |
7810 | ||
7811 | @code{g77} might offer, in a future release, explicit constructs by | |
7812 | which a wider variety of typeless constants may be specified, and/or | |
7813 | user-requested warnings indicating places where @code{g77} might differ | |
7814 | from how other compilers assign types to constants. | |
7815 | ||
7816 | @xref{Context-Sensitive Constants}, for more information on this issue. | |
7817 | ||
7818 | @node Compiler Intrinsics | |
7819 | @section Compiler Intrinsics | |
7820 | ||
7821 | @code{g77} offers an ever-widening set of intrinsics. | |
7822 | Currently these all are procedures (functions and subroutines). | |
7823 | ||
7824 | Some of these intrinsics are unimplemented, but their names reserved | |
7825 | to reduce future problems with existing code as they are implemented. | |
7826 | Others are implemented as part of the GNU Fortran language, while | |
7827 | yet others are provided for compatibility with other dialects of | |
7828 | Fortran but are not part of the GNU Fortran language. | |
7829 | ||
7830 | To manage these distinctions, @code{g77} provides intrinsic @emph{groups}, | |
7831 | a facility that is simply an extension of the intrinsic groups provided | |
7832 | by the GNU Fortran language. | |
7833 | ||
7834 | @menu | |
7835 | * Intrinsic Groups:: How intrinsics are grouped for easy management. | |
7836 | * Other Intrinsics:: Intrinsics other than those in the GNU | |
7837 | Fortran language. | |
7838 | @end menu | |
7839 | ||
7840 | @node Intrinsic Groups | |
7841 | @subsection Intrinsic Groups | |
7842 | @cindex groups of intrinsics | |
7843 | @cindex intrinsics, groups | |
7844 | ||
7845 | A given specific intrinsic belongs in one or more groups. | |
7846 | Each group is deleted, disabled, hidden, or enabled | |
7847 | by default or a command-line option. | |
7848 | The meaning of each term follows. | |
7849 | ||
7850 | @table @b | |
7851 | @cindex deleted intrinsics | |
7852 | @cindex intrinsics, deleted | |
7853 | @item Deleted | |
7854 | No intrinsics are recognized as belonging to that group. | |
7855 | ||
7856 | @cindex disabled intrinsics | |
7857 | @cindex intrinsics, disabled | |
7858 | @item Disabled | |
7859 | Intrinsics are recognized as belonging to the group, but | |
7860 | references to them (other than via the @code{INTRINSIC} statement) | |
7861 | are disallowed through that group. | |
7862 | ||
7863 | @cindex hidden intrinsics | |
7864 | @cindex intrinsics, hidden | |
7865 | @item Hidden | |
7866 | Intrinsics in that group are recognized and enabled (if implemented) | |
7867 | @emph{only} if the first mention of the actual name of an intrinsic | |
7868 | in a program unit is in an @code{INTRINSIC} statement. | |
7869 | ||
7870 | @cindex enabled intrinsics | |
7871 | @cindex intrinsics, enabled | |
7872 | @item Enabled | |
7873 | Intrinsics in that group are recognized and enabled (if implemented). | |
7874 | @end table | |
7875 | ||
7876 | The distinction between deleting and disabling a group is illustrated | |
7877 | by the following example. | |
7878 | Assume intrinsic @samp{FOO} belongs only to group @samp{FGR}. | |
7879 | If group @samp{FGR} is deleted, the following program unit will | |
7880 | successfully compile, because @samp{FOO()} will be seen as a | |
7881 | reference to an external function named @samp{FOO}: | |
7882 | ||
7883 | @example | |
7884 | PRINT *, FOO() | |
7885 | END | |
7886 | @end example | |
7887 | ||
7888 | @noindent | |
7889 | If group @samp{FGR} is disabled, compiling the above program will produce | |
7890 | diagnostics, either because the @samp{FOO} intrinsic is improperly invoked | |
7891 | or, if properly invoked, it is not enabled. | |
7892 | To change the above program so it references an external function @samp{FOO} | |
7893 | instead of the disabled @samp{FOO} intrinsic, | |
7894 | add the following line to the top: | |
7895 | ||
7896 | @example | |
7897 | EXTERNAL FOO | |
7898 | @end example | |
7899 | ||
7900 | @noindent | |
7901 | So, deleting a group tells @code{g77} to pretend as though the intrinsics in | |
7902 | that group do not exist at all, whereas disabling it tells @code{g77} to | |
7903 | recognize them as (disabled) intrinsics in intrinsic-like contexts. | |
7904 | ||
7905 | Hiding a group is like enabling it, but the intrinsic must be first | |
7906 | named in an @code{INTRINSIC} statement to be considered a reference to the | |
7907 | intrinsic rather than to an external procedure. | |
7908 | This might be the ``safest'' way to treat a new group of intrinsics | |
7909 | when compiling old | |
7910 | code, because it allows the old code to be generally written as if | |
7911 | those new intrinsics never existed, but to be changed to use them | |
7912 | by inserting @code{INTRINSIC} statements in the appropriate places. | |
7913 | However, it should be the goal of development to use @code{EXTERNAL} | |
7914 | for all names of external procedures that might be intrinsic names. | |
7915 | ||
7916 | If an intrinsic is in more than one group, it is enabled if any of its | |
7917 | containing groups are enabled; if not so enabled, it is hidden if | |
7918 | any of its containing groups are hidden; if not so hidden, it is disabled | |
7919 | if any of its containing groups are disabled; if not so disabled, it is | |
7920 | deleted. | |
7921 | This extra complication is necessary because some intrinsics, | |
7922 | such as @code{IBITS}, belong to more than one group, and hence should be | |
7923 | enabled if any of the groups to which they belong are enabled, and so | |
7924 | on. | |
7925 | ||
7926 | The groups are: | |
7927 | ||
7928 | @cindex intrinsics, groups of | |
7929 | @cindex groups of intrinsics | |
7930 | @table @code | |
56a0044b | 7931 | @cindex @code{badu77} intrinsics group |
5ff904cd JL |
7932 | @item badu77 |
7933 | UNIX intrinsics having inappropriate forms (usually functions that | |
7934 | have intended side effects). | |
7935 | ||
56a0044b | 7936 | @cindex @code{gnu} intrinsics group |
5ff904cd JL |
7937 | @item gnu |
7938 | Intrinsics the GNU Fortran language supports that are extensions to | |
7939 | the Fortran standards (77 and 90). | |
7940 | ||
56a0044b | 7941 | @cindex @code{f2c} intrinsics group |
5ff904cd JL |
7942 | @item f2c |
7943 | Intrinsics supported by AT&T's @code{f2c} converter and/or @code{libf2c}. | |
7944 | ||
56a0044b | 7945 | @cindex @code{f90} intrinsics group |
5ff904cd JL |
7946 | @item f90 |
7947 | Fortran 90 intrinsics. | |
7948 | ||
56a0044b | 7949 | @cindex @code{mil} intrinsics group |
5ff904cd JL |
7950 | @item mil |
7951 | MIL-STD 1753 intrinsics (@code{MVBITS}, @code{IAND}, @code{BTEST}, and so on). | |
7952 | ||
56a0044b | 7953 | @cindex @code{mil} intrinsics group |
5ff904cd JL |
7954 | @item unix |
7955 | UNIX intrinsics (@code{IARGC}, @code{EXIT}, @code{ERF}, and so on). | |
7956 | ||
56a0044b | 7957 | @cindex @code{mil} intrinsics group |
5ff904cd JL |
7958 | @item vxt |
7959 | VAX/VMS FORTRAN (current as of v4) intrinsics. | |
7960 | @end table | |
7961 | ||
7962 | @node Other Intrinsics | |
7963 | @subsection Other Intrinsics | |
7964 | @cindex intrinsics, others | |
7965 | @cindex other intrinsics | |
7966 | ||
7967 | @code{g77} supports intrinsics other than those in the GNU Fortran | |
7968 | language proper. | |
7969 | This set of intrinsics is described below. | |
7970 | ||
7971 | @ifinfo | |
7972 | (Note that the empty lines appearing in the menu below | |
7973 | are not intentional---they result from a bug in the | |
7974 | @code{makeinfo} program.) | |
7975 | @end ifinfo | |
7976 | ||
7977 | @c The actual documentation for intrinsics comes from | |
7978 | @c intdoc.texi, which in turn is automatically generated | |
7979 | @c from the internal g77 tables in intrin.def _and_ the | |
7980 | @c largely hand-written text in intdoc.h. So, if you want | |
7981 | @c to change or add to existing documentation on intrinsics, | |
7982 | @c you probably want to edit intdoc.h. | |
7983 | @c | |
7984 | @clear familyF77 | |
7985 | @clear familyGNU | |
7986 | @clear familyASC | |
7987 | @clear familyMIL | |
7988 | @clear familyF90 | |
7989 | @set familyVXT | |
7990 | @set familyFVZ | |
7991 | @clear familyF2C | |
7992 | @clear familyF2U | |
7993 | @set familyBADU77 | |
7994 | @include intdoc.texi | |
7995 | ||
7996 | @node Other Compilers | |
7997 | @chapter Other Compilers | |
7998 | ||
7999 | An individual Fortran source file can be compiled to | |
8000 | an object (@file{*.o}) file instead of to the final | |
8001 | program executable. | |
8002 | This allows several portions of a program to be compiled | |
8003 | at different times and linked together whenever a new | |
8004 | version of the program is needed. | |
8005 | However, it introduces the issue of @dfn{object compatibility} | |
8006 | across the various object files (and libraries, or @file{*.a} | |
8007 | files) that are linked together to produce any particular | |
8008 | executable file. | |
8009 | ||
8010 | Object compatibility is an issue when combining, in one | |
8011 | program, Fortran code compiled by more than one compiler | |
8012 | (or more than one configuration of a compiler). | |
8013 | If the compilers | |
8014 | disagree on how to transform the names of procedures, there | |
8015 | will normally be errors when linking such programs. | |
8016 | Worse, if the compilers agree on naming, but disagree on issues | |
8017 | like how to pass parameters, return arguments, and lay out | |
8018 | @code{COMMON} areas, the earliest detected errors might be the | |
8019 | incorrect results produced by the program (and that assumes | |
8020 | these errors are detected, which is not always the case). | |
8021 | ||
8022 | Normally, @code{g77} generates code that is | |
8023 | object-compatible with code generated by a version of | |
8024 | @code{f2c} configured (with, for example, @file{f2c.h} definitions) | |
8025 | to be generally compatible with @code{g77} as built by @code{gcc}. | |
8026 | (Normally, @code{f2c} will, by default, conform to the appropriate | |
8027 | configuration, but it is possible that older or perhaps even newer | |
8028 | versions of @code{f2c}, or versions having certain configuration changes | |
8029 | to @code{f2c} internals, will produce object files that are | |
8030 | incompatible with @code{g77}.) | |
8031 | ||
8032 | For example, a Fortran string subroutine | |
8033 | argument will become two arguments on the C side: a @code{char *} | |
8034 | and an @code{int} length. | |
8035 | ||
8036 | Much of this compatibility results from the fact that | |
95a1b676 CB |
8037 | @code{g77} uses the same run-time library, |
8038 | @code{libf2c}, used by @code{f2c}, | |
8039 | though @code{g77} gives its version the name @code{libg2c} | |
8040 | so as to avoid conflicts when linking, | |
8041 | installing them in the same directories, | |
8042 | and so on. | |
5ff904cd JL |
8043 | |
8044 | Other compilers might or might not generate code that | |
95a1b676 | 8045 | is object-compatible with @code{libg2c} and current @code{g77}, |
5ff904cd JL |
8046 | and some might offer such compatibility only when explicitly |
8047 | selected via a command-line option to the compiler. | |
8048 | ||
8049 | @emph{Note: This portion of the documentation definitely needs a lot | |
8050 | of work!} | |
8051 | ||
8052 | @menu | |
8053 | * Dropping f2c Compatibility:: When speed is more important. | |
8054 | * Compilers Other Than f2c:: Interoperation with code from other compilers. | |
8055 | @end menu | |
8056 | ||
8057 | @node Dropping f2c Compatibility | |
8058 | @section Dropping @code{f2c} Compatibility | |
8059 | ||
8060 | Specifying @samp{-fno-f2c} allows @code{g77} to generate, in | |
8061 | some cases, faster code, by not needing to allow to the possibility | |
8062 | of linking with code compiled by @code{f2c}. | |
8063 | ||
8064 | For example, this affects how @code{REAL(KIND=1)}, | |
8065 | @code{COMPLEX(KIND=1)}, and @code{COMPLEX(KIND=2)} functions are called. | |
8066 | With @samp{-fno-f2c}, they are | |
8067 | compiled as returning the appropriate @code{gcc} type | |
8068 | (@code{float}, @code{__complex__ float}, @code{__complex__ double}, | |
8069 | in many configurations). | |
8070 | ||
8071 | With @samp{-ff2c} in force, they | |
8072 | are compiled differently (with perhaps slower run-time performance) | |
8073 | to accommodate the restrictions inherent in @code{f2c}'s use of K&R | |
8074 | C as an intermediate language---@code{REAL(KIND=1)} functions | |
8075 | return C's @code{double} type, while @code{COMPLEX} functions return | |
8076 | @code{void} and use an extra argument pointing to a place for the functions to | |
8077 | return their values. | |
8078 | ||
8079 | It is possible that, in some cases, leaving @samp{-ff2c} in force | |
8080 | might produce faster code than using @samp{-fno-f2c}. | |
8081 | Feel free to experiment, but remember to experiment with changing the way | |
8082 | @emph{entire programs and their Fortran libraries are compiled} at | |
8083 | a time, since this sort of experimentation affects the interface | |
8084 | of code generated for a Fortran source file---that is, it affects | |
8085 | object compatibility. | |
8086 | ||
8087 | Note that @code{f2c} compatibility is a fairly static target to achieve, | |
8088 | though not necessarily perfectly so, since, like @code{g77}, it is | |
8089 | still being improved. | |
8090 | However, specifying @samp{-fno-f2c} causes @code{g77} | |
8091 | to generate code that will probably be incompatible with code | |
8092 | generated by future versions of @code{g77} when the same option | |
8093 | is in force. | |
8094 | You should make sure you are always able to recompile complete | |
8095 | programs from source code when upgrading to new versions of @code{g77} | |
8096 | or @code{f2c}, especially when using options such as @samp{-fno-f2c}. | |
8097 | ||
8098 | Therefore, if you are using @code{g77} to compile libraries and other | |
8099 | object files for possible future use and you don't want to require | |
8100 | recompilation for future use with subsequent versions of @code{g77}, | |
8101 | you might want to stick with @code{f2c} compatibility for now, and | |
8102 | carefully watch for any announcements about changes to the | |
8103 | @code{f2c}/@code{libf2c} interface that might affect existing programs | |
8104 | (thus requiring recompilation). | |
8105 | ||
8106 | It is probable that a future version of @code{g77} will not, | |
8107 | by default, generate object files compatible with @code{f2c}, | |
8108 | and that version probably would no longer use @code{libf2c}. | |
8109 | If you expect to depend on this compatibility in the | |
8110 | long term, use the options @samp{-ff2c -ff2c-library} when compiling | |
8111 | all of the applicable code. | |
8112 | This should cause future versions of @code{g77} either to produce | |
8113 | compatible code (at the expense of the availability of some features and | |
8114 | performance), or at the very least, to produce diagnostics. | |
8115 | ||
95a1b676 CB |
8116 | (The library @code{g77} produces will no longer be named @file{libg2c} |
8117 | when it is no longer generally compatible with @file{libf2c}. | |
8118 | It will likely be referred to, and, if installed as a distinct | |
8119 | library, named @code{libg77}, or some other as-yet-unused name.) | |
8120 | ||
5ff904cd JL |
8121 | @node Compilers Other Than f2c |
8122 | @section Compilers Other Than @code{f2c} | |
8123 | ||
8124 | On systems with Fortran compilers other than @code{f2c} and @code{g77}, | |
8125 | code compiled by @code{g77} is not expected to work | |
8126 | well with code compiled by the native compiler. | |
95a1b676 | 8127 | (This is true for @code{f2c}-compiled objects as well.) |
5ff904cd JL |
8128 | Libraries compiled with the native compiler probably will have |
8129 | to be recompiled with @code{g77} to be used with @code{g77}-compiled code. | |
8130 | ||
8131 | Reasons for such incompatibilities include: | |
8132 | ||
8133 | @itemize @bullet | |
8134 | @item | |
8135 | There might be differences in the way names of Fortran procedures | |
8136 | are translated for use in the system's object-file format. | |
8137 | For example, the statement @samp{CALL FOO} might be compiled | |
8138 | by @code{g77} to call a procedure the linker @code{ld} sees | |
8139 | given the name @samp{_foo_}, while the apparently corresponding | |
8140 | statement @samp{SUBROUTINE FOO} might be compiled by the | |
8141 | native compiler to define the linker-visible name @samp{_foo}, | |
8142 | or @samp{_FOO_}, and so on. | |
8143 | ||
8144 | @item | |
8145 | There might be subtle type mismatches which cause subroutine arguments | |
8146 | and function return values to get corrupted. | |
8147 | ||
8148 | This is why simply getting @code{g77} to | |
8149 | transform procedure names the same way a native | |
8150 | compiler does is not usually a good idea---unless | |
8151 | some effort has been made to ensure that, aside | |
8152 | from the way the two compilers transform procedure | |
8153 | names, everything else about the way they generate | |
8154 | code for procedure interfaces is identical. | |
8155 | ||
8156 | @item | |
8157 | Native compilers | |
8158 | use libraries of private I/O routines which will not be available | |
8159 | at link time unless you have the native compiler---and you would | |
8160 | have to explicitly ask for them. | |
8161 | ||
8162 | For example, on the Sun you | |
8163 | would have to add @samp{-L/usr/lang/SCx.x -lF77 -lV77} to the link | |
8164 | command. | |
8165 | @end itemize | |
8166 | ||
8167 | @node Other Languages | |
8168 | @chapter Other Languages | |
8169 | ||
8170 | @emph{Note: This portion of the documentation definitely needs a lot | |
8171 | of work!} | |
8172 | ||
8173 | @menu | |
66d18ad7 | 8174 | * Interoperating with C and C++:: |
5ff904cd JL |
8175 | @end menu |
8176 | ||
8177 | @node Interoperating with C and C++ | |
8178 | @section Tools and advice for interoperating with C and C++ | |
8179 | ||
8180 | @cindex C, linking with | |
8181 | @cindex C++, linking with | |
8182 | @cindex linking with C | |
8183 | The following discussion assumes that you are running @code{g77} in @code{f2c} | |
95a1b676 | 8184 | compatibility mode, i.e.@: not using @samp{-fno-f2c}. |
5ff904cd JL |
8185 | It provides some |
8186 | advice about quick and simple techniques for linking Fortran and C (or | |
8187 | C++), the most common requirement. | |
8188 | For the full story consult the | |
8189 | description of code generation. | |
8190 | @xref{Debugging and Interfacing}. | |
8191 | ||
8192 | When linking Fortran and C, it's usually best to use @code{g77} to do | |
8193 | the linking so that the correct libraries are included (including the | |
8194 | maths one). | |
8195 | If you're linking with C++ you will want to add | |
8196 | @samp{-lstdc++}, @samp{-lg++} or whatever. | |
8197 | If you need to use another | |
8198 | driver program (or @code{ld} directly), | |
8199 | you can find out what linkage | |
8200 | options @code{g77} passes by running @samp{g77 -v}. | |
8201 | ||
8202 | @menu | |
8203 | * C Interfacing Tools:: | |
8204 | * C Access to Type Information:: | |
8205 | * f2c Skeletons and Prototypes:: | |
8206 | * C++ Considerations:: | |
8207 | * Startup Code:: | |
8208 | @end menu | |
8209 | ||
8210 | @node C Interfacing Tools | |
8211 | @subsection C Interfacing Tools | |
8212 | @pindex f2c | |
8213 | @cindex cfortran.h | |
8214 | @cindex Netlib | |
4e6a1440 | 8215 | Even if you don't actually use it as a compiler, @code{f2c} from |
95a1b676 | 8216 | @uref{ftp://ftp.netlib.org/f2c/src}, can be a useful tool when you're |
5ff904cd JL |
8217 | interfacing (linking) Fortran and C@. |
8218 | @xref{f2c Skeletons and Prototypes,,Generating Skeletons and Prototypes with @code{f2c}}. | |
8219 | ||
8220 | To use @code{f2c} for this purpose you only need retrieve and | |
8221 | build the @file{src} directory from the distribution, consult the | |
8222 | @file{README} instructions there for machine-specifics, and install the | |
8223 | @code{f2c} program on your path. | |
8224 | ||
8225 | Something else that might be useful is @samp{cfortran.h} from | |
95a1b676 | 8226 | @uref{ftp://zebra/desy.de/cfortran}. |
5ff904cd JL |
8227 | This is a fairly general tool which |
8228 | can be used to generate interfaces for calling in both directions | |
8229 | between Fortran and C@. | |
8230 | It can be used in @code{f2c} mode with | |
8231 | @code{g77}---consult its documentation for details. | |
8232 | ||
8233 | @node C Access to Type Information | |
8234 | @subsection Accessing Type Information in C | |
8235 | ||
8236 | @cindex types, Fortran/C | |
8237 | Generally, C code written to link with | |
8238 | @code{g77} code---calling and/or being | |
95a1b676 | 8239 | called from Fortran---should @samp{#include <g2c.h>} to define the C |
5ff904cd JL |
8240 | versions of the Fortran types. |
8241 | Don't assume Fortran @code{INTEGER} types | |
4e6a1440 | 8242 | correspond to C @code{int}s, for instance; instead, declare them as |
95a1b676 CB |
8243 | @code{integer}, a type defined by @file{g2c.h}. |
8244 | @file{g2c.h} is installed where @code{gcc} will find it by | |
5ff904cd JL |
8245 | default, assuming you use a copy of @code{gcc} compatible with |
8246 | @code{g77}, probably built at the same time as @code{g77}. | |
8247 | ||
8248 | @node f2c Skeletons and Prototypes | |
8249 | @subsection Generating Skeletons and Prototypes with @code{f2c} | |
8250 | ||
8251 | @pindex f2c | |
8252 | @cindex -fno-second-underscore | |
95a1b676 | 8253 | A simple and foolproof way to write @code{g77}-callable C routines---e.g.@: to |
5ff904cd JL |
8254 | interface with an existing library---is to write a file (named, for |
8255 | example, @file{fred.f}) of dummy Fortran | |
8256 | skeletons comprising just the declaration of the routine(s) and dummy | |
4e6a1440 | 8257 | arguments plus @code{END} statements. |
5ff904cd JL |
8258 | Then run @code{f2c} on file @file{fred.f} to produce @file{fred.c} |
8259 | into which you can edit | |
8260 | useful code, confident the calling sequence is correct, at least. | |
8261 | (There are some errors otherwise commonly made in generating C | |
95a1b676 CB |
8262 | interfaces with @code{f2c} conventions, |
8263 | such as not using @code{doublereal} | |
8264 | as the return type of a @code{REAL} @code{FUNCTION}.) | |
5ff904cd JL |
8265 | |
8266 | @pindex ftnchek | |
8267 | @code{f2c} also can help with calling Fortran from C, using its | |
8268 | @samp{-P} option to generate C prototypes appropriate for calling the | |
8269 | Fortran.@footnote{The files generated like this can also be used for | |
8270 | inter-unit consistency checking of dummy and actual arguments, although | |
4e6a1440 | 8271 | the @code{ftnchek} tool from @uref{ftp://ftp.netlib.org/fortran} |
95a1b676 | 8272 | or @uref{ftp://ftp.dsm.fordham.edu} is |
5ff904cd JL |
8273 | probably better for this purpose.} |
8274 | If the Fortran code containing any | |
8275 | routines to be called from C is in file @file{joe.f}, use the command | |
8276 | @kbd{f2c -P joe.f} to generate the file @file{joe.P} containing | |
8277 | prototype information. | |
8278 | @code{#include} this in the C which has to call | |
8279 | the Fortran routines to make sure you get it right. | |
8280 | ||
0b31330e | 8281 | @xref{Arrays,,Arrays (DIMENSION)}, for information on the differences |
5ff904cd JL |
8282 | between the way Fortran (including compilers like @code{g77}) and |
8283 | C handle arrays. | |
8284 | ||
8285 | @node C++ Considerations | |
8286 | @subsection C++ Considerations | |
8287 | ||
8288 | @cindex C++ | |
8289 | @code{f2c} can be used to generate suitable code for compilation with a | |
8290 | C++ system using the @samp{-C++} option. | |
8291 | The important thing about linking @code{g77}-compiled | |
8292 | code with C++ is that the prototypes for the @code{g77} | |
8293 | routines must specify C linkage to avoid name mangling. | |
8294 | So, use an @samp{extern "C"} declaration. | |
8295 | @code{f2c}'s @samp{-C++} option will take care | |
8296 | of this when generating skeletons or prototype files as above, and also | |
8297 | avoid clashes with C++ reserved words in addition to those in C@. | |
8298 | ||
8299 | @node Startup Code | |
8300 | @subsection Startup Code | |
8301 | ||
8302 | @cindex startup code | |
26b9526e CB |
8303 | @cindex run-time, initialization |
8304 | @cindex initialization, run-time | |
43ebf5a4 DL |
8305 | Unlike with some runtime systems, |
8306 | it shouldn't be necessary | |
8307 | (unless there are bugs) | |
8308 | to use a Fortran main program unit to ensure the | |
8309 | runtime---specifically the I/O system---is initialized. | |
8310 | ||
8311 | However, to use the @code{g77} intrinsics @code{GETARG} and @code{IARGC}, | |
8312 | either the @code{main} routine from the @file{libg2c} library must be used, | |
8313 | or the @code{f_setarg} routine | |
8314 | (new as of @code{egcs} version 1.1 and @code{g77} version 0.5.23) | |
8315 | must be called with the appropriate @code{argc} and @code{argv} arguments | |
8316 | prior to the program calling @code{GETARG} or @code{IARGC}. | |
8317 | ||
8318 | To provide more flexibility for mixed-language programming | |
8319 | involving @code{g77} while allowing for shared libraries, | |
8320 | as of @code{egcs} version 1.1 and @code{g77} version 0.5.23, | |
8321 | @code{g77}'s @code{main} routine in @code{libg2c} | |
8322 | does the following, in order: | |
8323 | ||
8324 | @enumerate | |
8325 | @item | |
8326 | Calls @code{f_setarg} | |
8327 | with the incoming @code{argc} and @code{argv} arguments, | |
8328 | in the same order as for @code{main} itself. | |
8329 | ||
8330 | This sets up the command-line environment | |
8331 | for @code{GETARG} and @code{IARGC}. | |
8332 | ||
8333 | @item | |
8334 | Calls @code{f_setsig} (with no arguments). | |
8335 | ||
8336 | This sets up the signaling and exception environment. | |
8337 | ||
8338 | @item | |
8339 | Calls @code{f_init} (with no arguments). | |
8340 | ||
8341 | This initializes the I/O environment, | |
8342 | though that should not be necessary, | |
8343 | as all I/O functions in @code{libf2c} | |
8344 | are believed to call @code{f_init} automatically, | |
8345 | if necessary. | |
8346 | ||
8347 | (A future version of @code{g77} might skip this explicit step, | |
8348 | to speed up normal exit of a program.) | |
8349 | ||
8350 | @item | |
8351 | Arranges for @code{f_exit} to be called (with no arguments) | |
8352 | when the program exits. | |
8353 | ||
8354 | This ensures that the I/O environment is properly shut down | |
8355 | before the program exits normally. | |
8356 | Otherwise, output buffers might not be fully flushed, | |
8357 | scratch files might not be deleted, and so on. | |
8358 | ||
8359 | The simple way @code{main} does this is | |
8360 | to call @code{f_exit} itself after calling | |
8361 | @code{MAIN__} (in the next step). | |
8362 | ||
8363 | However, this does not catch the cases where the program | |
8364 | might call @code{exit} directly, | |
8365 | instead of using the @code{EXIT} intrinsic | |
8366 | (implemented as @code{exit_} in @code{libf2c}). | |
8367 | ||
8368 | So, @code{main} attempts to use | |
8369 | the operating environment's @code{onexit} or @code{atexit} | |
8370 | facility, if available, | |
8371 | to cause @code{f_exit} to be called automatically | |
8372 | upon any invocation of @code{exit}. | |
8373 | ||
8374 | @item | |
8375 | Calls @code{MAIN__} (with no arguments). | |
8376 | ||
8377 | This starts executing the Fortran main program unit for | |
8378 | the application. | |
8379 | (Both @code{g77} and @code{f2c} currently compile a main | |
8380 | program unit so that its global name is @code{MAIN__}.) | |
8381 | ||
8382 | @item | |
8383 | If no @code{onexit} or @code{atexit} is provided by the system, | |
8384 | calls @code{f_exit}. | |
8385 | ||
8386 | @item | |
8387 | Calls @code{exit} with a zero argument, | |
8388 | to signal a successful program termination. | |
8389 | ||
8390 | @item | |
8391 | Returns a zero value to the caller, | |
8392 | to signal a successful program termination, | |
8393 | in case @code{exit} doesn't exit on the system. | |
8394 | @end enumerate | |
8395 | ||
8396 | All of the above names are C @code{extern} names, | |
8397 | i.e.@: not mangled. | |
8398 | ||
8399 | When using the @code{main} procedure provided by @code{g77} | |
8400 | without a Fortran main program unit, | |
8401 | you need to provide @code{MAIN__} | |
8402 | as the entry point for your C code. | |
8403 | (Make sure you link the object file that defines that | |
8404 | entry point with the rest of your program.) | |
8405 | ||
8406 | To provide your own @code{main} procedure | |
8407 | in place of @code{g77}'s, | |
8408 | make sure you specify the object file defining that procedure | |
8409 | @emph{before} @samp{-lg2c} on the @code{g77} command line. | |
8410 | Since the @samp{-lg2c} option is implicitly provided, | |
8411 | this is usually straightforward. | |
8412 | (Use the @samp{--verbose} option to see how and where | |
8413 | @code{g77} implicitly adds @samp{-lg2c} in a command line | |
8414 | that will link the program. | |
8415 | Feel free to specify @samp{-lg2c} explicitly, | |
8416 | as appropriate.) | |
8417 | ||
8418 | However, when providing your own @code{main}, | |
8419 | make sure you perform the appropriate tasks in the | |
8420 | appropriate order. | |
8421 | For example, if your @code{main} does not call @code{f_setarg}, | |
8422 | make sure the rest of your application does not call | |
8423 | @code{GETARG} or @code{IARGC}. | |
8424 | ||
8425 | And, if your @code{main} fails to ensure that @code{f_exit} | |
8426 | is called upon program exit, | |
8427 | some files might end up incompletely written, | |
8428 | some scratch files might be left lying around, | |
8429 | and some existing files being written might be left | |
8430 | with old data not properly truncated at the end. | |
8431 | ||
8432 | Note that, generally, the @code{g77} operating environment | |
8433 | does not depend on a procedure named @code{MAIN__} actually | |
8434 | being called prior to any other @code{g77}-compiled code. | |
8435 | That is, @code{MAIN__} does not, itself, | |
8436 | set up any important operating-environment characteristics | |
8437 | upon which other code might depend. | |
8438 | This might change in future versions of @code{g77}, | |
8439 | with appropriate notification in the release notes. | |
8440 | ||
8441 | For more information, consult the source code for the above routines. | |
9a59ff4f | 8442 | These are in @file{@value{path-libf2c}/libF77/}, named @file{main.c}, |
43ebf5a4 DL |
8443 | @file{setarg.c}, @file{setsig.c}, @file{getarg_.c}, and @file{iargc_.c}. |
8444 | ||
9a59ff4f | 8445 | Also, the file @file{@value{path-g77}/com.c} contains the code @code{g77} |
43ebf5a4 | 8446 | uses to open-code (inline) references to @code{IARGC}. |
5ff904cd | 8447 | |
4ac480d6 | 8448 | @include g77install.texi |
5ff904cd JL |
8449 | |
8450 | @node Debugging and Interfacing | |
8451 | @chapter Debugging and Interfacing | |
8452 | @cindex debugging | |
8453 | @cindex interfacing | |
8454 | @cindex calling C routines | |
8455 | @cindex C routines calling Fortran | |
8456 | @cindex f2c compatibility | |
8457 | ||
8458 | GNU Fortran currently generates code that is object-compatible with | |
8459 | the @code{f2c} converter. | |
8460 | Also, it avoids limitations in the current GBE, such as the | |
8461 | inability to generate a procedure with | |
8462 | multiple entry points, by generating code that is structured | |
8463 | differently (in terms of procedure names, scopes, arguments, and | |
8464 | so on) than might be expected. | |
8465 | ||
8466 | As a result, writing code in other languages that calls on, is | |
8467 | called by, or shares in-memory data with @code{g77}-compiled code generally | |
8468 | requires some understanding of the way @code{g77} compiles code for | |
8469 | various constructs. | |
8470 | ||
8471 | Similarly, using a debugger to debug @code{g77}-compiled | |
8472 | code, even if that debugger supports native Fortran debugging, generally | |
8473 | requires this sort of information. | |
8474 | ||
8475 | This section describes some of the basic information on how | |
8476 | @code{g77} compiles code for constructs involving interfaces to other | |
8477 | languages and to debuggers. | |
8478 | ||
8479 | @emph{Caution:} Much or all of this information pertains to only the current | |
8480 | release of @code{g77}, sometimes even to using certain compiler options | |
8481 | with @code{g77} (such as @samp{-fno-f2c}). | |
8482 | Do not write code that depends on this | |
8483 | information without clearly marking said code as nonportable and | |
8484 | subject to review for every new release of @code{g77}. | |
8485 | This information | |
8486 | is provided primarily to make debugging of code generated by this | |
8487 | particular release of @code{g77} easier for the user, and partly to make | |
8488 | writing (generally nonportable) interface code easier. | |
8489 | Both of these | |
8490 | activities require tracking changes in new version of @code{g77} as they | |
8491 | are installed, because new versions can change the behaviors | |
8492 | described in this section. | |
8493 | ||
8494 | @menu | |
8495 | * Main Program Unit:: How @code{g77} compiles a main program unit. | |
8496 | * Procedures:: How @code{g77} constructs parameter lists | |
8497 | for procedures. | |
8498 | * Functions:: Functions returning floating-point or character data. | |
8499 | * Names:: Naming of user-defined variables, procedures, etc. | |
8500 | * Common Blocks:: Accessing common variables while debugging. | |
8501 | * Local Equivalence Areas:: Accessing @code{EQUIVALENCE} while debugging. | |
8502 | * Complex Variables:: How @code{g77} performs complex arithmetic. | |
8503 | * Arrays:: Dealing with (possibly multi-dimensional) arrays. | |
8504 | * Adjustable Arrays:: Special consideration for adjustable arrays. | |
8505 | * Alternate Entry Points:: How @code{g77} implements alternate @code{ENTRY}. | |
8506 | * Alternate Returns:: How @code{g77} handles alternate returns. | |
8507 | * Assigned Statement Labels:: How @code{g77} handles @code{ASSIGN}. | |
8508 | * Run-time Library Errors:: Meanings of some @code{IOSTAT=} values. | |
8509 | @end menu | |
8510 | ||
8511 | @node Main Program Unit | |
8512 | @section Main Program Unit (PROGRAM) | |
8513 | @cindex PROGRAM statement | |
8514 | @cindex statements, PROGRAM | |
8515 | ||
8516 | When @code{g77} compiles a main program unit, it gives it the public | |
4e6a1440 | 8517 | procedure name @code{MAIN__}. |
95a1b676 | 8518 | The @code{libg2c} library has the actual @code{main()} procedure |
5ff904cd JL |
8519 | as is typical of C-based environments, and |
8520 | it is this procedure that performs some initial start-up | |
4e6a1440 | 8521 | activity and then calls @code{MAIN__}. |
5ff904cd | 8522 | |
95a1b676 | 8523 | Generally, @code{g77} and @code{libg2c} are designed so that you need not |
5ff904cd JL |
8524 | include a main program unit written in Fortran in your program---it |
8525 | can be written in C or some other language. | |
8526 | Especially for I/O handling, this is the case, although @code{g77} version 0.5.16 | |
95a1b676 | 8527 | includes a bug fix for @code{libg2c} that solved a problem with using the |
5ff904cd JL |
8528 | @code{OPEN} statement as the first Fortran I/O activity in a program |
8529 | without a Fortran main program unit. | |
8530 | ||
8531 | However, if you don't intend to use @code{g77} (or @code{f2c}) to compile | |
8532 | your main program unit---that is, if you intend to compile a @code{main()} | |
8533 | procedure using some other language---you should carefully | |
95a1b676 | 8534 | examine the code for @code{main()} in @code{libg2c}, found in the source |
9a59ff4f | 8535 | file @file{@value{path-libf2c}/libF77/main.c}, to see what kinds of things |
5ff904cd JL |
8536 | might need to be done by your @code{main()} in order to provide the |
8537 | Fortran environment your Fortran code is expecting. | |
8538 | ||
26b9526e CB |
8539 | @cindex @code{IArgC} intrinsic |
8540 | @cindex intrinsics, @code{IArgC} | |
8541 | @cindex @code{GetArg} intrinsic | |
8542 | @cindex intrinsics, @code{GetArg} | |
95a1b676 | 8543 | For example, @code{libg2c}'s @code{main()} sets up the information used by |
5ff904cd | 8544 | the @code{IARGC} and @code{GETARG} intrinsics. |
95a1b676 | 8545 | Bypassing @code{libg2c}'s @code{main()} |
5ff904cd JL |
8546 | without providing a substitute for this activity would mean |
8547 | that invoking @code{IARGC} and @code{GETARG} would produce undefined | |
8548 | results. | |
8549 | ||
8550 | @cindex debugging | |
8551 | @cindex main program unit, debugging | |
8552 | @cindex main() | |
8553 | @cindex MAIN__() | |
8554 | @cindex .gdbinit | |
8555 | When debugging, one implication of the fact that @code{main()}, which | |
8556 | is the place where the debugged program ``starts'' from the | |
95a1b676 | 8557 | debugger's point of view, is in @code{libg2c} is that you won't be |
5ff904cd JL |
8558 | starting your Fortran program at a point you recognize as your |
8559 | Fortran code. | |
8560 | ||
8561 | The standard way to get around this problem is to set a break | |
8562 | point (a one-time, or temporary, break point will do) at | |
4e6a1440 | 8563 | the entrance to @code{MAIN__}, and then run the program. |
5ff904cd JL |
8564 | A convenient way to do so is to add the @code{gdb} command |
8565 | ||
8566 | @example | |
8567 | tbreak MAIN__ | |
8568 | @end example | |
8569 | ||
8570 | @noindent | |
8571 | to the file @file{.gdbinit} in the directory in which you're debugging | |
8572 | (using @code{gdb}). | |
8573 | ||
8574 | After doing this, the debugger will see the current execution | |
8575 | point of the program as at the beginning of the main program | |
8576 | unit of your program. | |
8577 | ||
8578 | Of course, if you really want to set a break point at some | |
8579 | other place in your program and just start the program | |
4e6a1440 | 8580 | running, without first breaking at @code{MAIN__}, |
5ff904cd JL |
8581 | that should work fine. |
8582 | ||
8583 | @node Procedures | |
8584 | @section Procedures (SUBROUTINE and FUNCTION) | |
8585 | @cindex procedures | |
8586 | @cindex SUBROUTINE statement | |
8587 | @cindex statements, SUBROUTINE | |
8588 | @cindex FUNCTION statement | |
8589 | @cindex statements, FUNCTION | |
8590 | @cindex signature of procedures | |
8591 | ||
8592 | Currently, @code{g77} passes arguments via reference---specifically, | |
8593 | by passing a pointer to the location in memory of a variable, array, | |
8594 | array element, a temporary location that holds the result of evaluating an | |
8595 | expression, or a temporary or permanent location that holds the value | |
8596 | of a constant. | |
8597 | ||
8598 | Procedures that accept @code{CHARACTER} arguments are implemented by | |
8599 | @code{g77} so that each @code{CHARACTER} argument has two actual arguments. | |
8600 | ||
8601 | The first argument occupies the expected position in the | |
8602 | argument list and has the user-specified name. | |
8603 | This argument | |
8604 | is a pointer to an array of characters, passed by the caller. | |
8605 | ||
8606 | The second argument is appended to the end of the user-specified | |
8607 | calling sequence and is named @samp{__g77_length_@var{x}}, where @var{x} | |
8608 | is the user-specified name. | |
8609 | This argument is of the C type @code{ftnlen} | |
9a59ff4f | 8610 | (see @file{@value{path-libf2c}/g2c.h.in} for information on that type) and |
5ff904cd JL |
8611 | is the number of characters the caller has allocated in the |
8612 | array pointed to by the first argument. | |
8613 | ||
8614 | A procedure will ignore the length argument if @samp{X} is not declared | |
8615 | @code{CHARACTER*(*)}, because for other declarations, it knows the | |
8616 | length. | |
8617 | Not all callers necessarily ``know'' this, however, which | |
8618 | is why they all pass the extra argument. | |
8619 | ||
8620 | The contents of the @code{CHARACTER} argument are specified by the | |
8621 | address passed in the first argument (named after it). | |
8622 | The procedure can read or write these contents as appropriate. | |
8623 | ||
8624 | When more than one @code{CHARACTER} argument is present in the argument | |
8625 | list, the length arguments are appended in the order | |
8626 | the original arguments appear. | |
8627 | So @samp{CALL FOO('HI','THERE')} is implemented in | |
8628 | C as @samp{foo("hi","there",2,5);}, ignoring the fact that @code{g77} | |
8629 | does not provide the trailing null bytes on the constant | |
8630 | strings (@code{f2c} does provide them, but they are unnecessary in | |
8631 | a Fortran environment, and you should not expect them to be | |
8632 | there). | |
8633 | ||
8634 | Note that the above information applies to @code{CHARACTER} variables and | |
8635 | arrays @strong{only}. | |
8636 | It does @strong{not} apply to external @code{CHARACTER} | |
8637 | functions or to intrinsic @code{CHARACTER} functions. | |
8638 | That is, no second length argument is passed to @samp{FOO} in this case: | |
8639 | ||
8640 | @example | |
8641 | CHARACTER X | |
8642 | EXTERNAL X | |
8643 | CALL FOO(X) | |
8644 | @end example | |
8645 | ||
8646 | @noindent | |
8647 | Nor does @samp{FOO} expect such an argument in this case: | |
8648 | ||
8649 | @example | |
8650 | SUBROUTINE FOO(X) | |
8651 | CHARACTER X | |
8652 | EXTERNAL X | |
8653 | @end example | |
8654 | ||
8655 | Because of this implementation detail, if a program has a bug | |
8656 | such that there is disagreement as to whether an argument is | |
8657 | a procedure, and the type of the argument is @code{CHARACTER}, subtle | |
8658 | symptoms might appear. | |
8659 | ||
8660 | @node Functions | |
8661 | @section Functions (FUNCTION and RETURN) | |
8662 | @cindex functions | |
8663 | @cindex FUNCTION statement | |
8664 | @cindex statements, FUNCTION | |
8665 | @cindex RETURN statement | |
8666 | @cindex statements, RETURN | |
8667 | @cindex return type of functions | |
8668 | ||
8669 | @code{g77} handles in a special way functions that return the following | |
8670 | types: | |
8671 | ||
8672 | @itemize @bullet | |
8673 | @item | |
8674 | @code{CHARACTER} | |
8675 | @item | |
8676 | @code{COMPLEX} | |
8677 | @item | |
8678 | @code{REAL(KIND=1)} | |
8679 | @end itemize | |
8680 | ||
8681 | For @code{CHARACTER}, @code{g77} implements a subroutine (a C function | |
8682 | returning @code{void}) | |
8683 | with two arguments prepended: @samp{__g77_result}, which the caller passes | |
8684 | as a pointer to a @code{char} array expected to hold the return value, | |
8685 | and @samp{__g77_length}, which the caller passes as an @code{ftnlen} value | |
8686 | specifying the length of the return value as declared in the calling | |
8687 | program. | |
8688 | For @code{CHARACTER*(*)}, the called function uses @samp{__g77_length} | |
8689 | to determine the size of the array that @samp{__g77_result} points to; | |
8690 | otherwise, it ignores that argument. | |
8691 | ||
8692 | For @code{COMPLEX}, when @samp{-ff2c} is in | |
8693 | force, @code{g77} implements | |
8694 | a subroutine with one argument prepended: @samp{__g77_result}, which the | |
8695 | caller passes as a pointer to a variable of the type of the function. | |
8696 | The called function writes the return value into this variable instead | |
8697 | of returning it as a function value. | |
8698 | When @samp{-fno-f2c} is in force, | |
8699 | @code{g77} implements a @code{COMPLEX} function as @code{gcc}'s | |
8700 | @samp{__complex__ float} or @samp{__complex__ double} function | |
8701 | (or an emulation thereof, when @samp{-femulate-complex} is in effect), | |
8702 | returning the result of the function in the same way as @code{gcc} would. | |
8703 | ||
8704 | For @code{REAL(KIND=1)}, when @samp{-ff2c} is in force, @code{g77} implements | |
8705 | a function that actually returns @code{REAL(KIND=2)} (typically | |
8706 | C's @code{double} type). | |
8707 | When @samp{-fno-f2c} is in force, @code{REAL(KIND=1)} | |
8708 | functions return @code{float}. | |
8709 | ||
8710 | @node Names | |
8711 | @section Names | |
8712 | @cindex symbol names | |
26b9526e | 8713 | @cindex transforming symbol names |
5ff904cd JL |
8714 | |
8715 | Fortran permits each implementation to decide how to represent | |
8716 | names as far as how they're seen in other contexts, such as debuggers | |
8717 | and when interfacing to other languages, and especially as far | |
8718 | as how casing is handled. | |
8719 | ||
8720 | External names---names of entities that are public, or ``accessible'', | |
8721 | to all modules in a program---normally have an underscore (@samp{_}) | |
95a1b676 CB |
8722 | appended by @code{g77}, |
8723 | to generate code that is compatible with @code{f2c}. | |
5ff904cd JL |
8724 | External names include names of Fortran things like common blocks, |
8725 | external procedures (subroutines and functions, but not including | |
8726 | statement functions, which are internal procedures), and entry point | |
8727 | names. | |
8728 | ||
8729 | However, use of the @samp{-fno-underscoring} option | |
8730 | disables this kind of transformation of external names (though inhibiting | |
8731 | the transformation certainly improves the chances of colliding with | |
8732 | incompatible externals written in other languages---but that | |
8733 | might be intentional. | |
8734 | ||
8735 | @cindex -fno-underscoring option | |
8736 | @cindex options, -fno-underscoring | |
8737 | @cindex -fno-second-underscore option | |
8738 | @cindex options, -fno-underscoring | |
8739 | When @samp{-funderscoring} is in force, any name (external or local) | |
8740 | that already has at least one underscore in it is | |
8741 | implemented by @code{g77} by appending two underscores. | |
8742 | (This second underscore can be disabled via the | |
95a1b676 | 8743 | @samp{-fno-second-underscore} option.) |
5ff904cd JL |
8744 | External names are changed this way for @code{f2c} compatibility. |
8745 | Local names are changed this way to avoid collisions with external names | |
8746 | that are different in the source code---@code{f2c} does the same thing, but | |
8747 | there's no compatibility issue there except for user expectations while | |
8748 | debugging. | |
8749 | ||
8750 | For example: | |
8751 | ||
8752 | @example | |
8753 | Max_Cost = 0 | |
8754 | @end example | |
8755 | ||
8756 | @cindex debugging | |
8757 | @noindent | |
8758 | Here, a user would, in the debugger, refer to this variable using the | |
8759 | name @samp{max_cost__} (or @samp{MAX_COST__} or @samp{Max_Cost__}, | |
8760 | as described below). | |
8761 | (We hope to improve @code{g77} in this regard in the future---don't | |
8762 | write scripts depending on this behavior! | |
8763 | Also, consider experimenting with the @samp{-fno-underscoring} | |
8764 | option to try out debugging without having to massage names by | |
8765 | hand like this.) | |
8766 | ||
8767 | @code{g77} provides a number of command-line options that allow the user | |
8768 | to control how case mapping is handled for source files. | |
8769 | The default is the traditional UNIX model for Fortran compilers---names | |
8770 | are mapped to lower case. | |
8771 | Other command-line options can be specified to map names to upper | |
8772 | case, or to leave them exactly as written in the source file. | |
8773 | ||
8774 | For example: | |
8775 | ||
8776 | @example | |
8777 | Foo = 9.436 | |
8778 | @end example | |
8779 | ||
8780 | @noindent | |
8781 | Here, it is normally the case that the variable assigned will be named | |
8782 | @samp{foo}. | |
8783 | This would be the name to enter when using a debugger to | |
8784 | access the variable. | |
8785 | ||
8786 | However, depending on the command-line options specified, the | |
8787 | name implemented by @code{g77} might instead be @samp{FOO} or even | |
8788 | @samp{Foo}, thus affecting how debugging is done. | |
8789 | ||
8790 | Also: | |
8791 | ||
8792 | @example | |
8793 | Call Foo | |
8794 | @end example | |
8795 | ||
8796 | @noindent | |
8797 | This would normally call a procedure that, if it were in a separate C program, | |
8798 | be defined starting with the line: | |
8799 | ||
8800 | @example | |
8801 | void foo_() | |
8802 | @end example | |
8803 | ||
8804 | @noindent | |
8805 | However, @code{g77} command-line options could be used to change the casing | |
8806 | of names, resulting in the name @samp{FOO_} or @samp{Foo_} being given to the | |
8807 | procedure instead of @samp{foo_}, and the @samp{-fno-underscoring} option | |
8808 | could be used to inhibit the appending of the underscore to the name. | |
8809 | ||
8810 | @node Common Blocks | |
8811 | @section Common Blocks (COMMON) | |
8812 | @cindex common blocks | |
26b9526e CB |
8813 | @cindex @code{COMMON} statement |
8814 | @cindex statements, @code{COMMON} | |
5ff904cd | 8815 | |
95a1b676 CB |
8816 | @code{g77} names and lays out @code{COMMON} areas |
8817 | the same way @code{f2c} does, | |
8818 | for compatibility with @code{f2c}. | |
5ff904cd JL |
8819 | |
8820 | Currently, @code{g77} does not emit ``true'' debugging information for | |
8821 | members of a @code{COMMON} area, due to an apparent bug in the GBE. | |
8822 | ||
8823 | (As of Version 0.5.19, @code{g77} emits debugging information for such | |
8824 | members in the form of a constant string specifying the base name of | |
8825 | the aggregate area and the offset of the member in bytes from the start | |
8826 | of the area. | |
8827 | Use the @samp{-fdebug-kludge} option to enable this behavior. | |
8828 | In @code{gdb}, use @samp{set language c} before printing the value | |
8829 | of the member, then @samp{set language fortran} to restore the default | |
8830 | language, since @code{gdb} doesn't provide a way to print a readable | |
8831 | version of a character string in Fortran language mode. | |
8832 | ||
8833 | This kludge will be removed in a future version of @code{g77} that, | |
8834 | in conjunction with a contemporary version of @code{gdb}, | |
8835 | properly supports Fortran-language debugging, including access | |
8836 | to members of @code{COMMON} areas.) | |
8837 | ||
8838 | @xref{Code Gen Options,,Options for Code Generation Conventions}, | |
8839 | for information on the @samp{-fdebug-kludge} option. | |
8840 | ||
8841 | Moreover, @code{g77} currently implements a @code{COMMON} area such that its | |
8842 | type is an array of the C @code{char} data type. | |
8843 | ||
8844 | So, when debugging, you must know the offset into a @code{COMMON} area | |
8845 | for a particular item in that area, and you have to take into | |
8846 | account the appropriate multiplier for the respective sizes | |
8847 | of the types (as declared in your code) for the items preceding | |
8848 | the item in question as compared to the size of the @code{char} type. | |
8849 | ||
8850 | For example, using default implicit typing, the statement | |
8851 | ||
8852 | @example | |
8853 | COMMON I(15), R(20), T | |
8854 | @end example | |
8855 | ||
8856 | @noindent | |
8857 | results in a public 144-byte @code{char} array named @samp{_BLNK__} | |
8858 | with @samp{I} placed at @samp{_BLNK__[0]}, @samp{R} at @samp{_BLNK__[60]}, | |
8859 | and @samp{T} at @samp{_BLNK__[140]}. | |
8860 | (This is assuming that the target machine for | |
8861 | the compilation has 4-byte @code{INTEGER(KIND=1)} and @code{REAL(KIND=1)} | |
8862 | types.) | |
8863 | ||
8864 | @node Local Equivalence Areas | |
8865 | @section Local Equivalence Areas (EQUIVALENCE) | |
8866 | @cindex equivalence areas | |
8867 | @cindex local equivalence areas | |
8868 | @cindex EQUIVALENCE statement | |
8869 | @cindex statements, EQUIVALENCE | |
8870 | ||
8871 | @code{g77} treats storage-associated areas involving a @code{COMMON} | |
8872 | block as explained in the section on common blocks. | |
8873 | ||
8874 | A local @code{EQUIVALENCE} area is a collection of variables and arrays | |
8875 | connected to each other in any way via @code{EQUIVALENCE}, none of which are | |
8876 | listed in a @code{COMMON} statement. | |
8877 | ||
8878 | Currently, @code{g77} does not emit ``true'' debugging information for | |
8879 | members in a local @code{EQUIVALENCE} area, due to an apparent bug in the GBE. | |
8880 | ||
8881 | (As of Version 0.5.19, @code{g77} does emit debugging information for such | |
8882 | members in the form of a constant string specifying the base name of | |
8883 | the aggregate area and the offset of the member in bytes from the start | |
8884 | of the area. | |
8885 | Use the @samp{-fdebug-kludge} option to enable this behavior. | |
8886 | In @code{gdb}, use @samp{set language c} before printing the value | |
8887 | of the member, then @samp{set language fortran} to restore the default | |
8888 | language, since @code{gdb} doesn't provide a way to print a readable | |
8889 | version of a character string in Fortran language mode. | |
8890 | ||
8891 | This kludge will be removed in a future version of @code{g77} that, | |
8892 | in conjunction with a contemporary version of @code{gdb}, | |
8893 | properly supports Fortran-language debugging, including access | |
8894 | to members of @code{EQUIVALENCE} areas.) | |
8895 | ||
8896 | @xref{Code Gen Options,,Options for Code Generation Conventions}, | |
8897 | for information on the @samp{-fdebug-kludge} option. | |
8898 | ||
8899 | Moreover, @code{g77} implements a local @code{EQUIVALENCE} area such that its | |
8900 | type is an array of the C @code{char} data type. | |
8901 | ||
8902 | The name @code{g77} gives this array of @code{char} type is @samp{__g77_equiv_@var{x}}, | |
8903 | where @var{x} is the name of the item that is placed at the beginning (offset 0) | |
8904 | of this array. | |
8905 | If more than one such item is placed at the beginning, @var{x} is | |
8906 | the name that sorts to the top in an alphabetical sort of the list of | |
8907 | such items. | |
8908 | ||
8909 | When debugging, you must therefore access members of @code{EQUIVALENCE} | |
8910 | areas by specifying the appropriate @samp{__g77_equiv_@var{x}} | |
8911 | array section with the appropriate offset. | |
8912 | See the explanation of debugging @code{COMMON} blocks | |
8913 | for info applicable to debugging local @code{EQUIVALENCE} areas. | |
8914 | ||
8915 | (@emph{Note:} @code{g77} version 0.5.18 and earlier chose the name | |
8916 | for @var{x} using a different method when more than one name was | |
8917 | in the list of names of entities placed at the beginning of the | |
8918 | array. | |
8919 | Though the documentation specified that the first name listed in | |
8920 | the @code{EQUIVALENCE} statements was chosen for @var{x}, @code{g77} | |
8921 | in fact chose the name using a method that was so complicated, | |
8922 | it seemed easier to change it to an alphabetical sort than to describe the | |
8923 | previous method in the documentation.) | |
8924 | ||
8925 | @node Complex Variables | |
8926 | @section Complex Variables (COMPLEX) | |
8927 | @cindex complex variables | |
26b9526e | 8928 | @cindex imaginary part |
5ff904cd JL |
8929 | @cindex COMPLEX statement |
8930 | @cindex statements, COMPLEX | |
8931 | ||
8932 | As of 0.5.20, @code{g77} defaults to handling @code{COMPLEX} types | |
8933 | (and related intrinsics, constants, functions, and so on) | |
8934 | in a manner that | |
8935 | makes direct debugging involving these types in Fortran | |
8936 | language mode difficult. | |
8937 | ||
8938 | Essentially, @code{g77} implements these types using an | |
8939 | internal construct similar to C's @code{struct}, at least | |
8940 | as seen by the @code{gcc} back end. | |
8941 | ||
8942 | Currently, the back end, when outputting debugging info with | |
8943 | the compiled code for the assembler to digest, does not detect | |
8944 | these @code{struct} types as being substitutes for Fortran | |
8945 | complex. | |
8946 | As a result, the Fortran language modes of debuggers such as | |
8947 | @code{gdb} see these types as C @code{struct} types, which | |
8948 | they might or might not support. | |
8949 | ||
8950 | Until this is fixed, switch to C language mode to work with | |
8951 | entities of @code{COMPLEX} type and then switch back to Fortran language | |
8952 | mode afterward. | |
8953 | (In @code{gdb}, this is accomplished via @samp{set lang c} and | |
8954 | either @samp{set lang fortran} or @samp{set lang auto}.) | |
8955 | ||
5ff904cd JL |
8956 | @node Arrays |
8957 | @section Arrays (DIMENSION) | |
8958 | @cindex DIMENSION statement | |
8959 | @cindex statements, DIMENSION | |
8960 | @cindex array ordering | |
8961 | @cindex ordering, array | |
8962 | @cindex column-major ordering | |
8963 | @cindex row-major ordering | |
8964 | @cindex arrays | |
8965 | ||
8966 | Fortran uses ``column-major ordering'' in its arrays. | |
8967 | This differs from other languages, such as C, which use ``row-major ordering''. | |
8968 | The difference is that, with Fortran, array elements adjacent to | |
8969 | each other in memory differ in the @emph{first} subscript instead of | |
8970 | the last; @samp{A(5,10,20)} immediately follows @samp{A(4,10,20)}, | |
8971 | whereas with row-major ordering it would follow @samp{A(5,10,19)}. | |
8972 | ||
8973 | This consideration | |
8974 | affects not only interfacing with and debugging Fortran code, | |
8975 | it can greatly affect how code is designed and written, especially | |
8976 | when code speed and size is a concern. | |
8977 | ||
8978 | Fortran also differs from C, a popular language for interfacing and | |
8979 | to support directly in debuggers, in the way arrays are treated. | |
8980 | In C, arrays are single-dimensional and have interesting relationships | |
8981 | to pointers, neither of which is true for Fortran. | |
8982 | As a result, dealing with Fortran arrays from within | |
8983 | an environment limited to C concepts can be challenging. | |
8984 | ||
8985 | For example, accessing the array element @samp{A(5,10,20)} is easy enough | |
8986 | in Fortran (use @samp{A(5,10,20)}), but in C some difficult machinations | |
8987 | are needed. | |
8988 | First, C would treat the A array as a single-dimension array. | |
8989 | Second, C does not understand low bounds for arrays as does Fortran. | |
8990 | Third, C assumes a low bound of zero (0), while Fortran defaults to a | |
8991 | low bound of one (1) and can supports an arbitrary low bound. | |
8992 | Therefore, calculations must be done | |
8993 | to determine what the C equivalent of @samp{A(5,10,20)} would be, and these | |
8994 | calculations require knowing the dimensions of @samp{A}. | |
8995 | ||
8996 | For @samp{DIMENSION A(2:11,21,0:29)}, the calculation of the offset of | |
8997 | @samp{A(5,10,20)} would be: | |
8998 | ||
8999 | @example | |
9000 | (5-2) | |
9001 | + (10-1)*(11-2+1) | |
9002 | + (20-0)*(11-2+1)*(21-1+1) | |
9003 | = 4293 | |
9004 | @end example | |
9005 | ||
9006 | @noindent | |
9007 | So the C equivalent in this case would be @samp{a[4293]}. | |
9008 | ||
9009 | When using a debugger directly on Fortran code, the C equivalent | |
9010 | might not work, because some debuggers cannot understand the notion | |
9011 | of low bounds other than zero. However, unlike @code{f2c}, @code{g77} | |
9012 | does inform the GBE that a multi-dimensional array (like @samp{A} | |
9013 | in the above example) is really multi-dimensional, rather than a | |
9014 | single-dimensional array, so at least the dimensionality of the array | |
9015 | is preserved. | |
9016 | ||
9017 | Debuggers that understand Fortran should have no trouble with | |
9018 | non-zero low bounds, but for non-Fortran debuggers, especially | |
9019 | C debuggers, the above example might have a C equivalent of | |
9020 | @samp{a[4305]}. | |
9021 | This calculation is arrived at by eliminating the subtraction | |
9022 | of the lower bound in the first parenthesized expression on each | |
9023 | line---that is, for @samp{(5-2)} substitute @samp{(5)}, for @samp{(10-1)} | |
9024 | substitute @samp{(10)}, and for @samp{(20-0)} substitute @samp{(20)}. | |
9025 | Actually, the implication of | |
9026 | this can be that the expression @samp{*(&a[2][1][0] + 4293)} works fine, | |
9027 | but that @samp{a[20][10][5]} produces the equivalent of | |
9028 | @samp{*(&a[0][0][0] + 4305)} because of the missing lower bounds. | |
9029 | ||
9030 | Come to think of it, perhaps | |
9031 | the behavior is due to the debugger internally compensating for | |
9032 | the lower bounds by offsetting the base address of @samp{a}, leaving | |
9033 | @samp{&a} set lower, in this case, than @samp{&a[2][1][0]} (the address of | |
9034 | its first element as identified by subscripts equal to the | |
9035 | corresponding lower bounds). | |
9036 | ||
9037 | You know, maybe nobody really needs to use arrays. | |
9038 | ||
9039 | @node Adjustable Arrays | |
9040 | @section Adjustable Arrays (DIMENSION) | |
9041 | @cindex arrays, adjustable | |
9042 | @cindex adjustable arrays | |
9043 | @cindex arrays, automatic | |
9044 | @cindex automatic arrays | |
9045 | @cindex DIMENSION statement | |
9046 | @cindex statements, DIMENSION | |
9047 | @cindex dimensioning arrays | |
9048 | @cindex arrays, dimensioning | |
9049 | ||
9050 | Adjustable and automatic arrays in Fortran require the implementation | |
9051 | (in this | |
9052 | case, the @code{g77} compiler) to ``memorize'' the expressions that | |
9053 | dimension the arrays each time the procedure is invoked. | |
9054 | This is so that subsequent changes to variables used in those | |
9055 | expressions, made during execution of the procedure, do not | |
9056 | have any effect on the dimensions of those arrays. | |
9057 | ||
9058 | For example: | |
9059 | ||
9060 | @example | |
9061 | REAL ARRAY(5) | |
9062 | DATA ARRAY/5*2/ | |
9063 | CALL X(ARRAY, 5) | |
9064 | END | |
9065 | SUBROUTINE X(A, N) | |
9066 | DIMENSION A(N) | |
9067 | N = 20 | |
9068 | PRINT *, N, A | |
9069 | END | |
9070 | @end example | |
9071 | ||
9072 | @noindent | |
9073 | Here, the implementation should, when running the program, print something | |
9074 | like: | |
9075 | ||
9076 | @example | |
9077 | 20 2. 2. 2. 2. 2. | |
9078 | @end example | |
9079 | ||
9080 | @noindent | |
9081 | Note that this shows that while the value of @samp{N} was successfully | |
9082 | changed, the size of the @samp{A} array remained at 5 elements. | |
9083 | ||
9084 | To support this, @code{g77} generates code that executes before any user | |
9085 | code (and before the internally generated computed @code{GOTO} to handle | |
9086 | alternate entry points, as described below) that evaluates each | |
9087 | (nonconstant) expression in the list of subscripts for an | |
9088 | array, and saves the result of each such evaluation to be used when | |
9089 | determining the size of the array (instead of re-evaluating the | |
9090 | expressions). | |
9091 | ||
9092 | So, in the above example, when @samp{X} is first invoked, code is | |
9093 | executed that copies the value of @samp{N} to a temporary. | |
9094 | And that same temporary serves as the actual high bound for the single | |
9095 | dimension of the @samp{A} array (the low bound being the constant 1). | |
9096 | Since the user program cannot (legitimately) change the value | |
9097 | of the temporary during execution of the procedure, the size | |
9098 | of the array remains constant during each invocation. | |
9099 | ||
9100 | For alternate entry points, the code @code{g77} generates takes into | |
9101 | account the possibility that a dummy adjustable array is not actually | |
9102 | passed to the actual entry point being invoked at that time. | |
9103 | In that case, the public procedure implementing the entry point | |
9104 | passes to the master private procedure implementing all the | |
9105 | code for the entry points a @code{NULL} pointer where a pointer to that | |
9106 | adjustable array would be expected. | |
9107 | The @code{g77}-generated code | |
9108 | doesn't attempt to evaluate any of the expressions in the subscripts | |
9109 | for an array if the pointer to that array is @code{NULL} at run time in | |
9110 | such cases. | |
9111 | (Don't depend on this particular implementation | |
9112 | by writing code that purposely passes @code{NULL} pointers where the | |
9113 | callee expects adjustable arrays, even if you know the callee | |
9114 | won't reference the arrays---nor should you pass @code{NULL} pointers | |
9115 | for any dummy arguments used in calculating the bounds of such | |
9116 | arrays or leave undefined any values used for that purpose in | |
9117 | COMMON---because the way @code{g77} implements these things might | |
9118 | change in the future!) | |
9119 | ||
9120 | @node Alternate Entry Points | |
9121 | @section Alternate Entry Points (ENTRY) | |
9122 | @cindex alternate entry points | |
9123 | @cindex entry points | |
9124 | @cindex ENTRY statement | |
9125 | @cindex statements, ENTRY | |
9126 | ||
9127 | The GBE does not understand the general concept of | |
9128 | alternate entry points as Fortran provides via the ENTRY statement. | |
9129 | @code{g77} gets around this by using an approach to compiling procedures | |
9130 | having at least one @code{ENTRY} statement that is almost identical to the | |
9131 | approach used by @code{f2c}. | |
9132 | (An alternate approach could be used that | |
9133 | would probably generate faster, but larger, code that would also | |
9134 | be a bit easier to debug.) | |
9135 | ||
9136 | Information on how @code{g77} implements @code{ENTRY} is provided for those | |
9137 | trying to debug such code. | |
9138 | The choice of implementation seems | |
9139 | unlikely to affect code (compiled in other languages) that interfaces | |
9140 | to such code. | |
9141 | ||
9142 | @code{g77} compiles exactly one public procedure for the primary entry | |
9143 | point of a procedure plus each @code{ENTRY} point it specifies, as usual. | |
9144 | That is, in terms of the public interface, there is no difference | |
9145 | between | |
9146 | ||
9147 | @example | |
9148 | SUBROUTINE X | |
9149 | END | |
9150 | SUBROUTINE Y | |
9151 | END | |
9152 | @end example | |
9153 | ||
9154 | @noindent | |
9155 | and: | |
9156 | ||
9157 | @example | |
9158 | SUBROUTINE X | |
9159 | ENTRY Y | |
9160 | END | |
9161 | @end example | |
9162 | ||
9163 | The difference between the above two cases lies in the code compiled | |
9164 | for the @samp{X} and @samp{Y} procedures themselves, plus the fact that, | |
9165 | for the second case, an extra internal procedure is compiled. | |
9166 | ||
9167 | For every Fortran procedure with at least one @code{ENTRY} | |
9168 | statement, @code{g77} compiles an extra procedure | |
9169 | named @samp{__g77_masterfun_@var{x}}, where @var{x} is | |
9170 | the name of the primary entry point (which, in the above case, | |
9171 | using the standard compiler options, would be @samp{x_} in C). | |
9172 | ||
9173 | This extra procedure is compiled as a private procedure---that is, | |
9174 | a procedure not accessible by name to separately compiled modules. | |
9175 | It contains all the code in the program unit, including the code | |
9176 | for the primary entry point plus for every entry point. | |
9177 | (The code for each public procedure is quite short, and explained later.) | |
9178 | ||
9179 | The extra procedure has some other interesting characteristics. | |
9180 | ||
9181 | The argument list for this procedure is invented by @code{g77}. | |
9182 | It contains | |
9183 | a single integer argument named @samp{__g77_which_entrypoint}, | |
9184 | passed by value (as in Fortran's @samp{%VAL()} intrinsic), specifying the | |
9185 | entry point index---0 for the primary entry point, 1 for the | |
9186 | first entry point (the first @code{ENTRY} statement encountered), 2 for | |
9187 | the second entry point, and so on. | |
9188 | ||
9189 | It also contains, for functions returning @code{CHARACTER} and | |
9190 | (when @samp{-ff2c} is in effect) @code{COMPLEX} functions, | |
9191 | and for functions returning different types among the | |
9192 | @code{ENTRY} statements (e.g. @samp{REAL FUNCTION R()} | |
9193 | containing @samp{ENTRY I()}), an argument named @samp{__g77_result} that | |
9194 | is expected at run time to contain a pointer to where to store | |
9195 | the result of the entry point. | |
9196 | For @code{CHARACTER} functions, this | |
9197 | storage area is an array of the appropriate number of characters; | |
9198 | for @code{COMPLEX} functions, it is the appropriate area for the return | |
9199 | type; for multiple-return-type functions, it is a union of all the supported return | |
9200 | types (which cannot include @code{CHARACTER}, since combining @code{CHARACTER} | |
9201 | and non-@code{CHARACTER} return types via @code{ENTRY} in a single function | |
9202 | is not supported by @code{g77}). | |
9203 | ||
9204 | For @code{CHARACTER} functions, the @samp{__g77_result} argument is followed | |
9205 | by yet another argument named @samp{__g77_length} that, at run time, | |
9206 | specifies the caller's expected length of the returned value. | |
9207 | Note that only @code{CHARACTER*(*)} functions and entry points actually | |
9208 | make use of this argument, even though it is always passed by | |
9209 | all callers of public @code{CHARACTER} functions (since the caller does not | |
9210 | generally know whether such a function is @code{CHARACTER*(*)} or whether | |
9211 | there are any other callers that don't have that information). | |
9212 | ||
9213 | The rest of the argument list is the union of all the arguments | |
9214 | specified for all the entry points (in their usual forms, e.g. | |
9215 | @code{CHARACTER} arguments have extra length arguments, all appended at | |
9216 | the end of this list). | |
9217 | This is considered the ``master list'' of | |
9218 | arguments. | |
9219 | ||
9220 | The code for this procedure has, before the code for the first | |
9221 | executable statement, code much like that for the following Fortran | |
9222 | statement: | |
9223 | ||
9224 | @smallexample | |
9225 | GOTO (100000,100001,100002), __g77_which_entrypoint | |
9226 | 100000 @dots{}code for primary entry point@dots{} | |
9227 | 100001 @dots{}code immediately following first ENTRY statement@dots{} | |
9228 | 100002 @dots{}code immediately following second ENTRY statement@dots{} | |
9229 | @end smallexample | |
9230 | ||
9231 | @noindent | |
9232 | (Note that invalid Fortran statement labels and variable names | |
9233 | are used in the above example to highlight the fact that it | |
9234 | represents code generated by the @code{g77} internals, not code to be | |
9235 | written by the user.) | |
9236 | ||
9237 | It is this code that, when the procedure is called, picks which | |
9238 | entry point to start executing. | |
9239 | ||
9240 | Getting back to the public procedures (@samp{x} and @samp{Y} in the original | |
9241 | example), those procedures are fairly simple. | |
9242 | Their interfaces | |
9243 | are just like they would be if they were self-contained procedures | |
9244 | (without @code{ENTRY}), of course, since that is what the callers | |
9245 | expect. | |
9246 | Their code consists of simply calling the private | |
9247 | procedure, described above, with the appropriate extra arguments | |
9248 | (the entry point index, and perhaps a pointer to a multiple-type- | |
9249 | return variable, local to the public procedure, that contains | |
9250 | all the supported returnable non-character types). | |
9251 | For arguments | |
9252 | that are not listed for a given entry point that are listed for | |
9253 | other entry points, and therefore that are in the ``master list'' | |
9254 | for the private procedure, null pointers (in C, the @code{NULL} macro) | |
9255 | are passed. | |
9256 | Also, for entry points that are part of a multiple-type- | |
9257 | returning function, code is compiled after the call of the private | |
9258 | procedure to extract from the multi-type union the appropriate result, | |
9259 | depending on the type of the entry point in question, returning | |
9260 | that result to the original caller. | |
9261 | ||
9262 | When debugging a procedure containing alternate entry points, you | |
9263 | can either set a break point on the public procedure itself (e.g. | |
9264 | a break point on @samp{X} or @samp{Y}) or on the private procedure that | |
9265 | contains most of the pertinent code (e.g. @samp{__g77_masterfun_@var{x}}). | |
9266 | If you do the former, you should use the debugger's command to | |
9267 | ``step into'' the called procedure to get to the actual code; with | |
9268 | the latter approach, the break point leaves you right at the | |
9269 | actual code, skipping over the public entry point and its call | |
9270 | to the private procedure (unless you have set a break point there | |
9271 | as well, of course). | |
9272 | ||
9273 | Further, the list of dummy arguments that is visible when the | |
9274 | private procedure is active is going to be the expanded version | |
9275 | of the list for whichever particular entry point is active, | |
9276 | as explained above, and the way in which return values are | |
9277 | handled might well be different from how they would be handled | |
9278 | for an equivalent single-entry function. | |
9279 | ||
9280 | @node Alternate Returns | |
9281 | @section Alternate Returns (SUBROUTINE and RETURN) | |
9282 | @cindex subroutines | |
9283 | @cindex alternate returns | |
9284 | @cindex SUBROUTINE statement | |
9285 | @cindex statements, SUBROUTINE | |
9286 | @cindex RETURN statement | |
9287 | @cindex statements, RETURN | |
9288 | ||
9289 | Subroutines with alternate returns (e.g. @samp{SUBROUTINE X(*)} and | |
9290 | @samp{CALL X(*50)}) are implemented by @code{g77} as functions returning | |
9291 | the C @code{int} type. | |
9292 | The actual alternate-return arguments are omitted from the calling sequence. | |
9293 | Instead, the caller uses | |
9294 | the return value to do a rough equivalent of the Fortran | |
9295 | computed-@code{GOTO} statement, as in @samp{GOTO (50), X()} in the | |
9296 | example above (where @samp{X} is quietly declared as an @code{INTEGER(KIND=1)} | |
9297 | function), and the callee just returns whatever integer | |
9298 | is specified in the @code{RETURN} statement for the subroutine | |
9299 | For example, @samp{RETURN 1} is implemented as @samp{X = 1} followed | |
9300 | by @samp{RETURN} | |
9301 | in C, and @samp{RETURN} by itself is @samp{X = 0} and @samp{RETURN}). | |
9302 | ||
9303 | @node Assigned Statement Labels | |
9304 | @section Assigned Statement Labels (ASSIGN and GOTO) | |
9305 | @cindex assigned statement labels | |
9306 | @cindex statement labels, assigned | |
9307 | @cindex ASSIGN statement | |
9308 | @cindex statements, ASSIGN | |
9309 | @cindex GOTO statement | |
9310 | @cindex statements, GOTO | |
9311 | ||
9312 | For portability to machines where a pointer (such as to a label, | |
9313 | which is how @code{g77} implements @code{ASSIGN} and its relatives, | |
9314 | the assigned-@code{GOTO} and assigned-@code{FORMAT}-I/O statements) | |
9315 | is wider (bitwise) than an @code{INTEGER(KIND=1)}, @code{g77} | |
9316 | uses a different memory location to hold the @code{ASSIGN}ed value of a variable | |
9317 | than it does the numerical value in that variable, unless the | |
9318 | variable is wide enough (can hold enough bits). | |
9319 | ||
9320 | In particular, while @code{g77} implements | |
9321 | ||
9322 | @example | |
9323 | I = 10 | |
9324 | @end example | |
9325 | ||
9326 | @noindent | |
9327 | as, in C notation, @samp{i = 10;}, it implements | |
9328 | ||
9329 | @example | |
9330 | ASSIGN 10 TO I | |
9331 | @end example | |
9332 | ||
9333 | @noindent | |
9334 | as, in GNU's extended C notation (for the label syntax), | |
9335 | @samp{__g77_ASSIGN_I = &&L10;} (where @samp{L10} is just a massaging | |
9336 | of the Fortran label @samp{10} to make the syntax C-like; @code{g77} doesn't | |
9337 | actually generate the name @samp{L10} or any other name like that, | |
9338 | since debuggers cannot access labels anyway). | |
9339 | ||
9340 | While this currently means that an @code{ASSIGN} statement does not | |
9341 | overwrite the numeric contents of its target variable, @emph{do not} | |
9342 | write any code depending on this feature. | |
9343 | @code{g77} has already changed this implementation across | |
9344 | versions and might do so in the future. | |
9345 | This information is provided only to make debugging Fortran programs | |
9346 | compiled with the current version of @code{g77} somewhat easier. | |
9347 | If there's no debugger-visible variable named @samp{__g77_ASSIGN_I} | |
9348 | in a program unit that does @samp{ASSIGN 10 TO I}, that probably | |
9349 | means @code{g77} has decided it can store the pointer to the label directly | |
9350 | into @samp{I} itself. | |
9351 | ||
9352 | @xref{Ugly Assigned Labels}, for information on a command-line option | |
9353 | to force @code{g77} to use the same storage for both normal and | |
9354 | assigned-label uses of a variable. | |
9355 | ||
9356 | @node Run-time Library Errors | |
9357 | @section Run-time Library Errors | |
9358 | @cindex IOSTAT= | |
9359 | @cindex error values | |
9360 | @cindex error messages | |
9361 | @cindex messages, run-time | |
9362 | @cindex I/O, errors | |
9363 | ||
95a1b676 | 9364 | The @code{libg2c} library currently has the following table to relate |
5ff904cd JL |
9365 | error code numbers, returned in @code{IOSTAT=} variables, to messages. |
9366 | This information should, in future versions of this document, be | |
9367 | expanded upon to include detailed descriptions of each message. | |
9368 | ||
9369 | In line with good coding practices, any of the numbers in the | |
9370 | list below should @emph{not} be directly written into Fortran | |
9371 | code you write. | |
9372 | Instead, make a separate @code{INCLUDE} file that defines | |
9373 | @code{PARAMETER} names for them, and use those in your code, | |
9374 | so you can more easily change the actual numbers in the future. | |
9375 | ||
9376 | The information below is culled from the definition | |
4e6a1440 | 9377 | of @code{F_err} in @file{f/runtime/libI77/err.c} in the |
5ff904cd JL |
9378 | @code{g77} source tree. |
9379 | ||
9380 | @smallexample | |
9381 | 100: "error in format" | |
9382 | 101: "illegal unit number" | |
9383 | 102: "formatted io not allowed" | |
9384 | 103: "unformatted io not allowed" | |
9385 | 104: "direct io not allowed" | |
9386 | 105: "sequential io not allowed" | |
9387 | 106: "can't backspace file" | |
9388 | 107: "null file name" | |
9389 | 108: "can't stat file" | |
9390 | 109: "unit not connected" | |
9391 | 110: "off end of record" | |
9392 | 111: "truncation failed in endfile" | |
9393 | 112: "incomprehensible list input" | |
9394 | 113: "out of free space" | |
9395 | 114: "unit not connected" | |
9396 | 115: "read unexpected character" | |
9397 | 116: "bad logical input field" | |
9398 | 117: "bad variable type" | |
9399 | 118: "bad namelist name" | |
9400 | 119: "variable not in namelist" | |
9401 | 120: "no end record" | |
9402 | 121: "variable count incorrect" | |
9403 | 122: "subscript for scalar variable" | |
9404 | 123: "invalid array section" | |
9405 | 124: "substring out of bounds" | |
9406 | 125: "subscript out of bounds" | |
9407 | 126: "can't read file" | |
9408 | 127: "can't write file" | |
9409 | 128: "'new' file exists" | |
9410 | 129: "can't append to file" | |
9411 | 130: "non-positive record number" | |
9412 | 131: "I/O started while already doing I/O" | |
9413 | @end smallexample | |
9414 | ||
9415 | @node Collected Fortran Wisdom | |
9416 | @chapter Collected Fortran Wisdom | |
9417 | @cindex wisdom | |
9418 | @cindex legacy code | |
9419 | @cindex code, legacy | |
9420 | @cindex writing code | |
9421 | @cindex code, writing | |
9422 | ||
9423 | Most users of @code{g77} can be divided into two camps: | |
9424 | ||
9425 | @itemize @bullet | |
9426 | @item | |
9427 | Those writing new Fortran code to be compiled by @code{g77}. | |
9428 | ||
9429 | @item | |
9430 | Those using @code{g77} to compile existing, ``legacy'' code. | |
9431 | @end itemize | |
9432 | ||
9433 | Users writing new code generally understand most of the necessary | |
9434 | aspects of Fortran to write ``mainstream'' code, but often need | |
9435 | help deciding how to handle problems, such as the construction | |
9436 | of libraries containing @code{BLOCK DATA}. | |
9437 | ||
9438 | Users dealing with ``legacy'' code sometimes don't have much | |
9439 | experience with Fortran, but believe that the code they're compiling | |
9440 | already works when compiled by other compilers (and might | |
9441 | not understand why, as is sometimes the case, it doesn't work | |
9442 | when compiled by @code{g77}). | |
9443 | ||
9444 | The following information is designed to help users do a better job | |
9445 | coping with existing, ``legacy'' Fortran code, and with writing | |
9446 | new code as well. | |
9447 | ||
9448 | @menu | |
9449 | * Advantages Over f2c:: If @code{f2c} is so great, why @code{g77}? | |
9450 | * Block Data and Libraries:: How @code{g77} solves a common problem. | |
9451 | * Loops:: Fortran @code{DO} loops surprise many people. | |
9452 | * Working Programs:: Getting programs to work should be done first. | |
9453 | * Overly Convenient Options:: Temptations to avoid, habits to not form. | |
9454 | * Faster Programs:: Everybody wants these, but at what cost? | |
9455 | @end menu | |
9456 | ||
9457 | @node Advantages Over f2c | |
9458 | @section Advantages Over f2c | |
9459 | ||
9460 | Without @code{f2c}, @code{g77} would have taken much longer to | |
9461 | do and probably not been as good for quite a while. | |
9462 | Sometimes people who notice how much @code{g77} depends on, and | |
9463 | documents encouragement to use, @code{f2c} ask why @code{g77} | |
9464 | was created if @code{f2c} already existed. | |
9465 | ||
9466 | This section gives some basic answers to these questions, though it | |
9467 | is not intended to be comprehensive. | |
9468 | ||
9469 | @menu | |
9470 | * Language Extensions:: Features used by Fortran code. | |
37cfb17c CB |
9471 | * Diagnostic Abilities:: Abilities to spot problems early. |
9472 | * Compiler Options:: Features helpful to accommodate legacy code, etc. | |
5ff904cd JL |
9473 | * Compiler Speed:: Speed of the compilation process. |
9474 | * Program Speed:: Speed of the generated, optimized code. | |
9475 | * Ease of Debugging:: Debugging ease-of-use at the source level. | |
9476 | * Character and Hollerith Constants:: A byte saved is a byte earned. | |
9477 | @end menu | |
9478 | ||
9479 | @node Language Extensions | |
9480 | @subsection Language Extensions | |
9481 | ||
37cfb17c CB |
9482 | @code{g77} offers several extensions to FORTRAN 77 language that @code{f2c} |
9483 | doesn't: | |
9484 | ||
9485 | @itemize @bullet | |
9486 | @item | |
9487 | Automatic arrays | |
9488 | ||
9489 | @item | |
9490 | @code{CYCLE} and @code{EXIT} | |
9491 | ||
9492 | @item | |
9493 | Construct names | |
9494 | ||
9495 | @item | |
9496 | @code{SELECT CASE} | |
9497 | ||
9498 | @item | |
9499 | @code{KIND=} and @code{LEN=} notation | |
9500 | ||
9501 | @item | |
9502 | Semicolon as statement separator | |
9503 | ||
9504 | @item | |
9505 | Constant expressions in @code{FORMAT} statements | |
9506 | (such as @samp{FORMAT(I<J>)}, | |
9507 | where @samp{J} is a @code{PARAMETER} named constant) | |
9508 | ||
9509 | @item | |
9510 | @code{MvBits} intrinsic | |
9511 | ||
9512 | @item | |
9513 | @code{libU77} (Unix-compatibility) library, | |
9514 | with routines known to compiler as intrinsics | |
9515 | (so they work even when compiler options are used | |
9516 | to change the interfaces used by Fortran routines) | |
9517 | @end itemize | |
9518 | ||
9519 | @code{g77} also implements iterative @code{DO} loops | |
9520 | so that they work even in the presence of certain ``extreme'' inputs, | |
9521 | unlike @code{f2c}. | |
9522 | @xref{Loops}. | |
9523 | ||
9524 | However, @code{f2c} offers a few that @code{g77} doesn't, such as: | |
9525 | ||
9526 | @itemize @bullet | |
9527 | @item | |
9528 | Intrinsics in @code{PARAMETER} statements | |
9529 | ||
9530 | @item | |
9531 | Array bounds expressions (such as @samp{REAL M(N(2))}) | |
9532 | ||
9533 | @item | |
9534 | @code{AUTOMATIC} statement | |
9535 | @end itemize | |
5ff904cd | 9536 | |
5ff904cd JL |
9537 | It is expected that @code{g77} will offer some or all of these missing |
9538 | features at some time in the future. | |
37cfb17c CB |
9539 | |
9540 | @node Diagnostic Abilities | |
9541 | @subsection Diagnostic Abilities | |
9542 | ||
9543 | @code{g77} offers better diagnosis of problems in @code{FORMAT} statements. | |
9544 | @code{f2c} doesn't, for example, emit any diagnostic for | |
9545 | @samp{FORMAT(XZFAJG10324)}, | |
9546 | leaving that to be diagnosed, at run time, by | |
9547 | the @code{libf2c} run-time library. | |
5ff904cd JL |
9548 | |
9549 | @node Compiler Options | |
9550 | @subsection Compiler Options | |
9551 | ||
37cfb17c CB |
9552 | @code{g77} offers compiler options that @code{f2c} doesn't, |
9553 | most of which are designed to more easily accommodate | |
9554 | legacy code: | |
9555 | ||
9556 | @itemize @bullet | |
9557 | @item | |
9558 | Two that control the automatic appending of extra | |
9559 | underscores to external names | |
9560 | ||
9561 | @item | |
9562 | One that allows dollar signs (@samp{$}) in symbol names | |
9563 | ||
9564 | @item | |
9565 | A variety that control acceptance of various | |
9566 | ``ugly'' constructs | |
9567 | ||
9568 | @item | |
9569 | Several that specify acceptable use of upper and lower case | |
9570 | in the source code | |
9571 | ||
9572 | @item | |
9573 | Many that enable, disable, delete, or hide | |
9574 | groups of intrinsics | |
9575 | ||
9576 | @item | |
9577 | One to specify the length of fixed-form source lines | |
9578 | (normally 72) | |
9579 | ||
9580 | @item | |
9581 | One to specify the the source code is written in | |
9582 | Fortran-90-style free-form | |
9583 | @end itemize | |
5ff904cd | 9584 | |
3880e745 CB |
9585 | However, @code{f2c} offers a few that @code{g77} doesn't, |
9586 | like an option to have @code{REAL} default to @code{REAL*8}. | |
9587 | It is expected that @code{g77} will offer all of the | |
9588 | missing options pertinent to being a Fortran compiler | |
9589 | at some time in the future. | |
5ff904cd JL |
9590 | |
9591 | @node Compiler Speed | |
9592 | @subsection Compiler Speed | |
9593 | ||
9594 | Saving the steps of writing and then rereading C code is a big reason | |
9595 | why @code{g77} should be able to compile code much faster than using | |
9596 | @code{f2c} in conjunction with the equivalent invocation of @code{gcc}. | |
9597 | ||
9598 | However, due to @code{g77}'s youth, lots of self-checking is still being | |
9599 | performed. | |
9600 | As a result, this improvement is as yet unrealized | |
9601 | (though the potential seems to be there for quite a big speedup | |
9602 | in the future). | |
9603 | It is possible that, as of version 0.5.18, @code{g77} | |
9604 | is noticeably faster compiling many Fortran source files than using | |
9605 | @code{f2c} in conjunction with @code{gcc}. | |
9606 | ||
9607 | @node Program Speed | |
9608 | @subsection Program Speed | |
9609 | ||
9610 | @code{g77} has the potential to better optimize code than @code{f2c}, | |
9611 | even when @code{gcc} is used to compile the output of @code{f2c}, | |
9612 | because @code{f2c} must necessarily | |
9613 | translate Fortran into a somewhat lower-level language (C) that cannot | |
9614 | preserve all the information that is potentially useful for optimization, | |
9615 | while @code{g77} can gather, preserve, and transmit that information directly | |
9616 | to the GBE. | |
9617 | ||
9618 | For example, @code{g77} implements @code{ASSIGN} and assigned | |
9619 | @code{GOTO} using direct assignment of pointers to labels and direct | |
9620 | jumps to labels, whereas @code{f2c} maps the assigned labels to | |
9621 | integer values and then uses a C @code{switch} statement to encode | |
9622 | the assigned @code{GOTO} statements. | |
9623 | ||
9624 | However, as is typical, theory and reality don't quite match, at least | |
9625 | not in all cases, so it is still the case that @code{f2c} plus @code{gcc} | |
9626 | can generate code that is faster than @code{g77}. | |
9627 | ||
9628 | Version 0.5.18 of @code{g77} offered default | |
9629 | settings and options, via patches to the @code{gcc} | |
9630 | back end, that allow for better program speed, though | |
9631 | some of these improvements also affected the performance | |
9632 | of programs translated by @code{f2c} and then compiled | |
9633 | by @code{g77}'s version of @code{gcc}. | |
9634 | ||
9635 | Version 0.5.20 of @code{g77} offers further performance | |
9636 | improvements, at least one of which (alias analysis) is | |
9637 | not generally applicable to @code{f2c} (though @code{f2c} | |
9638 | could presumably be changed to also take advantage of | |
9639 | this new capability of the @code{gcc} back end, assuming | |
9640 | this is made available in an upcoming release of @code{gcc}). | |
9641 | ||
9642 | @node Ease of Debugging | |
9643 | @subsection Ease of Debugging | |
9644 | ||
9645 | Because @code{g77} compiles directly to assembler code like @code{gcc}, | |
9646 | instead of translating to an intermediate language (C) as does @code{f2c}, | |
9647 | support for debugging can be better for @code{g77} than @code{f2c}. | |
9648 | ||
9649 | However, although @code{g77} might be somewhat more ``native'' in terms of | |
9650 | debugging support than @code{f2c} plus @code{gcc}, there still are a lot | |
9651 | of things ``not quite right''. | |
9652 | Many of the important ones should be resolved in the near future. | |
9653 | ||
9654 | For example, @code{g77} doesn't have to worry about reserved names | |
9655 | like @code{f2c} does. | |
9656 | Given @samp{FOR = WHILE}, @code{f2c} must necessarily | |
9657 | translate this to something @emph{other} than | |
9658 | @samp{for = while;}, because C reserves those words. | |
9659 | ||
9660 | However, @code{g77} does still uses things like an extra level of indirection | |
9661 | for @code{ENTRY}-laden procedures---in this case, because the back end doesn't | |
9662 | yet support multiple entry points. | |
9663 | ||
9664 | Another example is that, given | |
9665 | ||
9666 | @smallexample | |
9667 | COMMON A, B | |
9668 | EQUIVALENCE (B, C) | |
9669 | @end smallexample | |
9670 | ||
9671 | @noindent | |
9672 | the @code{g77} user should be able to access the variables directly, by name, | |
9673 | without having to traverse C-like structures and unions, while @code{f2c} | |
9674 | is unlikely to ever offer this ability (due to limitations in the | |
9675 | C language). | |
9676 | ||
9677 | However, due to apparent bugs in the back end, @code{g77} currently doesn't | |
9678 | take advantage of this facility at all---it doesn't emit any debugging | |
9679 | information for @code{COMMON} and @code{EQUIVALENCE} areas, | |
9680 | other than information | |
9681 | on the array of @code{char} it creates (and, in the case | |
9682 | of local @code{EQUIVALENCE}, names) for each such area. | |
9683 | ||
9684 | Yet another example is arrays. | |
9685 | @code{g77} represents them to the debugger | |
9686 | using the same ``dimensionality'' as in the source code, while @code{f2c} | |
9687 | must necessarily convert them all to one-dimensional arrays to fit | |
9688 | into the confines of the C language. | |
9689 | However, the level of support | |
9690 | offered by debuggers for interactive Fortran-style access to arrays | |
9691 | as compiled by @code{g77} can vary widely. | |
9692 | In some cases, it can actually | |
9693 | be an advantage that @code{f2c} converts everything to widely supported | |
9694 | C semantics. | |
9695 | ||
9696 | In fairness, @code{g77} could do many of the things @code{f2c} does | |
9697 | to get things working at least as well as @code{f2c}---for now, | |
9698 | the developers prefer making @code{g77} work the | |
9699 | way they think it is supposed to, and finding help improving the | |
9700 | other products (the back end of @code{gcc}; @code{gdb}; and so on) | |
9701 | to get things working properly. | |
9702 | ||
9703 | @node Character and Hollerith Constants | |
9704 | @subsection Character and Hollerith Constants | |
9705 | @cindex character constants | |
9706 | @cindex constants, character | |
9707 | @cindex Hollerith constants | |
9708 | @cindex constants, Hollerith | |
9709 | @cindex trailing null byte | |
9710 | @cindex null byte, trailing | |
9711 | @cindex zero byte, trailing | |
9712 | ||
9713 | To avoid the extensive hassle that would be needed to avoid this, | |
9714 | @code{f2c} uses C character constants to encode character and Hollerith | |
9715 | constants. | |
9716 | That means a constant like @samp{'HELLO'} is translated to | |
9717 | @samp{"hello"} in C, which further means that an extra null byte is | |
9718 | present at the end of the constant. | |
9719 | This null byte is superfluous. | |
9720 | ||
9721 | @code{g77} does not generate such null bytes. | |
9722 | This represents significant | |
9723 | savings of resources, such as on systems where @file{/dev/null} or | |
9724 | @file{/dev/zero} represent bottlenecks in the systems' performance, | |
9725 | because @code{g77} simply asks for fewer zeros from the operating | |
9726 | system than @code{f2c}. | |
0063c777 DL |
9727 | (Avoiding spurious use of zero bytes, each byte typically have |
9728 | eight zero bits, also reduces the liabilities in case | |
9729 | Microsoft's rumored patent on the digits 0 and 1 is upheld.) | |
5ff904cd JL |
9730 | |
9731 | @node Block Data and Libraries | |
9732 | @section Block Data and Libraries | |
9733 | @cindex block data and libraries | |
9734 | @cindex BLOCK DATA statement | |
9735 | @cindex statements, BLOCK DATA | |
9736 | @cindex libraries, containing BLOCK DATA | |
26b9526e CB |
9737 | @cindex f2c compatibility |
9738 | @cindex compatibility, f2c | |
5ff904cd JL |
9739 | |
9740 | To ensure that block data program units are linked, especially a concern | |
9741 | when they are put into libraries, give each one a name (as in | |
9742 | @samp{BLOCK DATA FOO}) and make sure there is an @samp{EXTERNAL FOO} | |
9743 | statement in every program unit that uses any common block | |
9744 | initialized by the corresponding @code{BLOCK DATA}. | |
9745 | @code{g77} currently compiles a @code{BLOCK DATA} as if it were a | |
9746 | @code{SUBROUTINE}, | |
9747 | that is, it generates an actual procedure having the appropriate name. | |
9748 | The procedure does nothing but return immediately if it happens to be | |
9749 | called. | |
9750 | For @samp{EXTERNAL FOO}, where @samp{FOO} is not otherwise referenced in the | |
9751 | same program unit, @code{g77} assumes there exists a @samp{BLOCK DATA FOO} | |
9752 | in the program and ensures that by generating a | |
9753 | reference to it so the linker will make sure it is present. | |
9754 | (Specifically, @code{g77} outputs in the data section a static pointer to the | |
9755 | external name @samp{FOO}.) | |
9756 | ||
9757 | The implementation @code{g77} currently uses to make this work is | |
9758 | one of the few things not compatible with @code{f2c} as currently | |
9759 | shipped. | |
9760 | @code{f2c} currently does nothing with @samp{EXTERNAL FOO} except | |
95a1b676 CB |
9761 | issue a warning that @samp{FOO} is not otherwise referenced, |
9762 | and, for @samp{BLOCK DATA FOO}, | |
9763 | @code{f2c} doesn't generate a dummy procedure with the name @samp{FOO}. | |
5ff904cd JL |
9764 | The upshot is that you shouldn't mix @code{f2c} and @code{g77} in |
9765 | this particular case. | |
95a1b676 | 9766 | If you use @code{f2c} to compile @samp{BLOCK DATA FOO}, |
5ff904cd JL |
9767 | then any @code{g77}-compiled program unit that says @samp{EXTERNAL FOO} |
9768 | will result in an unresolved reference when linked. | |
9769 | If you do the | |
9770 | opposite, then @samp{FOO} might not be linked in under various | |
9771 | circumstances (such as when @samp{FOO} is in a library, or you're | |
9772 | using a ``clever'' linker---so clever, it produces a broken program | |
9773 | with little or no warning by omitting initializations of global data | |
9774 | because they are contained in unreferenced procedures). | |
9775 | ||
9776 | The changes you make to your code to make @code{g77} handle this situation, | |
9777 | however, appear to be a widely portable way to handle it. | |
9778 | That is, many systems permit it (as they should, since the | |
9779 | FORTRAN 77 standard permits @samp{EXTERNAL FOO} when @samp{FOO} | |
9780 | is a block data program unit), and of the ones | |
9781 | that might not link @samp{BLOCK DATA FOO} under some circumstances, most of | |
9782 | them appear to do so once @samp{EXTERNAL FOO} is present in the appropriate | |
9783 | program units. | |
9784 | ||
9785 | Here is the recommended approach to modifying a program containing | |
9786 | a program unit such as the following: | |
9787 | ||
9788 | @smallexample | |
9789 | BLOCK DATA FOO | |
9790 | COMMON /VARS/ X, Y, Z | |
9791 | DATA X, Y, Z / 3., 4., 5. / | |
9792 | END | |
9793 | @end smallexample | |
9794 | ||
9795 | @noindent | |
9796 | If the above program unit might be placed in a library module, then | |
9797 | ensure that every program unit in every program that references that | |
9798 | particular @code{COMMON} area uses the @code{EXTERNAL} statement | |
9799 | to force the area to be initialized. | |
9800 | ||
9801 | For example, change a program unit that starts with | |
9802 | ||
9803 | @smallexample | |
9804 | INTEGER FUNCTION CURX() | |
9805 | COMMON /VARS/ X, Y, Z | |
9806 | CURX = X | |
9807 | END | |
9808 | @end smallexample | |
9809 | ||
9810 | @noindent | |
9811 | so that it uses the @code{EXTERNAL} statement, as in: | |
9812 | ||
9813 | @smallexample | |
9814 | INTEGER FUNCTION CURX() | |
9815 | COMMON /VARS/ X, Y, Z | |
9816 | EXTERNAL FOO | |
9817 | CURX = X | |
9818 | END | |
9819 | @end smallexample | |
9820 | ||
9821 | @noindent | |
9822 | That way, @samp{CURX} is compiled by @code{g77} (and many other | |
9823 | compilers) so that the linker knows it must include @samp{FOO}, | |
9824 | the @code{BLOCK DATA} program unit that sets the initial values | |
9825 | for the variables in @samp{VAR}, in the executable program. | |
9826 | ||
9827 | @node Loops | |
9828 | @section Loops | |
9829 | @cindex DO statement | |
9830 | @cindex statements, DO | |
9831 | @cindex trips, number of | |
9832 | @cindex number of trips | |
9833 | ||
9834 | The meaning of a @code{DO} loop in Fortran is precisely specified | |
9835 | in the Fortran standard@dots{}and is quite different from what | |
9836 | many programmers might expect. | |
9837 | ||
26b9526e | 9838 | In particular, Fortran iterative @code{DO} loops are implemented as if |
5ff904cd JL |
9839 | the number of trips through the loop is calculated @emph{before} |
9840 | the loop is entered. | |
9841 | ||
9842 | The number of trips for a loop is calculated from the @var{start}, | |
9843 | @var{end}, and @var{increment} values specified in a statement such as: | |
9844 | ||
9845 | @smallexample | |
9846 | DO @var{iter} = @var{start}, @var{end}, @var{increment} | |
9847 | @end smallexample | |
9848 | ||
9849 | @noindent | |
9850 | The trip count is evaluated using a fairly simple formula | |
9851 | based on the three values following the @samp{=} in the | |
9852 | statement, and it is that trip count that is effectively | |
9853 | decremented during each iteration of the loop. | |
9854 | If, at the beginning of an iteration of the loop, the | |
9855 | trip count is zero or negative, the loop terminates. | |
9856 | The per-loop-iteration modifications to @var{iter} are not | |
9857 | related to determining whether to terminate the loop. | |
9858 | ||
9859 | There are two important things to remember about the trip | |
9860 | count: | |
9861 | ||
9862 | @itemize @bullet | |
9863 | @item | |
9864 | It can be @emph{negative}, in which case it is | |
9865 | treated as if it was zero---meaning the loop is | |
9866 | not executed at all. | |
9867 | ||
9868 | @item | |
9869 | The type used to @emph{calculate} the trip count | |
9870 | is the same type as @var{iter}, but the final | |
9871 | calculation, and thus the type of the trip | |
9872 | count itself, always is @code{INTEGER(KIND=1)}. | |
9873 | @end itemize | |
9874 | ||
9875 | These two items mean that there are loops that cannot | |
9876 | be written in straightforward fashion using the Fortran @code{DO}. | |
9877 | ||
9878 | For example, on a system with the canonical 32-bit two's-complement | |
9879 | implementation of @code{INTEGER(KIND=1)}, the following loop will not work: | |
9880 | ||
9881 | @smallexample | |
9882 | DO I = -2000000000, 2000000000 | |
9883 | @end smallexample | |
9884 | ||
9885 | @noindent | |
9886 | Although the @var{start} and @var{end} values are well within | |
9887 | the range of @code{INTEGER(KIND=1)}, the @emph{trip count} is not. | |
9888 | The expected trip count is 40000000001, which is outside | |
9889 | the range of @code{INTEGER(KIND=1)} on many systems. | |
9890 | ||
9891 | Instead, the above loop should be constructed this way: | |
9892 | ||
9893 | @smallexample | |
9894 | I = -2000000000 | |
9895 | DO | |
9896 | IF (I .GT. 2000000000) EXIT | |
9897 | @dots{} | |
9898 | I = I + 1 | |
9899 | END DO | |
9900 | @end smallexample | |
9901 | ||
9902 | @noindent | |
9903 | The simple @code{DO} construct and the @code{EXIT} statement | |
9904 | (used to leave the innermost loop) | |
9905 | are F90 features that @code{g77} supports. | |
9906 | ||
9907 | Some Fortran compilers have buggy implementations of @code{DO}, | |
9908 | in that they don't follow the standard. | |
9909 | They implement @code{DO} as a straightforward translation | |
9910 | to what, in C, would be a @code{for} statement. | |
9911 | Instead of creating a temporary variable to hold the trip count | |
9912 | as calculated at run time, these compilers | |
9913 | use the iteration variable @var{iter} to control | |
9914 | whether the loop continues at each iteration. | |
9915 | ||
9916 | The bug in such an implementation shows up when the | |
9917 | trip count is within the range of the type of @var{iter}, | |
9918 | but the magnitude of @samp{ABS(@var{end}) + ABS(@var{incr})} | |
9919 | exceeds that range. For example: | |
9920 | ||
9921 | @smallexample | |
9922 | DO I = 2147483600, 2147483647 | |
9923 | @end smallexample | |
9924 | ||
9925 | @noindent | |
9926 | A loop started by the above statement will work as implemented | |
9927 | by @code{g77}, but the use, by some compilers, of a | |
9928 | more C-like implementation akin to | |
9929 | ||
9930 | @smallexample | |
9931 | for (i = 2147483600; i <= 2147483647; ++i) | |
9932 | @end smallexample | |
9933 | ||
9934 | @noindent | |
9935 | produces a loop that does not terminate, because @samp{i} | |
9936 | can never be greater than 2147483647, since incrementing it | |
9937 | beyond that value overflows @samp{i}, setting it to -2147483648. | |
9938 | This is a large, negative number that still is less than 2147483647. | |
9939 | ||
9940 | Another example of unexpected behavior of @code{DO} involves | |
9941 | using a nonintegral iteration variable @var{iter}, that is, | |
9942 | a @code{REAL} variable. | |
9943 | Consider the following program: | |
9944 | ||
9945 | @smallexample | |
9946 | DATA BEGIN, END, STEP /.1, .31, .007/ | |
9947 | DO 10 R = BEGIN, END, STEP | |
9948 | IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!' | |
9949 | PRINT *,R | |
9950 | 10 CONTINUE | |
9951 | PRINT *,'LAST = ',R | |
9952 | IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!' | |
9953 | END | |
9954 | @end smallexample | |
9955 | ||
9956 | @noindent | |
9957 | A C-like view of @code{DO} would hold that the two ``exclamatory'' | |
9958 | @code{PRINT} statements are never executed. | |
9959 | However, this is the output of running the above program | |
9960 | as compiled by @code{g77} on a GNU/Linux ix86 system: | |
9961 | ||
9962 | @smallexample | |
9963 | .100000001 | |
9964 | .107000001 | |
9965 | .114 | |
9966 | .120999999 | |
9967 | @dots{} | |
9968 | .289000005 | |
9969 | .296000004 | |
9970 | .303000003 | |
9971 | LAST = .310000002 | |
9972 | .310000002 .LE. .310000002!! | |
9973 | @end smallexample | |
9974 | ||
9975 | Note that one of the two checks in the program turned up | |
9976 | an apparent violation of the programmer's expectation---yet, | |
9977 | the loop is correctly implemented by @code{g77}, in that | |
9978 | it has 30 iterations. | |
9979 | This trip count of 30 is correct when evaluated using | |
9980 | the floating-point representations for the @var{begin}, | |
9981 | @var{end}, and @var{incr} values (.1, .31, .007) on GNU/Linux | |
9982 | ix86 are used. | |
9983 | On other systems, an apparently more accurate trip count | |
9984 | of 31 might result, but, nevertheless, @code{g77} is | |
9985 | faithfully following the Fortran standard, and the result | |
9986 | is not what the author of the sample program above | |
9987 | apparently expected. | |
9988 | (Such other systems might, for different values in the @code{DATA} | |
9989 | statement, violate the other programmer's expectation, | |
9990 | for example.) | |
9991 | ||
9992 | Due to this combination of imprecise representation | |
9993 | of floating-point values and the often-misunderstood | |
9994 | interpretation of @code{DO} by standard-conforming | |
9995 | compilers such as @code{g77}, use of @code{DO} loops | |
9996 | with @code{REAL} iteration | |
9997 | variables is not recommended. | |
9998 | Such use can be caught by specifying @samp{-Wsurprising}. | |
9999 | @xref{Warning Options}, for more information on this | |
10000 | option. | |
10001 | ||
10002 | @node Working Programs | |
10003 | @section Working Programs | |
10004 | ||
10005 | Getting Fortran programs to work in the first place can be | |
10006 | quite a challenge---even when the programs already work on | |
10007 | other systems, or when using other compilers. | |
10008 | ||
10009 | @code{g77} offers some facilities that might be useful for | |
10010 | tracking down bugs in such programs. | |
10011 | ||
10012 | @menu | |
10013 | * Not My Type:: | |
10014 | * Variables Assumed To Be Zero:: | |
10015 | * Variables Assumed To Be Saved:: | |
10016 | * Unwanted Variables:: | |
10017 | * Unused Arguments:: | |
10018 | * Surprising Interpretations of Code:: | |
10019 | * Aliasing Assumed To Work:: | |
10020 | * Output Assumed To Flush:: | |
10021 | * Large File Unit Numbers:: | |
26b9526e | 10022 | * Floating-point precision:: |
0b31330e | 10023 | * Inconsistent Calling Sequences:: |
5ff904cd JL |
10024 | @end menu |
10025 | ||
10026 | @node Not My Type | |
10027 | @subsection Not My Type | |
10028 | @cindex mistyped variables | |
10029 | @cindex variables, mistyped | |
10030 | @cindex mistyped functions | |
10031 | @cindex functions, mistyped | |
10032 | @cindex implicit typing | |
10033 | ||
10034 | A fruitful source of bugs in Fortran source code is use, or | |
10035 | mis-use, of Fortran's implicit-typing feature, whereby the | |
10036 | type of a variable, array, or function is determined by the | |
10037 | first character of its name. | |
10038 | ||
10039 | Simple cases of this include statements like @samp{LOGX=9.227}, | |
10040 | without a statement such as @samp{REAL LOGX}. | |
10041 | In this case, @samp{LOGX} is implicitly given @code{INTEGER(KIND=1)} | |
10042 | type, with the result of the assignment being that it is given | |
10043 | the value @samp{9}. | |
10044 | ||
10045 | More involved cases include a function that is defined starting | |
10046 | with a statement like @samp{DOUBLE PRECISION FUNCTION IPS(@dots{})}. | |
10047 | Any caller of this function that does not also declare @samp{IPS} | |
10048 | as type @code{DOUBLE PRECISION} (or, in GNU Fortran, @code{REAL(KIND=2)}) | |
10049 | is likely to assume it returns | |
10050 | @code{INTEGER}, or some other type, leading to invalid results | |
10051 | or even program crashes. | |
10052 | ||
10053 | The @samp{-Wimplicit} option might catch failures to | |
10054 | properly specify the types of | |
10055 | variables, arrays, and functions in the code. | |
10056 | ||
10057 | However, in code that makes heavy use of Fortran's | |
10058 | implicit-typing facility, this option might produce so | |
10059 | many warnings about cases that are working, it would be | |
10060 | hard to find the one or two that represent bugs. | |
10061 | This is why so many experienced Fortran programmers strongly | |
10062 | recommend widespread use of the @code{IMPLICIT NONE} statement, | |
10063 | despite it not being standard FORTRAN 77, to completely turn | |
10064 | off implicit typing. | |
10065 | (@code{g77} supports @code{IMPLICIT NONE}, as do almost all | |
10066 | FORTRAN 77 compilers.) | |
10067 | ||
10068 | Note that @samp{-Wimplicit} catches only implicit typing of | |
10069 | @emph{names}. | |
10070 | It does not catch implicit typing of expressions such | |
10071 | as @samp{X**(2/3)}. | |
10072 | Such expressions can be buggy as well---in fact, @samp{X**(2/3)} | |
10073 | is equivalent to @samp{X**0}, due to the way Fortran expressions | |
10074 | are given types and then evaluated. | |
10075 | (In this particular case, the programmer probably wanted | |
10076 | @samp{X**(2./3.)}.) | |
10077 | ||
10078 | @node Variables Assumed To Be Zero | |
10079 | @subsection Variables Assumed To Be Zero | |
10080 | @cindex zero-initialized variables | |
26b9526e | 10081 | @cindex variables, assumed to be zero |
5ff904cd JL |
10082 | @cindex uninitialized variables |
10083 | ||
10084 | Many Fortran programs were developed on systems that provided | |
10085 | automatic initialization of all, or some, variables and arrays | |
10086 | to zero. | |
10087 | As a result, many of these programs depend, sometimes | |
10088 | inadvertently, on this behavior, though to do so violates | |
10089 | the Fortran standards. | |
10090 | ||
10091 | You can ask @code{g77} for this behavior by specifying the | |
10092 | @samp{-finit-local-zero} option when compiling Fortran code. | |
10093 | (You might want to specify @samp{-fno-automatic} as well, | |
10094 | to avoid code-size inflation for non-optimized compilations.) | |
10095 | ||
10096 | Note that a program that works better when compiled with the | |
10097 | @samp{-finit-local-zero} option | |
10098 | is almost certainly depending on a particular system's, | |
10099 | or compiler's, tendency to initialize some variables to zero. | |
10100 | It might be worthwhile finding such cases and fixing them, | |
10101 | using techniques such as compiling with the @samp{-O -Wuninitialized} | |
10102 | options using @code{g77}. | |
10103 | ||
10104 | @node Variables Assumed To Be Saved | |
10105 | @subsection Variables Assumed To Be Saved | |
26b9526e | 10106 | @cindex variables, retaining values across calls |
5ff904cd JL |
10107 | @cindex saved variables |
10108 | @cindex static variables | |
10109 | ||
10110 | Many Fortran programs were developed on systems that | |
10111 | saved the values of all, or some, variables and arrays | |
10112 | across procedure calls. | |
10113 | As a result, many of these programs depend, sometimes | |
10114 | inadvertently, on being able to assign a value to a | |
10115 | variable, perform a @code{RETURN} to a calling procedure, | |
10116 | and, upon subsequent invocation, reference the previously | |
10117 | assigned variable to obtain the value. | |
10118 | ||
10119 | They expect this despite not using the @code{SAVE} statement | |
10120 | to specify that the value in a variable is expected to survive | |
10121 | procedure returns and calls. | |
10122 | Depending on variables and arrays to retain values across | |
10123 | procedure calls without using @code{SAVE} to require it violates | |
10124 | the Fortran standards. | |
10125 | ||
10126 | You can ask @code{g77} to assume @code{SAVE} is specified for all | |
10127 | relevant (local) variables and arrays by using the | |
10128 | @samp{-fno-automatic} option. | |
10129 | ||
10130 | Note that a program that works better when compiled with the | |
10131 | @samp{-fno-automatic} option | |
10132 | is almost certainly depending on not having to use | |
10133 | the @code{SAVE} statement as required by the Fortran standard. | |
10134 | It might be worthwhile finding such cases and fixing them, | |
10135 | using techniques such as compiling with the @samp{-O -Wuninitialized} | |
10136 | options using @code{g77}. | |
10137 | ||
10138 | @node Unwanted Variables | |
10139 | @subsection Unwanted Variables | |
10140 | ||
10141 | The @samp{-Wunused} option can find bugs involving | |
10142 | implicit typing, sometimes | |
10143 | more easily than using @samp{-Wimplicit} in code that makes | |
10144 | heavy use of implicit typing. | |
10145 | An unused variable or array might indicate that the | |
10146 | spelling for its declaration is different from that of | |
10147 | its intended uses. | |
10148 | ||
10149 | Other than cases involving typos, unused variables rarely | |
10150 | indicate actual bugs in a program. | |
10151 | However, investigating such cases thoroughly has, on occasion, | |
10152 | led to the discovery of code that had not been completely | |
10153 | written---where the programmer wrote declarations as needed | |
10154 | for the whole algorithm, wrote some or even most of the code | |
10155 | for that algorithm, then got distracted and forgot that the | |
10156 | job was not complete. | |
10157 | ||
10158 | @node Unused Arguments | |
10159 | @subsection Unused Arguments | |
10160 | @cindex unused arguments | |
10161 | @cindex arguments, unused | |
10162 | ||
10163 | As with unused variables, It is possible that unused arguments | |
10164 | to a procedure might indicate a bug. | |
10165 | Compile with @samp{-W -Wunused} option to catch cases of | |
10166 | unused arguments. | |
10167 | ||
10168 | Note that @samp{-W} also enables warnings regarding overflow | |
10169 | of floating-point constants under certain circumstances. | |
10170 | ||
10171 | @node Surprising Interpretations of Code | |
10172 | @subsection Surprising Interpretations of Code | |
10173 | ||
46511dd5 | 10174 | The @samp{-Wsurprising} option can help find bugs involving |
5ff904cd JL |
10175 | expression evaluation or in |
10176 | the way @code{DO} loops with non-integral iteration variables | |
10177 | are handled. | |
10178 | Cases found by this option might indicate a difference of | |
10179 | interpretation between the author of the code involved, and | |
10180 | a standard-conforming compiler such as @code{g77}. | |
10181 | Such a difference might produce actual bugs. | |
10182 | ||
10183 | In any case, changing the code to explicitly do what the | |
10184 | programmer might have expected it to do, so @code{g77} and | |
10185 | other compilers are more likely to follow the programmer's | |
10186 | expectations, might be worthwhile, especially if such changes | |
10187 | make the program work better. | |
10188 | ||
10189 | @node Aliasing Assumed To Work | |
10190 | @subsection Aliasing Assumed To Work | |
10191 | @cindex -falias-check option | |
10192 | @cindex options, -falias-check | |
10193 | @cindex -fargument-alias option | |
10194 | @cindex options, -fargument-alias | |
10195 | @cindex -fargument-noalias option | |
10196 | @cindex options, -fargument-noalias | |
10197 | @cindex -fno-argument-noalias-global option | |
10198 | @cindex options, -fno-argument-noalias-global | |
10199 | @cindex aliasing | |
10200 | @cindex anti-aliasing | |
10201 | @cindex overlapping arguments | |
10202 | @cindex overlays | |
10203 | @cindex association, storage | |
10204 | @cindex storage association | |
10205 | @cindex scheduling of reads and writes | |
10206 | @cindex reads and writes, scheduling | |
10207 | ||
10208 | The @samp{-falias-check}, @samp{-fargument-alias}, | |
10209 | @samp{-fargument-noalias}, | |
10210 | and @samp{-fno-argument-noalias-global} options, | |
10211 | introduced in version 0.5.20 and | |
10212 | @code{g77}'s version 2.7.2.2.f.2 of @code{gcc}, | |
95a1b676 CB |
10213 | were withdrawn as of @code{g77} version 0.5.23 |
10214 | due to their not being supported by @code{gcc} version 2.8. | |
5ff904cd | 10215 | |
95a1b676 CB |
10216 | These options, which control the assumptions regarding aliasing |
10217 | (overlapping) of writes and reads to main memory (core) made | |
10218 | by the @code{gcc} back end, | |
10219 | might well be added back (in some form) in a future version | |
10220 | of @code{gcc}. | |
10221 | ||
10222 | However, these options @emph{are} supported by @code{egcs}. | |
10223 | ||
10224 | The information below still is useful, but applies to | |
10225 | only those versions of @code{g77} that support the | |
10226 | alias analysis implied by support for these options. | |
10227 | ||
10228 | These options are effective only when compiling with @samp{-O} | |
10229 | (specifying any level other than @samp{-O0}) | |
10230 | or with @samp{-falias-check}. | |
5ff904cd JL |
10231 | |
10232 | The default for Fortran code is @samp{-fargument-noalias-global}. | |
10233 | (The default for C code and code written in other C-based languages | |
10234 | is @samp{-fargument-alias}. | |
10235 | These defaults apply regardless of whether you use @code{g77} or | |
10236 | @code{gcc} to compile your code.) | |
10237 | ||
10238 | Note that, on some systems, compiling with @samp{-fforce-addr} in | |
10239 | effect can produce more optimal code when the default aliasing | |
10240 | options are in effect (and when optimization is enabled). | |
10241 | ||
10242 | If your program is not working when compiled with optimization, | |
10243 | it is possible it is violating the Fortran standards (77 and 90) | |
10244 | by relying on the ability to ``safely'' modify variables and | |
10245 | arrays that are aliased, via procedure calls, to other variables | |
10246 | and arrays, without using @code{EQUIVALENCE} to explicitly | |
10247 | set up this kind of aliasing. | |
10248 | ||
10249 | (The FORTRAN 77 standard's prohibition of this sort of | |
10250 | overlap, generally referred to therein as ``storage | |
10251 | assocation'', appears in Sections 15.9.3.6. | |
10252 | This prohibition allows implementations, such as @code{g77}, | |
10253 | to, for example, implement the passing of procedures and | |
10254 | even values in @code{COMMON} via copy operations into local, | |
10255 | perhaps more efficiently accessed temporaries at entry to a | |
10256 | procedure, and, where appropriate, via copy operations back | |
10257 | out to their original locations in memory at exit from that | |
10258 | procedure, without having to take into consideration the | |
10259 | order in which the local copies are updated by the code, | |
10260 | among other things.) | |
10261 | ||
10262 | To test this hypothesis, try compiling your program with | |
10263 | the @samp{-fargument-alias} option, which causes the | |
10264 | compiler to revert to assumptions essentially the same as | |
10265 | made by versions of @code{g77} prior to 0.5.20. | |
10266 | ||
10267 | If the program works using this option, that strongly suggests | |
10268 | that the bug is in your program. | |
10269 | Finding and fixing the bug(s) should result in a program that | |
10270 | is more standard-conforming and that can be compiled by @code{g77} | |
10271 | in a way that results in a faster executable. | |
10272 | ||
10273 | (You might want to try compiling with @samp{-fargument-noalias}, | |
10274 | a kind of half-way point, to see if the problem is limited to | |
10275 | aliasing between dummy arguments and @code{COMMON} variables---this | |
10276 | option assumes that such aliasing is not done, while still allowing | |
10277 | aliasing among dummy arguments.) | |
10278 | ||
10279 | An example of aliasing that is invalid according to the standards | |
10280 | is shown in the following program, which might @emph{not} produce | |
10281 | the expected results when executed: | |
10282 | ||
10283 | @smallexample | |
10284 | I = 1 | |
10285 | CALL FOO(I, I) | |
10286 | PRINT *, I | |
10287 | END | |
10288 | ||
10289 | SUBROUTINE FOO(J, K) | |
10290 | J = J + K | |
10291 | K = J * K | |
10292 | PRINT *, J, K | |
10293 | END | |
10294 | @end smallexample | |
10295 | ||
10296 | The above program attempts to use the temporary aliasing of the | |
10297 | @samp{J} and @samp{K} arguments in @samp{FOO} to effect a | |
10298 | pathological behavior---the simultaneous changing of the values | |
10299 | of @emph{both} @samp{J} and @samp{K} when either one of them | |
10300 | is written. | |
10301 | ||
10302 | The programmer likely expects the program to print these values: | |
10303 | ||
10304 | @example | |
10305 | 2 4 | |
10306 | 4 | |
10307 | @end example | |
10308 | ||
10309 | However, since the program is not standard-conforming, an | |
10310 | implementation's behavior when running it is undefined, because | |
10311 | subroutine @samp{FOO} modifies at least one of the arguments, | |
10312 | and they are aliased with each other. | |
10313 | (Even if one of the assignment statements was deleted, the | |
10314 | program would still violate these rules. | |
10315 | This kind of on-the-fly aliasing is permitted by the standard | |
10316 | only when none of the aliased items are defined, or written, | |
10317 | while the aliasing is in effect.) | |
10318 | ||
10319 | As a practical example, an optimizing compiler might schedule | |
10320 | the @samp{J =} part of the second line of @samp{FOO} @emph{after} | |
10321 | the reading of @samp{J} and @samp{K} for the @samp{J * K} expression, | |
10322 | resulting in the following output: | |
10323 | ||
10324 | @example | |
10325 | 2 2 | |
10326 | 2 | |
10327 | @end example | |
10328 | ||
10329 | Essentially, compilers are promised (by the standard and, therefore, | |
10330 | by programmers who write code they claim to be standard-conforming) | |
10331 | that if they cannot detect aliasing via static analysis of a single | |
10332 | program unit's @code{EQUIVALENCE} and @code{COMMON} statements, no | |
10333 | such aliasing exists. | |
10334 | In such cases, compilers are free to assume that an assignment to | |
10335 | one variable will not change the value of another variable, allowing | |
10336 | it to avoid generating code to re-read the value of the other | |
10337 | variable, to re-schedule reads and writes, and so on, to produce | |
10338 | a faster executable. | |
10339 | ||
10340 | The same promise holds true for arrays (as seen by the called | |
10341 | procedure)---an element of one dummy array cannot be aliased | |
10342 | with, or overlap, any element of another dummy array or be | |
10343 | in a @code{COMMON} area known to the procedure. | |
10344 | ||
10345 | (These restrictions apply only when the procedure defines, or | |
10346 | writes to, one of the aliased variables or arrays.) | |
10347 | ||
10348 | Unfortunately, there is no way to find @emph{all} possible cases of | |
10349 | violations of the prohibitions against aliasing in Fortran code. | |
10350 | Static analysis is certainly imperfect, as is run-time analysis, | |
10351 | since neither can catch all violations. | |
10352 | (Static analysis can catch all likely violations, and some that | |
10353 | might never actually happen, while run-time analysis can catch | |
95a1b676 | 10354 | only those violations that actually happen during a particular run. |
5ff904cd JL |
10355 | Neither approach can cope with programs mixing Fortran code with |
10356 | routines written in other languages, however.) | |
10357 | ||
10358 | Currently, @code{g77} provides neither static nor run-time facilities | |
10359 | to detect any cases of this problem, although other products might. | |
10360 | Run-time facilities are more likely to be offered by future | |
10361 | versions of @code{g77}, though patches improving @code{g77} so that | |
10362 | it provides either form of detection are welcome. | |
10363 | ||
10364 | @node Output Assumed To Flush | |
10365 | @subsection Output Assumed To Flush | |
10366 | @cindex ALWAYS_FLUSH | |
10367 | @cindex synchronous write errors | |
10368 | @cindex disk full | |
10369 | @cindex flushing output | |
10370 | @cindex fflush() | |
10371 | @cindex I/O, flushing | |
10372 | @cindex output, flushing | |
10373 | @cindex writes, flushing | |
10374 | @cindex NFS | |
10375 | @cindex network file system | |
10376 | ||
10377 | For several versions prior to 0.5.20, @code{g77} configured its | |
10378 | version of the @code{libf2c} run-time library so that one of | |
4e6a1440 | 10379 | its configuration macros, @code{ALWAYS_FLUSH}, was defined. |
5ff904cd JL |
10380 | |
10381 | This was done as a result of a belief that many programs expected | |
10382 | output to be flushed to the operating system (under UNIX, via | |
10383 | the @code{fflush()} library call) with the result that errors, | |
10384 | such as disk full, would be immediately flagged via the | |
10385 | relevant @code{ERR=} and @code{IOSTAT=} mechanism. | |
10386 | ||
10387 | Because of the adverse effects this approach had on the performance | |
10388 | of many programs, @code{g77} no longer configures @code{libf2c} | |
95a1b676 | 10389 | (now named @code{libg2c} in its @code{g77} incarnation) |
5ff904cd JL |
10390 | to always flush output. |
10391 | ||
10392 | If your program depends on this behavior, either insert the | |
10393 | appropriate @samp{CALL FLUSH} statements, or modify the sources | |
95a1b676 | 10394 | to the @code{libg2c}, rebuild and reinstall @code{g77}, and |
5ff904cd JL |
10395 | relink your programs with the modified library. |
10396 | ||
95a1b676 | 10397 | (Ideally, @code{libg2c} would offer the choice at run-time, so |
5ff904cd JL |
10398 | that a compile-time option to @code{g77} or @code{f2c} could |
10399 | result in generating the appropriate calls to flushing or | |
10400 | non-flushing library routines.) | |
10401 | ||
10402 | @xref{Always Flush Output}, for information on how to modify | |
95a1b676 | 10403 | the @code{g77} source tree so that a version of @code{libg2c} |
4e6a1440 | 10404 | can be built and installed with the @code{ALWAYS_FLUSH} macro defined. |
5ff904cd JL |
10405 | |
10406 | @node Large File Unit Numbers | |
10407 | @subsection Large File Unit Numbers | |
10408 | @cindex MXUNIT | |
10409 | @cindex unit numbers | |
10410 | @cindex maximum unit number | |
10411 | @cindex illegal unit number | |
10412 | @cindex increasing maximum unit number | |
10413 | ||
10414 | If your program crashes at run time with a message including | |
10415 | the text @samp{illegal unit number}, that probably is | |
95a1b676 | 10416 | a message from the run-time library, @code{libg2c}. |
5ff904cd JL |
10417 | |
10418 | The message means that your program has attempted to use a | |
10419 | file unit number that is out of the range accepted by | |
95a1b676 | 10420 | @code{libg2c}. |
5ff904cd | 10421 | Normally, this range is 0 through 99, and the high end |
95a1b676 | 10422 | of the range is controlled by a @code{libg2c} source-file |
4e6a1440 | 10423 | macro named @code{MXUNIT}. |
5ff904cd JL |
10424 | |
10425 | If you can easily change your program to use unit numbers | |
10426 | in the range 0 through 99, you should do so. | |
10427 | ||
10428 | Otherwise, see @ref{Larger File Unit Numbers}, for information on how | |
4e6a1440 | 10429 | to change @code{MXUNIT} in @code{libg2c} so you can build and |
95a1b676 | 10430 | install a new version of @code{libg2c} that supports the larger |
5ff904cd JL |
10431 | unit numbers you need. |
10432 | ||
95a1b676 | 10433 | @emph{Note:} While @code{libg2c} places a limit on the range |
5ff904cd JL |
10434 | of Fortran file-unit numbers, the underlying library and operating |
10435 | system might impose different kinds of limits. | |
10436 | For example, some systems limit the number of files simultaneously | |
10437 | open by a running program. | |
10438 | Information on how to increase these limits should be found | |
10439 | in your system's documentation. | |
10440 | ||
26b9526e CB |
10441 | @node Floating-point precision |
10442 | @subsection Floating-point precision | |
0b31330e | 10443 | |
26b9526e CB |
10444 | @cindex IEEE 754 conformance |
10445 | @cindex conformance, IEEE 754 | |
10446 | @cindex floating-point, precision | |
10447 | @cindex ix86 floating-point | |
10448 | @cindex x86 floating-point | |
10449 | If your program depends on exact IEEE 754 floating-point handling it may | |
0b31330e | 10450 | help on some systems---specifically x86 or m68k hardware---to use |
4e6a1440 | 10451 | the @samp{-ffloat-store} option or to reset the precision flag on the |
26b9526e | 10452 | floating-point unit @xref{Optimize Options}. |
0b31330e DL |
10453 | |
10454 | However, it might be better simply to put the FPU into double precision | |
4e6a1440 | 10455 | mode and not take the performance hit of @samp{-ffloat-store}. On x86 |
0b31330e | 10456 | and m68k GNU systems you can do this with a technique similar to that |
26b9526e | 10457 | for turning on floating-point exceptions @xref{Floating-point Exception |
0b31330e DL |
10458 | Handling}. The control word could be set to double precision by |
10459 | replacing the @code{__setfpucw} call with one like this: | |
10460 | @smallexample | |
10461 | __setfpucw ((_FPU_DEFAULT & ~_FPU_EXTENDED) | _FPU_DOUBLE); | |
10462 | @end smallexample | |
10463 | (It is not clear whether this has any effect on the operation of the GNU | |
10464 | maths library, but we have no evidence of it causing trouble.) | |
10465 | ||
10466 | Some targets (such as the Alpha) may need special options for full IEEE | |
10467 | conformance @xref{Submodel Options,,Hardware Models and | |
10468 | Configurations,gcc,Using and Porting GNU CC}. | |
10469 | ||
10470 | @node Inconsistent Calling Sequences | |
10471 | @subsection Inconsistent Calling Sequences | |
10472 | ||
10473 | @pindex ftnchek | |
26b9526e CB |
10474 | @cindex floating-point, errors |
10475 | @cindex ix86 FPU stack | |
0b31330e DL |
10476 | @cindex x86 FPU stack |
10477 | Code containing inconsistent calling sequences in the same file is | |
10478 | normally rejected @xref{GLOBALS}. (Use, say, @code{ftnchek} to ensure | |
66d18ad7 | 10479 | consistency across source files |
0b31330e DL |
10480 | @c makeinfo 1.68 objects to the nested parens |
10481 | @ifinfo | |
10482 | @xref{f2c Skeletons and Prototypes}.) | |
10483 | @end ifinfo | |
10484 | @ifnotinfo | |
10485 | @xref{f2c Skeletons and Prototypes,, | |
10486 | {Generating Skeletons and Prototypes with @code{f2c}}}.) | |
10487 | @end ifnotinfo | |
10488 | ||
10489 | Mysterious errors, which may appear to be code generation problems, can | |
10490 | appear specifically on the x86 architecture with some such | |
26b9526e CB |
10491 | inconsistencies. On x86 hardware, floating-point return values of |
10492 | functions are placed on the floating-point unit's register stack, not | |
0b31330e DL |
10493 | the normal stack. Thus calling a @code{REAL} or @code{DOUBLE PRECISION} |
10494 | @code{FUNCTION} as some other sort of procedure, or vice versa, | |
26b9526e | 10495 | scrambles the floating-point stack. This may break unrelated code |
0b31330e DL |
10496 | executed later. Similarly if, say, external C routines are written |
10497 | incorrectly. | |
10498 | ||
5ff904cd JL |
10499 | @node Overly Convenient Options |
10500 | @section Overly Convenient Command-line Options | |
10501 | @cindex overly convenient options | |
10502 | @cindex options, overly convenient | |
10503 | ||
10504 | These options should be used only as a quick-and-dirty way to determine | |
10505 | how well your program will run under different compilation models | |
10506 | without having to change the source. | |
10507 | Some are more problematic | |
10508 | than others, depending on how portable and maintainable you want the | |
10509 | program to be (and, of course, whether you are allowed to change it | |
10510 | at all is crucial). | |
10511 | ||
10512 | You should not continue to use these command-line options to compile | |
10513 | a given program, but rather should make changes to the source code: | |
10514 | ||
10515 | @table @code | |
10516 | @cindex -finit-local-zero option | |
10517 | @cindex options, -finit-local-zero | |
10518 | @item -finit-local-zero | |
10519 | (This option specifies that any uninitialized local variables | |
10520 | and arrays have default initialization to binary zeros.) | |
10521 | ||
10522 | Many other compilers do this automatically, which means lots of | |
10523 | Fortran code developed with those compilers depends on it. | |
10524 | ||
10525 | It is safer (and probably | |
10526 | would produce a faster program) to find the variables and arrays that | |
10527 | need such initialization and provide it explicitly via @code{DATA}, so that | |
10528 | @samp{-finit-local-zero} is not needed. | |
10529 | ||
10530 | Consider using @samp{-Wuninitialized} (which requires @samp{-O}) to | |
10531 | find likely candidates, but | |
10532 | do not specify @samp{-finit-local-zero} or @samp{-fno-automatic}, | |
10533 | or this technique won't work. | |
10534 | ||
10535 | @cindex -fno-automatic option | |
10536 | @cindex options, -fno-automatic | |
10537 | @item -fno-automatic | |
10538 | (This option specifies that all local variables and arrays | |
10539 | are to be treated as if they were named in @code{SAVE} statements.) | |
10540 | ||
10541 | Many other compilers do this automatically, which means lots of | |
10542 | Fortran code developed with those compilers depends on it. | |
10543 | ||
10544 | The effect of this is that all non-automatic variables and arrays | |
10545 | are made static, that is, not placed on the stack or in heap storage. | |
10546 | This might cause a buggy program to appear to work better. | |
10547 | If so, rather than relying on this command-line option (and hoping all | |
10548 | compilers provide the equivalent one), add @code{SAVE} | |
10549 | statements to some or all program unit sources, as appropriate. | |
10550 | Consider using @samp{-Wuninitialized} (which requires @samp{-O}) | |
10551 | to find likely candidates, but | |
10552 | do not specify @samp{-finit-local-zero} or @samp{-fno-automatic}, | |
10553 | or this technique won't work. | |
10554 | ||
10555 | The default is @samp{-fautomatic}, which tells @code{g77} to try | |
10556 | and put variables and arrays on the stack (or in fast registers) | |
10557 | where possible and reasonable. | |
10558 | This tends to make programs faster. | |
10559 | ||
10560 | @cindex automatic arrays | |
10561 | @cindex arrays, automatic | |
10562 | @emph{Note:} Automatic variables and arrays are not affected | |
10563 | by this option. | |
10564 | These are variables and arrays that are @emph{necessarily} automatic, | |
10565 | either due to explicit statements, or due to the way they are | |
10566 | declared. | |
10567 | Examples include local variables and arrays not given the | |
10568 | @code{SAVE} attribute in procedures declared @code{RECURSIVE}, | |
10569 | and local arrays declared with non-constant bounds (automatic | |
10570 | arrays). | |
10571 | Currently, @code{g77} supports only automatic arrays, not | |
10572 | @code{RECURSIVE} procedures or other means of explicitly | |
10573 | specifying that variables or arrays are automatic. | |
10574 | ||
5ff904cd JL |
10575 | @cindex -f@var{group}-intrinsics-hide option |
10576 | @cindex options, -f@var{group}-intrinsics-hide | |
10577 | @item -f@var{group}-intrinsics-hide | |
10578 | Change the source code to use @code{EXTERNAL} for any external procedure | |
10579 | that might be the name of an intrinsic. | |
10580 | It is easy to find these using @samp{-f@var{group}-intrinsics-disable}. | |
10581 | @end table | |
10582 | ||
10583 | @node Faster Programs | |
10584 | @section Faster Programs | |
26b9526e | 10585 | @cindex speed, of programs |
5ff904cd JL |
10586 | @cindex programs, speeding up |
10587 | ||
10588 | Aside from the usual @code{gcc} options, such as @samp{-O}, | |
10589 | @samp{-ffast-math}, and so on, consider trying some of the | |
10590 | following approaches to speed up your program (once you get | |
10591 | it working). | |
10592 | ||
10593 | @menu | |
10594 | * Aligned Data:: | |
10595 | * Prefer Automatic Uninitialized Variables:: | |
10596 | * Avoid f2c Compatibility:: | |
10597 | * Use Submodel Options:: | |
10598 | @end menu | |
10599 | ||
10600 | @node Aligned Data | |
10601 | @subsection Aligned Data | |
7cceca32 | 10602 | @cindex alignment |
5ff904cd JL |
10603 | @cindex data, aligned |
10604 | @cindex stack, aligned | |
10605 | @cindex aligned data | |
10606 | @cindex aligned stack | |
10607 | @cindex Pentium optimizations | |
26b9526e | 10608 | @cindex optimization, for Pentium |
5ff904cd JL |
10609 | |
10610 | On some systems, such as those with Pentium Pro CPUs, programs | |
10611 | that make heavy use of @code{REAL(KIND=2)} (@code{DOUBLE PRECISION}) | |
10612 | might run much slower | |
10613 | than possible due to the compiler not aligning these 64-bit | |
10614 | values to 64-bit boundaries in memory. | |
10615 | (The effect also is present, though | |
10616 | to a lesser extent, on the 586 (Pentium) architecture.) | |
10617 | ||
10618 | The Intel x86 architecture generally ensures that these programs will | |
10619 | work on all its implementations, | |
10620 | but particular implementations (such as Pentium Pro) | |
10621 | perform better with more strict alignment. | |
795232f7 JL |
10622 | (Such behavior isn't unique to the Intel x86 architecture.) |
10623 | Other architectures might @emph{demand} 64-bit alignment | |
10624 | of 64-bit data. | |
5ff904cd | 10625 | |
795232f7 | 10626 | There are a variety of approaches to use to address this problem: |
5ff904cd JL |
10627 | |
10628 | @itemize @bullet | |
10629 | @item | |
26b9526e CB |
10630 | @cindex @code{COMMON} layout |
10631 | @cindex layout of @code{COMMON} blocks | |
5ff904cd JL |
10632 | Order your @code{COMMON} and @code{EQUIVALENCE} areas such |
10633 | that the variables and arrays with the widest alignment | |
10634 | guidelines come first. | |
10635 | ||
10636 | For example, on most systems, this would mean placing | |
10637 | @code{COMPLEX(KIND=2)}, @code{REAL(KIND=2)}, and | |
10638 | @code{INTEGER(KIND=2)} entities first, followed by @code{REAL(KIND=1)}, | |
10639 | @code{INTEGER(KIND=1)}, and @code{LOGICAL(KIND=1)} entities, then | |
10640 | @code{INTEGER(KIND=6)} entities, and finally @code{CHARACTER} | |
10641 | and @code{INTEGER(KIND=3)} entities. | |
10642 | ||
10643 | The reason to use such placement is it makes it more likely | |
10644 | that your data will be aligned properly, without requiring | |
10645 | you to do detailed analysis of each aggregate (@code{COMMON} | |
10646 | and @code{EQUIVALENCE}) area. | |
10647 | ||
10648 | Specifically, on systems where the above guidelines are | |
10649 | appropriate, placing @code{CHARACTER} entities before | |
10650 | @code{REAL(KIND=2)} entities can work just as well, | |
10651 | but only if the number of bytes occupied by the @code{CHARACTER} | |
10652 | entities is divisible by the recommended alignment for | |
10653 | @code{REAL(KIND=2)}. | |
10654 | ||
10655 | By ordering the placement of entities in aggregate | |
10656 | areas according to the simple guidelines above, you | |
10657 | avoid having to carefully count the number of bytes | |
10658 | occupied by each entity to determine whether the | |
10659 | actual alignment of each subsequent entity meets the | |
10660 | alignment guidelines for the type of that entity. | |
66d18ad7 | 10661 | |
795232f7 JL |
10662 | If you don't ensure correct alignment of @code{COMMON} elements, the |
10663 | compiler may be forced by some systems to violate the Fortran semantics by | |
10664 | adding padding to get @code{DOUBLE PRECISION} data properly aligned. | |
10665 | If the unfortunate practice is employed of overlaying different types of | |
10666 | data in the @code{COMMON} block, the different variants | |
10667 | of this block may become misaligned with respect to each other. | |
10668 | Even if your platform doesn't require strict alignment, | |
10669 | @code{COMMON} should be laid out as above for portability. | |
10670 | (Unfortunately the FORTRAN 77 standard didn't anticipate this | |
10671 | possible requirement, which is compiler-independent on a given platform.) | |
5ff904cd JL |
10672 | |
10673 | @item | |
795232f7 JL |
10674 | @cindex -malign-double option |
10675 | @cindex options, -malign-double | |
5ff904cd | 10676 | Use the (x86-specific) @samp{-malign-double} option when compiling |
795232f7 JL |
10677 | programs for the Pentium and Pentium Pro architectures (called 586 |
10678 | and 686 in the @code{gcc} configuration subsystem). | |
10679 | The warning about this in the @code{gcc} manual isn't | |
10680 | generally relevant to Fortran, | |
10681 | but using it will force @code{COMMON} to be padded if necessary to align | |
10682 | @code{DOUBLE PRECISION} data. | |
5ff904cd | 10683 | |
95a1b676 CB |
10684 | When @code{DOUBLE PRECISION} data is forcibly aligned |
10685 | in @code{COMMON} by @code{g77} due to specifying @samp{-malign-double}, | |
10686 | @code{g77} issues a warning about the need to | |
10687 | insert padding. | |
10688 | ||
10689 | In this case, each and every program unit that uses | |
10690 | the same @code{COMMON} area | |
10691 | must specify the same layout of variables and their types | |
10692 | for that area | |
10693 | and be compiled with @samp{-malign-double} as well. | |
10694 | @code{g77} will issue warnings in each case, | |
10695 | but as long as every program unit using that area | |
10696 | is compiled with the same warnings, | |
10697 | the resulting object files should work when linked together | |
10698 | unless the program makes additional assumptions about | |
10699 | @code{COMMON} area layouts that are outside the scope | |
10700 | of the FORTRAN 77 standard, | |
10701 | or uses @code{EQUIVALENCE} or different layouts | |
10702 | in ways that assume no padding is ever inserted by the compiler. | |
10703 | ||
5ff904cd JL |
10704 | @item |
10705 | Ensure that @file{crt0.o} or @file{crt1.o} | |
10706 | on your system guarantees a 64-bit | |
10707 | aligned stack for @code{main()}. | |
795232f7 JL |
10708 | The recent one from GNU (@code{glibc2}) will do this on x86 systems, |
10709 | but we don't know of any other x86 setups where it will be right. | |
10710 | Read your system's documentation to determine if | |
10711 | it is appropriate to upgrade to a more recent version | |
10712 | to obtain the optimal alignment. | |
5ff904cd JL |
10713 | @end itemize |
10714 | ||
795232f7 JL |
10715 | Progress is being made on making this work |
10716 | ``out of the box'' on future versions of @code{g77}, | |
10717 | @code{gcc}, and some of the relevant operating systems | |
10718 | (such as GNU/Linux). | |
5ff904cd | 10719 | |
7cceca32 CB |
10720 | @cindex alignment testing |
10721 | @cindex testing alignment | |
10722 | A package that tests the degree to which a Fortran compiler | |
10723 | (such as @code{g77}) | |
10724 | aligns 64-bit floating-point variables and arrays | |
10725 | is available at @uref{ftp://alpha.gnu.org/gnu/g77/align/}. | |
10726 | ||
5ff904cd JL |
10727 | @node Prefer Automatic Uninitialized Variables |
10728 | @subsection Prefer Automatic Uninitialized Variables | |
10729 | ||
10730 | If you're using @samp{-fno-automatic} already, you probably | |
10731 | should change your code to allow compilation with @samp{-fautomatic} | |
10732 | (the default), to allow the program to run faster. | |
10733 | ||
10734 | Similarly, you should be able to use @samp{-fno-init-local-zero} | |
10735 | (the default) instead of @samp{-finit-local-zero}. | |
10736 | This is because it is rare that every variable affected by these | |
10737 | options in a given program actually needs to | |
10738 | be so affected. | |
10739 | ||
10740 | For example, @samp{-fno-automatic}, which effectively @code{SAVE}s | |
10741 | every local non-automatic variable and array, affects even things like | |
10742 | @code{DO} iteration | |
10743 | variables, which rarely need to be @code{SAVE}d, and this often reduces | |
10744 | run-time performances. | |
10745 | Similarly, @samp{-fno-init-local-zero} forces such | |
10746 | variables to be initialized to zero---when @code{SAVE}d (such as when | |
10747 | @samp{-fno-automatic}), this by itself generally affects only | |
10748 | startup time for a program, but when not @code{SAVE}d, | |
10749 | it can slow down the procedure every time it is called. | |
10750 | ||
10751 | @xref{Overly Convenient Options,,Overly Convenient Command-Line Options}, | |
10752 | for information on the @samp{-fno-automatic} and | |
10753 | @samp{-finit-local-zero} options and how to convert | |
10754 | their use into selective changes in your own code. | |
10755 | ||
10756 | @node Avoid f2c Compatibility | |
10757 | @subsection Avoid f2c Compatibility | |
10758 | @cindex -fno-f2c option | |
10759 | @cindex options, -fno-f2c | |
10760 | @cindex @code{f2c} compatibility | |
10761 | @cindex compatibility, @code{f2c} | |
10762 | ||
10763 | If you aren't linking with any code compiled using | |
10764 | @code{f2c}, try using the @samp{-fno-f2c} option when | |
10765 | compiling @emph{all} the code in your program. | |
10766 | (Note that @code{libf2c} is @emph{not} an example of code | |
10767 | that is compiled using @code{f2c}---it is compiled by a C | |
10768 | compiler, typically @code{gcc}.) | |
10769 | ||
10770 | @node Use Submodel Options | |
10771 | @subsection Use Submodel Options | |
10772 | @cindex Pentium optimizations | |
26b9526e | 10773 | @cindex optimization, for Pentium |
5ff904cd JL |
10774 | @cindex 586/686 CPUs |
10775 | @cindex submodels | |
10776 | ||
10777 | Using an appropriate @samp{-m} option to generate specific code for your | |
10778 | CPU may be worthwhile, though it may mean the executable won't run on | |
10779 | other versions of the CPU that don't support the same instruction set. | |
10780 | @xref{Submodel Options,,Hardware Models and Configurations,gcc,Using and | |
10781 | Porting GNU CC}. | |
10782 | ||
10783 | For recent CPUs that don't have explicit support in | |
10784 | the released version of @code{gcc}, it may still be possible to get | |
10785 | improvements. | |
10786 | For instance, the flags recommended for 586/686 | |
10787 | (Pentium(Pro)) chips for building the Linux kernel are: | |
10788 | ||
10789 | @smallexample | |
10790 | -m486 -malign-loops=2 -malign-jumps=2 -malign-functions=2 | |
10791 | -fomit-frame-pointer | |
10792 | @end smallexample | |
10793 | ||
10794 | @noindent @samp{-fomit-frame-pointer} will, however, inhibit debugging | |
10795 | on x86 systems. | |
10796 | ||
10797 | @node Trouble | |
10798 | @chapter Known Causes of Trouble with GNU Fortran | |
10799 | @cindex bugs, known | |
10800 | @cindex installation trouble | |
10801 | @cindex known causes of trouble | |
10802 | ||
10803 | This section describes known problems that affect users of GNU Fortran. | |
10804 | Most of these are not GNU Fortran bugs per se---if they were, we would | |
10805 | fix them. | |
10806 | But the result for a user might be like the result of a bug. | |
10807 | ||
10808 | Some of these problems are due to bugs in other software, some are | |
10809 | missing features that are too much work to add, and some are places | |
10810 | where people's opinions differ as to what is best. | |
10811 | ||
10812 | Information on bugs that show up when configuring, porting, building, | |
10813 | or installing @code{g77} is not provided here. | |
10814 | @xref{Problems Installing}. | |
10815 | ||
10816 | To find out about major bugs discovered in the current release and | |
51efa892 | 10817 | possible workarounds for them, see |
95a1b676 | 10818 | @uref{ftp://alpha.gnu.org/g77.plan}. |
5ff904cd JL |
10819 | |
10820 | (Note that some of this portion of the manual is lifted | |
10821 | directly from the @code{gcc} manual, with minor modifications | |
10822 | to tailor it to users of @code{g77}. | |
10823 | Anytime a bug seems to have more to do with the @code{gcc} | |
10824 | portion of @code{g77}, | |
10825 | @xref{Trouble,,Known Causes of Trouble with GNU CC, | |
10826 | gcc,Using and Porting GNU CC}.) | |
10827 | ||
10828 | @menu | |
10829 | * But-bugs:: Bugs really in other programs or elsewhere. | |
51efa892 | 10830 | * Known Bugs:: Bugs known to be in this version of @code{g77}. |
5ff904cd JL |
10831 | * Missing Features:: Features we already know we want to add later. |
10832 | * Disappointments:: Regrettable things we can't change. | |
10833 | * Non-bugs:: Things we think are right, but some others disagree. | |
10834 | * Warnings and Errors:: Which problems in your code get warnings, | |
10835 | and which get errors. | |
10836 | @end menu | |
10837 | ||
10838 | @node But-bugs | |
10839 | @section Bugs Not In GNU Fortran | |
10840 | @cindex but-bugs | |
10841 | ||
10842 | These are bugs to which the maintainers often have to reply, | |
10843 | ``but that isn't a bug in @code{g77}@dots{}''. | |
10844 | Some of these already are fixed in new versions of other | |
10845 | software; some still need to be fixed; some are problems | |
10846 | with how @code{g77} is installed or is being used; | |
10847 | some are the result of bad hardware that causes software | |
10848 | to misbehave in sometimes bizarre ways; | |
10849 | some just cannot be addressed at this time until more | |
10850 | is known about the problem. | |
10851 | ||
10852 | Please don't re-report these bugs to the @code{g77} maintainers---if | |
10853 | you must remind someone how important it is to you that the problem | |
10854 | be fixed, talk to the people responsible for the other products | |
10855 | identified below, but preferably only after you've tried the | |
10856 | latest versions of those products. | |
10857 | The @code{g77} maintainers have their hands full working on | |
10858 | just fixing and improving @code{g77}, without serving as a | |
10859 | clearinghouse for all bugs that happen to affect @code{g77} | |
10860 | users. | |
10861 | ||
10862 | @xref{Collected Fortran Wisdom}, for information on behavior | |
10863 | of Fortran programs, and the programs that compile them, that | |
10864 | might be @emph{thought} to indicate bugs. | |
10865 | ||
10866 | @menu | |
10867 | * Signal 11 and Friends:: Strange behavior by any software. | |
10868 | * Cannot Link Fortran Programs:: Unresolved references. | |
10869 | * Large Common Blocks:: Problems on older GNU/Linux systems. | |
10870 | * Debugger Problems:: When the debugger crashes. | |
10871 | * NeXTStep Problems:: Misbehaving executables. | |
10872 | * Stack Overflow:: More misbehaving executables. | |
10873 | * Nothing Happens:: Less behaving executables. | |
10874 | * Strange Behavior at Run Time:: Executables misbehaving due to | |
10875 | bugs in your program. | |
10876 | * Floating-point Errors:: The results look wrong, but@dots{}. | |
10877 | @end menu | |
10878 | ||
10879 | @node Signal 11 and Friends | |
10880 | @subsection Signal 11 and Friends | |
10881 | @cindex signal 11 | |
10882 | @cindex hardware errors | |
10883 | ||
10884 | A whole variety of strange behaviors can occur when the | |
10885 | software, or the way you are using the software, | |
10886 | stresses the hardware in a way that triggers hardware bugs. | |
10887 | This might seem hard to believe, but it happens frequently | |
10888 | enough that there exist documents explaining in detail | |
10889 | what the various causes of the problems are, what | |
10890 | typical symptoms look like, and so on. | |
10891 | ||
10892 | Generally these problems are referred to in this document | |
10893 | as ``signal 11'' crashes, because the Linux kernel, running | |
10894 | on the most popular hardware (the Intel x86 line), often | |
10895 | stresses the hardware more than other popular operating | |
10896 | systems. | |
10897 | When hardware problems do occur under GNU/Linux on x86 | |
10898 | systems, these often manifest themselves as ``signal 11'' | |
10899 | problems, as illustrated by the following diagnostic: | |
10900 | ||
10901 | @smallexample | |
10902 | sh# @kbd{g77 myprog.f} | |
10903 | gcc: Internal compiler error: program f771 got fatal signal 11 | |
10904 | sh# | |
10905 | @end smallexample | |
10906 | ||
10907 | It is @emph{very} important to remember that the above | |
10908 | message is @emph{not} the only one that indicates a | |
10909 | hardware problem, nor does it always indicate a hardware | |
10910 | problem. | |
10911 | ||
10912 | In particular, on systems other than those running the Linux | |
10913 | kernel, the message might appear somewhat or very different, | |
10914 | as it will if the error manifests itself while running a | |
10915 | program other than the @code{g77} compiler. | |
10916 | For example, | |
10917 | it will appear somewhat different when running your program, | |
10918 | when running Emacs, and so on. | |
10919 | ||
10920 | How to cope with such problems is well beyond the scope | |
10921 | of this manual. | |
10922 | ||
10923 | However, users of Linux-based systems (such as GNU/Linux) | |
95a1b676 | 10924 | should review @uref{http://www.bitwizard.nl/sig11}, a source |
5ff904cd JL |
10925 | of detailed information on diagnosing hardware problems, |
10926 | by recognizing their common symptoms. | |
10927 | ||
10928 | Users of other operating systems and hardware might | |
10929 | find this reference useful as well. | |
10930 | If you know of similar material for another hardware/software | |
10931 | combination, please let us know so we can consider including | |
10932 | a reference to it in future versions of this manual. | |
10933 | ||
10934 | @node Cannot Link Fortran Programs | |
10935 | @subsection Cannot Link Fortran Programs | |
10936 | @cindex unresolved reference (various) | |
10937 | @cindex linking error for user code | |
10938 | @cindex code, user | |
26b9526e CB |
10939 | @cindex @code{ld}, error linking user code |
10940 | @cindex @code{ld}, can't find strange names | |
5ff904cd JL |
10941 | On some systems, perhaps just those with out-of-date (shared?) |
10942 | libraries, unresolved-reference errors happen when linking @code{g77}-compiled | |
10943 | programs (which should be done using @code{g77}). | |
10944 | ||
10945 | If this happens to you, try appending @samp{-lc} to the command you | |
10946 | use to link the program, e.g. @samp{g77 foo.f -lc}. | |
95a1b676 | 10947 | @code{g77} already specifies @samp{-lg2c -lm} when it calls the linker, |
5ff904cd JL |
10948 | but it cannot also specify @samp{-lc} because not all systems have a |
10949 | file named @file{libc.a}. | |
10950 | ||
10951 | It is unclear at this point whether there are legitimately installed | |
95a1b676 | 10952 | systems where @samp{-lg2c -lm} is insufficient to resolve code produced |
5ff904cd JL |
10953 | by @code{g77}. |
10954 | ||
10955 | @cindex undefined reference (_main) | |
26b9526e CB |
10956 | @cindex linking error, user code |
10957 | @cindex @code{ld}, error linking user code | |
5ff904cd | 10958 | @cindex code, user |
26b9526e | 10959 | @cindex @code{ld}, can't find @samp{_main} |
5ff904cd JL |
10960 | If your program doesn't link due to unresolved references to names |
10961 | like @samp{_main}, make sure you're using the @code{g77} command to do the | |
10962 | link, since this command ensures that the necessary libraries are | |
95a1b676 | 10963 | loaded by specifying @samp{-lg2c -lm} when it invokes the @code{gcc} |
5ff904cd JL |
10964 | command to do the actual link. |
10965 | (Use the @samp{-v} option to discover | |
10966 | more about what actually happens when you use the @code{g77} and @code{gcc} | |
10967 | commands.) | |
10968 | ||
10969 | Also, try specifying @samp{-lc} as the last item on the @code{g77} | |
10970 | command line, in case that helps. | |
10971 | ||
10972 | @node Large Common Blocks | |
10973 | @subsection Large Common Blocks | |
10974 | @cindex common blocks, large | |
10975 | @cindex large common blocks | |
26b9526e CB |
10976 | @cindex linking, errors |
10977 | @cindex @code{ld}, errors | |
5ff904cd JL |
10978 | @cindex errors, linker |
10979 | On some older GNU/Linux systems, programs with common blocks larger | |
10980 | than 16MB cannot be linked without some kind of error | |
10981 | message being produced. | |
10982 | ||
10983 | This is a bug in older versions of @code{ld}, fixed in | |
10984 | more recent versions of @code{binutils}, such as version 2.6. | |
10985 | ||
10986 | @node Debugger Problems | |
10987 | @subsection Debugger Problems | |
26b9526e | 10988 | @cindex @code{gdb}, support |
5ff904cd JL |
10989 | @cindex support, @code{gdb} |
10990 | There are some known problems when using @code{gdb} on code | |
10991 | compiled by @code{g77}. | |
10992 | Inadequate investigation as of the release of 0.5.16 results in not | |
10993 | knowing which products are the culprit, but @file{gdb-4.14} definitely | |
10994 | crashes when, for example, an attempt is made to print the contents | |
95a1b676 CB |
10995 | of a @code{COMPLEX(KIND=2)} dummy array, on at least some GNU/Linux |
10996 | machines, plus some others. | |
10997 | Attempts to access assumed-size arrays are | |
10998 | also known to crash recent versions of @code{gdb}. | |
10999 | (@code{gdb}'s Fortran support was done for a different compiler | |
11000 | and isn't properly compatible with @code{g77}.) | |
5ff904cd JL |
11001 | |
11002 | @node NeXTStep Problems | |
11003 | @subsection NeXTStep Problems | |
11004 | @cindex NeXTStep problems | |
11005 | @cindex bus error | |
11006 | @cindex segmentation violation | |
11007 | Developers of Fortran code on NeXTStep (all architectures) have to | |
11008 | watch out for the following problem when writing programs with | |
11009 | large, statically allocated (i.e. non-stack based) data structures | |
11010 | (common blocks, saved arrays). | |
11011 | ||
11012 | Due to the way the native loader (@file{/bin/ld}) lays out | |
11013 | data structures in virtual memory, it is very easy to create an | |
11014 | executable wherein the @samp{__DATA} segment overlaps (has addresses in | |
11015 | common) with the @samp{UNIX STACK} segment. | |
11016 | ||
11017 | This leads to all sorts of trouble, from the executable simply not | |
11018 | executing, to bus errors. | |
11019 | The NeXTStep command line tool @code{ebadexec} points to | |
11020 | the problem as follows: | |
11021 | ||
11022 | @smallexample | |
11023 | % @kbd{/bin/ebadexec a.out} | |
11024 | /bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000 | |
11025 | rounded size = 0x2a000) of executable file: a.out overlaps with UNIX | |
11026 | STACK segment (truncated address = 0x400000 rounded size = | |
11027 | 0x3c00000) of executable file: a.out | |
11028 | @end smallexample | |
11029 | ||
11030 | (In the above case, it is the @samp{__LINKEDIT} segment that overlaps the | |
11031 | stack segment.) | |
11032 | ||
11033 | This can be cured by assigning the @samp{__DATA} segment | |
11034 | (virtual) addresses beyond the stack segment. | |
11035 | A conservative | |
11036 | estimate for this is from address 6000000 (hexadecimal) onwards---this | |
11037 | has always worked for me [Toon Moene]: | |
11038 | ||
11039 | @smallexample | |
11040 | % @kbd{g77 -segaddr __DATA 6000000 test.f} | |
11041 | % @kbd{ebadexec a.out} | |
11042 | ebadexec: file: a.out appears to be executable | |
11043 | % | |
11044 | @end smallexample | |
11045 | ||
9a59ff4f | 11046 | Browsing through @file{@value{path-g77}/Makefile.in}, |
5ff904cd JL |
11047 | you will find that the @code{f771} program itself also has to be |
11048 | linked with these flags---it has large statically allocated | |
11049 | data structures. | |
11050 | (Version 0.5.18 reduces this somewhat, but probably | |
11051 | not enough.) | |
11052 | ||
11053 | (The above item was contributed by Toon Moene | |
11054 | (@email{toon@@moene.indiv.nluug.nl}).) | |
11055 | ||
11056 | @node Stack Overflow | |
11057 | @subsection Stack Overflow | |
26b9526e | 11058 | @cindex stack, overflow |
5ff904cd JL |
11059 | @cindex segmentation violation |
11060 | @code{g77} code might fail at runtime (probably with a ``segmentation | |
11061 | violation'') due to overflowing the stack. | |
11062 | This happens most often on systems with an environment | |
11063 | that provides substantially more heap space (for use | |
11064 | when arbitrarily allocating and freeing memory) than stack | |
11065 | space. | |
11066 | ||
11067 | Often this can be cured by | |
11068 | increasing or removing your shell's limit on stack usage, typically | |
11069 | using @kbd{limit stacksize} (in @code{csh} and derivatives) or | |
11070 | @kbd{ulimit -s} (in @code{sh} and derivatives). | |
11071 | ||
11072 | Increasing the allowed stack size might, however, require | |
11073 | changing some operating system or system configuration parameters. | |
11074 | ||
11075 | You might be able to work around the problem by compiling with the | |
11076 | @samp{-fno-automatic} option to reduce stack usage, probably at the | |
11077 | expense of speed. | |
11078 | ||
11079 | @xref{Maximum Stackable Size}, for information on patching | |
11080 | @code{g77} to use different criteria for placing local | |
11081 | non-automatic variables and arrays on the stack. | |
11082 | ||
11083 | @cindex automatic arrays | |
11084 | @cindex arrays, automatic | |
11085 | However, if your program uses large automatic arrays | |
11086 | (for example, has declarations like @samp{REAL A(N)} where | |
11087 | @samp{A} is a local array and @samp{N} is a dummy or | |
11088 | @code{COMMON} variable that can have a large value), | |
11089 | neither use of @samp{-fno-automatic}, | |
11090 | nor changing the cut-off point for @code{g77} for using the stack, | |
11091 | will solve the problem by changing the placement of these | |
11092 | large arrays, as they are @emph{necessarily} automatic. | |
11093 | ||
11094 | @code{g77} currently provides no means to specify that | |
11095 | automatic arrays are to be allocated on the heap instead | |
11096 | of the stack. | |
11097 | So, other than increasing the stack size, your best bet is to | |
11098 | change your source code to avoid large automatic arrays. | |
11099 | Methods for doing this currently are outside the scope of | |
11100 | this document. | |
11101 | ||
11102 | (@emph{Note:} If your system puts stack and heap space in the | |
11103 | same memory area, such that they are effectively combined, then | |
11104 | a stack overflow probably indicates a program that is either | |
11105 | simply too large for the system, or buggy.) | |
11106 | ||
11107 | @node Nothing Happens | |
11108 | @subsection Nothing Happens | |
11109 | @cindex nothing happens | |
26b9526e | 11110 | @cindex naming programs |
4e6a1440 CB |
11111 | @cindex @code{test} programs |
11112 | @cindex programs, @code{test} | |
5ff904cd JL |
11113 | It is occasionally reported that a ``simple'' program, |
11114 | such as a ``Hello, World!'' program, does nothing when | |
11115 | it is run, even though the compiler reported no errors, | |
11116 | despite the program containing nothing other than a | |
11117 | simple @code{PRINT} statement. | |
11118 | ||
11119 | This most often happens because the program has been | |
4e6a1440 | 11120 | compiled and linked on a UNIX system and named @code{test}, |
5ff904cd JL |
11121 | though other names can lead to similarly unexpected |
11122 | run-time behavior on various systems. | |
11123 | ||
11124 | Essentially this problem boils down to giving | |
11125 | your program a name that is already known to | |
11126 | the shell you are using to identify some other program, | |
11127 | which the shell continues to execute instead of your | |
11128 | program when you invoke it via, for example: | |
11129 | ||
11130 | @smallexample | |
11131 | sh# @kbd{test} | |
11132 | sh# | |
11133 | @end smallexample | |
11134 | ||
11135 | Under UNIX and many other system, a simple command name | |
11136 | invokes a searching mechanism that might well not choose | |
11137 | the program located in the current working directory if | |
11138 | there is another alternative (such as the @code{test} | |
11139 | command commonly installed on UNIX systems). | |
11140 | ||
11141 | The reliable way to invoke a program you just linked in | |
11142 | the current directory under UNIX is to specify it using | |
11143 | an explicit pathname, as in: | |
11144 | ||
11145 | @smallexample | |
11146 | sh# @kbd{./test} | |
11147 | Hello, World! | |
11148 | sh# | |
11149 | @end smallexample | |
11150 | ||
11151 | Users who encounter this problem should take the time to | |
11152 | read up on how their shell searches for commands, how to | |
11153 | set their search path, and so on. | |
11154 | The relevant UNIX commands to learn about include | |
11155 | @code{man}, @code{info} (on GNU systems), @code{setenv} (or | |
11156 | @code{set} and @code{env}), @code{which}, and @code{find}. | |
11157 | ||
11158 | @node Strange Behavior at Run Time | |
11159 | @subsection Strange Behavior at Run Time | |
11160 | @cindex segmentation violation | |
11161 | @cindex bus error | |
11162 | @cindex overwritten data | |
11163 | @cindex data, overwritten | |
11164 | @code{g77} code might fail at runtime with ``segmentation violation'', | |
11165 | ``bus error'', or even something as subtle as a procedure call | |
11166 | overwriting a variable or array element that it is not supposed | |
11167 | to touch. | |
11168 | ||
11169 | These can be symptoms of a wide variety of actual bugs that | |
11170 | occurred earlier during the program's run, but manifested | |
11171 | themselves as @emph{visible} problems some time later. | |
11172 | ||
11173 | Overflowing the bounds of an array---usually by writing beyond | |
11174 | the end of it---is one of two kinds of bug that often occurs | |
11175 | in Fortran code. | |
6b55276e CB |
11176 | (Compile your code with the @samp{-fsubscript-check} option |
11177 | to catch many of these kinds of errors at program run time.) | |
5ff904cd JL |
11178 | |
11179 | The other kind of bug is a mismatch between the actual arguments | |
11180 | passed to a procedure and the dummy arguments as declared by that | |
11181 | procedure. | |
11182 | ||
11183 | Both of these kinds of bugs, and some others as well, can be | |
11184 | difficult to track down, because the bug can change its behavior, | |
11185 | or even appear to not occur, when using a debugger. | |
11186 | ||
11187 | That is, these bugs can be quite sensitive to data, including | |
11188 | data representing the placement of other data in memory (that is, | |
11189 | pointers, such as the placement of stack frames in memory). | |
11190 | ||
6b55276e | 11191 | @code{g77} now offers the |
5ff904cd JL |
11192 | ability to catch and report some of these problems at compile, link, or |
11193 | run time, such as by generating code to detect references to | |
6b55276e CB |
11194 | beyond the bounds of most arrays (except assumed-size arrays), |
11195 | and checking for agreement between calling and called procedures. | |
11196 | Future improvements are likely to be made in the procedure-mismatch area, | |
11197 | at least. | |
5ff904cd JL |
11198 | |
11199 | In the meantime, finding and fixing the programming | |
11200 | bugs that lead to these behaviors is, ultimately, the user's | |
11201 | responsibility, as difficult as that task can sometimes be. | |
11202 | ||
d79904b8 | 11203 | @cindex infinite spaces printed |
26b9526e | 11204 | @cindex space, endless printing of |
5ff904cd JL |
11205 | @cindex libc, non-ANSI or non-default |
11206 | @cindex C library | |
11207 | @cindex linking against non-standard library | |
11208 | @cindex Solaris | |
11209 | One runtime problem that has been observed might have a simple solution. | |
11210 | If a formatted @code{WRITE} produces an endless stream of spaces, check | |
11211 | that your program is linked against the correct version of the C library. | |
11212 | The configuration process takes care to account for your | |
11213 | system's normal @file{libc} not being ANSI-standard, which will | |
11214 | otherwise cause this behaviour. | |
11215 | If your system's default library is | |
11216 | ANSI-standard and you subsequently link against a non-ANSI one, there | |
11217 | might be problems such as this one. | |
11218 | ||
11219 | Specifically, on Solaris2 systems, | |
11220 | avoid picking up the @code{BSD} library from @file{/usr/ucblib}. | |
11221 | ||
11222 | @node Floating-point Errors | |
11223 | @subsection Floating-point Errors | |
11224 | @cindex floating-point errors | |
11225 | @cindex rounding errors | |
11226 | @cindex inconsistent floating-point results | |
11227 | @cindex results, inconsistent | |
11228 | Some programs appear to produce inconsistent floating-point | |
11229 | results compiled by @code{g77} versus by other compilers. | |
11230 | ||
11231 | Often the reason for this behavior is the fact that floating-point | |
11232 | values are represented on almost all Fortran systems by | |
11233 | @emph{approximations}, and these approximations are inexact | |
11234 | even for apparently simple values like 0.1, 0.2, 0.3, 0.4, 0.6, | |
11235 | 0.7, 0.8, 0.9, 1.1, and so on. | |
11236 | Most Fortran systems, including all current ports of @code{g77}, | |
11237 | use binary arithmetic to represent these approximations. | |
11238 | ||
11239 | Therefore, the exact value of any floating-point approximation | |
11240 | as manipulated by @code{g77}-compiled code is representable by | |
11241 | adding some combination of the values 1.0, 0.5, 0.25, 0.125, and | |
11242 | so on (just keep dividing by two) through the precision of the | |
11243 | fraction (typically around 23 bits for @code{REAL(KIND=1)}, 52 for | |
11244 | @code{REAL(KIND=2)}), then multiplying the sum by a integral | |
11245 | power of two (in Fortran, by @samp{2**N}) that typically is between | |
11246 | -127 and +128 for @code{REAL(KIND=1)} and -1023 and +1024 for | |
11247 | @code{REAL(KIND=2)}, then multiplying by -1 if the number | |
11248 | is negative. | |
11249 | ||
11250 | So, a value like 0.2 is exactly represented in decimal---since | |
46511dd5 | 11251 | it is a fraction, @samp{2/10}, with a denominator that is compatible |
5ff904cd JL |
11252 | with the base of the number system (base 10). |
11253 | However, @samp{2/10} cannot be represented by any finite number | |
11254 | of sums of any of 1.0, 0.5, 0.25, and so on, so 0.2 cannot | |
11255 | be exactly represented in binary notation. | |
11256 | ||
11257 | (On the other hand, decimal notation can represent any binary | |
11258 | number in a finite number of digits. | |
11259 | Decimal notation cannot do so with ternary, or base-3, | |
11260 | notation, which would represent floating-point numbers as | |
11261 | sums of any of @samp{1/1}, @samp{1/3}, @samp{1/9}, and so on. | |
11262 | After all, no finite number of decimal digits can exactly | |
11263 | represent @samp{1/3}. | |
11264 | Fortunately, few systems use ternary notation.) | |
11265 | ||
11266 | Moreover, differences in the way run-time I/O libraries convert | |
11267 | between these approximations and the decimal representation often | |
11268 | used by programmers and the programs they write can result in | |
11269 | apparent differences between results that do not actually exist, | |
11270 | or exist to such a small degree that they usually are not worth | |
11271 | worrying about. | |
11272 | ||
11273 | For example, consider the following program: | |
11274 | ||
11275 | @smallexample | |
11276 | PRINT *, 0.2 | |
11277 | END | |
11278 | @end smallexample | |
11279 | ||
11280 | When compiled by @code{g77}, the above program might output | |
11281 | @samp{0.20000003}, while another compiler might produce a | |
11282 | executable that outputs @samp{0.2}. | |
11283 | ||
11284 | This particular difference is due to the fact that, currently, | |
95a1b676 | 11285 | conversion of floating-point values by the @code{libg2c} library, |
5ff904cd JL |
11286 | used by @code{g77}, handles only double-precision values. |
11287 | ||
11288 | Since @samp{0.2} in the program is a single-precision value, it | |
11289 | is converted to double precision (still in binary notation) | |
11290 | before being converted back to decimal. | |
4e6a1440 | 11291 | The conversion to binary appends @emph{binary} zero digits to the |
5ff904cd JL |
11292 | original value---which, again, is an inexact approximation of |
11293 | 0.2---resulting in an approximation that is much less exact | |
11294 | than is connoted by the use of double precision. | |
11295 | ||
11296 | (The appending of binary zero digits has essentially the same | |
11297 | effect as taking a particular decimal approximation of | |
11298 | @samp{1/3}, such as @samp{0.3333333}, and appending decimal | |
11299 | zeros to it, producing @samp{0.33333330000000000}. | |
11300 | Treating the resulting decimal approximation as if it really | |
11301 | had 18 or so digits of valid precision would make it seem | |
11302 | a very poor approximation of @samp{1/3}.) | |
11303 | ||
11304 | As a result of converting the single-precision approximation | |
11305 | to double precision by appending binary zeros, the conversion | |
11306 | of the resulting double-precision | |
11307 | value to decimal produces what looks like an incorrect | |
11308 | result, when in fact the result is @emph{inexact}, and | |
11309 | is probably no less inaccurate or imprecise an approximation | |
11310 | of 0.2 than is produced by other compilers that happen to output | |
11311 | the converted value as ``exactly'' @samp{0.2}. | |
11312 | (Some compilers behave in a way that can make them appear | |
11313 | to retain more accuracy across a conversion of a single-precision | |
11314 | constant to double precision. | |
11315 | @xref{Context-Sensitive Constants}, to see why | |
11316 | this practice is illusory and even dangerous.) | |
11317 | ||
11318 | Note that a more exact approximation of the constant is | |
11319 | computed when the program is changed to specify a | |
11320 | double-precision constant: | |
11321 | ||
11322 | @smallexample | |
11323 | PRINT *, 0.2D0 | |
11324 | END | |
11325 | @end smallexample | |
11326 | ||
95a1b676 | 11327 | Future versions of @code{g77} and/or @code{libg2c} might convert |
5ff904cd JL |
11328 | single-precision values directly to decimal, |
11329 | instead of converting them to double precision first. | |
11330 | This would tend to result in output that is more consistent | |
11331 | with that produced by some other Fortran implementations. | |
11332 | ||
26b9526e | 11333 | A useful source of information on floating-point computation is David |
0b31330e DL |
11334 | Goldberg, `What Every Computer Scientist Should Know About |
11335 | Floating-Point Arithmetic', Computing Surveys, 23, March 1991, pp.@: | |
4e6a1440 | 11336 | 5-48. |
fa0848d5 CB |
11337 | An online version is available at |
11338 | @uref{http://docs.sun.com}, | |
11339 | and there is a supplemented version, in PostScript form, at | |
11340 | @uref{http://www.validgh.com/goldberg/paper.ps}. | |
11341 | ||
11342 | Information related to the IEEE 754 | |
c7ce2011 | 11343 | floating-point standard by a leading light can be found at |
fa0848d5 CB |
11344 | @uref{http://http.cs.berkeley.edu/%7Ewkahan/ieee754status}; |
11345 | see also slides from the short course referenced from | |
0b31330e | 11346 | @uref{http://http.cs.berkeley.edu/%7Efateman/}. |
c55310ab | 11347 | @uref{http://www.linuxsupportline.com/%7Ebillm/} has a brief |
fa0848d5 CB |
11348 | guide to IEEE 754, a somewhat x86-GNU/Linux-specific FAQ, |
11349 | and library code for GNU/Linux x86 systems. | |
c7ce2011 | 11350 | |
fa0848d5 CB |
11351 | The supplement to the PostScript-formatted Goldberg document, |
11352 | referenced above, is available in HTML format. | |
11353 | See `Differences Among IEEE 754 Implementations' by Doug Priest, | |
11354 | available online at | |
c7ce2011 CB |
11355 | @uref{http://www.validgh.com/goldberg/addendum.html}. |
11356 | This document explores some of the issues surrounding computing | |
11357 | of extended (80-bit) results on processors such as the x86, | |
11358 | especially when those results are arbitrarily truncated | |
11359 | to 32-bit or 64-bit values by the compiler | |
11360 | as ``spills''. | |
11361 | ||
11362 | @cindex spills of floating-point results | |
11363 | @cindex 80-bit spills | |
26b9526e | 11364 | @cindex truncation, of floating-point values |
fa0848d5 CB |
11365 | (@emph{Note:} @code{g77} specifically, and @code{gcc} generally, |
11366 | does arbitrarily truncate 80-bit results during spills | |
c7ce2011 CB |
11367 | as of this writing. |
11368 | It is not yet clear whether a future version of | |
11369 | the GNU compiler suite will offer 80-bit spills | |
fa0848d5 | 11370 | as an option, or perhaps even as the default behavior.) |
c7ce2011 | 11371 | |
0b31330e DL |
11372 | @c xref would be different between editions: |
11373 | The GNU C library provides routines for controlling the FPU, and other | |
11374 | documentation about this. | |
11375 | ||
26b9526e | 11376 | @xref{Floating-point precision}, regarding IEEE 754 conformance. |
0b31330e | 11377 | |
5ff904cd JL |
11378 | @include bugs.texi |
11379 | ||
11380 | @node Missing Features | |
11381 | @section Missing Features | |
11382 | ||
11383 | This section lists features we know are missing from @code{g77}, | |
11384 | and which we want to add someday. | |
11385 | (There is no priority implied in the ordering below.) | |
11386 | ||
11387 | @menu | |
11388 | GNU Fortran language: | |
11389 | * Better Source Model:: | |
11390 | * Fortran 90 Support:: | |
11391 | * Intrinsics in PARAMETER Statements:: | |
6a843296 | 11392 | * Arbitrary Concatenation:: |
5ff904cd JL |
11393 | * SELECT CASE on CHARACTER Type:: |
11394 | * RECURSIVE Keyword:: | |
11395 | * Popular Non-standard Types:: | |
11396 | * Full Support for Compiler Types:: | |
11397 | * Array Bounds Expressions:: | |
11398 | * POINTER Statements:: | |
11399 | * Sensible Non-standard Constructs:: | |
4e6a1440 | 11400 | * READONLY Keyword:: |
5ff904cd JL |
11401 | * FLUSH Statement:: |
11402 | * Expressions in FORMAT Statements:: | |
11403 | * Explicit Assembler Code:: | |
11404 | * Q Edit Descriptor:: | |
11405 | ||
11406 | GNU Fortran dialects: | |
11407 | * Old-style PARAMETER Statements:: | |
11408 | * TYPE and ACCEPT I/O Statements:: | |
11409 | * STRUCTURE UNION RECORD MAP:: | |
11410 | * OPEN CLOSE and INQUIRE Keywords:: | |
11411 | * ENCODE and DECODE:: | |
51efa892 | 11412 | * AUTOMATIC Statement:: |
5ff904cd JL |
11413 | * Suppressing Space Padding:: |
11414 | * Fortran Preprocessor:: | |
11415 | * Bit Operations on Floating-point Data:: | |
11416 | ||
11417 | New facilities: | |
11418 | * POSIX Standard:: | |
11419 | * Floating-point Exception Handling:: | |
11420 | * Nonportable Conversions:: | |
11421 | * Large Automatic Arrays:: | |
11422 | * Support for Threads:: | |
11423 | * Increasing Precision/Range:: | |
11424 | ||
11425 | Better diagnostics: | |
11426 | * Gracefully Handle Sensible Bad Code:: | |
11427 | * Non-standard Conversions:: | |
11428 | * Non-standard Intrinsics:: | |
11429 | * Modifying DO Variable:: | |
11430 | * Better Pedantic Compilation:: | |
11431 | * Warn About Implicit Conversions:: | |
11432 | * Invalid Use of Hollerith Constant:: | |
11433 | * Dummy Array Without Dimensioning Dummy:: | |
11434 | * Invalid FORMAT Specifiers:: | |
11435 | * Ambiguous Dialects:: | |
11436 | * Unused Labels:: | |
11437 | * Informational Messages:: | |
11438 | ||
11439 | Run-time facilities: | |
11440 | * Uninitialized Variables at Run Time:: | |
0b31330e | 11441 | * Portable Unformatted Files:: |
5ff904cd JL |
11442 | |
11443 | Debugging: | |
11444 | * Labels Visible to Debugger:: | |
11445 | @end menu | |
11446 | ||
11447 | @node Better Source Model | |
11448 | @subsection Better Source Model | |
11449 | ||
11450 | @code{g77} needs to provide, as the default source-line model, | |
11451 | a ``pure visual'' mode, where | |
11452 | the interpretation of a source program in this mode can be accurately | |
11453 | determined by a user looking at a traditionally displayed rendition | |
11454 | of the program (assuming the user knows whether the program is fixed | |
11455 | or free form). | |
11456 | ||
11457 | The design should assume the user cannot tell tabs from spaces | |
11458 | and cannot see trailing spaces on lines, but has canonical tab stops | |
11459 | and, for fixed-form source, has the ability to always know exactly | |
11460 | where column 72 is (since the Fortran standard itself requires | |
11461 | this for fixed-form source). | |
11462 | ||
11463 | This would change the default treatment of fixed-form source | |
11464 | to not treat lines with tabs as if they were infinitely long---instead, | |
11465 | they would end at column 72 just as if the tabs were replaced | |
11466 | by spaces in the canonical way. | |
11467 | ||
11468 | As part of this, provide common alternate models (Digital, @code{f2c}, | |
11469 | and so on) via command-line options. | |
11470 | This includes allowing arbitrarily long | |
11471 | lines for free-form source as well as fixed-form source and providing | |
11472 | various limits and diagnostics as appropriate. | |
11473 | ||
11474 | @cindex sequence numbers | |
11475 | @cindex columns 73 through 80 | |
11476 | Also, @code{g77} should offer, perhaps even default to, warnings | |
11477 | when characters beyond the last valid column are anything other | |
11478 | than spaces. | |
11479 | This would mean code with ``sequence numbers'' in columns 73 through 80 | |
11480 | would be rejected, and there's a lot of that kind of code around, | |
11481 | but one of the most frequent bugs encountered by new users is | |
11482 | accidentally writing fixed-form source code into and beyond | |
11483 | column 73. | |
11484 | So, maybe the users of old code would be able to more easily handle | |
4e6a1440 | 11485 | having to specify, say, a @samp{-Wno-col73to80} option. |
5ff904cd JL |
11486 | |
11487 | @node Fortran 90 Support | |
11488 | @subsection Fortran 90 Support | |
26b9526e | 11489 | @cindex Fortran 90, support |
5ff904cd JL |
11490 | @cindex support, Fortran 90 |
11491 | ||
11492 | @code{g77} does not support many of the features that | |
11493 | distinguish Fortran 90 (and, now, Fortran 95) from | |
11494 | ANSI FORTRAN 77. | |
11495 | ||
11496 | Some Fortran 90 features are supported, because they | |
11497 | make sense to offer even to die-hard users of F77. | |
11498 | For example, many of them codify various ways F77 has | |
11499 | been extended to meet users' needs during its tenure, | |
11500 | so @code{g77} might as well offer them as the primary | |
11501 | way to meet those same needs, even if it offers compatibility | |
11502 | with one or more of the ways those needs were met | |
11503 | by other F77 compilers in the industry. | |
11504 | ||
11505 | Still, many important F90 features are not supported, | |
11506 | because no attempt has been made to research each and | |
11507 | every feature and assess its viability in @code{g77}. | |
11508 | In the meantime, users who need those features must | |
11509 | use Fortran 90 compilers anyway, and the best approach | |
11510 | to adding some F90 features to GNU Fortran might well be | |
11511 | to fund a comprehensive project to create GNU Fortran 95. | |
11512 | ||
11513 | @node Intrinsics in PARAMETER Statements | |
11514 | @subsection Intrinsics in @code{PARAMETER} Statements | |
11515 | @cindex PARAMETER statement | |
11516 | @cindex statements, PARAMETER | |
11517 | ||
11518 | @code{g77} doesn't allow intrinsics in @code{PARAMETER} statements. | |
11519 | This feature is considered to be absolutely vital, even though it | |
11520 | is not standard-conforming, and is scheduled for version 0.6. | |
11521 | ||
11522 | Related to this, @code{g77} doesn't allow non-integral | |
11523 | exponentiation in @code{PARAMETER} statements, such as | |
11524 | @samp{PARAMETER (R=2**.25)}. | |
11525 | It is unlikely @code{g77} will ever support this feature, | |
11526 | as doing it properly requires complete emulation of | |
11527 | a target computer's floating-point facilities when | |
11528 | building @code{g77} as a cross-compiler. | |
11529 | But, if the @code{gcc} back end is enhanced to provide | |
11530 | such a facility, @code{g77} will likely use that facility | |
11531 | in implementing this feature soon afterwards. | |
11532 | ||
6a843296 CB |
11533 | @node Arbitrary Concatenation |
11534 | @subsection Arbitrary Concatenation | |
11535 | @cindex concatenation | |
11536 | @cindex CHARACTER*(*) | |
11537 | @cindex run-time, dynamic allocation | |
11538 | ||
11539 | @code{g77} doesn't support arbitrary operands for concatenation | |
11540 | in contexts where run-time allocation is required. | |
11541 | For example: | |
11542 | ||
11543 | @smallexample | |
11544 | SUBROUTINE X(A) | |
11545 | CHARACTER*(*) A | |
11546 | CALL FOO(A // 'suffix') | |
11547 | @end smallexample | |
11548 | ||
5ff904cd JL |
11549 | @node SELECT CASE on CHARACTER Type |
11550 | @subsection @code{SELECT CASE} on @code{CHARACTER} Type | |
11551 | ||
11552 | Character-type selector/cases for @code{SELECT CASE} currently | |
11553 | are not supported. | |
11554 | ||
11555 | @node RECURSIVE Keyword | |
11556 | @subsection @code{RECURSIVE} Keyword | |
11557 | @cindex RECURSIVE keyword | |
11558 | @cindex keywords, RECURSIVE | |
11559 | @cindex recursion, lack of | |
11560 | @cindex lack of recursion | |
11561 | ||
11562 | @code{g77} doesn't support the @code{RECURSIVE} keyword that | |
11563 | F90 compilers do. | |
11564 | Nor does it provide any means for compiling procedures | |
11565 | designed to do recursion. | |
11566 | ||
11567 | All recursive code can be rewritten to not use recursion, | |
11568 | but the result is not pretty. | |
11569 | ||
11570 | @node Increasing Precision/Range | |
11571 | @subsection Increasing Precision/Range | |
11572 | @cindex -r8 | |
a20f31a0 | 11573 | @cindex -qrealsize=8 |
5ff904cd JL |
11574 | @cindex -i8 |
11575 | @cindex f2c | |
11576 | @cindex increasing precision | |
11577 | @cindex precision, increasing | |
11578 | @cindex increasing range | |
11579 | @cindex range, increasing | |
11580 | @cindex Toolpack | |
11581 | @cindex Netlib | |
11582 | ||
a20f31a0 DL |
11583 | Some compilers, such as @code{f2c}, have an option (@samp{-r8}, |
11584 | @samp{-qrealsize=8} or | |
5ff904cd JL |
11585 | similar) that provides automatic treatment of @code{REAL} |
11586 | entities such that they have twice the storage size, and | |
11587 | a corresponding increase in the range and precision, of what | |
11588 | would normally be the @code{REAL(KIND=1)} (default @code{REAL}) type. | |
11589 | (This affects @code{COMPLEX} the same way.) | |
11590 | ||
11591 | They also typically offer another option (@samp{-i8}) to increase | |
11592 | @code{INTEGER} entities so they are twice as large | |
11593 | (with roughly twice as much range). | |
11594 | ||
11595 | (There are potential pitfalls in using these options.) | |
11596 | ||
11597 | @code{g77} does not yet offer any option that performs these | |
11598 | kinds of transformations. | |
11599 | Part of the problem is the lack of detailed specifications regarding | |
11600 | exactly how these options affect the interpretation of constants, | |
11601 | intrinsics, and so on. | |
11602 | ||
11603 | Until @code{g77} addresses this need, programmers could improve | |
11604 | the portability of their code by modifying it to not require | |
11605 | compile-time options to produce correct results. | |
11606 | Some free tools are available which may help, specifically | |
11607 | in Toolpack (which one would expect to be sound) and the @file{fortran} | |
11608 | section of the Netlib repository. | |
11609 | ||
11610 | Use of preprocessors can provide a fairly portable means | |
11611 | to work around the lack of widely portable methods in the Fortran | |
11612 | language itself (though increasing acceptance of Fortran 90 would | |
11613 | alleviate this problem). | |
11614 | ||
11615 | @node Popular Non-standard Types | |
11616 | @subsection Popular Non-standard Types | |
26b9526e CB |
11617 | @cindex @code{INTEGER*2} support |
11618 | @cindex types, @code{INTEGER*2} | |
11619 | @cindex @code{LOGICAL*1} support | |
11620 | @cindex types, @code{LOGICAL*1} | |
5ff904cd JL |
11621 | |
11622 | @code{g77} doesn't fully support @code{INTEGER*2}, @code{LOGICAL*1}, | |
11623 | and similar. | |
11624 | Version 0.6 will provide full support for this very | |
11625 | popular set of features. | |
11626 | In the meantime, version 0.5.18 provides rudimentary support | |
11627 | for them. | |
11628 | ||
11629 | @node Full Support for Compiler Types | |
11630 | @subsection Full Support for Compiler Types | |
11631 | ||
26b9526e CB |
11632 | @cindex @code{REAL*16} support |
11633 | @cindex types, @code{REAL*16} | |
11634 | @cindex @code{INTEGER*8} support | |
11635 | @cindex types, @code{INTEGER*8} | |
5ff904cd JL |
11636 | @code{g77} doesn't support @code{INTEGER}, @code{REAL}, and @code{COMPLEX} equivalents |
11637 | for @emph{all} applicable back-end-supported types (@code{char}, @code{short int}, | |
11638 | @code{int}, @code{long int}, @code{long long int}, and @code{long double}). | |
11639 | This means providing intrinsic support, and maybe constant | |
11640 | support (using F90 syntax) as well, and, for most | |
11641 | machines will result in automatic support of @code{INTEGER*1}, | |
11642 | @code{INTEGER*2}, @code{INTEGER*8}, maybe even @code{REAL*16}, | |
11643 | and so on. | |
11644 | This is scheduled for version 0.6. | |
11645 | ||
11646 | @node Array Bounds Expressions | |
11647 | @subsection Array Bounds Expressions | |
11648 | @cindex array elements, in adjustable array bounds | |
11649 | @cindex function references, in adjustable array bounds | |
11650 | @cindex array bounds, adjustable | |
26b9526e CB |
11651 | @cindex @code{DIMENSION} statement |
11652 | @cindex statements, @code{DIMENSION} | |
5ff904cd JL |
11653 | |
11654 | @code{g77} doesn't support more general expressions to dimension | |
11655 | arrays, such as array element references, function | |
11656 | references, etc. | |
11657 | ||
11658 | For example, @code{g77} currently does not accept the following: | |
11659 | ||
11660 | @smallexample | |
11661 | SUBROUTINE X(M, N) | |
11662 | INTEGER N(10), M(N(2), N(1)) | |
11663 | @end smallexample | |
11664 | ||
11665 | @node POINTER Statements | |
11666 | @subsection POINTER Statements | |
11667 | @cindex POINTER statement | |
11668 | @cindex statements, POINTER | |
11669 | @cindex Cray pointers | |
11670 | ||
11671 | @code{g77} doesn't support pointers or allocatable objects | |
11672 | (other than automatic arrays). | |
11673 | This set of features is | |
11674 | probably considered just behind intrinsics | |
11675 | in @code{PARAMETER} statements on the list of large, | |
11676 | important things to add to @code{g77}. | |
11677 | ||
795232f7 JL |
11678 | In the meantime, consider using the @code{INTEGER(KIND=7)} |
11679 | declaration to specify that a variable must be | |
11680 | able to hold a pointer. | |
11681 | This construct is not portable to other non-GNU compilers, | |
11682 | but it is portable to all machines GNU Fortran supports | |
11683 | when @code{g77} is used. | |
11684 | ||
11685 | @xref{Functions and Subroutines}, for information on | |
11686 | @code{%VAL()}, @code{%REF()}, and @code{%DESCR()} | |
11687 | constructs, which are useful for passing pointers to | |
11688 | procedures written in languages other than Fortran. | |
11689 | ||
5ff904cd JL |
11690 | @node Sensible Non-standard Constructs |
11691 | @subsection Sensible Non-standard Constructs | |
11692 | ||
11693 | @code{g77} rejects things other compilers accept, | |
11694 | like @samp{INTRINSIC SQRT,SQRT}. | |
11695 | As time permits in the future, some of these things that are easy for | |
11696 | humans to read and write and unlikely to be intended to mean something | |
11697 | else will be accepted by @code{g77} (though @samp{-fpedantic} should | |
11698 | trigger warnings about such non-standard constructs). | |
11699 | ||
11700 | Until @code{g77} no longer gratuitously rejects sensible code, | |
11701 | you might as well fix your code | |
11702 | to be more standard-conforming and portable. | |
11703 | ||
11704 | The kind of case that is important to except from the | |
11705 | recommendation to change your code is one where following | |
11706 | good coding rules would force you to write non-standard | |
11707 | code that nevertheless has a clear meaning. | |
11708 | ||
11709 | For example, when writing an @code{INCLUDE} file that | |
11710 | defines a common block, it might be appropriate to | |
11711 | include a @code{SAVE} statement for the common block | |
11712 | (such as @samp{SAVE /CBLOCK/}), so that variables | |
11713 | defined in the common block retain their values even | |
11714 | when all procedures declaring the common block become | |
11715 | inactive (return to their callers). | |
11716 | ||
11717 | However, putting @code{SAVE} statements in an @code{INCLUDE} | |
11718 | file would prevent otherwise standard-conforming code | |
11719 | from also specifying the @code{SAVE} statement, by itself, | |
11720 | to indicate that all local variables and arrays are to | |
11721 | have the @code{SAVE} attribute. | |
11722 | ||
11723 | For this reason, @code{g77} already has been changed to | |
11724 | allow this combination, because although the general | |
11725 | problem of gratuitously rejecting unambiguous and | |
11726 | ``safe'' constructs still exists in @code{g77}, this | |
11727 | particular construct was deemed useful enough that | |
11728 | it was worth fixing @code{g77} for just this case. | |
11729 | ||
11730 | So, while there is no need to change your code | |
11731 | to avoid using this particular construct, there | |
11732 | might be other, equally appropriate but non-standard | |
11733 | constructs, that you shouldn't have to stop using | |
11734 | just because @code{g77} (or any other compiler) | |
11735 | gratuitously rejects it. | |
11736 | ||
11737 | Until the general problem is solved, if you have | |
11738 | any such construct you believe is worthwhile | |
11739 | using (e.g. not just an arbitrary, redundant | |
11740 | specification of an attribute), please submit a | |
11741 | bug report with an explanation, so we can consider | |
11742 | fixing @code{g77} just for cases like yours. | |
11743 | ||
4e6a1440 CB |
11744 | @node READONLY Keyword |
11745 | @subsection @code{READONLY} Keyword | |
11746 | @cindex READONLY | |
11747 | ||
11748 | Support for @code{READONLY}, in @code{OPEN} statements, | |
11749 | requires @code{libg2c} support, | |
11750 | to make sure that @samp{CLOSE(@dots{},STATUS='DELETE')} | |
11751 | does not delete a file opened on a unit | |
11752 | with the @code{READONLY} keyword, | |
11753 | and perhaps to trigger a fatal diagnostic | |
11754 | if a @code{WRITE} or @code{PRINT} | |
11755 | to such a unit is attempted. | |
11756 | ||
11757 | @emph{Note:} It is not sufficient for @code{g77} and @code{libg2c} | |
11758 | (its version of @code{libf2c}) | |
11759 | to assume that @code{READONLY} does not need some kind of explicit support | |
11760 | at run time, | |
11761 | due to UNIX systems not (generally) needing it. | |
11762 | @code{g77} is not just a UNIX-based compiler! | |
11763 | ||
11764 | Further, mounting of non-UNIX filesystems on UNIX systems | |
11765 | (such as via NFS) | |
11766 | might require proper @code{READONLY} support. | |
11767 | ||
11768 | @cindex SHARED | |
11769 | (Similar issues might be involved with supporting the @code{SHARED} | |
11770 | keyword.) | |
11771 | ||
5ff904cd JL |
11772 | @node FLUSH Statement |
11773 | @subsection @code{FLUSH} Statement | |
11774 | ||
11775 | @code{g77} could perhaps use a @code{FLUSH} statement that | |
11776 | does what @samp{CALL FLUSH} does, | |
11777 | but that supports @samp{*} as the unit designator (same unit as for | |
11778 | @code{PRINT}) and accepts @code{ERR=} and/or @code{IOSTAT=} | |
11779 | specifiers. | |
11780 | ||
11781 | @node Expressions in FORMAT Statements | |
11782 | @subsection Expressions in @code{FORMAT} Statements | |
11783 | @cindex FORMAT statement | |
11784 | @cindex statements, FORMAT | |
11785 | ||
11786 | @code{g77} doesn't support @samp{FORMAT(I<J>)} and the like. | |
11787 | Supporting this requires a significant redesign or replacement | |
95a1b676 | 11788 | of @code{libg2c}. |
5ff904cd | 11789 | |
56a0044b JL |
11790 | However, @code{g77} does support |
11791 | this construct when the expression is constant | |
11792 | (as of version 0.5.22). | |
11793 | For example: | |
5ff904cd JL |
11794 | |
11795 | @smallexample | |
11796 | PARAMETER (IWIDTH = 12) | |
11797 | 10 FORMAT (I<IWIDTH>) | |
11798 | @end smallexample | |
11799 | ||
56a0044b | 11800 | Otherwise, at least for output (@code{PRINT} and |
5ff904cd JL |
11801 | @code{WRITE}), Fortran code making use of this feature can |
11802 | be rewritten to avoid it by constructing the @code{FORMAT} | |
11803 | string in a @code{CHARACTER} variable or array, then | |
11804 | using that variable or array in place of the @code{FORMAT} | |
11805 | statement label to do the original @code{PRINT} or @code{WRITE}. | |
11806 | ||
11807 | Many uses of this feature on input can be rewritten this way | |
11808 | as well, but not all can. | |
11809 | For example, this can be rewritten: | |
11810 | ||
11811 | @smallexample | |
11812 | READ 20, I | |
11813 | 20 FORMAT (I<J>) | |
11814 | @end smallexample | |
11815 | ||
11816 | However, this cannot, in general, be rewritten, especially | |
11817 | when @code{ERR=} and @code{END=} constructs are employed: | |
11818 | ||
11819 | @smallexample | |
11820 | READ 30, J, I | |
11821 | 30 FORMAT (I<J>) | |
11822 | @end smallexample | |
11823 | ||
11824 | @node Explicit Assembler Code | |
11825 | @subsection Explicit Assembler Code | |
11826 | ||
11827 | @code{g77} needs to provide some way, a la @code{gcc}, for @code{g77} | |
11828 | code to specify explicit assembler code. | |
11829 | ||
11830 | @node Q Edit Descriptor | |
11831 | @subsection Q Edit Descriptor | |
11832 | @cindex FORMAT statement | |
11833 | @cindex Q edit descriptor | |
0b31330e | 11834 | @cindex edit descriptor, Q |
5ff904cd JL |
11835 | |
11836 | The @code{Q} edit descriptor in @code{FORMAT}s isn't supported. | |
11837 | (This is meant to get the number of characters remaining in an input record.) | |
11838 | Supporting this requires a significant redesign or replacement | |
95a1b676 | 11839 | of @code{libg2c}. |
5ff904cd JL |
11840 | |
11841 | A workaround might be using internal I/O or the stream-based intrinsics. | |
11842 | @xref{FGetC Intrinsic (subroutine)}. | |
11843 | ||
11844 | @node Old-style PARAMETER Statements | |
11845 | @subsection Old-style PARAMETER Statements | |
11846 | @cindex PARAMETER statement | |
11847 | @cindex statements, PARAMETER | |
11848 | ||
11849 | @code{g77} doesn't accept @samp{PARAMETER I=1}. | |
11850 | Supporting this obsolete form of | |
11851 | the @code{PARAMETER} statement would not be particularly hard, as most of the | |
11852 | parsing code is already in place and working. | |
11853 | ||
11854 | Until time/money is | |
11855 | spent implementing it, you might as well fix your code to use the | |
11856 | standard form, @samp{PARAMETER (I=1)} (possibly needing | |
11857 | @samp{INTEGER I} preceding the @code{PARAMETER} statement as well, | |
11858 | otherwise, in the obsolete form of @code{PARAMETER}, the | |
11859 | type of the variable is set from the type of the constant being | |
11860 | assigned to it). | |
11861 | ||
11862 | @node TYPE and ACCEPT I/O Statements | |
11863 | @subsection @code{TYPE} and @code{ACCEPT} I/O Statements | |
11864 | @cindex TYPE statement | |
11865 | @cindex statements, TYPE | |
11866 | @cindex ACCEPT statement | |
11867 | @cindex statements, ACCEPT | |
11868 | ||
11869 | @code{g77} doesn't support the I/O statements @code{TYPE} and | |
11870 | @code{ACCEPT}. | |
11871 | These are common extensions that should be easy to support, | |
11872 | but also are fairly easy to work around in user code. | |
11873 | ||
11874 | Generally, any @samp{TYPE fmt,list} I/O statement can be replaced | |
11875 | by @samp{PRINT fmt,list}. | |
11876 | And, any @samp{ACCEPT fmt,list} statement can be | |
11877 | replaced by @samp{READ fmt,list}. | |
11878 | ||
11879 | @node STRUCTURE UNION RECORD MAP | |
11880 | @subsection @code{STRUCTURE}, @code{UNION}, @code{RECORD}, @code{MAP} | |
11881 | @cindex STRUCTURE statement | |
11882 | @cindex statements, STRUCTURE | |
11883 | @cindex UNION statement | |
11884 | @cindex statements, UNION | |
11885 | @cindex RECORD statement | |
11886 | @cindex statements, RECORD | |
11887 | @cindex MAP statement | |
11888 | @cindex statements, MAP | |
11889 | ||
11890 | @code{g77} doesn't support @code{STRUCTURE}, @code{UNION}, @code{RECORD}, | |
11891 | @code{MAP}. | |
11892 | This set of extensions is quite a bit | |
11893 | lower on the list of large, important things to add to @code{g77}, partly | |
11894 | because it requires a great deal of work either upgrading or | |
95a1b676 | 11895 | replacing @code{libg2c}. |
5ff904cd JL |
11896 | |
11897 | @node OPEN CLOSE and INQUIRE Keywords | |
11898 | @subsection @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} Keywords | |
11899 | @cindex disposition of files | |
11900 | @cindex OPEN statement | |
11901 | @cindex statements, OPEN | |
11902 | @cindex CLOSE statement | |
11903 | @cindex statements, CLOSE | |
11904 | @cindex INQUIRE statement | |
11905 | @cindex statements, INQUIRE | |
11906 | ||
11907 | @code{g77} doesn't have support for keywords such as @code{DISP='DELETE'} in | |
11908 | the @code{OPEN}, @code{CLOSE}, and @code{INQUIRE} statements. | |
11909 | These extensions are easy to add to @code{g77} itself, but | |
95a1b676 | 11910 | require much more work on @code{libg2c}. |
5ff904cd | 11911 | |
0b31330e DL |
11912 | @cindex FORM='PRINT' |
11913 | @cindex ANS carriage control | |
26b9526e | 11914 | @cindex carriage control |
0b31330e DL |
11915 | @pindex asa |
11916 | @pindex fpr | |
11917 | @code{g77} doesn't support @code{FORM='PRINT'} or an equivalent to | |
36ded32a | 11918 | translate the traditional `carriage control' characters in column 1 of |
0b31330e DL |
11919 | output to use backspaces, carriage returns and the like. However |
11920 | programs exist to translate them in output files (or standard output). | |
11921 | These are typically called either @code{fpr} or @code{asa}. You can get | |
11922 | a version of @code{asa} from | |
11923 | @uref{ftp://sunsite.unc.edu/pub/Linux/devel/lang/fortran} for GNU | |
11924 | systems which will probably build easily on other systems. | |
11925 | Alternatively, @code{fpr} is in BSD distributions in various archive | |
11926 | sites. | |
11927 | ||
36ded32a JL |
11928 | @c (Can both programs can be used in a pipeline, |
11929 | @c with a named input file, | |
11930 | @c and/or with a named output file???) | |
0b31330e | 11931 | |
5ff904cd JL |
11932 | @node ENCODE and DECODE |
11933 | @subsection @code{ENCODE} and @code{DECODE} | |
11934 | @cindex ENCODE statement | |
11935 | @cindex statements, ENCODE | |
11936 | @cindex DECODE statement | |
11937 | @cindex statements, DECODE | |
11938 | ||
11939 | @code{g77} doesn't support @code{ENCODE} or @code{DECODE}. | |
11940 | ||
11941 | These statements are best replaced by READ and WRITE statements | |
11942 | involving internal files (CHARACTER variables and arrays). | |
11943 | ||
11944 | For example, replace a code fragment like | |
11945 | ||
11946 | @smallexample | |
11947 | INTEGER*1 LINE(80) | |
11948 | @dots{} | |
11949 | DECODE (80, 9000, LINE) A, B, C | |
11950 | @dots{} | |
11951 | 9000 FORMAT (1X, 3(F10.5)) | |
11952 | @end smallexample | |
11953 | ||
11954 | @noindent | |
11955 | with: | |
11956 | ||
11957 | @smallexample | |
11958 | CHARACTER*80 LINE | |
11959 | @dots{} | |
11960 | READ (UNIT=LINE, FMT=9000) A, B, C | |
11961 | @dots{} | |
11962 | 9000 FORMAT (1X, 3(F10.5)) | |
11963 | @end smallexample | |
11964 | ||
11965 | Similarly, replace a code fragment like | |
11966 | ||
11967 | @smallexample | |
11968 | INTEGER*1 LINE(80) | |
11969 | @dots{} | |
11970 | ENCODE (80, 9000, LINE) A, B, C | |
11971 | @dots{} | |
11972 | 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) | |
11973 | @end smallexample | |
11974 | ||
11975 | @noindent | |
11976 | with: | |
11977 | ||
11978 | @smallexample | |
11979 | CHARACTER*80 LINE | |
11980 | @dots{} | |
11981 | WRITE (UNIT=LINE, FMT=9000) A, B, C | |
11982 | @dots{} | |
11983 | 9000 FORMAT (1X, 'OUTPUT IS ', 3(F10.5)) | |
11984 | @end smallexample | |
11985 | ||
11986 | It is entirely possible that @code{ENCODE} and @code{DECODE} will | |
11987 | be supported by a future version of @code{g77}. | |
11988 | ||
51efa892 CB |
11989 | @node AUTOMATIC Statement |
11990 | @subsection @code{AUTOMATIC} Statement | |
11991 | @cindex @code{AUTOMATIC} statement | |
11992 | @cindex statements, @code{AUTOMATIC} | |
11993 | @cindex automatic variables | |
11994 | @cindex variables, automatic | |
11995 | ||
4e6a1440 | 11996 | @code{g77} doesn't support the @code{AUTOMATIC} statement that |
51efa892 CB |
11997 | @code{f2c} does. |
11998 | ||
4e6a1440 CB |
11999 | @code{AUTOMATIC} would identify a variable or array |
12000 | as not being @code{SAVE}'d, which is normally the default, | |
12001 | but which would be especially useful for code that, @emph{generally}, | |
12002 | needed to be compiled with the @samp{-fno-automatic} option. | |
12003 | ||
12004 | @code{AUTOMATIC} also would serve as a hint to the compiler that placing | |
12005 | the variable or array---even a very large array--on the stack is acceptable. | |
12006 | ||
12007 | @code{AUTOMATIC} would not, by itself, designate the containing procedure | |
12008 | as recursive. | |
51efa892 | 12009 | |
4e6a1440 CB |
12010 | @code{AUTOMATIC} should work syntactically like @code{SAVE}, |
12011 | in that @code{AUTOMATIC} with no variables listed should apply to | |
12012 | all pertinent variables and arrays | |
12013 | (which would not include common blocks or their members). | |
51efa892 | 12014 | |
4e6a1440 CB |
12015 | Variables and arrays denoted as @code{AUTOMATIC} |
12016 | would not be permitted to be initialized via @code{DATA} | |
12017 | or other specification of any initial values, | |
12018 | requiring explicit initialization, | |
12019 | such as via assignment statements. | |
12020 | ||
12021 | @cindex UNSAVE | |
12022 | @cindex STATIC | |
12023 | Perhaps @code{UNSAVE} and @code{STATIC}, | |
12024 | as strict semantic opposites to @code{SAVE} and @code{AUTOMATIC}, | |
12025 | should be provided as well. | |
51efa892 | 12026 | |
5ff904cd JL |
12027 | @node Suppressing Space Padding |
12028 | @subsection Suppressing Space Padding of Source Lines | |
12029 | ||
12030 | @code{g77} should offer VXT-Fortran-style suppression of virtual | |
12031 | spaces at the end of a source line | |
12032 | if an appropriate command-line option is specified. | |
12033 | ||
12034 | This affects cases where | |
12035 | a character constant is continued onto the next line in a fixed-form | |
12036 | source file, as in the following example: | |
12037 | ||
12038 | @smallexample | |
12039 | 10 PRINT *,'HOW MANY | |
12040 | 1 SPACES?' | |
12041 | @end smallexample | |
12042 | ||
12043 | @noindent | |
12044 | @code{g77}, and many other compilers, virtually extend | |
12045 | the continued line through column 72 with spaces that become part | |
12046 | of the character constant, but Digital Fortran normally didn't, | |
12047 | leaving only one space between @samp{MANY} and @samp{SPACES?} | |
12048 | in the output of the above statement. | |
12049 | ||
12050 | Fairly recently, at least one version of Digital Fortran | |
12051 | was enhanced to provide the other behavior when a | |
12052 | command-line option is specified, apparently due to demand | |
12053 | from readers of the USENET group @file{comp.lang.fortran} | |
12054 | to offer conformance to this widespread practice in the | |
12055 | industry. | |
12056 | @code{g77} should return the favor by offering conformance | |
12057 | to Digital's approach to handling the above example. | |
12058 | ||
12059 | @node Fortran Preprocessor | |
12060 | @subsection Fortran Preprocessor | |
12061 | ||
12062 | @code{g77} should offer a preprocessor designed specifically | |
12063 | for Fortran to replace @samp{cpp -traditional}. | |
12064 | There are several out there worth evaluating, at least. | |
12065 | ||
12066 | Such a preprocessor would recognize Hollerith constants, | |
12067 | properly parse comments and character constants, and so on. | |
12068 | It might also recognize, process, and thus preprocess | |
12069 | files included via the @code{INCLUDE} directive. | |
12070 | ||
12071 | @node Bit Operations on Floating-point Data | |
12072 | @subsection Bit Operations on Floating-point Data | |
26b9526e CB |
12073 | @cindex @code{And} intrinsic |
12074 | @cindex intrinsics, @code{And} | |
12075 | @cindex @code{Or} intrinsic | |
12076 | @cindex intrinsics, @code{Or} | |
12077 | @cindex @code{Shift} intrinsic | |
12078 | @cindex intrinsics, @code{Shift} | |
5ff904cd JL |
12079 | |
12080 | @code{g77} does not allow @code{REAL} and other non-integral types for | |
26b9526e | 12081 | arguments to intrinsics like @code{And}, @code{Or}, and @code{Shift}. |
5ff904cd JL |
12082 | |
12083 | For example, this program is rejected by @code{g77}, because | |
26b9526e | 12084 | the intrinsic @code{Iand} does not accept @code{REAL} arguments: |
5ff904cd JL |
12085 | |
12086 | @smallexample | |
12087 | DATA A/7.54/, B/9.112/ | |
12088 | PRINT *, IAND(A, B) | |
12089 | END | |
12090 | @end smallexample | |
12091 | ||
12092 | @node POSIX Standard | |
12093 | @subsection @code{POSIX} Standard | |
12094 | ||
12095 | @code{g77} should support the POSIX standard for Fortran. | |
12096 | ||
12097 | @node Floating-point Exception Handling | |
12098 | @subsection Floating-point Exception Handling | |
26b9526e CB |
12099 | @cindex floating-point, exceptions |
12100 | @cindex exceptions, floating-point | |
5ff904cd JL |
12101 | @cindex FPE handling |
12102 | @cindex NaN values | |
12103 | ||
12104 | The @code{gcc} backend and, consequently, @code{g77}, currently provides no | |
0b31330e | 12105 | general control over whether or not floating-point exceptions are trapped or |
5ff904cd JL |
12106 | ignored. |
12107 | (Ignoring them typically results in NaN values being | |
95a1b676 | 12108 | propagated in systems that conform to IEEE 754.) |
0b31330e DL |
12109 | The behaviour is normally inherited from the system-dependent startup |
12110 | code, though some targets, such as the Alpha, have code generation | |
12111 | options which change the behaviour. | |
5ff904cd JL |
12112 | |
12113 | Most systems provide some C-callable mechanism to change this; this can | |
12114 | be invoked at startup using @code{gcc}'s @code{constructor} attribute. | |
12115 | For example, just compiling and linking the following C code with your | |
12116 | program will turn on exception trapping for the ``common'' exceptions | |
12117 | on an x86-based GNU system: | |
12118 | ||
12119 | @smallexample | |
12120 | #include <fpu_control.h> | |
0b31330e DL |
12121 | static void __attribute__ ((constructor)) |
12122 | trapfpe () | |
12123 | @{ | |
12124 | __setfpucw (_FPU_DEFAULT & | |
12125 | ~(_FPU_MASK_IM | _FPU_MASK_ZM | _FPU_MASK_OM)); | |
5ff904cd JL |
12126 | @} |
12127 | @end smallexample | |
12128 | ||
0b31330e DL |
12129 | A convenient trick is to compile this something like: |
12130 | @smallexample | |
12131 | gcc -o libtrapfpe.a trapfpe.c | |
12132 | @end smallexample | |
4e6a1440 | 12133 | and then use it by adding @samp{-trapfpe} to the @code{g77} command line |
0b31330e DL |
12134 | when linking. |
12135 | ||
5ff904cd JL |
12136 | @node Nonportable Conversions |
12137 | @subsection Nonportable Conversions | |
12138 | @cindex nonportable conversions | |
12139 | @cindex conversions, nonportable | |
12140 | ||
12141 | @code{g77} doesn't accept some particularly nonportable, | |
12142 | silent data-type conversions such as @code{LOGICAL} | |
12143 | to @code{REAL} (as in @samp{A=.FALSE.}, where @samp{A} | |
12144 | is type @code{REAL}), that other compilers might | |
12145 | quietly accept. | |
12146 | ||
12147 | Some of these conversions are accepted by @code{g77} | |
4e6a1440 | 12148 | when the @samp{-fugly-logint} option is specified. |
5ff904cd JL |
12149 | Perhaps it should accept more or all of them. |
12150 | ||
12151 | @node Large Automatic Arrays | |
12152 | @subsection Large Automatic Arrays | |
12153 | @cindex automatic arrays | |
12154 | @cindex arrays, automatic | |
12155 | ||
12156 | Currently, automatic arrays always are allocated on the stack. | |
12157 | For situations where the stack cannot be made large enough, | |
12158 | @code{g77} should offer a compiler option that specifies | |
12159 | allocation of automatic arrays in heap storage. | |
12160 | ||
12161 | @node Support for Threads | |
12162 | @subsection Support for Threads | |
12163 | @cindex threads | |
12164 | @cindex parallel processing | |
12165 | ||
95a1b676 | 12166 | Neither the code produced by @code{g77} nor the @code{libg2c} library |
5ff904cd JL |
12167 | are thread-safe, nor does @code{g77} have support for parallel processing |
12168 | (other than the instruction-level parallelism available on some | |
12169 | processors). | |
12170 | A package such as PVM might help here. | |
12171 | ||
12172 | @node Gracefully Handle Sensible Bad Code | |
12173 | @subsection Gracefully Handle Sensible Bad Code | |
12174 | ||
12175 | @code{g77} generally should continue processing for | |
12176 | warnings and recoverable (user) errors whenever possible---that | |
12177 | is, it shouldn't gratuitously make bad or useless code. | |
12178 | ||
12179 | For example: | |
12180 | ||
12181 | @smallexample | |
12182 | INTRINSIC ZABS | |
12183 | CALL FOO(ZABS) | |
12184 | END | |
12185 | @end smallexample | |
12186 | ||
12187 | @noindent | |
12188 | When compiling the above with @samp{-ff2c-intrinsics-disable}, | |
12189 | @code{g77} should indeed complain about passing @code{ZABS}, | |
12190 | but it still should compile, instead of rejecting | |
12191 | the entire @code{CALL} statement. | |
12192 | (Some of this is related to improving | |
12193 | the compiler internals to improve how statements are analyzed.) | |
12194 | ||
12195 | @node Non-standard Conversions | |
12196 | @subsection Non-standard Conversions | |
12197 | ||
12198 | @samp{-Wconversion} and related should flag places where non-standard | |
12199 | conversions are found. | |
12200 | Perhaps much of this would be part of @samp{-Wugly*}. | |
12201 | ||
12202 | @node Non-standard Intrinsics | |
12203 | @subsection Non-standard Intrinsics | |
12204 | ||
12205 | @code{g77} needs a new option, like @samp{-Wintrinsics}, to warn about use of | |
12206 | non-standard intrinsics without explicit @code{INTRINSIC} statements for them. | |
12207 | This would help find code that might fail silently when ported to another | |
12208 | compiler. | |
12209 | ||
12210 | @node Modifying DO Variable | |
12211 | @subsection Modifying @code{DO} Variable | |
12212 | ||
12213 | @code{g77} should warn about modifying @code{DO} variables | |
12214 | via @code{EQUIVALENCE}. | |
12215 | (The internal information gathered to produce this warning | |
12216 | might also be useful in setting the | |
12217 | internal ``doiter'' flag for a variable or even array | |
12218 | reference within a loop, since that might produce faster code someday.) | |
12219 | ||
12220 | For example, this code is invalid, so @code{g77} should warn about | |
12221 | the invalid assignment to @samp{NOTHER}: | |
12222 | ||
12223 | @smallexample | |
12224 | EQUIVALENCE (I, NOTHER) | |
12225 | DO I = 1, 100 | |
12226 | IF (I.EQ. 10) NOTHER = 20 | |
12227 | END DO | |
12228 | @end smallexample | |
12229 | ||
12230 | @node Better Pedantic Compilation | |
12231 | @subsection Better Pedantic Compilation | |
12232 | ||
12233 | @code{g77} needs to support @samp{-fpedantic} more thoroughly, | |
12234 | and use it only to generate | |
12235 | warnings instead of rejecting constructs outright. | |
12236 | Have it warn: | |
12237 | if a variable that dimensions an array is not a dummy or placed | |
12238 | explicitly in @code{COMMON} (F77 does not allow it to be | |
12239 | placed in @code{COMMON} via @code{EQUIVALENCE}); if specification statements | |
12240 | follow statement-function-definition statements; about all sorts of | |
12241 | syntactic extensions. | |
12242 | ||
12243 | @node Warn About Implicit Conversions | |
12244 | @subsection Warn About Implicit Conversions | |
12245 | ||
12246 | @code{g77} needs a @samp{-Wpromotions} option to warn if source code appears | |
12247 | to expect automatic, silent, and | |
12248 | somewhat dangerous compiler-assisted conversion of @code{REAL(KIND=1)} | |
12249 | constants to @code{REAL(KIND=2)} based on context. | |
12250 | ||
12251 | For example, it would warn about cases like this: | |
12252 | ||
12253 | @smallexample | |
12254 | DOUBLE PRECISION FOO | |
12255 | PARAMETER (TZPHI = 9.435784839284958) | |
12256 | FOO = TZPHI * 3D0 | |
12257 | @end smallexample | |
12258 | ||
12259 | @node Invalid Use of Hollerith Constant | |
12260 | @subsection Invalid Use of Hollerith Constant | |
12261 | ||
12262 | @code{g77} should disallow statements like @samp{RETURN 2HAB}, | |
12263 | which are invalid in both source forms | |
12264 | (unlike @samp{RETURN (2HAB)}, | |
12265 | which probably still makes no sense but at least can | |
12266 | be reliably parsed). | |
12267 | Fixed-form processing rejects it, but not free-form, except | |
12268 | in a way that is a bit difficult to understand. | |
12269 | ||
12270 | @node Dummy Array Without Dimensioning Dummy | |
12271 | @subsection Dummy Array Without Dimensioning Dummy | |
12272 | ||
12273 | @code{g77} should complain when a list of dummy arguments containing an | |
12274 | adjustable dummy array does | |
12275 | not also contain every variable listed in the dimension list of the | |
12276 | adjustable array. | |
12277 | ||
12278 | Currently, @code{g77} does complain about a variable that | |
12279 | dimensions an array but doesn't appear in any dummy list or @code{COMMON} | |
12280 | area, but this needs to be extended to catch cases where it doesn't appear in | |
12281 | every dummy list that also lists any arrays it dimensions. | |
12282 | ||
12283 | For example, @code{g77} should warn about the entry point @samp{ALT} | |
12284 | below, since it includes @samp{ARRAY} but not @samp{ISIZE} in its | |
12285 | list of arguments: | |
12286 | ||
12287 | @smallexample | |
12288 | SUBROUTINE PRIMARY(ARRAY, ISIZE) | |
12289 | REAL ARRAY(ISIZE) | |
12290 | ENTRY ALT(ARRAY) | |
12291 | @end smallexample | |
12292 | ||
12293 | @node Invalid FORMAT Specifiers | |
12294 | @subsection Invalid FORMAT Specifiers | |
12295 | ||
12296 | @code{g77} should check @code{FORMAT} specifiers for validity | |
12297 | as it does @code{FORMAT} statements. | |
12298 | ||
12299 | For example, a diagnostic would be produced for: | |
12300 | ||
12301 | @smallexample | |
12302 | PRINT 'HI THERE!' !User meant PRINT *, 'HI THERE!' | |
12303 | @end smallexample | |
12304 | ||
12305 | @node Ambiguous Dialects | |
12306 | @subsection Ambiguous Dialects | |
12307 | ||
12308 | @code{g77} needs a set of options such as @samp{-Wugly*}, @samp{-Wautomatic}, | |
12309 | @samp{-Wvxt}, @samp{-Wf90}, and so on. | |
12310 | These would warn about places in the user's source where ambiguities | |
12311 | are found, helpful in resolving ambiguities in the program's | |
12312 | dialect or dialects. | |
12313 | ||
12314 | @node Unused Labels | |
12315 | @subsection Unused Labels | |
12316 | ||
12317 | @code{g77} should warn about unused labels when @samp{-Wunused} is in effect. | |
12318 | ||
12319 | @node Informational Messages | |
12320 | @subsection Informational Messages | |
12321 | ||
12322 | @code{g77} needs an option to suppress information messages (notes). | |
12323 | @samp{-w} does this but also suppresses warnings. | |
12324 | The default should be to suppress info messages. | |
12325 | ||
12326 | Perhaps info messages should simply be eliminated. | |
12327 | ||
12328 | @node Uninitialized Variables at Run Time | |
12329 | @subsection Uninitialized Variables at Run Time | |
12330 | ||
12331 | @code{g77} needs an option to initialize everything (not otherwise | |
12332 | explicitly initialized) to ``weird'' | |
12333 | (machine-dependent) values, e.g. NaNs, bad (non-@code{NULL}) pointers, and | |
12334 | largest-magnitude integers, would help track down references to | |
12335 | some kinds of uninitialized variables at run time. | |
12336 | ||
12337 | Note that use of the options @samp{-O -Wuninitialized} can catch | |
12338 | many such bugs at compile time. | |
12339 | ||
0b31330e DL |
12340 | @node Portable Unformatted Files |
12341 | @subsection Portable Unformatted Files | |
12342 | ||
12343 | @cindex unformatted files | |
12344 | @cindex file formats | |
12345 | @cindex binary data | |
12346 | @cindex byte ordering | |
12347 | @code{g77} has no facility for exchanging unformatted files with systems | |
12348 | using different number formats---even differing only in endianness (byte | |
12349 | order)---or written by other compilers. Some compilers provide | |
12350 | facilities at least for doing byte-swapping during unformatted I/O. | |
12351 | ||
12352 | It is unrealistic to expect to cope with exchanging unformatted files | |
12353 | with arbitrary other compiler runtimes, but the @code{g77} runtime | |
12354 | should at least be able to read files written by @code{g77} on systems | |
12355 | with different number formats, particularly if they differ only in byte | |
12356 | order. | |
12357 | ||
12358 | In case you do need to write a program to translate to or from | |
12359 | @code{g77} (@code{libf2c}) unformatted files, they are written as | |
12360 | follows: | |
12361 | @table @asis | |
12362 | @item Sequential | |
12363 | Unformatted sequential records consist of | |
12364 | @enumerate | |
12365 | @item | |
12366 | A number giving the length of the record contents; | |
12367 | @item | |
12368 | the length of record contents again (for backspace). | |
12369 | @end enumerate | |
a20f31a0 | 12370 | |
0b31330e DL |
12371 | The record length is of C type |
12372 | @code{long}; this means that it is 8 bytes on 64-bit systems such as | |
12373 | Alpha GNU/Linux and 4 bytes on other systems, such as x86 GNU/Linux. | |
12374 | Consequently such files cannot be exchanged between 64-bit and 32-bit | |
12375 | systems, even with the same basic number format. | |
12376 | @item Direct access | |
12377 | Unformatted direct access files form a byte stream of length | |
12378 | @var{records}*@var{recl} bytes, where @var{records} is the maximum | |
12379 | record number (@code{REC=@var{records}}) written and @var{recl} is the | |
12380 | record length in bytes specified in the @code{OPEN} statement | |
12381 | (@code{RECL=@var{recl}}). Data appear in the records as determined by | |
12382 | the relevant @code{WRITE} statement. Dummy records with arbitrary | |
12383 | contents appear in the file in place of records which haven't been | |
12384 | written. | |
12385 | @end table | |
12386 | ||
12387 | Thus for exchanging a sequential or direct access unformatted file | |
12388 | between big- and little-endian 32-bit systems using IEEE 754 floating | |
12389 | point it would be sufficient to reverse the bytes in consecutive words | |
811cabee | 12390 | in the file if, and @emph{only} if, only @code{REAL*4}, @code{COMPLEX}, |
0b31330e DL |
12391 | @code{INTEGER*4} and/or @code{LOGICAL*4} data have been written to it by |
12392 | @code{g77}. | |
12393 | ||
12394 | If necessary, it is possible to do byte-oriented i/o with @code{g77}'s | |
12395 | @code{FGETC} and @code{FPUTC} intrinsics. Byte-swapping can be done in | |
12396 | Fortran by equivalencing larger sized variables to an @code{INTEGER*1} | |
12397 | array or a set of scalars. | |
12398 | ||
12399 | @cindex HDF | |
12400 | @cindex PDB | |
12401 | If you need to exchange binary data between arbitrary system and | |
12402 | compiler variations, we recommend using a portable binary format with | |
12403 | Fortran bindings, such as NCSA's HDF (@uref{http://hdf.ncsa.uiuc.edu/}) | |
12404 | or PACT's PDB@footnote{No, not @emph{that} one.} | |
12405 | (@uref{http://www.llnl.gov/def_sci/pact/pact_homepage.html}). (Unlike, | |
12406 | say, CDF or XDR, HDF-like systems write in the native number formats and | |
12407 | only incur overhead when they are read on a system with a different | |
12408 | format.) A future @code{g77} runtime library should use such | |
12409 | techniques. | |
12410 | ||
5ff904cd JL |
12411 | @node Labels Visible to Debugger |
12412 | @subsection Labels Visible to Debugger | |
12413 | ||
12414 | @code{g77} should output debugging information for statements labels, | |
12415 | for use by debuggers that know how to support them. | |
12416 | Same with weirder things like construct names. | |
12417 | It is not yet known if any debug formats or debuggers support these. | |
12418 | ||
12419 | @node Disappointments | |
12420 | @section Disappointments and Misunderstandings | |
12421 | ||
12422 | These problems are perhaps regrettable, but we don't know any practical | |
12423 | way around them for now. | |
12424 | ||
12425 | @menu | |
12426 | * Mangling of Names:: @samp{SUBROUTINE FOO} is given | |
12427 | external name @samp{foo_}. | |
12428 | * Multiple Definitions of External Names:: No doing both @samp{COMMON /FOO/} | |
12429 | and @samp{SUBROUTINE FOO}. | |
12430 | * Limitation on Implicit Declarations:: No @samp{IMPLICIT CHARACTER*(*)}. | |
12431 | @end menu | |
12432 | ||
12433 | @node Mangling of Names | |
12434 | @subsection Mangling of Names in Source Code | |
12435 | @cindex naming issues | |
12436 | @cindex external names | |
12437 | @cindex common blocks | |
12438 | @cindex name space | |
26b9526e | 12439 | @cindex underscore |
5ff904cd JL |
12440 | |
12441 | The current external-interface design, which includes naming of | |
12442 | external procedures, COMMON blocks, and the library interface, | |
12443 | has various usability problems, including things like adding | |
12444 | underscores where not really necessary (and preventing easier | |
12445 | inter-language operability) and yet not providing complete | |
12446 | namespace freedom for user C code linked with Fortran apps (due | |
12447 | to the naming of functions in the library, among other things). | |
12448 | ||
12449 | Project GNU should at least get all this ``right'' for systems | |
12450 | it fully controls, such as the Hurd, and provide defaults and | |
12451 | options for compatibility with existing systems and interoperability | |
12452 | with popular existing compilers. | |
12453 | ||
12454 | @node Multiple Definitions of External Names | |
12455 | @subsection Multiple Definitions of External Names | |
12456 | @cindex block data | |
12457 | @cindex BLOCK DATA statement | |
12458 | @cindex statements, BLOCK DATA | |
26b9526e CB |
12459 | @cindex @code{COMMON} statement |
12460 | @cindex statements, @code{COMMON} | |
5ff904cd JL |
12461 | @cindex naming conflicts |
12462 | ||
12463 | @code{g77} doesn't allow a common block and an external procedure or | |
12464 | @code{BLOCK DATA} to have the same name. | |
12465 | Some systems allow this, but @code{g77} does not, | |
12466 | to be compatible with @code{f2c}. | |
12467 | ||
12468 | @code{g77} could special-case the way it handles | |
12469 | @code{BLOCK DATA}, since it is not compatible with @code{f2c} in this | |
12470 | particular area (necessarily, since @code{g77} offers an | |
12471 | important feature here), but | |
12472 | it is likely that such special-casing would be very annoying to people | |
12473 | with programs that use @samp{EXTERNAL FOO}, with no other mention of | |
12474 | @samp{FOO} in the same program unit, to refer to external procedures, since | |
12475 | the result would be that @code{g77} would treat these references as requests to | |
12476 | force-load BLOCK DATA program units. | |
12477 | ||
12478 | In that case, if @code{g77} modified | |
12479 | names of @code{BLOCK DATA} so they could have the same names as | |
12480 | @code{COMMON}, users | |
12481 | would find that their programs wouldn't link because the @samp{FOO} procedure | |
12482 | didn't have its name translated the same way. | |
12483 | ||
12484 | (Strictly speaking, | |
12485 | @code{g77} could emit a null-but-externally-satisfying definition of | |
12486 | @samp{FOO} with its name transformed as if it had been a | |
12487 | @code{BLOCK DATA}, but that probably invites more trouble than it's | |
12488 | worth.) | |
12489 | ||
12490 | @node Limitation on Implicit Declarations | |
12491 | @subsection Limitation on Implicit Declarations | |
12492 | @cindex IMPLICIT CHARACTER*(*) statement | |
12493 | @cindex statements, IMPLICIT CHARACTER*(*) | |
12494 | ||
12495 | @code{g77} disallows @code{IMPLICIT CHARACTER*(*)}. | |
12496 | This is not standard-conforming. | |
12497 | ||
12498 | @node Non-bugs | |
12499 | @section Certain Changes We Don't Want to Make | |
12500 | ||
12501 | This section lists changes that people frequently request, but which | |
12502 | we do not make because we think GNU Fortran is better without them. | |
12503 | ||
12504 | @menu | |
12505 | * Backslash in Constants:: Why @samp{'\\'} is a constant that | |
12506 | is one, not two, characters long. | |
12507 | * Initializing Before Specifying:: Why @samp{DATA VAR/1/} can't precede | |
12508 | @samp{COMMON VAR}. | |
12509 | * Context-Sensitive Intrinsicness:: Why @samp{CALL SQRT} won't work. | |
12510 | * Context-Sensitive Constants:: Why @samp{9.435784839284958} is a | |
12511 | single-precision constant, | |
12512 | and might be interpreted as | |
12513 | @samp{9.435785} or similar. | |
12514 | * Equivalence Versus Equality:: Why @samp{.TRUE. .EQ. .TRUE.} won't work. | |
12515 | * Order of Side Effects:: Why @samp{J = IFUNC() - IFUNC()} might | |
12516 | not behave as expected. | |
12517 | @end menu | |
12518 | ||
12519 | @node Backslash in Constants | |
12520 | @subsection Backslash in Constants | |
12521 | @cindex backslash | |
26b9526e CB |
12522 | @cindex @code{f77} support |
12523 | @cindex support, @code{f77} | |
5ff904cd JL |
12524 | |
12525 | In the opinion of many experienced Fortran users, | |
12526 | @samp{-fno-backslash} should be the default, not @samp{-fbackslash}, | |
12527 | as currently set by @code{g77}. | |
12528 | ||
12529 | First of all, you can always specify | |
12530 | @samp{-fno-backslash} to turn off this processing. | |
12531 | ||
12532 | Despite not being within the spirit (though apparently within the | |
12533 | letter) of the ANSI FORTRAN 77 standard, @code{g77} defaults to | |
12534 | @samp{-fbackslash} because that is what most UNIX @code{f77} commands | |
12535 | default to, and apparently lots of code depends on this feature. | |
12536 | ||
12537 | This is a particularly troubling issue. | |
12538 | The use of a C construct in the midst of Fortran code | |
12539 | is bad enough, worse when it makes existing Fortran | |
12540 | programs stop working (as happens when programs written | |
12541 | for non-UNIX systems are ported to UNIX systems with | |
12542 | compilers that provide the @samp{-fbackslash} feature | |
12543 | as the default---sometimes with no option to turn it off). | |
12544 | ||
12545 | The author of GNU Fortran wished, for reasons of linguistic | |
12546 | purity, to make @samp{-fno-backslash} the default for GNU | |
12547 | Fortran and thus require users of UNIX @code{f77} and @code{f2c} | |
12548 | to specify @samp{-fbackslash} to get the UNIX behavior. | |
12549 | ||
12550 | However, the realization that @code{g77} is intended as | |
12551 | a replacement for @emph{UNIX} @code{f77}, caused the author | |
12552 | to choose to make @code{g77} as compatible with | |
12553 | @code{f77} as feasible, which meant making @samp{-fbackslash} | |
12554 | the default. | |
12555 | ||
12556 | The primary focus on compatibility is at the source-code | |
12557 | level, and the question became ``What will users expect | |
12558 | a replacement for @code{f77} to do, by default?'' | |
12559 | Although at least one UNIX @code{f77} does not provide | |
12560 | @samp{-fbackslash} as a default, it appears that | |
12561 | the majority of them do, which suggests that | |
12562 | the majority of code that is compiled by UNIX @code{f77} | |
12563 | compilers expects @samp{-fbackslash} to be the default. | |
12564 | ||
12565 | It is probably the case that more code exists | |
12566 | that would @emph{not} work with @samp{-fbackslash} | |
12567 | in force than code that requires it be in force. | |
12568 | ||
12569 | However, most of @emph{that} code is not being compiled | |
12570 | with @code{f77}, | |
12571 | and when it is, new build procedures (shell scripts, | |
12572 | makefiles, and so on) must be set up anyway so that | |
12573 | they work under UNIX. | |
12574 | That makes a much more natural and safe opportunity for | |
12575 | non-UNIX users to adapt their build procedures for | |
12576 | @code{g77}'s default of @samp{-fbackslash} than would | |
12577 | exist for the majority of UNIX @code{f77} users who | |
12578 | would have to modify existing, working build procedures | |
12579 | to explicitly specify @samp{-fbackslash} if that was | |
12580 | not the default. | |
12581 | ||
12582 | One suggestion has been to configure the default for | |
12583 | @samp{-fbackslash} (and perhaps other options as well) | |
12584 | based on the configuration of @code{g77}. | |
12585 | ||
12586 | This is technically quite straightforward, but will be avoided | |
12587 | even in cases where not configuring defaults to be | |
12588 | dependent on a particular configuration greatly inconveniences | |
12589 | some users of legacy code. | |
12590 | ||
12591 | Many users appreciate the GNU compilers because they provide an | |
12592 | environment that is uniform across machines. | |
12593 | These users would be | |
12594 | inconvenienced if the compiler treated things like the | |
12595 | format of the source code differently on certain machines. | |
12596 | ||
12597 | Occasionally users write programs intended only for a particular machine | |
12598 | type. | |
12599 | On these occasions, the users would benefit if the GNU Fortran compiler | |
12600 | were to support by default the same dialect as the other compilers on | |
12601 | that machine. | |
12602 | But such applications are rare. | |
12603 | And users writing a | |
12604 | program to run on more than one type of machine cannot possibly benefit | |
12605 | from this kind of compatibility. | |
12606 | (This is consistent with the design goals for @code{gcc}. | |
12607 | To change them for @code{g77}, you must first change them | |
12608 | for @code{gcc}. | |
12609 | Do not ask the maintainers of @code{g77} to do this for you, | |
12610 | or to disassociate @code{g77} from the widely understood, if | |
12611 | not widely agreed-upon, goals for GNU compilers in general.) | |
12612 | ||
12613 | This is why GNU Fortran does and will treat backslashes in the same | |
12614 | fashion on all types of machines (by default). | |
12615 | @xref{Direction of Language Development}, for more information on | |
12616 | this overall philosophy guiding the development of the GNU Fortran | |
12617 | language. | |
12618 | ||
12619 | Of course, users strongly concerned about portability should indicate | |
12620 | explicitly in their build procedures which options are expected | |
12621 | by their source code, or write source code that has as few such | |
12622 | expectations as possible. | |
12623 | ||
12624 | For example, avoid writing code that depends on backslash (@samp{\}) | |
12625 | being interpreted either way in particular, such as by | |
12626 | starting a program unit with: | |
12627 | ||
12628 | @smallexample | |
12629 | CHARACTER BACKSL | |
12630 | PARAMETER (BACKSL = '\\') | |
12631 | @end smallexample | |
12632 | ||
12633 | @noindent | |
12634 | Then, use concatenation of @samp{BACKSL} anyplace a backslash | |
12635 | is desired. | |
12636 | In this way, users can write programs which have the same meaning | |
12637 | in many Fortran dialects. | |
12638 | ||
12639 | (However, this technique does not work for Hollerith constants---which | |
12640 | is just as well, since the only generally portable uses for Hollerith | |
12641 | constants are in places where character constants can and should | |
12642 | be used instead, for readability.) | |
12643 | ||
12644 | @node Initializing Before Specifying | |
12645 | @subsection Initializing Before Specifying | |
12646 | @cindex initialization, statement placement | |
12647 | @cindex placing initialization statements | |
12648 | ||
12649 | @code{g77} does not allow @samp{DATA VAR/1/} to appear in the | |
12650 | source code before @samp{COMMON VAR}, | |
12651 | @samp{DIMENSION VAR(10)}, @samp{INTEGER VAR}, and so on. | |
12652 | In general, @code{g77} requires initialization of a variable | |
12653 | or array to be specified @emph{after} all other specifications | |
12654 | of attributes (type, size, placement, and so on) of that variable | |
12655 | or array are specified (though @emph{confirmation} of data type is | |
12656 | permitted). | |
12657 | ||
12658 | It is @emph{possible} @code{g77} will someday allow all of this, | |
12659 | even though it is not allowed by the FORTRAN 77 standard. | |
12660 | ||
12661 | Then again, maybe it is better to have | |
12662 | @code{g77} always require placement of @code{DATA} | |
12663 | so that it can possibly immediately write constants | |
12664 | to the output file, thus saving time and space. | |
12665 | ||
12666 | That is, @samp{DATA A/1000000*1/} should perhaps always | |
12667 | be immediately writable to canonical assembler, unless it's already known | |
12668 | to be in a @code{COMMON} area following as-yet-uninitialized stuff, | |
12669 | and to do this it cannot be followed by @samp{COMMON A}. | |
12670 | ||
12671 | @node Context-Sensitive Intrinsicness | |
12672 | @subsection Context-Sensitive Intrinsicness | |
12673 | @cindex intrinsics, context-sensitive | |
12674 | @cindex context-sensitive intrinsics | |
12675 | ||
12676 | @code{g77} treats procedure references to @emph{possible} intrinsic | |
12677 | names as always enabling their intrinsic nature, regardless of | |
12678 | whether the @emph{form} of the reference is valid for that | |
12679 | intrinsic. | |
12680 | ||
12681 | For example, @samp{CALL SQRT} is interpreted by @code{g77} as | |
12682 | an invalid reference to the @code{SQRT} intrinsic function, | |
12683 | because the reference is a subroutine invocation. | |
12684 | ||
12685 | First, @code{g77} recognizes the statement @samp{CALL SQRT} | |
12686 | as a reference to a @emph{procedure} named @samp{SQRT}, not | |
12687 | to a @emph{variable} with that name (as it would for a statement | |
12688 | such as @samp{V = SQRT}). | |
12689 | ||
12690 | Next, @code{g77} establishes that, in the program unit being compiled, | |
12691 | @code{SQRT} is an intrinsic---not a subroutine that | |
12692 | happens to have the same name as an intrinsic (as would be | |
12693 | the case if, for example, @samp{EXTERNAL SQRT} was present). | |
12694 | ||
12695 | Finally, @code{g77} recognizes that the @emph{form} of the | |
12696 | reference is invalid for that particular intrinsic. | |
12697 | That is, it recognizes that it is invalid for an intrinsic | |
12698 | @emph{function}, such as @code{SQRT}, to be invoked as | |
12699 | a @emph{subroutine}. | |
12700 | ||
12701 | At that point, @code{g77} issues a diagnostic. | |
12702 | ||
12703 | Some users claim that it is ``obvious'' that @samp{CALL SQRT} | |
12704 | references an external subroutine of their own, not an | |
12705 | intrinsic function. | |
12706 | ||
12707 | However, @code{g77} knows about intrinsic | |
12708 | subroutines, not just functions, and is able to support both having | |
12709 | the same names, for example. | |
12710 | ||
12711 | As a result of this, @code{g77} rejects calls | |
12712 | to intrinsics that are not subroutines, and function invocations | |
12713 | of intrinsics that are not functions, just as it (and most compilers) | |
12714 | rejects invocations of intrinsics with the wrong number (or types) | |
12715 | of arguments. | |
12716 | ||
12717 | So, use the @samp{EXTERNAL SQRT} statement in a program unit that calls | |
12718 | a user-written subroutine named @samp{SQRT}. | |
12719 | ||
12720 | @node Context-Sensitive Constants | |
12721 | @subsection Context-Sensitive Constants | |
12722 | @cindex constants, context-sensitive | |
12723 | @cindex context-sensitive constants | |
12724 | ||
12725 | @code{g77} does not use context to determine the types of | |
12726 | constants or named constants (@code{PARAMETER}), except | |
12727 | for (non-standard) typeless constants such as @samp{'123'O}. | |
12728 | ||
12729 | For example, consider the following statement: | |
12730 | ||
12731 | @smallexample | |
12732 | PRINT *, 9.435784839284958 * 2D0 | |
12733 | @end smallexample | |
12734 | ||
12735 | @noindent | |
12736 | @code{g77} will interpret the (truncated) constant | |
12737 | @samp{9.435784839284958} as a @code{REAL(KIND=1)}, not @code{REAL(KIND=2)}, | |
12738 | constant, because the suffix @code{D0} is not specified. | |
12739 | ||
12740 | As a result, the output of the above statement when | |
12741 | compiled by @code{g77} will appear to have ``less precision'' | |
12742 | than when compiled by other compilers. | |
12743 | ||
12744 | In these and other cases, some compilers detect the | |
12745 | fact that a single-precision constant is used in | |
12746 | a double-precision context and therefore interpret the | |
12747 | single-precision constant as if it was @emph{explicitly} | |
12748 | specified as a double-precision constant. | |
12749 | (This has the effect of appending @emph{decimal}, not | |
12750 | @emph{binary}, zeros to the fractional part of the | |
12751 | number---producing different computational results.) | |
12752 | ||
12753 | The reason this misfeature is dangerous is that a slight, | |
12754 | apparently innocuous change to the source code can change | |
95a1b676 CB |
12755 | the computational results. |
12756 | Consider: | |
5ff904cd JL |
12757 | |
12758 | @smallexample | |
12759 | REAL ALMOST, CLOSE | |
12760 | DOUBLE PRECISION FIVE | |
12761 | PARAMETER (ALMOST = 5.000000000001) | |
12762 | FIVE = 5 | |
12763 | CLOSE = 5.000000000001 | |
12764 | PRINT *, 5.000000000001 - FIVE | |
12765 | PRINT *, ALMOST - FIVE | |
12766 | PRINT *, CLOSE - FIVE | |
12767 | END | |
12768 | @end smallexample | |
12769 | ||
12770 | @noindent | |
12771 | Running the above program should | |
12772 | result in the same value being | |
12773 | printed three times. | |
12774 | With @code{g77} as the compiler, | |
12775 | it does. | |
12776 | ||
12777 | However, compiled by many other compilers, | |
12778 | running the above program would print | |
12779 | two or three distinct values, because | |
12780 | in two or three of the statements, the | |
12781 | constant @samp{5.000000000001}, which | |
12782 | on most systems is exactly equal to @samp{5.} | |
12783 | when interpreted as a single-precision constant, | |
12784 | is instead interpreted as a double-precision | |
12785 | constant, preserving the represented | |
12786 | precision. | |
12787 | However, this ``clever'' promotion of | |
12788 | type does not extend to variables or, | |
12789 | in some compilers, to named constants. | |
12790 | ||
12791 | Since programmers often are encouraged to replace manifest | |
12792 | constants or permanently-assigned variables with named | |
12793 | constants (@code{PARAMETER} in Fortran), and might need | |
12794 | to replace some constants with variables having the same | |
12795 | values for pertinent portions of code, | |
12796 | it is important that compilers treat code so modified in the | |
12797 | same way so that the results of such programs are the same. | |
12798 | @code{g77} helps in this regard by treating constants just | |
12799 | the same as variables in terms of determining their types | |
12800 | in a context-independent way. | |
12801 | ||
12802 | Still, there is a lot of existing Fortran code that has | |
12803 | been written to depend on the way other compilers freely | |
12804 | interpret constants' types based on context, so anything | |
12805 | @code{g77} can do to help flag cases of this in such code | |
12806 | could be very helpful. | |
12807 | ||
12808 | @node Equivalence Versus Equality | |
12809 | @subsection Equivalence Versus Equality | |
12810 | @cindex .EQV., with integer operands | |
12811 | @cindex comparing logical expressions | |
12812 | @cindex logical expressions, comparing | |
12813 | ||
12814 | Use of @code{.EQ.} and @code{.NE.} on @code{LOGICAL} operands | |
4e6a1440 | 12815 | is not supported, except via @samp{-fugly-logint}, which is not |
5ff904cd JL |
12816 | recommended except for legacy code (where the behavior expected |
12817 | by the @emph{code} is assumed). | |
12818 | ||
12819 | Legacy code should be changed, as resources permit, to use @code{.EQV.} | |
12820 | and @code{.NEQV.} instead, as these are permitted by the various | |
12821 | Fortran standards. | |
12822 | ||
12823 | New code should never be written expecting @code{.EQ.} or @code{.NE.} | |
12824 | to work if either of its operands is @code{LOGICAL}. | |
12825 | ||
12826 | The problem with supporting this ``feature'' is that there is | |
12827 | unlikely to be consensus on how it works, as illustrated by the | |
12828 | following sample program: | |
12829 | ||
12830 | @smallexample | |
12831 | LOGICAL L,M,N | |
12832 | DATA L,M,N /3*.FALSE./ | |
12833 | IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N' | |
12834 | END | |
12835 | @end smallexample | |
12836 | ||
12837 | The issue raised by the above sample program is: what is the | |
12838 | precedence of @code{.EQ.} (and @code{.NE.}) when applied to | |
12839 | @code{LOGICAL} operands? | |
12840 | ||
12841 | Some programmers will argue that it is the same as the precedence | |
12842 | for @code{.EQ.} when applied to numeric (such as @code{INTEGER}) | |
12843 | operands. | |
12844 | By this interpretation, the subexpression @samp{M.EQ.N} must be | |
12845 | evaluated first in the above program, resulting in a program that, | |
12846 | when run, does not execute the @code{PRINT} statement. | |
12847 | ||
12848 | Other programmers will argue that the precedence is the same as | |
12849 | the precedence for @code{.EQV.}, which is restricted by the standards | |
12850 | to @code{LOGICAL} operands. | |
12851 | By this interpretation, the subexpression @samp{L.AND.M} must be | |
12852 | evaluated first, resulting in a program that @emph{does} execute | |
12853 | the @code{PRINT} statement. | |
12854 | ||
12855 | Assigning arbitrary semantic interpretations to syntactic expressions | |
12856 | that might legitimately have more than one ``obvious'' interpretation | |
12857 | is generally unwise. | |
12858 | ||
12859 | The creators of the various Fortran standards have done a good job | |
12860 | in this case, requiring a distinct set of operators (which have their | |
12861 | own distinct precedence) to compare @code{LOGICAL} operands. | |
12862 | This requirement results in expression syntax with more certain | |
12863 | precedence (without requiring substantial context), making it easier | |
12864 | for programmers to read existing code. | |
12865 | @code{g77} will avoid muddying up elements of the Fortran language | |
12866 | that were well-designed in the first place. | |
12867 | ||
12868 | (Ask C programmers about the precedence of expressions such as | |
12869 | @samp{(a) & (b)} and @samp{(a) - (b)}---they cannot even tell | |
12870 | you, without knowing more context, whether the @samp{&} and @samp{-} | |
12871 | operators are infix (binary) or unary!) | |
12872 | ||
4e6a1440 CB |
12873 | Most dangerous of all is the fact that, |
12874 | even assuming consensus on its meaning, | |
12875 | an expression like @samp{L.AND.M.EQ.N}, | |
12876 | if it is the result of a typographical error, | |
12877 | doesn't @emph{look} like it has such a typo. | |
12878 | Even experienced Fortran programmers would not likely notice that | |
12879 | @samp{L.AND.M.EQV.N} was, in fact, intended. | |
12880 | ||
12881 | So, this is a prime example of a circumstance in which | |
12882 | a quality compiler diagnoses the code, | |
12883 | instead of leaving it up to someone debugging it | |
12884 | to know to turn on special compiler options | |
12885 | that might diagnose it. | |
12886 | ||
5ff904cd JL |
12887 | @node Order of Side Effects |
12888 | @subsection Order of Side Effects | |
12889 | @cindex side effects, order of evaluation | |
12890 | @cindex order of evaluation, side effects | |
12891 | ||
12892 | @code{g77} does not necessarily produce code that, when run, performs | |
12893 | side effects (such as those performed by function invocations) | |
12894 | in the same order as in some other compiler---or even in the same | |
12895 | order as another version, port, or invocation (using different | |
12896 | command-line options) of @code{g77}. | |
12897 | ||
12898 | It is never safe to depend on the order of evaluation of side effects. | |
12899 | For example, an expression like this may very well behave differently | |
12900 | from one compiler to another: | |
12901 | ||
12902 | @smallexample | |
12903 | J = IFUNC() - IFUNC() | |
12904 | @end smallexample | |
12905 | ||
12906 | @noindent | |
12907 | There is no guarantee that @samp{IFUNC} will be evaluated in any particular | |
12908 | order. | |
12909 | Either invocation might happen first. | |
12910 | If @samp{IFUNC} returns 5 the first time it is invoked, and | |
12911 | returns 12 the second time, @samp{J} might end up with the | |
12912 | value @samp{7}, or it might end up with @samp{-7}. | |
12913 | ||
12914 | Generally, in Fortran, procedures with side-effects intended to | |
12915 | be visible to the caller are best designed as @emph{subroutines}, | |
12916 | not functions. | |
12917 | Examples of such side-effects include: | |
12918 | ||
12919 | @itemize @bullet | |
12920 | @item | |
12921 | The generation of random numbers | |
12922 | that are intended to influence return values. | |
12923 | ||
12924 | @item | |
12925 | Performing I/O | |
12926 | (other than internal I/O to local variables). | |
12927 | ||
12928 | @item | |
12929 | Updating information in common blocks. | |
12930 | @end itemize | |
12931 | ||
12932 | An example of a side-effect that is not intended to be visible | |
12933 | to the caller is a function that maintains a cache of recently | |
12934 | calculated results, intended solely to speed repeated invocations | |
12935 | of the function with identical arguments. | |
12936 | Such a function can be safely used in expressions, because | |
12937 | if the compiler optimizes away one or more calls to the | |
12938 | function, operation of the program is unaffected (aside | |
12939 | from being speeded up). | |
12940 | ||
12941 | @node Warnings and Errors | |
12942 | @section Warning Messages and Error Messages | |
12943 | ||
12944 | @cindex error messages | |
12945 | @cindex warnings vs errors | |
12946 | @cindex messages, warning and error | |
12947 | The GNU compiler can produce two kinds of diagnostics: errors and | |
12948 | warnings. | |
12949 | Each kind has a different purpose: | |
12950 | ||
12951 | @itemize @w{} | |
66d18ad7 | 12952 | @item |
5ff904cd JL |
12953 | @emph{Errors} report problems that make it impossible to compile your |
12954 | program. | |
12955 | GNU Fortran reports errors with the source file name, line | |
12956 | number, and column within the line where the problem is apparent. | |
12957 | ||
12958 | @item | |
12959 | @emph{Warnings} report other unusual conditions in your code that | |
12960 | @emph{might} indicate a problem, although compilation can (and does) | |
12961 | proceed. | |
12962 | Warning messages also report the source file name, line number, | |
12963 | and column information, | |
12964 | but include the text @samp{warning:} to distinguish them | |
12965 | from error messages. | |
12966 | @end itemize | |
12967 | ||
12968 | Warnings might indicate danger points where you should check to make sure | |
12969 | that your program really does what you intend; or the use of obsolete | |
12970 | features; or the use of nonstandard features of GNU Fortran. | |
12971 | Many warnings are issued only if you ask for them, with one of the | |
12972 | @samp{-W} options (for instance, @samp{-Wall} requests a variety of | |
12973 | useful warnings). | |
12974 | ||
12975 | @emph{Note:} Currently, the text of the line and a pointer to the column | |
12976 | is printed in most @code{g77} diagnostics. | |
12977 | Probably, as of version 0.6, @code{g77} will | |
12978 | no longer print the text of the source line, instead printing | |
12979 | the column number following the file name and line number in | |
12980 | a form that GNU Emacs recognizes. | |
12981 | This change is expected to speed up and reduce the memory usage | |
12982 | of the @code{g77} compiler. | |
12983 | @c | |
12984 | @c Say this when it is true -- hopefully 0.6, maybe 0.7 or later. --burley | |
12985 | @c | |
12986 | @c GNU Fortran always tries to compile your program if possible; it never | |
12987 | @c gratuitously rejects a program whose meaning is clear merely because | |
12988 | @c (for instance) it fails to conform to a standard. In some cases, | |
12989 | @c however, the Fortran standard specifies that certain extensions are | |
12990 | @c forbidden, and a diagnostic @emph{must} be issued by a conforming | |
12991 | @c compiler. The @samp{-pedantic} option tells GNU Fortran to issue warnings | |
12992 | @c in such cases; @samp{-pedantic-errors} says to make them errors instead. | |
12993 | @c This does not mean that @emph{all} non-ANSI constructs get warnings | |
12994 | @c or errors. | |
12995 | ||
12996 | @xref{Warning Options,,Options to Request or Suppress Warnings}, for | |
12997 | more detail on these and related command-line options. | |
12998 | ||
12999 | @node Open Questions | |
13000 | @chapter Open Questions | |
13001 | ||
13002 | Please consider offering useful answers to these questions! | |
13003 | ||
13004 | @itemize @bullet | |
5ff904cd JL |
13005 | @item |
13006 | @code{LOC()} and other intrinsics are probably somewhat misclassified. | |
13007 | Is the a need for more precise classification of intrinsics, and if so, | |
13008 | what are the appropriate groupings? | |
13009 | Is there a need to individually | |
13010 | enable/disable/delete/hide intrinsics from the command line? | |
13011 | @end itemize | |
13012 | ||
13013 | @node Bugs | |
13014 | @chapter Reporting Bugs | |
13015 | @cindex bugs | |
13016 | @cindex reporting bugs | |
13017 | ||
13018 | Your bug reports play an essential role in making GNU Fortran reliable. | |
13019 | ||
13020 | When you encounter a problem, the first thing to do is to see if it is | |
13021 | already known. | |
13022 | @xref{Trouble}. | |
13023 | If it isn't known, then you should report the problem. | |
13024 | ||
13025 | Reporting a bug might help you by bringing a solution to your problem, or | |
13026 | it might not. | |
13027 | (If it does not, look in the service directory; see | |
95a1b676 | 13028 | @ref{Service}.) |
5ff904cd JL |
13029 | In any case, the principal function of a bug report is |
13030 | to help the entire community by making the next version of GNU Fortran work | |
13031 | better. | |
13032 | Bug reports are your contribution to the maintenance of GNU Fortran. | |
13033 | ||
13034 | Since the maintainers are very overloaded, we cannot respond to every | |
13035 | bug report. | |
13036 | However, if the bug has not been fixed, we are likely to | |
66d18ad7 | 13037 | send you a patch and ask you to tell us whether it works. |
5ff904cd JL |
13038 | |
13039 | In order for a bug report to serve its purpose, you must include the | |
13040 | information that makes for fixing the bug. | |
13041 | ||
13042 | @menu | |
13043 | * Criteria: Bug Criteria. Have you really found a bug? | |
13044 | * Where: Bug Lists. Where to send your bug report. | |
13045 | * Reporting: Bug Reporting. How to report a bug effectively. | |
13046 | * Patches: Sending Patches. How to send a patch for GNU Fortran. | |
13047 | @end menu | |
13048 | ||
13049 | @xref{Trouble,,Known Causes of Trouble with GNU Fortran}, | |
13050 | for information on problems we already know about. | |
13051 | ||
13052 | @xref{Service,,How To Get Help with GNU Fortran}, | |
13053 | for information on where to ask for help. | |
13054 | ||
13055 | @node Bug Criteria | |
13056 | @section Have You Found a Bug? | |
13057 | @cindex bug criteria | |
13058 | ||
13059 | If you are not sure whether you have found a bug, here are some guidelines: | |
13060 | ||
13061 | @itemize @bullet | |
13062 | @cindex fatal signal | |
13063 | @cindex core dump | |
13064 | @item | |
13065 | If the compiler gets a fatal signal, for any input whatever, that is a | |
13066 | compiler bug. | |
13067 | Reliable compilers never crash---they just remain obsolete. | |
13068 | ||
13069 | @cindex invalid assembly code | |
13070 | @cindex assembly code, invalid | |
13071 | @item | |
13072 | If the compiler produces invalid assembly code, for any input whatever, | |
13073 | @c (except an @code{asm} statement), | |
13074 | that is a compiler bug, unless the | |
13075 | compiler reports errors (not just warnings) which would ordinarily | |
13076 | prevent the assembler from being run. | |
13077 | ||
13078 | @cindex undefined behavior | |
13079 | @cindex undefined function value | |
13080 | @item | |
13081 | If the compiler produces valid assembly code that does not correctly | |
13082 | execute the input source code, that is a compiler bug. | |
13083 | ||
13084 | However, you must double-check to make sure, because you might have run | |
13085 | into an incompatibility between GNU Fortran and traditional Fortran. | |
13086 | @c (@pxref{Incompatibilities}). | |
13087 | These incompatibilities might be considered | |
13088 | bugs, but they are inescapable consequences of valuable features. | |
13089 | ||
13090 | Or you might have a program whose behavior is undefined, which happened | |
13091 | by chance to give the desired results with another Fortran compiler. | |
13092 | It is best to check the relevant Fortran standard thoroughly if | |
13093 | it is possible that the program indeed does something undefined. | |
13094 | ||
13095 | After you have localized the error to a single source line, it should | |
13096 | be easy to check for these things. | |
13097 | If your program is correct and well defined, you have found | |
13098 | a compiler bug. | |
13099 | ||
13100 | It might help if, in your submission, you identified the specific | |
13101 | language in the relevant Fortran standard that specifies the | |
13102 | desired behavior, if it isn't likely to be obvious and agreed-upon | |
13103 | by all Fortran users. | |
13104 | ||
13105 | @item | |
13106 | If the compiler produces an error message for valid input, that is a | |
13107 | compiler bug. | |
13108 | ||
13109 | @cindex invalid input | |
13110 | @item | |
13111 | If the compiler does not produce an error message for invalid input, | |
13112 | that is a compiler bug. | |
13113 | However, you should note that your idea of | |
13114 | ``invalid input'' might be someone else's idea | |
13115 | of ``an extension'' or ``support for traditional practice''. | |
13116 | ||
13117 | @item | |
13118 | If you are an experienced user of Fortran compilers, your suggestions | |
13119 | for improvement of GNU Fortran are welcome in any case. | |
13120 | @end itemize | |
13121 | ||
795232f7 JL |
13122 | Many, perhaps most, bug reports against @code{g77} turn out to |
13123 | be bugs in the user's code. | |
13124 | While we find such bug reports educational, they sometimes take | |
13125 | a considerable amount of time to track down or at least respond | |
13126 | to---time we could be spending making @code{g77}, not some user's | |
13127 | code, better. | |
13128 | ||
13129 | Some steps you can take to verify that the bug is not certainly | |
13130 | in the code you're compiling with @code{g77}: | |
13131 | ||
13132 | @itemize @bullet | |
13133 | @item | |
13134 | Compile your code using the @code{g77} options @samp{-W -Wall -O}. | |
13135 | These options enable many useful warning; the @samp{-O} option | |
13136 | enables flow analysis that enables the uninitialized-variable | |
13137 | warning. | |
13138 | ||
13139 | If you investigate the warnings and find evidence of possible bugs | |
13140 | in your code, fix them first and retry @code{g77}. | |
13141 | ||
13142 | @item | |
13143 | Compile your code using the @code{g77} options @samp{-finit-local-zero}, | |
13144 | @samp{-fno-automatic}, @samp{-ffloat-store}, and various | |
13145 | combinations thereof. | |
13146 | ||
13147 | If your code works with any of these combinations, that is not | |
13148 | proof that the bug isn't in @code{g77}---a @code{g77} bug exposed | |
13149 | by your code might simply be avoided, or have a different, more subtle | |
13150 | effect, when different options are used---but it can be a | |
46511dd5 | 13151 | strong indicator that your code is making unwarranted assumptions |
795232f7 JL |
13152 | about the Fortran dialect and/or underlying machine it is |
13153 | being compiled and run on. | |
13154 | ||
13155 | @xref{Overly Convenient Options,,Overly Convenient Command-Line Options}, | |
13156 | for information on the @samp{-fno-automatic} and | |
13157 | @samp{-finit-local-zero} options and how to convert | |
13158 | their use into selective changes in your own code. | |
13159 | ||
13160 | @item | |
46511dd5 | 13161 | @pindex ftnchek |
795232f7 JL |
13162 | Validate your code with @code{ftnchek} or a similar code-checking |
13163 | tool. | |
46511dd5 | 13164 | @code{ftnchek} can be found at @uref{ftp://ftp.netlib.org/fortran} |
95a1b676 | 13165 | or @uref{ftp://ftp.dsm.fordham.edu}. |
56a0044b JL |
13166 | |
13167 | @pindex make | |
13168 | @cindex Makefile example | |
13169 | Here are some sample @file{Makefile} rules using @code{ftnchek} | |
13170 | ``project'' files to do cross-file checking and @code{sfmakedepend} | |
95a1b676 | 13171 | (from @uref{ftp://ahab.rutgers.edu/pub/perl/sfmakedepend}) |
56a0044b JL |
13172 | to maintain dependencies automatically. |
13173 | These assume the use of GNU @code{make}. | |
13174 | ||
13175 | @smallexample | |
13176 | # Dummy suffix for ftnchek targets: | |
13177 | .SUFFIXES: .chek | |
13178 | .PHONY: chekall | |
13179 | ||
13180 | # How to compile .f files (for implicit rule): | |
13181 | FC = g77 | |
13182 | # Assume `include' directory: | |
13183 | FFLAGS = -Iinclude -g -O -Wall | |
13184 | ||
13185 | # Flags for ftnchek: | |
13186 | CHEK1 = -array=0 -include=includes -noarray | |
13187 | CHEK2 = -nonovice -usage=1 -notruncation | |
13188 | CHEKFLAGS = $(CHEK1) $(CHEK2) | |
13189 | ||
13190 | # Run ftnchek with all the .prj files except the one corresponding | |
13191 | # to the target's root: | |
13192 | %.chek : %.f ; \ | |
13193 | ftnchek $(filter-out $*.prj,$(PRJS)) $(CHEKFLAGS) \ | |
13194 | -noextern -library $< | |
13195 | ||
13196 | # Derive a project file from a source file: | |
13197 | %.prj : %.f ; \ | |
13198 | ftnchek $(CHEKFLAGS) -noextern -project -library $< | |
13199 | ||
13200 | # The list of objects is assumed to be in variable OBJS. | |
13201 | # Sources corresponding to the objects: | |
13202 | SRCS = $(OBJS:%.o=%.f) | |
13203 | # ftnchek project files: | |
13204 | PRJS = $(OBJS:%.o=%.prj) | |
13205 | ||
13206 | # Build the program | |
13207 | prog: $(OBJS) ; \ | |
13208 | $(FC) -o $@ $(OBJS) | |
13209 | ||
13210 | chekall: $(PRJS) ; \ | |
13211 | ftnchek $(CHEKFLAGS) $(PRJS) | |
13212 | ||
13213 | prjs: $(PRJS) | |
13214 | ||
13215 | # For Emacs M-x find-tag: | |
13216 | TAGS: $(SRCS) ; \ | |
13217 | etags $(SRCS) | |
13218 | ||
13219 | # Rebuild dependencies: | |
13220 | depend: ; \ | |
13221 | sfmakedepend -I $(PLTLIBDIR) -I includes -a prj $(SRCS1) | |
13222 | @end smallexample | |
795232f7 JL |
13223 | |
13224 | @item | |
13225 | Try your code out using other Fortran compilers, such as @code{f2c}. | |
13226 | If it does not work on at least one other compiler (assuming the | |
13227 | compiler supports the features the code needs), that is a strong | |
13228 | indicator of a bug in the code. | |
13229 | ||
13230 | However, even if your code works on many compilers @emph{except} | |
13231 | @code{g77}, that does @emph{not} mean the bug is in @code{g77}. | |
13232 | It might mean the bug is in your code, and that @code{g77} simply | |
13233 | exposes it more readily than other compilers. | |
13234 | @end itemize | |
13235 | ||
5ff904cd JL |
13236 | @node Bug Lists |
13237 | @section Where to Report Bugs | |
13238 | @cindex bug report mailing lists | |
9a59ff4f CB |
13239 | @kindex @value{email-bugs} |
13240 | Send bug reports for GNU Fortran to @email{@value{email-bugs}}. | |
5ff904cd JL |
13241 | |
13242 | Often people think of posting bug reports to a newsgroup instead of | |
13243 | mailing them. | |
13244 | This sometimes appears to work, but it has one problem which can be | |
13245 | crucial: a newsgroup posting does not contain a mail path back to the | |
13246 | sender. | |
13247 | Thus, if maintainers need more information, they might be unable | |
13248 | to reach you. For this reason, you should always send bug reports by | |
13249 | mail to the proper mailing list. | |
13250 | ||
13251 | As a last resort, send bug reports on paper to: | |
13252 | ||
13253 | @example | |
13254 | GNU Compiler Bugs | |
13255 | Free Software Foundation | |
13256 | 59 Temple Place - Suite 330 | |
13257 | Boston, MA 02111-1307, USA | |
13258 | @end example | |
13259 | ||
13260 | @node Bug Reporting | |
13261 | @section How to Report Bugs | |
13262 | @cindex compiler bugs, reporting | |
13263 | ||
13264 | The fundamental principle of reporting bugs usefully is this: | |
13265 | @strong{report all the facts}. | |
13266 | If you are not sure whether to state a | |
13267 | fact or leave it out, state it! | |
13268 | ||
13269 | Often people omit facts because they think they know what causes the | |
13270 | problem and they conclude that some details don't matter. | |
13271 | Thus, you might | |
13272 | assume that the name of the variable you use in an example does not matter. | |
13273 | Well, probably it doesn't, but one cannot be sure. | |
13274 | Perhaps the bug is a | |
13275 | stray memory reference which happens to fetch from the location where that | |
13276 | name is stored in memory; perhaps, if the name were different, the contents | |
13277 | of that location would fool the compiler into doing the right thing despite | |
13278 | the bug. | |
13279 | Play it safe and give a specific, complete example. | |
13280 | That is the | |
13281 | easiest thing for you to do, and the most helpful. | |
13282 | ||
13283 | Keep in mind that the purpose of a bug report is to enable someone to | |
13284 | fix the bug if it is not known. | |
13285 | It isn't very important what happens if | |
13286 | the bug is already known. | |
13287 | Therefore, always write your bug reports on | |
13288 | the assumption that the bug is not known. | |
13289 | ||
13290 | Sometimes people give a few sketchy facts and ask, ``Does this ring a | |
13291 | bell?'' | |
13292 | This cannot help us fix a bug, so it is rarely helpful. | |
13293 | We respond by asking for enough details to enable us to investigate. | |
13294 | You might as well expedite matters by sending them to begin with. | |
13295 | (Besides, there are enough bells ringing around here as it is.) | |
13296 | ||
13297 | Try to make your bug report self-contained. | |
13298 | If we have to ask you for | |
13299 | more information, it is best if you include all the previous information | |
13300 | in your response, as well as the information that was missing. | |
13301 | ||
13302 | Please report each bug in a separate message. | |
13303 | This makes it easier for | |
13304 | us to track which bugs have been fixed and to forward your bugs reports | |
13305 | to the appropriate maintainer. | |
13306 | ||
13307 | Do not compress and encode any part of your bug report using programs | |
13308 | such as @file{uuencode}. | |
13309 | If you do so it will slow down the processing | |
13310 | of your bug. | |
13311 | If you must submit multiple large files, use @file{shar}, | |
13312 | which allows us to read your message without having to run any | |
13313 | decompression programs. | |
13314 | ||
13315 | (As a special exception for GNU Fortran bug-reporting, at least | |
13316 | for now, if you are sending more than a few lines of code, if | |
13317 | your program's source file format contains ``interesting'' things | |
13318 | like trailing spaces or strange characters, or if you need to | |
13319 | include binary data files, it is acceptable to put all the | |
13320 | files together in a @code{tar} archive, and, whether you need to | |
13321 | do that, it is acceptable to then compress the single file (@code{tar} | |
13322 | archive or source file) | |
13323 | using @code{gzip} and encode it via @code{uuencode}. | |
13324 | Do not use any MIME stuff---the current maintainer can't decode this. | |
13325 | Using @code{compress} instead of @code{gzip} is acceptable, assuming | |
13326 | you have licensed the use of the patented algorithm in | |
13327 | @code{compress} from Unisys.) | |
13328 | ||
13329 | To enable someone to investigate the bug, you should include all these | |
13330 | things: | |
13331 | ||
13332 | @itemize @bullet | |
13333 | @item | |
13334 | The version of GNU Fortran. | |
13335 | You can get this by running @code{g77} with the @samp{-v} option. | |
13336 | (Ignore any error messages that might be displayed | |
13337 | when the linker is run.) | |
13338 | ||
13339 | Without this, we won't know whether there is any point in looking for | |
13340 | the bug in the current version of GNU Fortran. | |
13341 | ||
13342 | @item | |
13343 | @cindex preprocessor | |
13344 | @cindex cpp program | |
13345 | @cindex programs, cpp | |
58dd1c34 | 13346 | @pindex cpp |
5ff904cd | 13347 | A complete input file that will reproduce the bug. |
1d770e13 CB |
13348 | |
13349 | If your source file(s) require preprocessing | |
13350 | (for example, their names have suffixes like | |
13351 | @samp{.F}, @samp{.fpp}, @samp{.FPP}, and @samp{.r}), | |
13352 | and the bug is in the compiler proper (@file{f771}) | |
13353 | or in a subsequent phase of processing, | |
13354 | run your source file through the C preprocessor | |
13355 | by doing @samp{g77 -E @var{sourcefile} > @var{newfile}}. | |
13356 | Then, include the contents of @var{newfile} in the bug report. | |
13357 | (When you do this, use the same preprocessor options---such as | |
13358 | @samp{-I}, @samp{-D}, and @samp{-U}---that you used in actual | |
5ff904cd JL |
13359 | compilation.) |
13360 | ||
13361 | A single statement is not enough of an example. | |
13362 | In order to compile it, | |
1d770e13 CB |
13363 | it must be embedded in a complete file of compiler input. |
13364 | The bug might depend on the details of how this is done. | |
13365 | ||
13366 | Without a real example one can compile, | |
13367 | all anyone can do about your bug report is wish you luck. | |
13368 | It would be futile to try to guess how to provoke the bug. | |
13369 | For example, bugs in register allocation and reloading | |
13370 | can depend on every little detail of the source and include files | |
13371 | that trigger them. | |
5ff904cd JL |
13372 | |
13373 | @item | |
13374 | @cindex included files | |
13375 | @cindex INCLUDE directive | |
13376 | @cindex directive, INCLUDE | |
13377 | @cindex #include directive | |
13378 | @cindex directive, #include | |
13379 | Note that you should include with your bug report any files | |
13380 | included by the source file | |
13381 | (via the @code{#include} or @code{INCLUDE} directive) | |
13382 | that you send, and any files they include, and so on. | |
13383 | ||
13384 | It is not necessary to replace | |
13385 | the @code{#include} and @code{INCLUDE} directives | |
13386 | with the actual files in the version of the source file that | |
13387 | you send, but it might make submitting the bug report easier | |
13388 | in the end. | |
13389 | However, be sure to @emph{reproduce} the bug using the @emph{exact} | |
13390 | version of the source material you submit, to avoid wild-goose | |
13391 | chases. | |
13392 | ||
13393 | @item | |
13394 | The command arguments you gave GNU Fortran to compile that example | |
13395 | and observe the bug. For example, did you use @samp{-O}? To guarantee | |
13396 | you won't omit something important, list all the options. | |
13397 | ||
13398 | If we were to try to guess the arguments, we would probably guess wrong | |
13399 | and then we would not encounter the bug. | |
13400 | ||
13401 | @item | |
13402 | The type of machine you are using, and the operating system name and | |
13403 | version number. | |
13404 | (Much of this information is printed by @samp{g77 -v}---if you | |
13405 | include that, send along any additional info you have that you | |
13406 | don't see clearly represented in that output.) | |
13407 | ||
13408 | @item | |
13409 | The operands you gave to the @code{configure} command when you installed | |
13410 | the compiler. | |
13411 | ||
13412 | @item | |
13413 | A complete list of any modifications you have made to the compiler | |
13414 | source. (We don't promise to investigate the bug unless it happens in | |
13415 | an unmodified compiler. But if you've made modifications and don't tell | |
13416 | us, then you are sending us on a wild-goose chase.) | |
13417 | ||
13418 | Be precise about these changes. A description in English is not | |
13419 | enough---send a context diff for them. | |
13420 | ||
13421 | Adding files of your own (such as a machine description for a machine we | |
13422 | don't support) is a modification of the compiler source. | |
13423 | ||
13424 | @item | |
13425 | Details of any other deviations from the standard procedure for installing | |
13426 | GNU Fortran. | |
13427 | ||
13428 | @item | |
13429 | A description of what behavior you observe that you believe is | |
13430 | incorrect. For example, ``The compiler gets a fatal signal,'' or, | |
13431 | ``The assembler instruction at line 208 in the output is incorrect.'' | |
13432 | ||
13433 | Of course, if the bug is that the compiler gets a fatal signal, then one | |
13434 | can't miss it. But if the bug is incorrect output, the maintainer might | |
13435 | not notice unless it is glaringly wrong. None of us has time to study | |
13436 | all the assembler code from a 50-line Fortran program just on the chance that | |
13437 | one instruction might be wrong. We need @emph{you} to do this part! | |
13438 | ||
13439 | Even if the problem you experience is a fatal signal, you should still | |
13440 | say so explicitly. Suppose something strange is going on, such as, your | |
13441 | copy of the compiler is out of synch, or you have encountered a bug in | |
13442 | the C library on your system. (This has happened!) Your copy might | |
13443 | crash and the copy here would not. If you @i{said} to expect a crash, | |
13444 | then when the compiler here fails to crash, we would know that the bug | |
13445 | was not happening. If you don't say to expect a crash, then we would | |
13446 | not know whether the bug was happening. We would not be able to draw | |
13447 | any conclusion from our observations. | |
13448 | ||
13449 | If the problem is a diagnostic when building GNU Fortran with some other | |
13450 | compiler, say whether it is a warning or an error. | |
13451 | ||
13452 | Often the observed symptom is incorrect output when your program is run. | |
13453 | Sad to say, this is not enough information unless the program is short | |
13454 | and simple. None of us has time to study a large program to figure out | |
13455 | how it would work if compiled correctly, much less which line of it was | |
13456 | compiled wrong. So you will have to do that. Tell us which source line | |
13457 | it is, and what incorrect result happens when that line is executed. A | |
13458 | person who understands the program can find this as easily as finding a | |
13459 | bug in the program itself. | |
13460 | ||
13461 | @item | |
13462 | If you send examples of assembler code output from GNU Fortran, | |
13463 | please use @samp{-g} when you make them. The debugging information | |
13464 | includes source line numbers which are essential for correlating the | |
13465 | output with the input. | |
13466 | ||
13467 | @item | |
13468 | If you wish to mention something in the GNU Fortran source, refer to it by | |
13469 | context, not by line number. | |
13470 | ||
13471 | The line numbers in the development sources don't match those in your | |
13472 | sources. Your line numbers would convey no convenient information to the | |
13473 | maintainers. | |
13474 | ||
13475 | @item | |
13476 | Additional information from a debugger might enable someone to find a | |
13477 | problem on a machine which he does not have available. However, you | |
13478 | need to think when you collect this information if you want it to have | |
13479 | any chance of being useful. | |
13480 | ||
13481 | @cindex backtrace for bug reports | |
13482 | For example, many people send just a backtrace, but that is never | |
13483 | useful by itself. A simple backtrace with arguments conveys little | |
13484 | about GNU Fortran because the compiler is largely data-driven; the same | |
13485 | functions are called over and over for different RTL insns, doing | |
13486 | different things depending on the details of the insn. | |
13487 | ||
13488 | Most of the arguments listed in the backtrace are useless because they | |
13489 | are pointers to RTL list structure. The numeric values of the | |
13490 | pointers, which the debugger prints in the backtrace, have no | |
13491 | significance whatever; all that matters is the contents of the objects | |
13492 | they point to (and most of the contents are other such pointers). | |
13493 | ||
13494 | In addition, most compiler passes consist of one or more loops that | |
13495 | scan the RTL insn sequence. The most vital piece of information about | |
13496 | such a loop---which insn it has reached---is usually in a local variable, | |
13497 | not in an argument. | |
13498 | ||
13499 | @findex debug_rtx | |
13500 | What you need to provide in addition to a backtrace are the values of | |
13501 | the local variables for several stack frames up. When a local | |
13502 | variable or an argument is an RTX, first print its value and then use | |
13503 | the GDB command @code{pr} to print the RTL expression that it points | |
13504 | to. (If GDB doesn't run on your machine, use your debugger to call | |
13505 | the function @code{debug_rtx} with the RTX as an argument.) In | |
13506 | general, whenever a variable is a pointer, its value is no use | |
13507 | without the data it points to. | |
13508 | @end itemize | |
13509 | ||
13510 | Here are some things that are not necessary: | |
13511 | ||
13512 | @itemize @bullet | |
13513 | @item | |
13514 | A description of the envelope of the bug. | |
13515 | ||
13516 | Often people who encounter a bug spend a lot of time investigating | |
13517 | which changes to the input file will make the bug go away and which | |
13518 | changes will not affect it. | |
13519 | ||
13520 | This is often time consuming and not very useful, because the way we | |
13521 | will find the bug is by running a single example under the debugger with | |
13522 | breakpoints, not by pure deduction from a series of examples. You might | |
13523 | as well save your time for something else. | |
13524 | ||
13525 | Of course, if you can find a simpler example to report @emph{instead} of | |
13526 | the original one, that is a convenience. Errors in the output will be | |
13527 | easier to spot, running under the debugger will take less time, etc. | |
13528 | Most GNU Fortran bugs involve just one function, so the most straightforward | |
13529 | way to simplify an example is to delete all the function definitions | |
13530 | except the one where the bug occurs. Those earlier in the file may be | |
13531 | replaced by external declarations if the crucial function depends on | |
13532 | them. (Exception: inline functions might affect compilation of functions | |
13533 | defined later in the file.) | |
13534 | ||
13535 | However, simplification is not vital; if you don't want to do this, | |
13536 | report the bug anyway and send the entire test case you used. | |
13537 | ||
13538 | @item | |
13539 | In particular, some people insert conditionals @samp{#ifdef BUG} around | |
13540 | a statement which, if removed, makes the bug not happen. These are just | |
13541 | clutter; we won't pay any attention to them anyway. Besides, you should | |
13542 | send us preprocessor output, and that can't have conditionals. | |
13543 | ||
13544 | @item | |
13545 | A patch for the bug. | |
13546 | ||
13547 | A patch for the bug is useful if it is a good one. But don't omit the | |
13548 | necessary information, such as the test case, on the assumption that a | |
13549 | patch is all we need. We might see problems with your patch and decide | |
13550 | to fix the problem another way, or we might not understand it at all. | |
13551 | ||
13552 | Sometimes with a program as complicated as GNU Fortran it is very hard to | |
13553 | construct an example that will make the program follow a certain path | |
13554 | through the code. If you don't send the example, we won't be able to | |
13555 | construct one, so we won't be able to verify that the bug is fixed. | |
13556 | ||
13557 | And if we can't understand what bug you are trying to fix, or why your | |
13558 | patch should be an improvement, we won't install it. A test case will | |
13559 | help us to understand. | |
13560 | ||
13561 | @xref{Sending Patches}, for guidelines on how to make it easy for us to | |
13562 | understand and install your patches. | |
13563 | ||
13564 | @item | |
13565 | A guess about what the bug is or what it depends on. | |
13566 | ||
13567 | Such guesses are usually wrong. Even the maintainer can't guess right | |
13568 | about such things without first using the debugger to find the facts. | |
13569 | ||
13570 | @item | |
13571 | A core dump file. | |
13572 | ||
13573 | We have no way of examining a core dump for your type of machine | |
13574 | unless we have an identical system---and if we do have one, | |
13575 | we should be able to reproduce the crash ourselves. | |
13576 | @end itemize | |
13577 | ||
13578 | @node Sending Patches | |
13579 | @section Sending Patches for GNU Fortran | |
13580 | ||
13581 | If you would like to write bug fixes or improvements for the GNU Fortran | |
13582 | compiler, that is very helpful. | |
13583 | Send suggested fixes to the bug report | |
9a59ff4f | 13584 | mailing list, @email{@value{email-bugs}}. |
5ff904cd JL |
13585 | |
13586 | Please follow these guidelines so we can study your patches efficiently. | |
13587 | If you don't follow these guidelines, your information might still be | |
13588 | useful, but using it will take extra work. Maintaining GNU Fortran is a lot | |
13589 | of work in the best of circumstances, and we can't keep up unless you do | |
13590 | your best to help. | |
13591 | ||
13592 | @itemize @bullet | |
13593 | @item | |
13594 | Send an explanation with your changes of what problem they fix or what | |
13595 | improvement they bring about. For a bug fix, just include a copy of the | |
13596 | bug report, and explain why the change fixes the bug. | |
13597 | ||
13598 | (Referring to a bug report is not as good as including it, because then | |
13599 | we will have to look it up, and we have probably already deleted it if | |
13600 | we've already fixed the bug.) | |
13601 | ||
13602 | @item | |
13603 | Always include a proper bug report for the problem you think you have | |
13604 | fixed. We need to convince ourselves that the change is right before | |
13605 | installing it. Even if it is right, we might have trouble judging it if | |
13606 | we don't have a way to reproduce the problem. | |
13607 | ||
13608 | @item | |
13609 | Include all the comments that are appropriate to help people reading the | |
13610 | source in the future understand why this change was needed. | |
13611 | ||
13612 | @item | |
13613 | Don't mix together changes made for different reasons. | |
13614 | Send them @emph{individually}. | |
13615 | ||
13616 | If you make two changes for separate reasons, then we might not want to | |
13617 | install them both. We might want to install just one. If you send them | |
13618 | all jumbled together in a single set of diffs, we have to do extra work | |
13619 | to disentangle them---to figure out which parts of the change serve | |
13620 | which purpose. If we don't have time for this, we might have to ignore | |
13621 | your changes entirely. | |
13622 | ||
13623 | If you send each change as soon as you have written it, with its own | |
13624 | explanation, then the two changes never get tangled up, and we can | |
13625 | consider each one properly without any extra work to disentangle them. | |
13626 | ||
13627 | Ideally, each change you send should be impossible to subdivide into | |
13628 | parts that we might want to consider separately, because each of its | |
13629 | parts gets its motivation from the other parts. | |
13630 | ||
13631 | @item | |
13632 | Send each change as soon as that change is finished. Sometimes people | |
13633 | think they are helping us by accumulating many changes to send them all | |
13634 | together. As explained above, this is absolutely the worst thing you | |
13635 | could do. | |
13636 | ||
13637 | Since you should send each change separately, you might as well send it | |
13638 | right away. That gives us the option of installing it immediately if it | |
13639 | is important. | |
13640 | ||
13641 | @item | |
13642 | Use @samp{diff -c} to make your diffs. Diffs without context are hard | |
13643 | for us to install reliably. More than that, they make it hard for us to | |
13644 | study the diffs to decide whether we want to install them. Unidiff | |
13645 | format is better than contextless diffs, but not as easy to read as | |
13646 | @samp{-c} format. | |
13647 | ||
13648 | If you have GNU @code{diff}, use @samp{diff -cp}, which shows the name of the | |
13649 | function that each change occurs in. | |
13650 | (The maintainer of GNU Fortran currently uses @samp{diff -rcp2N}.) | |
13651 | ||
13652 | @item | |
13653 | Write the change log entries for your changes. We get lots of changes, | |
13654 | and we don't have time to do all the change log writing ourselves. | |
13655 | ||
13656 | Read the @file{ChangeLog} file to see what sorts of information to put | |
13657 | in, and to learn the style that we use. The purpose of the change log | |
13658 | is to show people where to find what was changed. So you need to be | |
13659 | specific about what functions you changed; in large functions, it's | |
13660 | often helpful to indicate where within the function the change was. | |
13661 | ||
13662 | On the other hand, once you have shown people where to find the change, | |
13663 | you need not explain its purpose. Thus, if you add a new function, all | |
13664 | you need to say about it is that it is new. If you feel that the | |
13665 | purpose needs explaining, it probably does---but the explanation will be | |
13666 | much more useful if you put it in comments in the code. | |
13667 | ||
13668 | If you would like your name to appear in the header line for who made | |
13669 | the change, send us the header line. | |
13670 | ||
13671 | @item | |
13672 | When you write the fix, keep in mind that we can't install a change that | |
13673 | would break other systems. | |
13674 | ||
13675 | People often suggest fixing a problem by changing machine-independent | |
13676 | files such as @file{toplev.c} to do something special that a particular | |
13677 | system needs. Sometimes it is totally obvious that such changes would | |
13678 | break GNU Fortran for almost all users. We can't possibly make a change like | |
13679 | that. At best it might tell us how to write another patch that would | |
13680 | solve the problem acceptably. | |
13681 | ||
13682 | Sometimes people send fixes that @emph{might} be an improvement in | |
13683 | general---but it is hard to be sure of this. It's hard to install | |
13684 | such changes because we have to study them very carefully. Of course, | |
13685 | a good explanation of the reasoning by which you concluded the change | |
13686 | was correct can help convince us. | |
13687 | ||
13688 | The safest changes are changes to the configuration files for a | |
13689 | particular machine. These are safe because they can't create new bugs | |
13690 | on other machines. | |
13691 | ||
13692 | Please help us keep up with the workload by designing the patch in a | |
13693 | form that is good to install. | |
13694 | @end itemize | |
13695 | ||
13696 | @node Service | |
13697 | @chapter How To Get Help with GNU Fortran | |
13698 | ||
13699 | If you need help installing, using or changing GNU Fortran, there are two | |
13700 | ways to find it: | |
13701 | ||
13702 | @itemize @bullet | |
13703 | @item | |
13704 | Look in the service directory for someone who might help you for a fee. | |
13705 | The service directory is found in the file named @file{SERVICE} in the | |
13706 | GNU CC distribution. | |
13707 | ||
13708 | @item | |
9a59ff4f | 13709 | Send a message to @email{@value{email-general}}. |
5ff904cd JL |
13710 | @end itemize |
13711 | ||
13712 | @end ifset | |
13713 | @ifset INTERNALS | |
13714 | @node Adding Options | |
13715 | @chapter Adding Options | |
13716 | @cindex options, adding | |
13717 | @cindex adding options | |
13718 | ||
13719 | To add a new command-line option to @code{g77}, first decide | |
13720 | what kind of option you wish to add. | |
13721 | Search the @code{g77} and @code{gcc} documentation for one | |
13722 | or more options that is most closely like the one you want to add | |
13723 | (in terms of what kind of effect it has, and so on) to | |
13724 | help clarify its nature. | |
13725 | ||
13726 | @itemize @bullet | |
13727 | @item | |
13728 | @emph{Fortran options} are options that apply only | |
13729 | when compiling Fortran programs. | |
13730 | They are accepted by @code{g77} and @code{gcc}, but | |
13731 | they apply only when compiling Fortran programs. | |
13732 | ||
13733 | @item | |
13734 | @emph{Compiler options} are options that apply | |
13735 | when compiling most any kind of program. | |
13736 | @end itemize | |
13737 | ||
13738 | @emph{Fortran options} are listed in the file | |
9a59ff4f | 13739 | @file{@value{path-g77}/lang-options.h}, |
5ff904cd JL |
13740 | which is used during the build of @code{gcc} to |
13741 | build a list of all options that are accepted by | |
13742 | at least one language's compiler. | |
4e6a1440 | 13743 | This list goes into the @code{lang_options} array |
5ff904cd JL |
13744 | in @file{gcc/toplev.c}, which uses this array to |
13745 | determine whether a particular option should be | |
13746 | offered to the linked-in front end for processing | |
4e6a1440 | 13747 | by calling @code{lang_option_decode}, which, for |
9a59ff4f | 13748 | @code{g77}, is in @file{@value{path-g77}/com.c} and just |
4e6a1440 | 13749 | calls @code{ffe_decode_option}. |
5ff904cd JL |
13750 | |
13751 | If the linked-in front end ``rejects'' a | |
13752 | particular option passed to it, @file{toplev.c} | |
13753 | just ignores the option, because @emph{some} | |
13754 | language's compiler is willing to accept it. | |
13755 | ||
13756 | This allows commands like @samp{gcc -fno-asm foo.c bar.f} | |
13757 | to work, even though Fortran compilation does | |
13758 | not currently support the @samp{-fno-asm} option; | |
4e6a1440 | 13759 | even though the @code{f771} version of @code{lang_decode_option} |
5ff904cd JL |
13760 | rejects @samp{-fno-asm}, @file{toplev.c} doesn't |
13761 | produce a diagnostic because some other language (C) | |
13762 | does accept it. | |
13763 | ||
13764 | This also means that commands like | |
13765 | @samp{g77 -fno-asm foo.f} yield no diagnostics, | |
13766 | despite the fact that no phase of the command was | |
13767 | able to recognize and process @samp{-fno-asm}---perhaps | |
13768 | a warning about this would be helpful if it were | |
13769 | possible. | |
13770 | ||
13771 | Code that processes Fortran options is found in | |
4e6a1440 | 13772 | @file{@value{path-g77}/top.c}, function @code{ffe_decode_option}. |
5ff904cd JL |
13773 | This code needs to check positive and negative forms |
13774 | of each option. | |
13775 | ||
13776 | The defaults for Fortran options are set in their | |
9a59ff4f | 13777 | global definitions, also found in @file{@value{path-g77}/top.c}. |
5ff904cd | 13778 | Many of these defaults are actually macros defined |
9a59ff4f | 13779 | in @file{@value{path-g77}/target.h}, since they might be |
5ff904cd JL |
13780 | machine-specific. |
13781 | However, since, in practice, GNU compilers | |
13782 | should behave the same way on all configurations | |
13783 | (especially when it comes to language constructs), | |
13784 | the practice of setting defaults in @file{target.h} | |
13785 | is likely to be deprecated and, ultimately, stopped | |
13786 | in future versions of @code{g77}. | |
13787 | ||
13788 | Accessor macros for Fortran options, used by code | |
9a59ff4f | 13789 | in the @code{g77} FFE, are defined in @file{@value{path-g77}/top.h}. |
5ff904cd JL |
13790 | |
13791 | @emph{Compiler options} are listed in @file{gcc/toplev.c} | |
4e6a1440 CB |
13792 | in the array @code{f_options}. |
13793 | An option not listed in @code{lang_options} is | |
13794 | looked up in @code{f_options} and handled from there. | |
5ff904cd JL |
13795 | |
13796 | The defaults for compiler options are set in the | |
13797 | global definitions for the corresponding variables, | |
13798 | some of which are in @file{gcc/toplev.c}. | |
13799 | ||
13800 | You can set different defaults for @emph{Fortran-oriented} | |
13801 | or @emph{Fortran-reticent} compiler options by changing | |
d1c32ce1 CB |
13802 | the source code of @code{g77} and rebuilding. |
13803 | How to do this depends on the version of @code{g77}: | |
13804 | ||
13805 | @table @code | |
13806 | @item EGCS-1.0 | |
13807 | @itemx FSF | |
13808 | Change the way @code{f771} handles the @samp{-fset-g77-defaults} | |
5ff904cd JL |
13809 | option, which is always provided as the first option when |
13810 | called by @code{g77} or @code{gcc}. | |
13811 | ||
4e6a1440 | 13812 | This code is in @code{ffe_decode_options} in @file{@value{path-g77}/top.c}. |
5ff904cd JL |
13813 | Have it change just the variables that you want to default |
13814 | to a different setting for Fortran compiles compared to | |
13815 | compiles of other languages. | |
13816 | ||
13817 | The @samp{-fset-g77-defaults} option is passed to @code{f771} | |
13818 | automatically because of the specification information | |
9a59ff4f | 13819 | kept in @file{@value{path-g77}/lang-specs.h}. |
5ff904cd JL |
13820 | This file tells the @code{gcc} command how to recognize, |
13821 | in this case, Fortran source files (those to be preprocessed, | |
13822 | and those that are not), and further, how to invoke the | |
13823 | appropriate programs (including @code{f771}) to process | |
13824 | those source files. | |
13825 | ||
9a59ff4f | 13826 | It is in @file{@value{path-g77}/lang-specs.h} that @samp{-fset-g77-defaults}, |
5ff904cd JL |
13827 | @samp{-fversion}, and other options are passed, as appropriate, |
13828 | even when the user has not explicitly specified them. | |
13829 | Other ``internal'' options such as @samp{-quiet} also | |
13830 | are passed via this mechanism. | |
13831 | ||
d1c32ce1 CB |
13832 | @item EGCS-1.1 |
13833 | @itemx EGCS-1.2 | |
4e6a1440 | 13834 | Change the @code{lang_init_options} routine in @file{egcs/gcc/f/com.c}. |
d1c32ce1 CB |
13835 | |
13836 | (Note that these versions of @code{g77} | |
13837 | perform internal consistency checking automatically | |
13838 | when the @samp{-fversion} option is specified.) | |
13839 | @end table | |
13840 | ||
5ff904cd JL |
13841 | @node Projects |
13842 | @chapter Projects | |
13843 | @cindex projects | |
13844 | ||
13845 | If you want to contribute to @code{g77} by doing research, | |
13846 | design, specification, documentation, coding, or testing, | |
13847 | the following information should give you some ideas. | |
0b31330e DL |
13848 | More relevant information might be available from |
13849 | @uref{ftp://alpha.gnu.org/gnu/g77/projects/}. | |
5ff904cd JL |
13850 | |
13851 | @menu | |
13852 | * Efficiency:: Make @code{g77} itself compile code faster. | |
13853 | * Better Optimization:: Teach @code{g77} to generate faster code. | |
13854 | * Simplify Porting:: Make @code{g77} easier to configure, build, | |
13855 | and install. | |
13856 | * More Extensions:: Features many users won't know to ask for. | |
13857 | * Machine Model:: @code{g77} should better leverage @code{gcc}. | |
13858 | * Internals Documentation:: Make maintenance easier. | |
13859 | * Internals Improvements:: Make internals more robust. | |
13860 | * Better Diagnostics:: Make using @code{g77} on new code easier. | |
13861 | @end menu | |
13862 | ||
13863 | @node Efficiency | |
13864 | @section Improve Efficiency | |
13865 | @cindex efficiency | |
13866 | ||
13867 | Don't bother doing any performance analysis until most of the | |
13868 | following items are taken care of, because there's no question | |
13869 | they represent serious space/time problems, although some of | |
13870 | them show up only given certain kinds of (popular) input. | |
13871 | ||
13872 | @itemize @bullet | |
13873 | @item | |
4e6a1440 | 13874 | Improve @code{malloc} package and its uses to specify more info about |
5ff904cd JL |
13875 | memory pools and, where feasible, use obstacks to implement them. |
13876 | ||
13877 | @item | |
13878 | Skip over uninitialized portions of aggregate areas (arrays, | |
13879 | @code{COMMON} areas, @code{EQUIVALENCE} areas) so zeros need not be output. | |
13880 | This would reduce memory usage for large initialized aggregate | |
13881 | areas, even ones with only one initialized element. | |
13882 | ||
13883 | As of version 0.5.18, a portion of this item has already been | |
13884 | accomplished. | |
13885 | ||
13886 | @item | |
13887 | Prescan the statement (in @file{sta.c}) so that the nature of the statement | |
13888 | is determined as much as possible by looking entirely at its form, | |
13889 | and not looking at any context (previous statements, including types | |
13890 | of symbols). | |
13891 | This would allow ripping out of the statement-confirmation, | |
13892 | symbol retraction/confirmation, and diagnostic inhibition | |
13893 | mechanisms. | |
13894 | Plus, it would result in much-improved diagnostics. | |
13895 | For example, @samp{CALL some-intrinsic(@dots{})}, where the intrinsic | |
13896 | is not a subroutine intrinsic, would result actual error instead of the | |
13897 | unimplemented-statement catch-all. | |
13898 | ||
13899 | @item | |
13900 | Throughout @code{g77}, don't pass line/column pairs where | |
4e6a1440 CB |
13901 | a simple @code{ffewhere} type, which points to the error as much as is |
13902 | desired by the configuration, will do, and don't pass @code{ffelexToken} types | |
13903 | where a simple @code{ffewhere} type will do. | |
5ff904cd | 13904 | Then, allow new default |
4e6a1440 | 13905 | configuration of @code{ffewhere} such that the source line text is not |
5ff904cd JL |
13906 | preserved, and leave it to things like Emacs' next-error function |
13907 | to point to them (now that @samp{next-error} supports column, | |
13908 | or, perhaps, character-offset, numbers). | |
13909 | The change in calling sequences should improve performance somewhat, | |
13910 | as should not having to save source lines. | |
13911 | (Whether this whole | |
13912 | item will improve performance is questionable, but it should | |
13913 | improve maintainability.) | |
13914 | ||
13915 | @item | |
13916 | Handle @samp{DATA (A(I),I=1,1000000)/1000000*2/} more efficiently, especially | |
13917 | as regards the assembly output. | |
13918 | Some of this might require improving | |
13919 | the back end, but lots of improvement in space/time required in @code{g77} | |
13920 | itself can be fairly easily obtained without touching the back end. | |
13921 | Maybe type-conversion, where necessary, can be speeded up as well in | |
13922 | cases like the one shown (converting the @samp{2} into @samp{2.}). | |
13923 | ||
13924 | @item | |
13925 | If analysis shows it to be worthwhile, optimize @file{lex.c}. | |
13926 | ||
13927 | @item | |
13928 | Consider redesigning @file{lex.c} to not need any feedback | |
13929 | during tokenization, by keeping track of enough parse state on its | |
13930 | own. | |
13931 | @end itemize | |
13932 | ||
13933 | @node Better Optimization | |
13934 | @section Better Optimization | |
13935 | @cindex optimization, better | |
13936 | @cindex code generation, improving | |
13937 | ||
13938 | Much of this work should be put off until after @code{g77} has | |
13939 | all the features necessary for its widespread acceptance as a | |
13940 | useful F77 compiler. | |
13941 | However, perhaps this work can be done in parallel during | |
13942 | the feature-adding work. | |
13943 | ||
13944 | @itemize @bullet | |
13945 | @item | |
13946 | Do the equivalent of the trick of putting @samp{extern inline} in front | |
95a1b676 | 13947 | of every function definition in @code{libg2c} and #include'ing the resulting |
5ff904cd JL |
13948 | file in @code{f2c}+@code{gcc}---that is, inline all run-time-library functions |
13949 | that are at all worth inlining. | |
13950 | (Some of this has already been done, such as for integral exponentiation.) | |
13951 | ||
13952 | @item | |
13953 | When doing @samp{CHAR_VAR = CHAR_FUNC(@dots{})}, | |
13954 | and it's clear that types line up | |
4e6a1440 | 13955 | and @samp{CHAR_VAR} is addressable or not a @code{VAR_DECL}, |
5ff904cd JL |
13956 | make @samp{CHAR_VAR}, not a |
13957 | temporary, be the receiver for @samp{CHAR_FUNC}. | |
13958 | (This is now done for @code{COMPLEX} variables.) | |
13959 | ||
13960 | @item | |
13961 | Design and implement Fortran-specific optimizations that don't | |
13962 | really belong in the back end, or where the front end needs to | |
13963 | give the back end more info than it currently does. | |
13964 | ||
13965 | @item | |
13966 | Design and implement a new run-time library interface, with the | |
13967 | code going into @code{libgcc} so no special linking is required to | |
13968 | link Fortran programs using standard language features. | |
13969 | This library | |
13970 | would speed up lots of things, from I/O (using precompiled formats, | |
13971 | doing just one, or, at most, very few, calls for arrays or array sections, | |
13972 | and so on) to general computing (array/section implementations of | |
13973 | various intrinsics, implementation of commonly performed loops that | |
13974 | aren't likely to be optimally compiled otherwise, etc.). | |
13975 | ||
13976 | Among the important things the library would do are: | |
13977 | ||
13978 | @itemize @bullet | |
13979 | @item | |
13980 | Be a one-stop-shop-type | |
13981 | library, hence shareable and usable by all, in that what are now | |
95a1b676 | 13982 | library-build-time options in @code{libg2c} would be moved at least to the |
5ff904cd JL |
13983 | @code{g77} compile phase, if not to finer grains (such as choosing how |
13984 | list-directed I/O formatting is done by default at @code{OPEN} time, for | |
13985 | preconnected units via options or even statements in the main program | |
13986 | unit, maybe even on a per-I/O basis with appropriate pragma-like | |
13987 | devices). | |
13988 | @end itemize | |
13989 | ||
13990 | @item | |
13991 | Probably requiring the new library design, change interface to | |
13992 | normally have @code{COMPLEX} functions return their values in the way | |
13993 | @code{gcc} would if they were declared @code{__complex__ float}, | |
13994 | rather than using | |
13995 | the mechanism currently used by @code{CHARACTER} functions (whereby the | |
13996 | functions are compiled as returning void and their first arg is | |
13997 | a pointer to where to store the result). | |
13998 | (Don't append underscores to | |
13999 | external names for @code{COMPLEX} functions in some cases once @code{g77} uses | |
14000 | @code{gcc} rather than @code{f2c} calling conventions.) | |
14001 | ||
14002 | @item | |
4e6a1440 | 14003 | Do something useful with @code{doiter} references where possible. |
5ff904cd JL |
14004 | For example, @samp{CALL FOO(I)} cannot modify @samp{I} if within |
14005 | a @code{DO} loop that uses @samp{I} as the | |
14006 | iteration variable, and the back end might find that info useful | |
14007 | in determining whether it needs to read @samp{I} back into a register after | |
14008 | the call. | |
14009 | (It normally has to do that, unless it knows @samp{FOO} never | |
14010 | modifies its passed-by-reference argument, which is rarely the case | |
14011 | for Fortran-77 code.) | |
14012 | @end itemize | |
14013 | ||
14014 | @node Simplify Porting | |
14015 | @section Simplify Porting | |
14016 | @cindex porting, simplify | |
14017 | @cindex simplify porting | |
14018 | ||
14019 | Making @code{g77} easier to configure, port, build, and install, either | |
14020 | as a single-system compiler or as a cross-compiler, would be | |
14021 | very useful. | |
14022 | ||
14023 | @itemize @bullet | |
14024 | @item | |
95a1b676 | 14025 | A new library (replacing @code{libg2c}) should improve portability as well as |
5ff904cd JL |
14026 | produce more optimal code. |
14027 | Further, @code{g77} and the new library should | |
14028 | conspire to simplify naming of externals, such as by removing unnecessarily | |
14029 | added underscores, and to reduce/eliminate the possibility of naming | |
14030 | conflicts, while making debugger more straightforward. | |
14031 | ||
14032 | Also, it should | |
14033 | make multi-language applications more feasible, such as by providing | |
14034 | Fortran intrinsics that get Fortran unit numbers given C @code{FILE *} | |
14035 | descriptors. | |
14036 | ||
14037 | @item | |
14038 | Possibly related to a new library, @code{g77} should produce the equivalent | |
14039 | of a @code{gcc} @samp{main(argc, argv)} function when it compiles a | |
14040 | main program unit, instead of compiling something that must be | |
14041 | called by a library | |
14042 | implementation of @code{main()}. | |
14043 | ||
14044 | This would do many useful things such as | |
14045 | provide more flexibility in terms of setting up exception handling, | |
14046 | not requiring programmers to start their debugging sessions with | |
14047 | @kbd{breakpoint MAIN__} followed by @kbd{run}, and so on. | |
14048 | ||
14049 | @item | |
14050 | The GBE needs to understand the difference between alignment | |
14051 | requirements and desires. | |
14052 | For example, on Intel x86 machines, @code{g77} currently imposes | |
14053 | overly strict alignment requirements, due to the back end, but it | |
14054 | would be useful for Fortran and C programmers to be able to override | |
14055 | these @emph{recommendations} as long as they don't violate the actual | |
14056 | processor @emph{requirements}. | |
14057 | @end itemize | |
14058 | ||
14059 | @node More Extensions | |
14060 | @section More Extensions | |
14061 | @cindex extensions, more | |
14062 | ||
14063 | These extensions are not the sort of things users ask for ``by name'', | |
14064 | but they might improve the usability of @code{g77}, and Fortran in | |
14065 | general, in the long run. | |
14066 | Some of these items really pertain to improving @code{g77} internals | |
14067 | so that some popular extensions can be more easily supported. | |
14068 | ||
14069 | @itemize @bullet | |
14070 | @item | |
14071 | Look through all the documentation on the GNU Fortran language, | |
14072 | dialects, compiler, missing features, bugs, and so on. | |
14073 | Many mentions of incomplete or missing features are | |
14074 | sprinkled throughout. | |
14075 | It is not worth repeating them here. | |
14076 | ||
5ff904cd JL |
14077 | @item |
14078 | Consider adding a @code{NUMERIC} type to designate typeless numeric constants, | |
14079 | named and unnamed. | |
14080 | The idea is to provide a forward-looking, effective | |
14081 | replacement for things like the old-style @code{PARAMETER} statement | |
14082 | when people | |
14083 | really need typelessness in a maintainable, portable, clearly documented | |
14084 | way. | |
14085 | Maybe @code{TYPELESS} would include @code{CHARACTER}, @code{POINTER}, | |
14086 | and whatever else might come along. | |
14087 | (This is not really a call for polymorphism per se, just | |
14088 | an ability to express limited, syntactic polymorphism.) | |
14089 | ||
14090 | @item | |
14091 | Support @samp{OPEN(@dots{},KEY=(@dots{}),@dots{})}. | |
14092 | ||
14093 | @item | |
14094 | Support arbitrary file unit numbers, instead of limiting them | |
14095 | to 0 through @samp{MXUNIT-1}. | |
95a1b676 | 14096 | (This is a @code{libg2c} issue.) |
5ff904cd JL |
14097 | |
14098 | @item | |
14099 | @samp{OPEN(NOSPANBLOCKS,@dots{})} is treated as | |
14100 | @samp{OPEN(UNIT=NOSPANBLOCKS,@dots{})}, so a | |
14101 | later @code{UNIT=} in the first example is invalid. | |
14102 | Make sure this is what users of this feature would expect. | |
14103 | ||
14104 | @item | |
14105 | Currently @code{g77} disallows @samp{READ(1'10)} since | |
14106 | it is an obnoxious syntax, but | |
14107 | supporting it might be pretty easy if needed. | |
14108 | More details are needed, such | |
14109 | as whether general expressions separated by an apostrophe are supported, | |
14110 | or maybe the record number can be a general expression, and so on. | |
14111 | ||
14112 | @item | |
14113 | Support @code{STRUCTURE}, @code{UNION}, @code{MAP}, and @code{RECORD} | |
14114 | fully. | |
14115 | Currently there is no support at all | |
14116 | for @code{%FILL} in @code{STRUCTURE} and related syntax, | |
14117 | whereas the rest of the | |
14118 | stuff has at least some parsing support. | |
14119 | This requires either major | |
95a1b676 | 14120 | changes to @code{libg2c} or its replacement. |
5ff904cd JL |
14121 | |
14122 | @item | |
14123 | F90 and @code{g77} probably disagree about label scoping relative to | |
14124 | @code{INTERFACE} and @code{END INTERFACE}, and their contained | |
14125 | procedure interface bodies (blocks?). | |
14126 | ||
14127 | @item | |
14128 | @code{ENTRY} doesn't support F90 @code{RESULT()} yet, | |
14129 | since that was added after S8.112. | |
14130 | ||
14131 | @item | |
14132 | Empty-statement handling (10 ;;CONTINUE;;) probably isn't consistent | |
14133 | with the final form of the standard (it was vague at S8.112). | |
14134 | ||
14135 | @item | |
14136 | It seems to be an ``open'' question whether a file, immediately after being | |
14137 | @code{OPEN}ed,is positioned at the beginning, the end, or wherever---it | |
14138 | might be nice to offer an option of opening to ``undefined'' status, requiring | |
14139 | an explicit absolute-positioning operation to be performed before any | |
14140 | other (besides @code{CLOSE}) to assist in making applications port to systems | |
14141 | (some IBM?) that @code{OPEN} to the end of a file or some such thing. | |
14142 | @end itemize | |
14143 | ||
14144 | @node Machine Model | |
14145 | @section Machine Model | |
14146 | ||
14147 | This items pertain to generalizing @code{g77}'s view of | |
14148 | the machine model to more fully accept whatever the GBE | |
14149 | provides it via its configuration. | |
14150 | ||
14151 | @itemize @bullet | |
14152 | @item | |
4e6a1440 | 14153 | Switch to using @code{REAL_VALUE_TYPE} to represent floating-point constants |
5ff904cd JL |
14154 | exclusively so the target float format need not be required. |
14155 | This | |
14156 | means changing the way @code{g77} handles initialization of aggregate areas | |
14157 | having more than one type, such as @code{REAL} and @code{INTEGER}, | |
14158 | because currently | |
14159 | it initializes them as if they were arrays of @code{char} and uses the | |
14160 | bit patterns of the constants of the various types in them to determine | |
14161 | what to stuff in elements of the arrays. | |
14162 | ||
14163 | @item | |
14164 | Rely more and more on back-end info and capabilities, especially in the | |
14165 | area of constants (where having the @code{g77} front-end's IL just store | |
14166 | the appropriate tree nodes containing constants might be best). | |
14167 | ||
14168 | @item | |
14169 | Suite of C and Fortran programs that a user/administrator can run on a | |
14170 | machine to help determine the configuration for @code{g77} before building | |
14171 | and help determine if the compiler works (especially with whatever | |
14172 | libraries are installed) after building. | |
14173 | @end itemize | |
14174 | ||
14175 | @node Internals Documentation | |
14176 | @section Internals Documentation | |
14177 | ||
14178 | Better info on how @code{g77} works and how to port it is needed. | |
14179 | Much of this should be done only after the redesign planned for | |
14180 | 0.6 is complete. | |
14181 | ||
6a843296 CB |
14182 | @xref{Front End}, which contains some information |
14183 | on @code{g77} internals. | |
14184 | ||
5ff904cd JL |
14185 | @node Internals Improvements |
14186 | @section Internals Improvements | |
14187 | ||
14188 | Some more items that would make @code{g77} more reliable | |
14189 | and easier to maintain: | |
14190 | ||
14191 | @itemize @bullet | |
14192 | @item | |
14193 | Generally make expression handling focus | |
14194 | more on critical syntax stuff, leaving semantics to callers. | |
14195 | For example, | |
14196 | anything a caller can check, semantically, let it do so, rather | |
14197 | than having @file{expr.c} do it. | |
14198 | (Exceptions might include things like | |
14199 | diagnosing @samp{FOO(I--K:)=BAR} where @samp{FOO} is a @code{PARAMETER}---if | |
14200 | it seems | |
14201 | important to preserve the left-to-right-in-source order of production | |
14202 | of diagnostics.) | |
14203 | ||
14204 | @item | |
14205 | Come up with better naming conventions for @samp{-D} to establish requirements | |
14206 | to achieve desired implementation dialect via @file{proj.h}. | |
14207 | ||
14208 | @item | |
4e6a1440 | 14209 | Clean up used tokens and @code{ffewhere}s in @code{ffeglobal_terminate_1}. |
5ff904cd JL |
14210 | |
14211 | @item | |
4e6a1440 | 14212 | Replace @file{sta.c} @code{outpooldisp} mechanism with @code{malloc_pool_use}. |
5ff904cd JL |
14213 | |
14214 | @item | |
4e6a1440 | 14215 | Check for @code{opANY} in more places in @file{com.c}, @file{std.c}, |
5ff904cd JL |
14216 | and @file{ste.c}, and get rid of the @samp{opCONVERT(opANY)} kludge |
14217 | (after determining if there is indeed no real need for it). | |
14218 | ||
14219 | @item | |
14220 | Utility to read and check @file{bad.def} messages and their references in the | |
14221 | code, to make sure calls are consistent with message templates. | |
14222 | ||
14223 | @item | |
14224 | Search and fix @samp{&ffe@dots{}} and similar so that | |
14225 | @samp{ffe@dots{}ptr@dots{}} macros are | |
14226 | available instead (a good argument for wishing this could have written all | |
14227 | this stuff in C++, perhaps). | |
14228 | On the other hand, it's questionable whether this sort of | |
14229 | improvement is really necessary, given the availability of | |
14230 | tools such as Emacs and Perl, which make finding any | |
14231 | address-taking of structure members easy enough? | |
14232 | ||
14233 | @item | |
14234 | Some modules truly export the member names of their structures (and the | |
14235 | structures themselves), maybe fix this, and fix other modules that just | |
14236 | appear to as well (by appending @samp{_}, though it'd be ugly and probably | |
14237 | not worth the time). | |
14238 | ||
14239 | @item | |
14240 | Implement C macros @samp{RETURNS(value)} and @samp{SETS(something,value)} | |
14241 | in @file{proj.h} | |
14242 | and use them throughout @code{g77} source code (especially in the definitions | |
14243 | of access macros in @samp{.h} files) so they can be tailored | |
14244 | to catch code writing into a @samp{RETURNS()} or reading from a @samp{SETS()}. | |
14245 | ||
14246 | @item | |
14247 | Decorate throughout with @code{const} and other such stuff. | |
14248 | ||
14249 | @item | |
14250 | All F90 notational derivations in the source code are still based | |
14251 | on the S8.112 version of the draft standard. | |
14252 | Probably should update | |
14253 | to the official standard, or put documentation of the rules as used | |
14254 | in the code@dots{}uh@dots{}in the code. | |
14255 | ||
14256 | @item | |
4e6a1440 CB |
14257 | Some @code{ffebld_new} calls (those outside of @file{ffeexpr.c} or |
14258 | inside but invoked via paths not involving @code{ffeexpr_lhs} or | |
14259 | @code{ffeexpr_rhs}) might be creating things | |
5ff904cd JL |
14260 | in improper pools, leading to such things staying around too long or |
14261 | (doubtful, but possible and dangerous) not long enough. | |
14262 | ||
14263 | @item | |
4e6a1440 CB |
14264 | Some @code{ffebld_list_new} (or whatever) calls might not be matched by |
14265 | @code{ffebld_list_bottom} (or whatever) calls, which might someday matter. | |
5ff904cd JL |
14266 | (It definitely is not a problem just yet.) |
14267 | ||
14268 | @item | |
14269 | Probably not doing clean things when we fail to @code{EQUIVALENCE} something | |
14270 | due to alignment/mismatch or other problems---they end up without | |
4e6a1440 CB |
14271 | @code{ffestorag} objects, so maybe the backend (and other parts of the front |
14272 | end) can notice that and handle like an @code{opANY} (do what it wants, just | |
5ff904cd JL |
14273 | don't complain or crash). |
14274 | Most of this seems to have been addressed | |
14275 | by now, but a code review wouldn't hurt. | |
14276 | @end itemize | |
14277 | ||
14278 | @node Better Diagnostics | |
14279 | @section Better Diagnostics | |
14280 | ||
14281 | These are things users might not ask about, or that need to | |
14282 | be looked into, before worrying about. | |
14283 | Also here are items that involve reducing unnecessary diagnostic | |
14284 | clutter. | |
14285 | ||
14286 | @itemize @bullet | |
14287 | @item | |
14288 | When @code{FUNCTION} and @code{ENTRY} point types disagree (@code{CHARACTER} | |
14289 | lengths, type classes, and so on), | |
4e6a1440 | 14290 | @code{ANY}-ize the offending @code{ENTRY} point and any @emph{new} dummies |
5ff904cd JL |
14291 | it specifies. |
14292 | ||
14293 | @item | |
14294 | Speed up and improve error handling for data when repeat-count is | |
14295 | specified. | |
14296 | For example, don't output 20 unnecessary messages after the | |
14297 | first necessary one for: | |
14298 | ||
14299 | @smallexample | |
14300 | INTEGER X(20) | |
14301 | CONTINUE | |
14302 | DATA (X(I), J= 1, 20) /20*5/ | |
14303 | END | |
14304 | @end smallexample | |
14305 | ||
14306 | @noindent | |
14307 | (The @code{CONTINUE} statement ensures the @code{DATA} statement | |
14308 | is processed in the context of executable, not specification, | |
14309 | statements.) | |
14310 | @end itemize | |
75e8000e CB |
14311 | |
14312 | @include ffe.texi | |
14313 | ||
5ff904cd JL |
14314 | @end ifset |
14315 | ||
14316 | @ifset USING | |
14317 | @node Diagnostics | |
14318 | @chapter Diagnostics | |
14319 | @cindex diagnostics | |
14320 | ||
14321 | Some diagnostics produced by @code{g77} require sufficient explanation | |
14322 | that the explanations are given below, and the diagnostics themselves | |
14323 | identify the appropriate explanation. | |
14324 | ||
14325 | Identification uses the GNU Info format---specifically, the @code{info} | |
56a0044b | 14326 | command that displays the explanation is given within square |
5ff904cd JL |
14327 | brackets in the diagnostic. |
14328 | For example: | |
14329 | ||
14330 | @smallexample | |
14331 | foo.f:5: Invalid statement [info -f g77 M FOOEY] | |
14332 | @end smallexample | |
14333 | ||
14334 | More details about the above diagnostic is found in the @code{g77} Info | |
14335 | documentation, menu item @samp{M}, submenu item @samp{FOOEY}, | |
14336 | which is displayed by typing the UNIX command | |
14337 | @samp{info -f g77 M FOOEY}. | |
14338 | ||
14339 | Other Info readers, such as EMACS, may be just as easily used to display | |
14340 | the pertinent node. | |
14341 | In the above example, @samp{g77} is the Info document name, | |
14342 | @samp{M} is the top-level menu item to select, | |
14343 | and, in that node (named @samp{Diagnostics}, the name of | |
14344 | this chapter, which is the very text you're reading now), | |
14345 | @samp{FOOEY} is the menu item to select. | |
14346 | ||
14347 | @iftex | |
14348 | In this printed version of the @code{g77} manual, the above example | |
14349 | points to a section, below, entitled @samp{FOOEY}---though, of course, | |
14350 | as the above is just a sample, no such section exists. | |
14351 | @end iftex | |
14352 | ||
14353 | @menu | |
14354 | * CMPAMBIG:: Ambiguous use of intrinsic. | |
14355 | * EXPIMP:: Intrinsic used explicitly and implicitly. | |
14356 | * INTGLOB:: Intrinsic also used as name of global. | |
14357 | * LEX:: Various lexer messages | |
14358 | * GLOBALS:: Disagreements about globals. | |
4e6a1440 | 14359 | * LINKFAIL:: When linking @code{f771} fails. |
411d4e28 | 14360 | * Y2KBAD:: Use of non-Y2K-compliant intrinsic. |
5ff904cd JL |
14361 | @end menu |
14362 | ||
14363 | @node CMPAMBIG | |
14364 | @section @code{CMPAMBIG} | |
14365 | ||
14366 | @noindent | |
14367 | @smallexample | |
14368 | Ambiguous use of intrinsic @var{intrinsic} @dots{} | |
14369 | @end smallexample | |
14370 | ||
14371 | The type of the argument to the invocation of the @var{intrinsic} | |
14372 | intrinsic is a @code{COMPLEX} type other than @code{COMPLEX(KIND=1)}. | |
14373 | Typically, it is @code{COMPLEX(KIND=2)}, also known as | |
14374 | @code{DOUBLE COMPLEX}. | |
14375 | ||
14376 | The interpretation of this invocation depends on the particular | |
14377 | dialect of Fortran for which the code was written. | |
14378 | Some dialects convert the real part of the argument to | |
14379 | @code{REAL(KIND=1)}, thus losing precision; other dialects, | |
14380 | and Fortran 90, do no such conversion. | |
14381 | ||
14382 | So, GNU Fortran rejects such invocations except under certain | |
14383 | circumstances, to avoid making an incorrect assumption that results | |
14384 | in generating the wrong code. | |
14385 | ||
14386 | To determine the dialect of the program unit, perhaps even whether | |
14387 | that particular invocation is properly coded, determine how the | |
14388 | result of the intrinsic is used. | |
14389 | ||
14390 | The result of @var{intrinsic} is expected (by the original programmer) | |
14391 | to be @code{REAL(KIND=1)} (the non-Fortran-90 interpretation) if: | |
14392 | ||
14393 | @itemize @bullet | |
14394 | @item | |
14395 | It is passed as an argument to a procedure that explicitly or | |
14396 | implicitly declares that argument @code{REAL(KIND=1)}. | |
14397 | ||
14398 | For example, | |
14399 | a procedure with no @code{DOUBLE PRECISION} or @code{IMPLICIT DOUBLE PRECISION} | |
14400 | statement specifying the dummy argument corresponding to an | |
14401 | actual argument of @samp{REAL(Z)}, where @samp{Z} is declared | |
14402 | @code{DOUBLE COMPLEX}, strongly suggests that the programmer | |
14403 | expected @samp{REAL(Z)} to return @code{REAL(KIND=1)} instead | |
14404 | of @code{REAL(KIND=2)}. | |
14405 | ||
14406 | @item | |
14407 | It is used in a context that would otherwise not include | |
14408 | any @code{REAL(KIND=2)} but where treating the @var{intrinsic} | |
14409 | invocation as @code{REAL(KIND=2)} would result in unnecessary | |
14410 | promotions and (typically) more expensive operations on the | |
14411 | wider type. | |
14412 | ||
14413 | For example: | |
14414 | ||
14415 | @smallexample | |
14416 | DOUBLE COMPLEX Z | |
14417 | @dots{} | |
14418 | R(1) = T * REAL(Z) | |
14419 | @end smallexample | |
14420 | ||
14421 | The above example suggests the programmer expected the real part | |
14422 | of @samp{Z} to be converted to @code{REAL(KIND=1)} before being | |
14423 | multiplied by @samp{T} (presumed, along with @samp{R} above, to | |
14424 | be type @code{REAL(KIND=1)}). | |
14425 | ||
14426 | Otherwise, the conversion would have to be delayed until after | |
14427 | the multiplication, requiring not only an extra conversion | |
14428 | (of @samp{T} to @code{REAL(KIND=2)}), but a (typically) more | |
14429 | expensive multiplication (a double-precision multiplication instead | |
14430 | of a single-precision one). | |
14431 | @end itemize | |
14432 | ||
14433 | The result of @var{intrinsic} is expected (by the original programmer) | |
14434 | to be @code{REAL(KIND=2)} (the Fortran 90 interpretation) if: | |
14435 | ||
14436 | @itemize @bullet | |
14437 | @item | |
14438 | It is passed as an argument to a procedure that explicitly or | |
14439 | implicitly declares that argument @code{REAL(KIND=2)}. | |
14440 | ||
14441 | For example, a procedure specifying a @code{DOUBLE PRECISION} | |
14442 | dummy argument corresponding to an | |
14443 | actual argument of @samp{REAL(Z)}, where @samp{Z} is declared | |
14444 | @code{DOUBLE COMPLEX}, strongly suggests that the programmer | |
14445 | expected @samp{REAL(Z)} to return @code{REAL(KIND=2)} instead | |
14446 | of @code{REAL(KIND=1)}. | |
14447 | ||
14448 | @item | |
14449 | It is used in an expression context that includes | |
14450 | other @code{REAL(KIND=2)} operands, | |
14451 | or is assigned to a @code{REAL(KIND=2)} variable or array element. | |
14452 | ||
14453 | For example: | |
14454 | ||
14455 | @smallexample | |
14456 | DOUBLE COMPLEX Z | |
14457 | DOUBLE PRECISION R, T | |
14458 | @dots{} | |
14459 | R(1) = T * REAL(Z) | |
14460 | @end smallexample | |
14461 | ||
14462 | The above example suggests the programmer expected the real part | |
14463 | of @samp{Z} to @emph{not} be converted to @code{REAL(KIND=1)} | |
14464 | by the @code{REAL()} intrinsic. | |
14465 | ||
14466 | Otherwise, the conversion would have to be immediately followed | |
14467 | by a conversion back to @code{REAL(KIND=2)}, losing | |
14468 | the original, full precision of the real part of @code{Z}, | |
14469 | before being multiplied by @samp{T}. | |
14470 | @end itemize | |
14471 | ||
14472 | Once you have determined whether a particular invocation of @var{intrinsic} | |
14473 | expects the Fortran 90 interpretation, you can: | |
14474 | ||
14475 | @itemize @bullet | |
14476 | @item | |
14477 | Change it to @samp{DBLE(@var{expr})} (if @var{intrinsic} is | |
4e6a1440 CB |
14478 | @code{REAL}) or @samp{DIMAG(@var{expr})} (if @var{intrinsic} |
14479 | is @code{AIMAG}) | |
5ff904cd JL |
14480 | if it expected the Fortran 90 interpretation. |
14481 | ||
14482 | This assumes @var{expr} is @code{COMPLEX(KIND=2)}---if it is | |
14483 | some other type, such as @code{COMPLEX*32}, you should use the | |
14484 | appropriate intrinsic, such as the one to convert to @code{REAL*16} | |
14485 | (perhaps @code{DBLEQ()} in place of @code{DBLE()}, and | |
14486 | @code{QIMAG()} in place of @code{DIMAG()}). | |
14487 | ||
14488 | @item | |
14489 | Change it to @samp{REAL(@var{intrinsic}(@var{expr}))}, | |
14490 | otherwise. | |
14491 | This converts to @code{REAL(KIND=1)} in all working | |
14492 | Fortran compilers. | |
14493 | @end itemize | |
14494 | ||
14495 | If you don't want to change the code, and you are certain that all | |
14496 | ambiguous invocations of @var{intrinsic} in the source file have | |
14497 | the same expectation regarding interpretation, you can: | |
14498 | ||
14499 | @itemize @bullet | |
14500 | @item | |
14501 | Compile with the @code{g77} option @samp{-ff90}, to enable the | |
14502 | Fortran 90 interpretation. | |
14503 | ||
14504 | @item | |
14505 | Compile with the @code{g77} options @samp{-fno-f90 -fugly-complex}, | |
14506 | to enable the non-Fortran-90 interpretations. | |
14507 | @end itemize | |
14508 | ||
14509 | @xref{REAL() and AIMAG() of Complex}, for more information on this | |
14510 | issue. | |
14511 | ||
14512 | Note: If the above suggestions don't produce enough evidence | |
14513 | as to whether a particular program expects the Fortran 90 | |
14514 | interpretation of this ambiguous invocation of @var{intrinsic}, | |
14515 | there is one more thing you can try. | |
14516 | ||
14517 | If you have access to most or all the compilers used on the | |
14518 | program to create successfully tested and deployed executables, | |
14519 | read the documentation for, and @emph{also} test out, each compiler | |
14520 | to determine how it treats the @var{intrinsic} intrinsic in | |
14521 | this case. | |
14522 | (If all the compilers don't agree on an interpretation, there | |
14523 | might be lurking bugs in the deployed versions of the program.) | |
14524 | ||
14525 | The following sample program might help: | |
14526 | ||
14527 | @cindex JCB003 program | |
14528 | @smallexample | |
14529 | PROGRAM JCB003 | |
14530 | C | |
14531 | C Written by James Craig Burley 1997-02-23. | |
5ff904cd JL |
14532 | C |
14533 | C Determine how compilers handle non-standard REAL | |
14534 | C and AIMAG on DOUBLE COMPLEX operands. | |
14535 | C | |
14536 | DOUBLE COMPLEX Z | |
14537 | REAL R | |
14538 | Z = (3.3D0, 4.4D0) | |
14539 | R = Z | |
14540 | CALL DUMDUM(Z, R) | |
14541 | R = REAL(Z) - R | |
14542 | IF (R .NE. 0.) PRINT *, 'REAL() is Fortran 90' | |
14543 | IF (R .EQ. 0.) PRINT *, 'REAL() is not Fortran 90' | |
14544 | R = 4.4D0 | |
14545 | CALL DUMDUM(Z, R) | |
14546 | R = AIMAG(Z) - R | |
14547 | IF (R .NE. 0.) PRINT *, 'AIMAG() is Fortran 90' | |
14548 | IF (R .EQ. 0.) PRINT *, 'AIMAG() is not Fortran 90' | |
14549 | END | |
14550 | C | |
14551 | C Just to make sure compiler doesn't use naive flow | |
14552 | C analysis to optimize away careful work above, | |
14553 | C which might invalidate results.... | |
14554 | C | |
14555 | SUBROUTINE DUMDUM(Z, R) | |
14556 | DOUBLE COMPLEX Z | |
14557 | REAL R | |
14558 | END | |
14559 | @end smallexample | |
14560 | ||
14561 | If the above program prints contradictory results on a | |
14562 | particular compiler, run away! | |
14563 | ||
14564 | @node EXPIMP | |
14565 | @section @code{EXPIMP} | |
14566 | ||
14567 | @noindent | |
14568 | @smallexample | |
14569 | Intrinsic @var{intrinsic} referenced @dots{} | |
14570 | @end smallexample | |
14571 | ||
14572 | The @var{intrinsic} is explicitly declared in one program | |
14573 | unit in the source file and implicitly used as an intrinsic | |
14574 | in another program unit in the same source file. | |
14575 | ||
14576 | This diagnostic is designed to catch cases where a program | |
14577 | might depend on using the name @var{intrinsic} as an intrinsic | |
14578 | in one program unit and as a global name (such as the name | |
14579 | of a subroutine or function) in another, but @code{g77} recognizes | |
14580 | the name as an intrinsic in both cases. | |
14581 | ||
14582 | After verifying that the program unit making implicit use | |
14583 | of the intrinsic is indeed written expecting the intrinsic, | |
14584 | add an @samp{INTRINSIC @var{intrinsic}} statement to that | |
14585 | program unit to prevent this warning. | |
14586 | ||
14587 | This and related warnings are disabled by using | |
14588 | the @samp{-Wno-globals} option when compiling. | |
14589 | ||
14590 | Note that this warning is not issued for standard intrinsics. | |
14591 | Standard intrinsics include those described in the FORTRAN 77 | |
14592 | standard and, if @samp{-ff90} is specified, those described | |
14593 | in the Fortran 90 standard. | |
14594 | Such intrinsics are not as likely to be confused with user | |
14595 | procedures as intrinsics provided as extensions to the | |
14596 | standard by @code{g77}. | |
14597 | ||
14598 | @node INTGLOB | |
14599 | @section @code{INTGLOB} | |
14600 | ||
14601 | @noindent | |
14602 | @smallexample | |
14603 | Same name `@var{intrinsic}' given @dots{} | |
14604 | @end smallexample | |
14605 | ||
14606 | The name @var{intrinsic} is used for a global entity (a common | |
14607 | block or a program unit) in one program unit and implicitly | |
14608 | used as an intrinsic in another program unit. | |
14609 | ||
14610 | This diagnostic is designed to catch cases where a program | |
14611 | intends to use a name entirely as a global name, but @code{g77} | |
14612 | recognizes the name as an intrinsic in the program unit that | |
14613 | references the name, a situation that would likely produce | |
14614 | incorrect code. | |
14615 | ||
14616 | For example: | |
14617 | ||
14618 | @smallexample | |
14619 | INTEGER FUNCTION TIME() | |
14620 | @dots{} | |
14621 | END | |
14622 | @dots{} | |
14623 | PROGRAM SAMP | |
14624 | INTEGER TIME | |
14625 | PRINT *, 'Time is ', TIME() | |
14626 | END | |
14627 | @end smallexample | |
14628 | ||
14629 | The above example defines a program unit named @samp{TIME}, but | |
14630 | the reference to @samp{TIME} in the main program unit @samp{SAMP} | |
14631 | is normally treated by @code{g77} as a reference to the intrinsic | |
14632 | @code{TIME()} (unless a command-line option that prevents such | |
14633 | treatment has been specified). | |
14634 | ||
14635 | As a result, the program @samp{SAMP} will @emph{not} | |
14636 | invoke the @samp{TIME} function in the same source file. | |
14637 | ||
14638 | Since @code{g77} recognizes @code{libU77} procedures as | |
14639 | intrinsics, and since some existing code uses the same names | |
14640 | for its own procedures as used by some @code{libU77} | |
14641 | procedures, this situation is expected to arise often enough | |
14642 | to make this sort of warning worth issuing. | |
14643 | ||
14644 | After verifying that the program unit making implicit use | |
14645 | of the intrinsic is indeed written expecting the intrinsic, | |
14646 | add an @samp{INTRINSIC @var{intrinsic}} statement to that | |
14647 | program unit to prevent this warning. | |
14648 | ||
14649 | Or, if you believe the program unit is designed to invoke the | |
14650 | program-defined procedure instead of the intrinsic (as | |
14651 | recognized by @code{g77}), add an @samp{EXTERNAL @var{intrinsic}} | |
14652 | statement to the program unit that references the name to | |
14653 | prevent this warning. | |
14654 | ||
14655 | This and related warnings are disabled by using | |
14656 | the @samp{-Wno-globals} option when compiling. | |
14657 | ||
14658 | Note that this warning is not issued for standard intrinsics. | |
14659 | Standard intrinsics include those described in the FORTRAN 77 | |
14660 | standard and, if @samp{-ff90} is specified, those described | |
14661 | in the Fortran 90 standard. | |
14662 | Such intrinsics are not as likely to be confused with user | |
14663 | procedures as intrinsics provided as extensions to the | |
14664 | standard by @code{g77}. | |
14665 | ||
14666 | @node LEX | |
14667 | @section @code{LEX} | |
14668 | ||
14669 | @noindent | |
14670 | @smallexample | |
14671 | Unrecognized character @dots{} | |
14672 | Invalid first character @dots{} | |
14673 | Line too long @dots{} | |
14674 | Non-numeric character @dots{} | |
14675 | Continuation indicator @dots{} | |
14676 | Label at @dots{} invalid with continuation line indicator @dots{} | |
14677 | Character constant @dots{} | |
14678 | Continuation line @dots{} | |
14679 | Statement at @dots{} begins with invalid token | |
14680 | @end smallexample | |
14681 | ||
14682 | Although the diagnostics identify specific problems, they can | |
14683 | be produced when general problems such as the following occur: | |
14684 | ||
14685 | @itemize @bullet | |
14686 | @item | |
14687 | The source file contains something other than Fortran code. | |
14688 | ||
14689 | If the code in the file does not look like many of the examples | |
14690 | elsewhere in this document, it might not be Fortran code. | |
14691 | (Note that Fortran code often is written in lower case letters, | |
14692 | while the examples in this document use upper case letters, | |
14693 | for stylistic reasons.) | |
14694 | ||
14695 | For example, if the file contains lots of strange-looking | |
14696 | characters, it might be APL source code; if it contains lots | |
14697 | of parentheses, it might be Lisp source code; if it | |
14698 | contains lots of bugs, it might be C++ source code. | |
14699 | ||
14700 | @item | |
14701 | The source file contains free-form Fortran code, but @samp{-ffree-form} | |
14702 | was not specified on the command line to compile it. | |
14703 | ||
14704 | Free form is a newer form for Fortran code. | |
14705 | The older, classic form is called fixed form. | |
14706 | ||
26b9526e CB |
14707 | @cindex continuation character |
14708 | @cindex characters, continuation | |
5ff904cd JL |
14709 | Fixed-form code is visually fairly distinctive, because |
14710 | numerical labels and comments are all that appear in | |
14711 | the first five columns of a line, the sixth column is | |
14712 | reserved to denote continuation lines, | |
14713 | and actual statements start at or beyond column 7. | |
14714 | Spaces generally are not significant, so if you | |
14715 | see statements such as @samp{REALX,Y} and @samp{DO10I=1,100}, | |
14716 | you are looking at fixed-form code. | |
26b9526e CB |
14717 | @cindex * |
14718 | @cindex asterisk | |
5ff904cd JL |
14719 | Comment lines are indicated by the letter @samp{C} or the symbol |
14720 | @samp{*} in column 1. | |
26b9526e CB |
14721 | @cindex trailing comment |
14722 | @cindex comment | |
14723 | @cindex characters, comment | |
14724 | @cindex ! | |
14725 | @cindex exclamation point | |
5ff904cd JL |
14726 | (Some code uses @samp{!} or @samp{/*} to begin in-line comments, |
14727 | which many compilers support.) | |
14728 | ||
14729 | Free-form code is distinguished from fixed-form source | |
14730 | primarily by the fact that statements may start anywhere. | |
14731 | (If lots of statements start in columns 1 through 6, | |
14732 | that's a strong indicator of free-form source.) | |
14733 | Consecutive keywords must be separated by spaces, so | |
14734 | @samp{REALX,Y} is not valid, while @samp{REAL X,Y} is. | |
14735 | There are no comment lines per se, but @samp{!} starts a | |
14736 | comment anywhere in a line (other than within a character or | |
0b31330e | 14737 | Hollerith constant). |
5ff904cd JL |
14738 | |
14739 | @xref{Source Form}, for more information. | |
14740 | ||
14741 | @item | |
14742 | The source file is in fixed form and has been edited without | |
14743 | sensitivity to the column requirements. | |
14744 | ||
14745 | Statements in fixed-form code must be entirely contained within | |
14746 | columns 7 through 72 on a given line. | |
14747 | Starting them ``early'' is more likely to result in diagnostics | |
14748 | than finishing them ``late'', though both kinds of errors are | |
14749 | often caught at compile time. | |
14750 | ||
14751 | For example, if the following code fragment is edited by following | |
14752 | the commented instructions literally, the result, shown afterward, | |
14753 | would produce a diagnostic when compiled: | |
14754 | ||
14755 | @smallexample | |
14756 | C On XYZZY systems, remove "C" on next line: | |
14757 | C CALL XYZZY_RESET | |
14758 | @end smallexample | |
14759 | ||
14760 | The result of editing the above line might be: | |
14761 | ||
14762 | @smallexample | |
14763 | C On XYZZY systems, remove "C" on next line: | |
14764 | CALL XYZZY_RESET | |
14765 | @end smallexample | |
14766 | ||
4e6a1440 | 14767 | However, that leaves the first @samp{C} in the @code{CALL} |
5ff904cd JL |
14768 | statement in column 6, making it a comment line, which is |
14769 | not really what the author intended, and which is likely | |
14770 | to result in one of the above-listed diagnostics. | |
14771 | ||
14772 | @emph{Replacing} the @samp{C} in column 1 with a space | |
4e6a1440 | 14773 | is the proper change to make, to ensure the @code{CALL} |
5ff904cd JL |
14774 | keyword starts in or after column 7. |
14775 | ||
14776 | Another common mistake like this is to forget that fixed-form | |
14777 | source lines are significant through only column 72, and that, | |
14778 | normally, any text beyond column 72 is ignored or is diagnosed | |
14779 | at compile time. | |
14780 | ||
14781 | @xref{Source Form}, for more information. | |
14782 | ||
14783 | @item | |
14784 | The source file requires preprocessing, and the preprocessing | |
14785 | is not being specified at compile time. | |
14786 | ||
14787 | A source file containing lines beginning with @code{#define}, | |
14788 | @code{#include}, @code{#if}, and so on is likely one that | |
14789 | requires preprocessing. | |
14790 | ||
d1d80a92 CB |
14791 | If the file's suffix is @samp{.f}, @samp{.for}, or @samp{.FOR}, |
14792 | the file normally will be compiled @emph{without} preprocessing | |
14793 | by @code{g77}. | |
5ff904cd | 14794 | |
d1d80a92 CB |
14795 | Change the file's suffix from @samp{.f} to @samp{.F} |
14796 | (or, on systems with case-insensitive file names, | |
14797 | to @samp{.fpp} or @samp{.FPP}), | |
14798 | from @samp{.for} to @samp{.fpp}, | |
14799 | or from @samp{.FOR} to @samp{.FPP}. | |
5ff904cd JL |
14800 | @code{g77} compiles files with such names @emph{with} |
14801 | preprocessing. | |
14802 | ||
58dd1c34 DL |
14803 | @pindex cpp |
14804 | @cindex preprocessor | |
14805 | @cindex cpp program | |
14806 | @cindex programs, cpp | |
14807 | @cindex @samp{-x f77-cpp-input} option | |
14808 | @cindex options, @samp{-x f77-cpp-input} | |
5ff904cd JL |
14809 | Or, learn how to use @code{gcc}'s @samp{-x} option to specify |
14810 | the language @samp{f77-cpp-input} for Fortran files that | |
14811 | require preprocessing. | |
14812 | @xref{Overall Options,,gcc,Using and Porting GNU CC}. | |
14813 | ||
14814 | @item | |
14815 | The source file is preprocessed, and the results of preprocessing | |
14816 | result in syntactic errors that are not necessarily obvious to | |
14817 | someone examining the source file itself. | |
14818 | ||
14819 | Examples of errors resulting from preprocessor macro expansion | |
14820 | include exceeding the line-length limit, improperly starting, | |
14821 | terminating, or incorporating the apostrophe or double-quote in | |
0b31330e | 14822 | a character constant, improperly forming a Hollerith constant, |
5ff904cd JL |
14823 | and so on. |
14824 | ||
14825 | @xref{Overall Options,,Options Controlling the Kind of Output}, | |
14826 | for suggestions about how to use, and not use, preprocessing | |
14827 | for Fortran code. | |
14828 | @end itemize | |
14829 | ||
14830 | @node GLOBALS | |
14831 | @section @code{GLOBALS} | |
14832 | ||
14833 | @noindent | |
14834 | @smallexample | |
14835 | Global name @var{name} defined at @dots{} already defined@dots{} | |
14836 | Global name @var{name} at @dots{} has different type@dots{} | |
14837 | Too many arguments passed to @var{name} at @dots{} | |
14838 | Too few arguments passed to @var{name} at @dots{} | |
14839 | Argument #@var{n} of @var{name} is @dots{} | |
14840 | @end smallexample | |
14841 | ||
14842 | These messages all identify disagreements about the | |
c89524a8 CB |
14843 | global procedure named @var{name} among different program units |
14844 | (usually including @var{name} itself). | |
14845 | ||
14846 | Whether a particular disagreement is reported | |
14847 | as a warning or an error | |
14848 | can depend on the relative order | |
14849 | of the disagreeing portions of the source file. | |
14850 | ||
14851 | Disagreements between a procedure invocation | |
14852 | and the @emph{subsequent} procedure itself | |
14853 | are, usually, diagnosed as errors | |
14854 | when the procedure itself @emph{precedes} the invocation. | |
14855 | Other disagreements are diagnosed via warnings. | |
14856 | ||
14857 | @cindex forward references | |
14858 | @cindex in-line code | |
14859 | @cindex compilation, in-line | |
14860 | This distinction, between warnings and errors, | |
14861 | is due primarily to the present tendency of the @code{gcc} back end | |
14862 | to inline only those procedure invocations that are | |
14863 | @emph{preceded} by the corresponding procedure definitions. | |
14864 | If the @code{gcc} back end is changed | |
14865 | to inline ``forward references'', | |
14866 | in which invocations precede definitions, | |
14867 | the @code{g77} front end will be changed | |
14868 | to treat both orderings as errors, accordingly. | |
14869 | ||
14870 | The sorts of disagreements that are diagnosed by @code{g77} include | |
14871 | whether a procedure is a subroutine or function; | |
14872 | if it is a function, the type of the return value of the procedure; | |
14873 | the number of arguments the procedure accepts; | |
14874 | and the type of each argument. | |
14875 | ||
14876 | Disagreements regarding global names among program units | |
14877 | in a Fortran program @emph{should} be fixed in the code itself. | |
14878 | However, if that is not immediately practical, | |
14879 | and the code has been working for some time, | |
14880 | it is possible it will work | |
14881 | when compiled with the @samp{-fno-globals} option. | |
14882 | ||
14883 | The @samp{-fno-globals} option | |
14884 | causes these diagnostics to all be warnings | |
14885 | and disables all inlining of references to global procedures | |
14886 | (to avoid subsequent compiler crashes and bad-code generation). | |
14887 | Use of the @samp{-Wno-globals} option as well as @samp{-fno-globals} | |
14888 | suppresses all of these diagnostics. | |
14889 | (@samp{-Wno-globals} by itself disables only the warnings, | |
14890 | not the errors.) | |
5ff904cd JL |
14891 | |
14892 | After using @samp{-fno-globals} to work around these problems, | |
14893 | it is wise to stop using that option and address them by fixing | |
14894 | the Fortran code, because such problems, while they might not | |
14895 | actually result in bugs on some systems, indicate that the code | |
14896 | is not as portable as it could be. | |
14897 | In particular, the code might appear to work on a particular | |
14898 | system, but have bugs that affect the reliability of the data | |
14899 | without exhibiting any other outward manifestations of the bugs. | |
14900 | ||
95a1b676 CB |
14901 | @node LINKFAIL |
14902 | @section @code{LINKFAIL} | |
14903 | ||
14904 | @noindent | |
14905 | @smallexample | |
14906 | If the above command failed due to an unresolved reference | |
14907 | to strtoul, _strtoul, bsearch, _bsearch, or similar, see | |
14908 | [info -f g77 M LINKFAIL] (a node in the g77 documentation) | |
14909 | for information on what causes this, how to work around | |
14910 | the problem by editing $@{srcdir@}/proj.c, and what else to do. | |
14911 | @end smallexample | |
14912 | ||
14913 | @xref{Missing strtoul or bsearch}, for more information on | |
14914 | this problem, | |
14915 | which occurs only in releases of @code{g77} | |
14916 | based on @code{gcc}. | |
14917 | (It does not occur in @code{egcs}.) | |
14918 | ||
14919 | On AIX 4.1, @code{g77} might not build with the native (non-GNU) tools | |
0b31330e DL |
14920 | due to a linker bug in coping with the @samp{-bbigtoc} option which |
14921 | leads to a @samp{Relocation overflow} error. The GNU linker is not | |
14922 | recommended on current AIX versions, though; it was developed under a | |
14923 | now-unsupported version. This bug is said to be fixed by `update PTF | |
14924 | U455193 for APAR IX75823'. | |
95a1b676 CB |
14925 | |
14926 | Compiling with @samp{-mminimal-toc} | |
14927 | might solve this problem, e.g.@: by adding | |
14928 | @smallexample | |
14929 | BOOT_CFLAGS='-mminimal-toc -O2 -g' | |
14930 | @end smallexample | |
14931 | to the @code{make bootstrap} command line. | |
411d4e28 CB |
14932 | |
14933 | @node Y2KBAD | |
14934 | @section @code{Y2KBAD} | |
14935 | @cindex Y2K compliance | |
14936 | @cindex Year 2000 compliance | |
14937 | ||
14938 | @noindent | |
14939 | @smallexample | |
14940 | Intrinsic `@var{name}', invoked at (^), known to be non-Y2K-compliant@dots{} | |
14941 | @end smallexample | |
14942 | ||
14943 | This diagnostic indicates that | |
14944 | the specific intrinsic invoked by the name @var{name} | |
14945 | is known to have an interface | |
14946 | that is not Year-2000 (Y2K) compliant. | |
14947 | ||
14948 | @xref{Year 2000 (Y2K) Problems}. | |
14949 | ||
5ff904cd JL |
14950 | @end ifset |
14951 | ||
14952 | @node Index | |
14953 | @unnumbered Index | |
14954 | ||
14955 | @printindex cp | |
14956 | @summarycontents | |
14957 | @contents | |
14958 | @bye |