path: root/gnu/usr.bin/gcc/f/g77.texi

\input texinfo  @c -*-texinfo-*-
@c fix @set inside @example:
@tex
\gdef\set{\begingroup\catcode` =10 \parsearg\setxxx}
\gdef\setyyy#1 #2\endsetyyy{%
  \def\temp{#2}%
  \ifx\temp\empty \global\expandafter\let\csname SET#1\endcsname = \empty
  \else \setzzz{#1}#2\endsetzzz % Remove the trailing space \setxxx inserted.
  \fi
  \endgroup
}
@end tex

@c %**start of header 
@setfilename g77.info
@c @setfilename useg77.info
@c @setfilename portg77.info
@c To produce the full manual, use the "g77.info" setfilename, and
@c make sure the following do NOT begin with '@c' (and the @clear lines DO)
@set INTERNALS
@set USING
@c To produce a user-only manual, use the "useg77.info" setfilename, and
@c make sure the following does NOT begin with '@c':
@c @clear INTERNALS
@c To produce a porter-only manual, use the "portg77.info" setfilename,
@c and make sure the following does NOT begin with '@c':
@c @clear USING

@c (For FSF printing, turn on smallbook; that is all that is needed.)

@c smallbook

@ifset INTERNALS
@ifset USING
@settitle Using and Porting GNU Fortran
@end ifset
@end ifset
@c seems reasonable to assume at least one of INTERNALS or USING is set...
@ifclear INTERNALS
@settitle Using GNU Fortran
@end ifclear
@ifclear USING
@settitle Porting GNU Fortran
@end ifclear 
@c then again, have some fun
@ifclear INTERNALS
@ifclear USING
@settitle Doing Squat with GNU Fortran
@end ifclear
@end ifclear

@syncodeindex fn cp
@syncodeindex vr cp
@c %**end of header
@setchapternewpage odd

@ifinfo
This file explains how to use the GNU Fortran system.

Published by the Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

Copyright (C) 1995, 1996 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through Tex and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``GNU General Public License,'' ``Funding for Free
Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``GNU General Public License,''
``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look
And Feel'@w{}'', and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.
@end ifinfo

Contributed by James Craig Burley (@code{burley@@gnu.ai.mit.edu}).
Inspired by a first pass at translating @code{g77-0.5.16/f/DOC} that
was contributed to Craig by David Ronis (@code{ronis@@onsager.chem.mcgill.ca}).

@finalout
@titlepage
@comment The title is printed in a large font.
@center @titlefont{Using GNU Fortran}
@sp 2
@center James Craig Burley
@sp 3
@center Last updated 1996-12-03
@sp 1
@c The version number appears some more times in this file.

@center for version 0.5.19
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1995, 1996 Free Software Foundation, Inc.
@sp 2
For GNU Fortran Version 0.5.19*
@sp 1
Published by the Free Software Foundation @*
59 Temple Place - Suite 330@*
Boston, MA 02111-1307, USA@*
@c Last printed ??ber, 19??.@*
@c Printed copies are available for $? each.@*
@c ISBN ???
@sp 1
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled ``GNU General Public License,'' ``Funding for Free
Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that the sections entitled ``GNU General Public License,''
``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look
And Feel'@w{}'', and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.
@end titlepage
@page

@ifinfo

@node Top, Copying,, (DIR)
@top Introduction
@cindex Introduction

@ifset INTERNALS
@ifset USING
This manual documents how to run, install and port the GNU Fortran
compiler, as well as its new features and incompatibilities, and how to
report bugs.  It corresponds to GNU Fortran version 0.5.19.
@end ifset
@end ifset

@ifclear INTERNALS
This manual documents how to run and install the GNU Fortran compiler,
as well as its new features and incompatibilities, and how to report
bugs.  It corresponds to GNU Fortran version 0.5.19.
@end ifclear
@ifclear USING
This manual documents how to port the GNU Fortran compiler,
as well as its new features and incompatibilities, and how to report
bugs.  It corresponds to GNU Fortran version 0.5.19.
@end ifclear

@end ifinfo
@menu
* Copying::         GNU General Public License says
                    how you can copy and share GNU Fortran.
* Contributors::    People who have contributed to GNU Fortran.
* Funding::         How to help assure continued work for free software.
* Funding GNU Fortran::  How to help assure continued work on GNU Fortran.
* Look and Feel::   Protect your freedom---fight ``look and feel''.
@ifset USING
* Getting Started:: Finding your way around this manual.
* What is GNU Fortran?::  How @code{g77} fits into the universe.
* G77 and GCC::     You can compile Fortran, C, or other programs.
* Invoking G77::    Command options supported by @code{g77}.
* News::            News about recent releases of @code{g77}.
* Changes::         User-visible changes to recent releases of @code{g77}.
* Language::        The GNU Fortran language.
* Installation::    How to configure, compile and install GNU Fortran.
* Debugging and Interfacing::  How @code{g77} generates code.
* Collected Fortran Wisdom::  How to avoid Trouble.
* Trouble::         If you have trouble with GNU Fortran.
* Open Questions::  Things we'd like to know.
* Bugs::            How, why, and where to report bugs.
* Service::         How to find suppliers of support for GNU Fortran.
@end ifset
@ifset INTERNALS
* Adding Options::  Guidance on teaching @code{g77} about new options.
* Projects::        Projects for @code{g77} internals hackers.
@end ifset

* Index::	    Index of concepts and symbol names.
@end menu

@node Copying
@unnumbered GNU GENERAL PUBLIC LICENSE
@center Version 2, June 1991

@display
Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display

@unnumberedsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software---to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

@iftex
@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end ifinfo

@enumerate 0
@item
This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The ``Program'', below,
refers to any such program or work, and a ``work based on the Program''
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term ``modification''.)  Each licensee is addressed as ``you''.

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

@item
You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

@item
You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

@enumerate a
@item
You must cause the modified files to carry prominent notices
stating that you changed the files and the date of any change.

@item
You must cause any work that you distribute or publish, that in
whole or in part contains or is derived from the Program or any
part thereof, to be licensed as a whole at no charge to all third
parties under the terms of this License.

@item
If the modified program normally reads commands interactively
when run, you must cause it, when started running for such
interactive use in the most ordinary way, to print or display an
announcement including an appropriate copyright notice and a
notice that there is no warranty (or else, saying that you provide
a warranty) and that users may redistribute the program under
these conditions, and telling the user how to view a copy of this
License.  (Exception: if the Program itself is interactive but
does not normally print such an announcement, your work based on
the Program is not required to print an announcement.)
@end enumerate

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

@item
You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

@enumerate a
@item
Accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of Sections
1 and 2 above on a medium customarily used for software interchange; or,

@item
Accompany it with a written offer, valid for at least three
years, to give any third party, for a charge no more than your
cost of physically performing source distribution, a complete
machine-readable copy of the corresponding source code, to be
distributed under the terms of Sections 1 and 2 above on a medium
customarily used for software interchange; or,

@item
Accompany it with the information you received as to the offer
to distribute corresponding source code.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form with such
an offer, in accord with Subsection b above.)
@end enumerate

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

@item
You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

@item
You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

@item
Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

@item
If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

@item
If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

@item
The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and ``any
later version'', you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

@item
If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

@iftex
@heading NO WARRANTY
@end iftex
@ifinfo
@center NO WARRANTY
@end ifinfo

@item
BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

@item
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
@end enumerate

@iftex
@heading END OF TERMS AND CONDITIONS
@end iftex
@ifinfo
@center END OF TERMS AND CONDITIONS
@end ifinfo

@page
@unnumberedsec How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.

@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) 19@var{yy}  @var{name of author}

This program is free software; you can redistribute it and/or modify 
it under the terms of the GNU General Public License as published by 
the Free Software Foundation; either version 2 of the License, or 
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
@end smallexample

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

@smallexample
Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'.  
This is free software, and you are welcome to redistribute it 
under certain conditions; type `show c' for details.
@end smallexample

The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than @samp{show w} and
@samp{show c}; they could even be mouse-clicks or menu items---whatever
suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a ``copyright disclaimer'' for the program, if
necessary.  Here is a sample; alter the names:

@smallexample
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
`Gnomovision' (which makes passes at compilers) written by James Hacker.

@var{signature of Ty Coon}, 1 April 1989
Ty Coon, President of Vice
@end smallexample

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

@node Contributors
@unnumbered Contributors to GNU Fortran
@cindex contributors
@cindex credits

In addition to James Craig Burley, who wrote the front end,
many people have helped create and improve GNU Fortran.

@itemize @bullet
@item
The packaging and compiler portions of GNU Fortran are based largely
on the GNU CC compiler.
@xref{Contributors,,Contributors to GNU CC,gcc,Using and Porting GNU CC},
for more information.

@item
The run-time library used by GNU Fortran is a minor repackaging
of the @code{libf2c} library (combined from the @code{libF77} and
@code{libI77} libraries) provided as part of @code{f2c}, available for
free from @code{netlib} sites on the Internet.

@item
Cygnus Support and The Free Software Foundation contributed
significant money and/or equipment to Craig's efforts.

@item
The following individuals served as alpha testers prior to @code{g77}'s
public release.  This work consisted of testing, researching, sometimes
debugging, and occasionally providing small amounts of code and fixes
for @code{g77}, plus offering plenty of helpful advice to Craig:

@itemize @w{}
@item
Jonathan Corbet
@item
Dr.@: Mark Fernyhough
@item
Takafumi Hayashi (The University of AIzu)---@code{takafumi@@u-aizu.ac.jp}
@item
Kate Hedstrom
@item
Michel Kern (INRIA and Rice University)---@code{Michel.Kern@@inria.fr}
@item
Dr.@: A. O. V. Le Blanc
@item
Dave Love
@item
Rick Lutowski
@item
Toon Moene
@item
Rick Niles
@item
Derk Reefman
@item
Wayne K. Schroll
@item
Bill Thorson
@item
Pedro A. M. Vazquez
@item
Ian Watson
@end itemize

@item
Scott Snyder (@code{snyder@@d0sgif.fnal.gov})
provided the patch to add rudimentary support
for @samp{INTEGER*1}, @samp{INTEGER*2}, and
@samp{LOGICAL*1}.
This inspired Craig to add further support,
even though the resulting support
would still be incomplete, because version 0.6 is still
a ways off.

@item
David Ronis (@code{ronis@@onsager.chem.mcgill.ca}) inspired
and encouraged Craig to rewrite the documentation in texinfo
format by contributing a first pass at a translation of the
old @code{g77-0.5.16/f/DOC} file.

@item
Toon Moene (@code{toon@@moene.indiv.nluug.nl}) performed
some analysis of generated code as part of an overall project
to improve @code{g77} code generation to at least be as good
as @code{f2c} used in conjunction with @code{gcc}.
So far, this has resulted in the three, somewhat
experimental, options added by @code{g77} to the @code{gcc}
compiler and its back end.

@item
Many other individuals have helped debug, test, and improve @code{g77}
over the past several years, and undoubtedly more people
will be doing so in the future.
If you have done so, and would like
to see your name listed in the above list, please ask!
The default is that people wish to remain anonymous.
@end itemize

@node Funding
@chapter Funding Free Software

If you want to have more free software a few years from now, it makes
sense for you to help encourage people to contribute funds for its
development.  The most effective approach known is to encourage
commercial redistributors to donate.

Users of free software systems can boost the pace of development by
encouraging for-a-fee distributors to donate part of their selling price
to free software developers---the Free Software Foundation, and others.

The way to convince distributors to do this is to demand it and expect
it from them.  So when you compare distributors, judge them partly by
how much they give to free software development.  Show distributors
they must compete to be the one who gives the most.

To make this approach work, you must insist on numbers that you can
compare, such as, ``We will donate ten dollars to the Frobnitz project
for each disk sold.''  Don't be satisfied with a vague promise, such as
``A portion of the profits are donated,'' since it doesn't give a basis
for comparison.

Even a precise fraction ``of the profits from this disk'' is not very
meaningful, since creative accounting and unrelated business decisions
can greatly alter what fraction of the sales price counts as profit.
If the price you pay is $50, ten percent of the profit is probably
less than a dollar; it might be a few cents, or nothing at all.

Some redistributors do development work themselves.  This is useful too;
but to keep everyone honest, you need to inquire how much they do, and
what kind.  Some kinds of development make much more long-term
difference than others.  For example, maintaining a separate version of
a program contributes very little; maintaining the standard version of a
program for the whole community contributes much.  Easy new ports
contribute little, since someone else would surely do them; difficult
ports such as adding a new CPU to the GNU C compiler contribute more;
major new features or packages contribute the most.

By establishing the idea that supporting further development is ``the
proper thing to do'' when distributing free software for a fee, we can
assure a steady flow of resources into making more free software.

@display
Copyright (C) 1994 Free Software Foundation, Inc.
Verbatim copying and redistribution of this section is permitted
without royalty; alteration is not permitted.
@end display

@node Funding GNU Fortran
@chapter Funding GNU Fortran
@cindex funding improvements
@cindex improvements, funding

Work on GNU Fortran is still being done mostly by its author,
James Craig Burley (@code{burley@@gnu.ai.mit.edu}), who is a volunteer
for, not an employee of, the Free Software Foundation (FSF).
As with other GNU software, funding is important because it can pay for
needed equipment, personnel, and so on.

@cindex FSF, funding the
@cindex funding the FSF
The FSF provides information on the best way to fund ongoing
development of GNU software (such as GNU Fortran) in documents
such as the ``GNUS Bulletin''.
Email @code{gnu@@prep.ai.mit.edu} for information on funding the FSF.

To fund specific GNU Fortran work in particular, the FSF might
provide a means for that, but the FSF does not provide direct funding
to the author of GNU Fortran to continue his work.  The FSF has
employee salary restrictions that can be incompatible with the
financial needs of some volunteers, who therefore choose to
remain volunteers and thus be able to be free to do contract work
and otherwise make their own schedules for doing GNU work.

Still, funding the FSF at least indirectly benefits work
on specific projects like GNU Fortran because it ensures the
continuing operation of the FSF offices, their workstations, their
network connections, and so on, which are invaluable to volunteers.
(Similarly, hiring Cygnus Support can help a project like GNU
Fortran---Cygnus has been a long-time donor of equipment usage to the author
of GNU Fortran, and this too has been invaluable---@xref{Contributors}.)

Currently, the only way to directly fund the author of GNU Fortran
in his work on that project is to hire him for the work you want
him to do, or donate money to him.
Several people have done this
already, with the result that he has not needed to immediately find
contract work on a few occasions.
If more people did this, he
would be able to plan on not doing contract work for many months and
could thus devote that time to work on projects (such as the planned
changes for @code{g77-0.6}) that require longer timeframes to complete.
For the latest information on the status of the author, do
@samp{finger -l burley@@gnu.ai.mit.edu}, i.e. access @code{burley}'s
@code{.plan} file just as you would @code{fortran}'s to get @code{g77}
status (except there's no public @code{ftp} access to @code{burley}'s
@code{.plan} file---you can email him asking for it).

Another important way to support work on GNU Fortran is to volunteer
to help out.
Work is needed on documentation, testing, porting
to various machines, and in some cases, coding (although major
changes planned for version 0.6 make it difficult to add manpower to this
area).
Email @code{fortran@@gnu.ai.mit.edu} to volunteer for this work.

@xref{Funding,,Funding Free Software}, for more information.

@node Look and Feel
@chapter Protect Your Freedom---Fight ``Look And Feel''
@c the above chapter heading overflows onto the next line. --mew 1/26/93 

To preserve the ability to write free software, including replacements
for proprietary software, authors must be free to replicate the
user interface to which users of existing software have become
accustomed.

@xref{Look and Feel,,Protect Your Freedom---Fight ``Look And Feel'',
gcc,Using and Porting GNU CC}, for more information.

@node Getting Started
@chapter Getting Started
@cindex getting started
@cindex new users
@cindex newbies
@cindex beginners

If you don't need help getting started reading the portions
of this manual that are most important to you, you should skip
this portion of the manual.

If you are new to compilers, especially Fortran compilers, or
new to how compilers are structured under UNIX and UNIX-like
systems, you'll want to see @ref{What is GNU Fortran?}.

If you are new to GNU compilers, or have used only one GNU
compiler in the past and not had to delve into how it lets
you manage various versions and configurations of @code{gcc},
you should see @ref{G77 and GCC}.

Everyone except experienced @code{g77} users should
see @ref{Invoking G77}.

If you're acquainted with previous versions of @code{g77},
you should see @ref{News}.
Further, if you've actually used previous versions of @code{g77},
especially if you've written or modified Fortran code to
be compiled by previous versions of @code{g77}, you
should see @ref{Changes}.

If you intend to write or otherwise compile code that is
not already strictly conforming ANSI FORTRAN 77---and this
is probably everyone---you should see @ref{Language}.

If you don't already have @code{g77} installed on your
system, you must see @ref{Installation}.

If you run into trouble getting Fortran code to compile,
link, run, or work properly, you might find answers
if you see @ref{Debugging and Interfacing},
see @ref{Collected Fortran Wisdom},
and see @ref{Trouble}.
You might also find that the problems you are encountering
are bugs in @code{g77}---see @ref{Bugs}, for information on
reporting them, after reading the other material.

If you need further help with @code{g77}, or with
freely redistributable software in general,
see @ref{Service}.

If you would like to help the @code{g77} project,
see @ref{Funding GNU Fortran}, for information on
helping financially, and see @ref{Projects}, for information
on helping in other ways.

If you're generally curious about the future of
@code{g77}, see @ref{Projects}.
If you're curious about its past,
see @ref{Contributors},
and see @ref{Funding GNU Fortran}.

To see a few of the questions maintainers of @code{g77} have,
and that you might be able to answer,
see @ref{Open Questions}.

@ifset USING
@node What is GNU Fortran?
@chapter What is GNU Fortran?
@cindex concepts, basic
@cindex basic concepts

GNU Fortran, or @code{g77}, is designed initially as a free replacement
for, or alternative to, the UNIX @code{f77} command.
(Similarly, @code{gcc} is designed as a replacement
for the UNIX @code{cc} command.)

@code{g77} also is designed to fit in well with the other
fine GNU compilers and tools.

Sometimes these design goals conflict---in such cases, resolution
often is made in favor of fitting in well with Project GNU.
These cases are usually identified in the appropriate
sections of this manual.

@cindex compilers
As compilers, @code{g77}, @code{gcc}, and @code{f77}
share the following characteristics:

@itemize @bullet
@cindex source code
@cindex file, source
@cindex code, source
@cindex source file
@item
They read a user's program, stored in a file and
containing instructions written in the appropriate
language (Fortran, C, and so on).
This file contains @dfn{source code}.

@cindex translation of user programs
@cindex machine code
@cindex code, machine
@cindex mistakes
@item
They translate the user's program into instructions
a computer can carry out more quickly than it takes
to translate the instructions in the first place.
These instructions are called @dfn{machine code}---code
designed to be efficiently translated and processed
by a machine such as a computer.
Humans usually aren't as good writing machine code
as they are at writing Fortran or C, because
it is easy to make tiny mistakes writing machine code.
When writing Fortran or C, it is easy
to make big mistakes.

@cindex debugger
@cindex bugs
@cindex gdb command
@cindex commands, gdb
@item
They provide information in the generated machine code
that can make it easier to find bugs in the program
(using a debugging tool, called a @dfn{debugger},
such as @code{gdb}).

@cindex libraries
@cindex linking
@cindex ld command
@cindex commands, ld
@item
They locate and gather machine code already generated
to perform actions requested by statements in
the user's program.
This machine code is organized
into @dfn{libraries} and is located and gathered
during the @dfn{link} phase of the compilation
process.
(Linking often is thought of as a separate
step, because it can be directly invoked via the
@code{ld} command.
However, the @code{g77} and @code{gcc}
commands, as with most compiler commands, automatically
perform the linking step by calling on @code{ld}
directly, unless asked to not do so by the user.)

@cindex language, incorrect use of
@cindex incorrect use of language
@item
They attempt to diagnose cases where the user's
program contains incorrect usages of the language.
The @dfn{diagnostics} produced by the compiler
indicate the problem and the location in the user's
source file where the problem was first noticed.
The user can use this information to locate and
fix the problem.
@cindex diagnostics, incorrect
@cindex incorrect diagnostics
@cindex error messages, incorrect
@cindex incorrect error messages
(Sometimes an incorrect usage
of the language leads to a situation where the
compiler can no longer make any sense of what
follows---while a human might be able to---and
thus ends up complaining about many ``problems''
it encounters that, in fact, stem from just one
problem, usually the first one reported.)

@cindex warnings
@cindex questionable instructions
@item
They attempt to diagnose cases where the user's
program contains a correct usage of the language,
but instructs the computer to do something questionable.
These diagnostics often are in the form of @dfn{warnings},
instead of the @dfn{errors} that indicate incorrect
usage of the language.
@end itemize

How these actions are performed is generally under the
control of the user.
Using command-line options, the user can specify
how persnickety the compiler is to be regarding
the program (whether to diagnose questionable usage
of the language), how much time to spend making
the generated machine code run faster, and so on.

@cindex components of g77
@cindex g77, components of
@code{g77} consists of several components:

@cindex gcc command
@cindex commands, gcc
@itemize @bullet
@item
A modified version of the @code{gcc} command, which also might be
installed as the system's @code{cc} command.
(In many cases, @code{cc} refers to the
system's ``native'' C compiler, which
might be a non-GNU compiler, or an older version
of @code{gcc} considered more stable or that is
used to build the operating system kernel.)

@cindex g77 command
@cindex commands, g77
@item
The @code{g77} command itself, which also might be installed as the
system's @code{f77} command.

@cindex libf2c library
@cindex libraries, libf2c
@cindex run-time library
@item
The @code{libf2c} run-time library.
This library contains the machine code needed to support
capabilities of the Fortran language that are not directly
provided by the machine code generated by the @code{g77}
compilation phase.

@cindex f771 program
@cindex programs, f771
@cindex assembler
@cindex as command
@cindex commands, as
@cindex assembly code
@cindex code, assembly
@item
The compiler itself, internally named @code{f771}.

Note that @code{f771} does not generate machine code directly---it
generates @dfn{assembly code} that is a more readable form
of machine code, leaving the conversion to actual machine code
to an @dfn{assembler}, usually named @code{as}.
@end itemize

@code{gcc} is often thought of as ``the C compiler'' only,
but it does more than that.
Based on command-line options and the names given for files
on the command line, @code{gcc} determines which actions to perform, including
preprocessing, compiling (in a variety of possible languages), assembling,
and linking.

@cindex driver, gcc command as
@cindex gcc command as driver
@cindex executable file
@cindex files, executable
@cindex cc1 program
@cindex programs, cc1
@cindex preprocessor
@cindex cpp program
@cindex programs, cpp
For example, the command @samp{gcc foo.c} @dfn{drives} the file
@samp{foo.c} through the preprocessor @samp{cpp}, then
the C compiler (internally named
@code{cc1}), then the assembler (usually @code{as}), then the linker
(@code{ld}), producing an executable program named @file{a.out} (on
UNIX systems).

@cindex cc1plus program
@cindex programs, cc1plus
As another example, the command @samp{gcc foo.cc} would do much the same as
@samp{gcc foo.c}, but instead of using the C compiler named @code{cc1},
@code{gcc} would use the C++ compiler (named @code{cc1plus}).

@cindex f771 program
@cindex programs, f771
In a GNU Fortran installation, @code{gcc} recognizes Fortran source
files by name just like it does C and C++ source files.
It knows to use the Fortran compiler named @code{f771}, instead of
@code{cc1} or @code{cc1plus}, to compile Fortran files.

@cindex gcc not recognizing Fortran source
@cindex unrecognized file format
@cindex file format not recognized
Non-Fortran-related operation of @code{gcc} is generally
unaffected by installing the GNU Fortran version of @code{gcc}.
However, without the installed version of @code{gcc} being the
GNU Fortran version, @code{gcc} will not be able to compile
and link Fortran programs---and since @code{g77} uses @code{gcc}
to do most of the actual work, neither will @code{g77}!

@cindex g77 command
@cindex commands, g77
The @code{g77} command is essentially just a front-end for
the @code{gcc} command.
Fortran users will normally use @code{g77} instead of @code{gcc},
because @code{g77}
knows how to specify the libraries needed to link with Fortran programs
(@code{libf2c} and @code{lm}).
@code{g77} can still compile and link programs and
source files written in other languages, just like @code{gcc}.

@cindex printing version information
@cindex version information, printing
The command @samp{g77 -v} is a quick
way to display lots of version information for the various programs
used to compile a typical preprocessed Fortran source file---this
produces much more output than @samp{gcc -v} currently does.
(It also produces an error message near the end of the output,
a diagnostic from the linker, usually @code{ld}---you can safely
ignore this error, but do include the entire output with any
bug report you submit.)
In the output of this command, the line beginning @samp{GNU Fortran Front
End} identifies the version number of GNU Fortran; immediately
preceding that line is a line identifying the version of @code{gcc}
with which that version of @code{g77} was built.

@cindex libf2c library
@cindex libraries, libf2c
The @code{libf2c} library is distributed with GNU Fortran for
the convenience of its users, but is not part of GNU Fortran.
It contains the procedures
needed by Fortran programs while they are running.

@cindex in-line code
@cindex code, in-line
For example, while code generated by @code{g77} is likely
to do additions, subtractions, and multiplications @dfn{in line}---in
the actual compiled code---it is not likely to do trigonometric
functions this way.

Instead, operations like trigonometric
functions are compiled by the @code{f771} compiler
(invoked by @code{g77} when compiling Fortran code) into machine
code that, when run, calls on functions in @code{libf2c}, so
@code{libf2c} must be linked with almost every useful program
having any component compiled by GNU Fortran.
(As mentioned above, the @code{g77} command takes
care of all this for you.)

The @code{f771} program represents most of what is unique to GNU Fortran.
While the @code{libf2c} component is really part of @code{f2c}, a
free Fortran-to-C converter distributed by Bellcore (AT&T), and
the @code{g77} command is just a small front-end to @code{gcc},
@code{f771} is a combination of two rather
large chunks of code.

@cindex GNU Back End (GBE)
@cindex GBE
@cindex gcc back end
@cindex back end, gcc
@cindex code generator
One chunk is the so-called @dfn{GNU Back End}, or GBE,
which knows how to generate fast code for a wide variety of processors.
The same GBE is used by the C, C++, and Fortran compiler programs @code{cc1},
@code{cc1plus}, and @code{f771}, plus others.
Often the GBE is referred to as the ``gcc back end'' or
even just ``gcc''---in this manual, the term GBE is used
whenever the distinction is important.

@cindex GNU Fortran Front End (FFE)
@cindex FFE
@cindex g77 front end
@cindex front end, g77
The other chunk of @code{f771} is the
majority of what is unique about GNU Fortran---the code that knows how
to interpret Fortran programs to determine what they are intending to
do, and then communicate that knowledge to the GBE for actual compilation
of those programs.
This chunk is called the @dfn{Fortran Front End} (FFE).
The @code{cc1} and @code{cc1plus} programs have their own front ends,
for the C and C++ languages, respectively.
These fronts ends are responsible for diagnosing
incorrect usage of their respective languages by the
programs the process, and are responsible for most of
the warnings about questionable constructs as well.
(The GBE handles producing some warnings, like those
concerning possible references to undefined variables.)

Because so much is shared among the compilers for various languages,
much of the behavior and many of the user-selectable options for these
compilers are similar.
For example, diagnostics (error messages and
warnings) are similar in appearance; command-line
options like @samp{-Wall} have generally similar effects; and the quality
of generated code (in terms of speed and size) is roughly similar
(since that work is done by the shared GBE).

@node G77 and GCC
@chapter Compile Fortran, C, or Other Programs
@cindex compiling programs
@cindex programs, compiling

@cindex gcc command
@cindex commands, gcc
A GNU Fortran installation includes a modified version of the @code{gcc}
command.

In a non-Fortran installation, @code{gcc} recognizes C, C++,
and Objective-C source files.

In a GNU Fortran installation, @code{gcc} also recognizes Fortran source
files and accepts Fortran-specific command-line options, plus some
command-line options that are designed to cater to Fortran users
but apply to other languages as well.

@xref{G++ and GCC,,Compile C; C++; or Objective-C,gcc,Using and Porting GNU CC},
for information on the way different languages are handled
by the GNU CC compiler (@code{gcc}).

@cindex g77 command
@cindex commands, g77
Also provided as part of GNU Fortran is the @code{g77} command.
The @code{g77} command is designed to make compiling and linking Fortran
programs somewhat easier than when using the @code{gcc} command for
these tasks.
It does this by analyzing the command line somewhat and changing it
appropriately before submitting it to the @code{gcc} command.

@cindex -v option
@cindex g77 options, -v
@cindex options, -v
@cindex -@w{}-driver option
@cindex g77 options, -@w{}-driver
@cindex options, -@w{}-driver
Use the @samp{-v} option with @code{g77}
to see what is going on---the first line of output is the invocation
of the @code{gcc} command.
Use @samp{--driver=true} to disable actual invocation
of @code{gcc} (this works because @samp{true} is the name of a
UNIX command that simply returns success status).

@node Invoking G77
@chapter GNU Fortran Command Options
@cindex GNU Fortran command options
@cindex command options
@cindex options, GNU Fortran command

The @code{g77} command supports all the options supported by the
@code{gcc} command.
@xref{Invoking GCC,,GNU CC Command Options,gcc,Using and Porting GNU CC},
for information
on the non-Fortran-specific aspects of the @code{gcc} command (and,
therefore, the @code{g77} command).

The @code{g77} command supports one option not supported by
the @code{gcc} command:

@table @code
@cindex -@w{}-driver option
@cindex g77 options, driver
@cindex options, -@w{}-driver
@item --driver=@var{command}
Specifies that @var{command}, rather than @code{gcc}, is to
be invoked by @code{g77} to do its job.
For example, within the @samp{gcc} build directory after
building GNU Fortran (but without having to install it),
@samp{./g77 --driver=./xgcc foo.f -B./}.
@end table

@cindex options, negative forms
@cindex negative forms of options
All other options are supported both by @code{g77} and by @code{gcc} as
modified (and reinstalled) by the @code{g77} distribution.
In some cases, options have positive and negative forms;
the negative form of @samp{-ffoo} would be @samp{-fno-foo}.
This manual documents only one of these two forms, whichever
one is not the default.

@menu
* Option Summary::	Brief list of all @code{g77} options,
                        without explanations.
* Overall Options::     Controlling the kind of output:
                        an executable, object files, assembler files,
                        or preprocessed source.
* Shorthand Options::   Options that are shorthand for other options.
* Fortran Dialect Options::  Controlling the variant of Fortran language
                             compiled.
* Warning Options::     How picky should the compiler be?
* Debugging Options::   Symbol tables, measurements, and debugging dumps.
* Optimize Options::    How much optimization?
* Preprocessor Options:: Controlling header files and macro definitions.
                         Also, getting dependency information for Make.
* Directory Options::   Where to find header files and libraries.
                        Where to find the compiler executable files.
* Code Gen Options::    Specifying conventions for function calls, data layout
                        and register usage.
* Environment Variables:: Env vars that affect GNU Fortran.
@end menu

@node Option Summary
@section Option Summary

Here is a summary of all the options specific to GNU Fortran, grouped
by type.  Explanations are in the following sections.

@table @emph
@item Overall Options
@xref{Overall Options,,Options Controlling the Kind of Output}.
@smallexample
--driver  -fversion  -fset-g77-defaults
-fno-silent
@end smallexample

@item Shorthand Options
@xref{Shorthand Options}.
@smallexample
-ff66  -fno-f66
-ff77  -fno-f77
-fugly  -fno-ugly
@end smallexample

@item Fortran Language Options
@xref{Fortran Dialect Options,,Options Controlling Fortran Dialect}.
@smallexample
-ffree-form  -fno-fixed-form  -ff90  -fvxt-not-f90
-ff90-not-vxt  -fdollar-ok  -fno-backslash
-fno-ugly-args  -fno-ugly-assumed  -fugly-comma
-fugly-init  -fugly-logint
-fonetrip  -fno-typeless-boz
-fintrin-case-initcap  -fintrin-case-upper
-fintrin-case-lower  -fintrin-case-any
-fmatch-case-initcap  -fmatch-case-upper
-fmatch-case-lower  -fmatch-case-any
-fsource-case-upper -fsource-case-lower  -fsource-case-preserve
-fsymbol-case-initcap  -fsymbol-case-upper
-fsymbol-case-lower  -fsymbol-case-any
-fcase-strict-upper  -fcase-strict-lower
-fcase-initcap  -fcase-upper  -fcase-lower  -fcase-preserve
-fdcp-intrinsics-delete  -fdcp-intrinsics-hide
-fdcp-intrinsics-disable  -fdcp-intrinsics-enable
-ff2c-intrinsics-delete  -ff2c-intrinsics-hide
-ff2c-intrinsics-disable  -ff2c-intrinsics-enable
-ff90-intrinsics-delete  -ff90-intrinsics-hide
-ff90-intrinsics-disable  -ff90-intrinsics-enable
-fmil-intrinsics-delete  -fmil-intrinsics-hide
-fmil-intrinsics-disable  -fmil-intrinsics-enable
-funix-intrinsics-delete  -funix-intrinsics-hide
-funix-intrinsics-disable  -funix-intrinsics-enable
-fvxt-intrinsics-delete  -fvxt-intrinsics-hide
-fvxt-intrinsics-disable  -fvxt-intrinsics-enable
-ffixed-line-length-@var{n}  -ffixed-line-length-none
@end smallexample

@item Warning Options
@xref{Warning Options,,Options to Request or Suppress Warnings}.
@smallexample
-fsyntax-only  -pedantic  -pedantic-errors  -fpedantic
-w  -Wimplicit -Wunused  -Wuninitialized  -Wall  -Wsurprising
-Werror  -W
@end smallexample

@item Debugging Options
@xref{Debugging Options,,Options for Debugging Your Program or GCC}.
@smallexample
-g
@end smallexample

@item Optimization Options
@xref{Optimize Options,,Options that Control Optimization}.
@smallexample
-ffloat-store  -fforce-mem  -fforce-addr  -fno-inline
-ffast-math  -fstrength-reduce  -frerun-cse-after-loop
-fexpensive-optimizations  -fdelayed-branch
-fschedule-insns  -fschedule-insn2  -fcaller-saves
-funroll-loops  -funroll-all-loops
-fno-move-all-movables  -fno-reduce-all-givs
-fno-rerun-loop-opt
@end smallexample

@item Directory Options
@xref{Directory Options,,Options for Directory Search}.
@smallexample
-I@var{dir}  -I-
@end smallexample

@item Code Generation Options
@xref{Code Gen Options,,Options for Code Generation Conventions}.
@smallexample
-fno-automatic  -finit-local-zero  -fno-f2c
-ff2c-library  -fno-underscoring  -fno-ident
-fpcc-struct-return  -freg-struct-return
-fshort-double  -fno-common  -fpack-struct
-fzeros  -fno-second-underscore
-fdebug-kludge
@end smallexample
@end table

@menu
* Overall Options::     Controlling the kind of output:
                        an executable, object files, assembler files,
                        or preprocessed source.
* Shorthand Options::   Options that are shorthand for other options.
* Fortran Dialect Options::  Controlling the variant of Fortran language
                             compiled.
* Warning Options::     How picky should the compiler be?
* Debugging Options::   Symbol tables, measurements, and debugging dumps.
* Optimize Options::    How much optimization?
* Preprocessor Options:: Controlling header files and macro definitions.
                         Also, getting dependency information for Make.
* Directory Options::   Where to find header files and libraries.
                        Where to find the compiler executable files.
* Code Gen Options::    Specifying conventions for function calls, data layout
                        and register usage.
@end menu

@node Overall Options
@section Options Controlling the Kind of Output
@cindex overall options
@cindex options, overall

Compilation can involve as many as four stages: preprocessing, compilation
proper, assembly, and linking, always in that order.  The first three
stages apply to an individual source file, and end by producing an
object file; linking combines all the object files (those newly
compiled, and those specified as input) into an executable file.

@cindex file name suffix
@cindex suffixes, file name
@cindex file name extension
@cindex extensions, file name
@cindex file type
@cindex types, file
For any given input file, the file name suffix determines what kind of
compilation is done.
Suffixes specific to GNU Fortran are listed
below.
@xref{Overall Options,,gcc,Using and Porting GNU CC}, for
information on suffixes recognized by GNU CC.

@table @code
@item @var{file}.f
@item @var{file}.for
Fortran source code that should not be preprocessed.

@cindex preprocessor
@cindex C preprocessor
@cindex cpp preprocessor
@cindex Fortran preprocessor
@cindex cpp program
@cindex programs, cpp
@cindex .F
@cindex .fpp
@item @var{file}.F
@item @var{file}.fpp
Fortran source code that must be preprocessed (by the C preprocessor
@code{cpp}, which is part of GNU CC).
@end table

UNIX users typically use the @file{@var{file}.f} and @file{@var{file}.F}
nomenclature.
Users of other operating systems, especially those that cannot
distinguish upper-case
letters from lower-case letters in their file names, typically use
the @file{@var{file}.for} and @file{@var{file}.fpp} nomenclature.

@cindex #define
@cindex #include
@cindex #if
Use of the preprocessor @code{cpp} allows use of C-like
constructs such as @samp{#define} and @samp{#include}, but can
lead to unexpected, even mistaken, results due to Fortran's source file
format.
It is recommended that use of the C preprocessor
be limited to @samp{#include} and, in
conjunction with @samp{#define}, only @samp{#if} and related directives,
thus avoiding in-line macro expansion entirely.
This recommendation applies especially
when using the traditional fixed source form.
With free source form,
fewer unexpected transformations are likely to happen, but use of
Hollerith and things like continued character constants can nevertheless
present problems.

The following options that affect overall processing are recognized
by the @code{g77} and @code{gcc} commands in a GNU Fortran installation:

@table @code
@item --driver=@var{command}
This works only when invoking the @code{g77} command, not
when invoking the @code{gcc} command.
@xref{Invoking G77,,GNU Fortran Command Options}, for
information on this option.

@cindex -fversion option
@cindex options, -fversion
@cindex printing version information
@cindex version information, printing
@item -fversion
Ensure that the @code{g77}-specific version of the compiler phase is reported,
if run.
(This is supplied automatically when @samp{-v} or @samp{--verbose}
is specified as a command-line option for @code{g77} or @code{gcc}
and when the resulting commands compile Fortran source files.)

@cindex -fset-g77-defaults option
@cindex options, -fset-g77-defaults
@item -fset-g77-defaults
Set up whatever @code{gcc} options are to apply to Fortran
compilations.
As of version 0.5.18, this is equivalent to @samp{-fmove-all-movables
-freduce-all-givs -frerun-loop-opt}.
(This is supplied automatically when compiling Fortran code.
The description of this option is here so that users seeing
it in the output of, say, @samp{g77 -v} understand why it is
there.
Also, developers who run @code{f771} directly might want to specify it
by hand to get the same defaults as they would running @code{f771}
via @code{g77} or @code{gcc}.)

@cindex -fno-silent option
@cindex options, -fno-silent
@cindex @code{f2c} compatibility
@cindex compatibility, @code{f2c}
@cindex status, compilation
@cindex compilation status
@cindex reporting compilation status
@cindex printing compilation status
@item -fno-silent
Print (to @code{stderr}) the names of the program units as
they are compiled, in a form similar to that used by popular
UNIX @code{f77} implementations and @code{f2c}.
@end table

@xref{Overall Options,,Options Controlling the Kind of Output,
gcc,Using and Porting GNU CC}, for information
on more options that control the overall operation of the @code{gcc} command
(and, by extension, the @code{g77} command).

@node Shorthand Options
@section Shorthand Options
@cindex shorthand options
@cindex options, shorthand
@cindex macro options
@cindex options, macro

The following options serve as ``shorthand''
for other options accepted by the compiler:

@table @code
@cindex -fugly option
@cindex options, -fugly
@item -fugly
@cindex ugly features
@cindex features, ugly
Specify that certain ``ugly'' constructs are to be quietly accepted.
Same as:

@smallexample
-fugly-args -fugly-assumed -fugly-comma -fugly-init -fugly-logint
@end smallexample

These constructs are considered inappropriate to use in new
or well-maintained portable Fortran code, but widely used
in old code.
@xref{Distensions}, for more information.

@cindex -fno-ugly option
@cindex options, -fno-ugly
@item -fno-ugly
@cindex ugly features
@cindex features, ugly
Specify that all ``ugly'' constructs are to be noisily rejected.
Same as:

@smallexample
-fno-ugly-args -fno-ugly-assumed -fno-ugly-comma -fno-ugly-init
-fno-ugly-logint
@end smallexample

@cindex -ff66 option
@cindex options, -ff66
@item -ff66
@cindex FORTRAN 66
@cindex compatibility, FORTRAN 66
Specify that the program is written in idiomatic FORTRAN 66.
Same as @samp{-fonetrip -fugly-assumed}.

The @samp{-fno-f66} option is the inverse of @samp{-ff66}.
As such, it is the same as @samp{-fno-onetrip -fno-ugly-assumed}.

The meaning of this option is likely to be refined as future
versions of @code{g77} provide more compatibility with other
existing and obsolete Fortran implementations.

@cindex -ff77 option
@cindex options, -ff77
@item -ff77
@cindex UNIX f77
@cindex @code{f2c} compatibility
@cindex compatibility, @code{f2c}
@cindex @code{f77} compatibility
@cindex compatibility, @code{f77}
Specify that the program is written in idiomatic UNIX FORTRAN 77
and/or the dialect accepted by the @code{f2c} product.
Same as @samp{-fbackslash -fno-typeless-boz}.

The meaning of this option is likely to be refined as future
versions of @code{g77} provide more compatibility with other
existing and obsolete Fortran implementations.

@cindex -fno-f77 option
@cindex options, -fno-f77
@item -fno-f77
@cindex UNIX f77
The @samp{-fno-f77} option is @emph{not} the inverse
of @samp{-ff77}.
It specifies that the program is not written in idiomatic UNIX
FORTRAN 77 or @code{f2c}, but in a more widely portable dialect.
@samp{-fno-f77} is the same as @samp{-fno-backslash}.

The meaning of this option is likely to be refined as future
versions of @code{g77} provide more compatibility with other
existing and obsolete Fortran implementations.
@end table

@node Fortran Dialect Options
@section Options Controlling Fortran Dialect
@cindex dialect options
@cindex language dialect options
@cindex options, dialect

The following options control the dialect of Fortran
that the compiler accepts:

@table @code
@cindex -ffree-form option
@cindex options, -ffree-form
@cindex -fno-fixed-form option
@cindex options, -fno-fixed-form
@cindex source file form
@cindex free form
@cindex fixed form
@cindex Fortran 90 features
@item -ffree-form
@item -fno-fixed-form
Specify that the source file is written in free form
(introduced in Fortran 90) instead of the more-traditional fixed form.

@cindex -ff90 option
@cindex options, -ff90
@cindex Fortran 90 features
@item -ff90
Allow certain Fortran-90 constructs.

This option controls whether certain
Fortran 90 constructs are recognized.
(Other Fortran 90 constructs
might or might not be recognized depending on other options such as
@samp{-fvxt-not-f90}, @samp{-ff90-intrinsics-enable}, and the
current level of support for Fortran 90.)

@xref{Extensions,,GNU Fortran Extensions}, for more information.

@cindex -fvxt-not-f90 option
@cindex options, -fvxt-not-f90
@item -fvxt-not-f90
@cindex -ff90-not-vxt option
@cindex options, -ff90-not-vxt
@item -ff90-not-vxt
@cindex Fortran 90 features
@cindex VXT features
Specify whether Fortran 90 or other popular extensions
are to be assumed for ambiguous constructs.
The default is -fvxt-not-f90.

For example, with @samp{-ff90-not-vxt},
@samp{PRINT *,"double-quoted string"} is valid,
while with @samp{-fvxt-not-f90}, @samp{PRINT *,"2000} is valid.

(There is no way to allow
both constructs in the general case, since statements like
@samp{PRINT *,"2000 !comment?"} would be ambiguous.)

@xref{Dialects,,GNU Fortran Dialects}, for more information.

@cindex -fdollar-ok option
@cindex options, -fdollar-ok
@item -fdollar-ok
@cindex dollar sign
@cindex symbol names
@cindex character set
Allow @samp{$} as a valid character in a symbol name.

@cindex -fno-backslash option
@cindex options, -fno-backslash
@item -fno-backslash
@cindex backslash
@cindex character constants
@cindex Hollerith constants
Specify that @samp{\} is not to be specially interpreted in character
and Hollerith constants a la C and many UNIX Fortran compilers.

For example, with @samp{-fbackslash} in effect, @samp{A\nB} specifies
three characters, with the second one being newline.
With @samp{-fno-backslash}, it specifies four characters,
@samp{A}, @samp{\}, @samp{n}, and @samp{B}.

Note that @code{g77} implements a fairly general form of backslash
processing that is incompatible with the narrower forms supported
by some other compilers.
For example, @samp{'A\003B'} is a three-character string in @code{g77},
whereas other compilers that support backslash might not support
the three-octal-digit form, and thus treat that string as longer
than three characters.

@xref{Backslash in Constants}, for
information on why @samp{-fbackslash} is the default
instead of @samp{-fno-backslash}.

@cindex -fno-ugly-args option
@cindex options, -fno-ugly-args
@item -fno-ugly-args
Disallow passing Hollerith and typeless constants as actual
arguments (for example, @samp{CALL FOO(4HABCD)}).

@xref{Ugly Implicit Argument Conversion}, for more information.

@cindex -fugly-assumed option
@cindex options, -fugly-assumed
@item -fugly-assumed
Assume any array with a final dimension specified as @samp{1}
is really an assumed-size array, as if @samp{*} had been specified
instead.

For example, @samp{DIMENSION X(1)} is treated as if it
had read @samp{DIMENSION X(*)}.

@xref{Ugly Assumed-Size Arrays}, for more information.

@cindex -fugly-comma option
@cindex options, -fugly-comma
@item -fugly-comma
Treat a trailing comma in an argument list as specification
of a trailing null argument, and treat an empty argument
list as specification of a single null argument.

For example, @samp{CALL FOO(,)} is treated as
@samp{CALL FOO(%VAL(0), %VAL(0))}.
That is, @emph{two} null arguments are specified
by the procedure call when @samp{-fugly-comma} is in force.
And @samp{F = FUNC()} is treated as @samp{F = FUNC(%VAL(0))}.

The default behavior, @samp{-fno-ugly-comma}, is to ignore
a single trailing comma in an argument list.

@xref{Ugly Null Arguments}, for more information.

@cindex -fno-ugly-init option
@cindex options, -fno-ugly-init
@item -fno-ugly-init
Disallow use of Hollerith and typeless constants as initial
values (in @code{PARAMETER} and @code{DATA} statements), and
use of character constants to
initialize numeric types and vice versa.

For example, @samp{DATA I/'F'/, CHRVAR/65/, J/4HABCD/} is disallowed by
@samp{-fno-ugly-init}.

@xref{Ugly Conversion of Initializers}, for more information.

@cindex -fugly-logint option
@cindex options, -fugly-logint
@item -fugly-logint
Treat @samp{INTEGER} and @samp{LOGICAL} variables and
expressions as potential stand-ins for each other.

For example, automatic conversion between @samp{INTEGER} and
@samp{LOGICAL} is enabled, for many contexts, via this option.

@xref{Ugly Integer Conversions}, for more information.

@cindex -fonetrip option
@cindex options, -fonetrip
@item -fonetrip
@cindex FORTRAN 66
@cindex DO loops, one-trip
@cindex one-trip DO loops
@cindex compatibility, FORTRAN 66
Imperative executable @samp{DO} loops are to be executed at
least once each time they are reached.

ANSI FORTRAN 77 and more recent versions of the Fortran standard
specify that the body of an imperative @samp{DO} loop is not executed
if the number of iterations calculated from the parameters of the
loop is less than 1.
(For example, @samp{DO 10 I = 1, 0}.)
Such a loop is called a @dfn{zero-trip loop}.

Prior to ANSI FORTRAN 77, many compilers implemented @samp{DO} loops
such that the body of a loop would be executed at least once, even
if the iteration count was zero.
Fortran code written assuming this behavior is said to require
@dfn{one-trip loops}.
For example, some code written to the FORTRAN 66 standard
expects this behavior from its @samp{DO} loops, although that
standard did not specify this behavior.

The @samp{-fonetrip} option specifies that the source file(s) being
compiled require one-trip loops.

This option affects only those loops specified by the (imperative) @samp{DO}
statement and by implied-@samp{DO} lists in I/O statements.
Loops specified by implied-@samp{DO} lists in @samp{DATA} and
specification (non-executable) statements are not affected.

@cindex -fno-typeless-boz option
@cindex options, -fno-typeless-boz
@cindex prefix-radix constants
@cindex constants, prefix-radix
@cindex constants, types
@cindex types, constants
@item -fno-typeless-boz
Specifies that prefix-radix non-decimal constants, such as
@samp{Z'ABCD'}, as @samp{INTEGER} instead of typeless.

Currently plans call for this option being the default as of
version 0.5.20.

You can test for yourself whether a particular compiler treats
the prefix form as @samp{INTEGER} or typeless by running the
following program:

@smallexample
EQUIVALENCE (I, R)
R = Z'ABCD1234'
J = Z'ABCD1234'
IF (J .EQ. I) PRINT *, 'Prefix form is TYPELESS'
IF (J .NE. I) PRINT *, 'Prefix form is INTEGER'
END
@end smallexample

Reports indicate that many compilers process this form as
@samp{INTEGER}, though a few as typeless, and at least one
based on a command-line option specifying some kind of
compatibility.

@cindex -fintrin-case-initcap option
@cindex options, -fintrin-case-initcap
@item -fintrin-case-initcap
@cindex -fintrin-case-upper option
@cindex options, -fintrin-case-upper
@item -fintrin-case-upper
@cindex -fintrin-case-lower option
@cindex options, -fintrin-case-lower
@item -fintrin-case-lower
@cindex -fintrin-case-any option
@cindex options, -fintrin-case-any
@item -fintrin-case-any
Specify expected case for intrinsic names.
@samp{-fintrin-case-lower} is the default.

@cindex -fmatch-case-initcap option
@cindex options, -fmatch-case-initcap
@item -fmatch-case-initcap
@cindex -fmatch-case-upper option
@cindex options, -fmatch-case-upper
@item -fmatch-case-upper
@cindex -fmatch-case-lower option
@cindex options, -fmatch-case-lower
@item -fmatch-case-lower
@cindex -fmatch-case-any option
@cindex options, -fmatch-case-any
@item -fmatch-case-any
Specify expected case for keywords.
@samp{-fmatch-case-lower} is the default.

@cindex -fsource-case-upper option
@cindex options, -fsource-case-upper
@item -fsource-case-upper
@cindex -fsource-case-lower option
@cindex options, -fsource-case-lower
@item -fsource-case-lower
@cindex -fsource-case-preserve option
@cindex options, -fsource-case-preserve
@item -fsource-case-preserve
Specify whether source text other than character and Hollerith constants
is to be translated to uppercase, to lowercase, or preserved as is.
@samp{-fsource-case-lower} is the default.

@cindex -fsymbol-case-initcap option
@cindex options, -fsymbol-case-initcap
@item -fsymbol-case-initcap
@cindex -fsymbol-case-upper option
@cindex options, -fsymbol-case-upper
@item -fsymbol-case-upper
@cindex -fsymbol-case-lower option
@cindex options, -fsymbol-case-lower
@item -fsymbol-case-lower
@cindex -fsymbol-case-any option
@cindex options, -fsymbol-case-any
@item -fsymbol-case-any
Specify valid cases for user-defined symbol names.
@samp{-fsymbol-case-any} is the default.

@cindex -fcase-strict-upper option
@cindex options, -fcase-strict-upper
@item -fcase-strict-upper
Same as @samp{-fintrin-case-upper -fmatch-case-upper -fsource-case-preserve
-fsymbol-case-upper}.
(Requires all pertinent source to be in uppercase.)

@cindex -fcase-strict-lower option
@cindex options, -fcase-strict-lower
@item -fcase-strict-lower
Same as @samp{-fintrin-case-lower -fmatch-case-lower -fsource-case-preserve
-fsymbol-case-lower}.
(Requires all pertinent source to be in lowercase.)

@cindex -fcase-initcap option
@cindex options, -fcase-initcap
@item -fcase-initcap
Same as @samp{-fintrin-case-initcap -fmatch-case-initcap -fsource-case-preserve
-fsymbol-case-initcap}.
(Requires all pertinent source to be in initial capitals,
as in @samp{Print *,SqRt(Value)}.)

@cindex -fcase-upper option
@cindex options, -fcase-upper
@item -fcase-upper
Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-upper
-fsymbol-case-any}.
(Maps all pertinent source to uppercase.)

@cindex -fcase-lower option
@cindex options, -fcase-lower
@item -fcase-lower
Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-lower
-fsymbol-case-any}.
(Maps all pertinent source to lowercase.)

@cindex -fcase-preserve option
@cindex options, -fcase-preserve
@item -fcase-preserve
Same as @samp{-fintrin-case-any -fmatch-case-any -fsource-case-preserve
-fsymbol-case-any}.
(Preserves all case in user-defined symbols,
while allowing any-case matching of intrinsics and keywords.
For example, @samp{call Foo(i,I)} would pass two @emph{different}
variables named @samp{i} and @samp{I} to a procedure named @samp{Foo}.)

@cindex -fdcp-intrinsics-delete option
@cindex options, -fdcp-intrinsics-delete
@item -fdcp-intrinsics-delete
@cindex -fdcp-intrinsics-hide option
@cindex options, -fdcp-intrinsics-hide
@item -fdcp-intrinsics-hide
@cindex -fdcp-intrinsics-disable option
@cindex options, -fdcp-intrinsics-disable
@item -fdcp-intrinsics-disable
@cindex -fdcp-intrinsics-enable option
@cindex options, -fdcp-intrinsics-enable
@item -fdcp-intrinsics-enable
@cindex Digital Fortran features
@cindex COMPLEX intrinsics
@cindex intrinsics, COMPLEX
Specify status of Digital's COMPLEX-related intrinsics.
@samp{-fdcp-intrinsics-enable} is the default.

@cindex -ff2c-intrinsics-delete option
@cindex options, -ff2c-intrinsics-delete
@item -ff2c-intrinsics-delete
@cindex -ff2c-intrinsics-hide option
@cindex options, -ff2c-intrinsics-hide
@item -ff2c-intrinsics-hide
@cindex -ff2c-intrinsics-disable option
@cindex options, -ff2c-intrinsics-disable
@item -ff2c-intrinsics-disable
@cindex -ff2c-intrinsics-enable option
@cindex options, -ff2c-intrinsics-enable
@item -ff2c-intrinsics-enable
@cindex f2c intrinsics
@cindex intrinsics, f2c
Specify status of f2c-specific intrinsics.
@samp{-ff2c-intrinsics-enable} is the default.

@cindex -ff90-intrinsics-delete option
@cindex options, -ff90-intrinsics-delete
@item -ff90-intrinsics-delete
@cindex -ff90-intrinsics-hide option
@cindex options, -ff90-intrinsics-hide
@item -ff90-intrinsics-hide
@cindex -ff90-intrinsics-disable option
@cindex options, -ff90-intrinsics-disable
@item -ff90-intrinsics-disable
@cindex -ff90-intrinsics-enable option
@cindex options, -ff90-intrinsics-enable
@item -ff90-intrinsics-enable
@cindex Fortran 90 intrinsics
@cindex intrinsics, Fortran 90
Specify status of F90-specific intrinsics.
@samp{-ff90-intrinsics-delete} is the default.

@cindex -fmil-intrinsics-delete option
@cindex options, -fmil-intrinsics-delete
@item -fmil-intrinsics-delete
@cindex -fmil-intrinsics-hide option
@cindex options, -fmil-intrinsics-hide
@item -fmil-intrinsics-hide
@cindex -fmil-intrinsics-disable option
@cindex options, -fmil-intrinsics-disable
@item -fmil-intrinsics-disable
@cindex -fmil-intrinsics-enable option
@cindex options, -fmil-intrinsics-enable
@item -fmil-intrinsics-enable
@cindex MIL-STD 1753
@cindex intrinsics, MIL-STD 1753
Specify status of MIL-STD-1753-specific intrinsics.
@samp{-fmil-intrinsics-enable} is the default.

@cindex -funix-intrinsics-delete option
@cindex options, -funix-intrinsics-delete
@item -funix-intrinsics-delete
@cindex -funix-intrinsics-hide option
@cindex options, -funix-intrinsics-hide
@item -funix-intrinsics-hide
@cindex -funix-intrinsics-disable option
@cindex options, -funix-intrinsics-disable
@item -funix-intrinsics-disable
@cindex -funix-intrinsics-enable option
@cindex options, -funix-intrinsics-enable
@item -funix-intrinsics-enable
@cindex UNIX intrinsics
@cindex intrinsics, UNIX
Specify status of UNIX intrinsics.
@samp{-funix-intrinsics-enable} is the default.

@cindex FLUSH() intrinsic
@cindex intrinsics, FLUSH()
For example, if your code invokes @code{FLUSH} as
a library function and thus works with other UNIX Fortran
compilers or earlier version of @code{g77}, either add the
@samp{EXTERNAL FLUSH} statement or, perhaps
more convenient for you, compile with the
@samp{-funix-intrinsics-hide} or
@samp{-funix-intrinsics-delete} option.

@cindex ABORT() intrinsic
@cindex intrinsics, ABORT()
@cindex EXIT() intrinsic
@cindex intrinsics, EXIT()
@cindex FSEEK() intrinsic
@cindex intrinsics, FSEEK()
@cindex SIGNAL() intrinsic
@cindex intrinsics, SIGNAL()
@cindex SYSTEM() intrinsic
@cindex intrinsics, SYSTEM()
@cindex intrinsic subroutines
@cindex subroutines, intrinsic
@cindex intrinsic functions
@cindex functions, intrinsic
@cindex side effects
@cindex intrinsics, side effects of
Note that @code{ABORT}, @code{EXIT}, @code{FLUSH}, @code{FSEEK},
@code{SIGNAL}, and
@code{SYSTEM} are intrinsic subroutines, not functions (since they have
side effects), so to get the return values from @code{FSEEK},
@code{SIGNAL}, and @code{SYSTEM}, append a final argument specifying
an @samp{INTEGER}
variable or array element to receive the returned status.
(For example, @samp{CALL SYSTEM('rm foo',ISTAT)}.)

@code{FLUSH()} accepts an optional single @samp{INTEGER} argument,
since many Fortran implementations allow or require a unit number.
Currently, since @code{libf2c}
does not flush a given unit number, this argument is not used---all
units are flushed by @code{libf2c}'s implementation of @code{FLUSH()}.
Do not depend on this behavior---if you want to flush all units,
use @samp{CALL FLUSH} (that is, specify no arguments to @code{FLUSH}).

@code{EXIT()} accepts an optional single @samp{INTEGER} argument.
If omitted, zero is the default (as in @samp{CALL EXIT(0)}).
The default might change on
configurations where the ``normal return status'' is not zero, however.
If you want to return a ``success'' status, it is best to call @code{EXIT}
with no arguments in your code, and let @code{g77} choose the appropriate
default.

@cindex -fvxt-intrinsics-delete option
@cindex options, -fvxt-intrinsics-delete
@item -fvxt-intrinsics-delete
@cindex -fvxt-intrinsics-hide option
@cindex options, -fvxt-intrinsics-hide
@item -fvxt-intrinsics-hide
@cindex -fvxt-intrinsics-disable option
@cindex options, -fvxt-intrinsics-disable
@item -fvxt-intrinsics-disable
@cindex -fvxt-intrinsics-enable option
@cindex options, -fvxt-intrinsics-enable
@item -fvxt-intrinsics-enable
@cindex VXT intrinsics
@cindex intrinsics, VXT
Specify status of VXT intrinsics.
@samp{-fvxt-intrinsics-delete} is the default.

@cindex -ffixed-line-length-@var{n} option
@cindex options, -ffixed-line-length-@var{n}
@item -ffixed-line-length-@var{n}
@cindex source file format
@cindex line length
@cindex length of source lines
@cindex fixed-form line length
Set column after which characters are ignored in typical fixed-form
lines in the source file.

@cindex card image
@cindex extended-source option
Popular values for @var{n} include 72 (the
standard and the default), 80 (card image), and 132 (corresponds
to ``extended-source'' options in some popular compilers).
@var{n} may be @samp{none}, meaning that the entire line is meaningful
and that continued character constants never have implicit spaces appended
to them to fill out the line.
@samp{-ffixed-line-length-0} means the same thing as
@samp{-ffixed-line-length-none}.
@end table

@node Warning Options
@section Options to Request or Suppress Warnings
@cindex options to control warnings
@cindex warning messages
@cindex messages, warning
@cindex suppressing warnings

Warnings are diagnostic messages that report constructions which
are not inherently erroneous but which are risky or suggest there
might have been an error.

You can request many specific warnings with options beginning @samp{-W},
for example @samp{-Wimplicit} to request warnings on implicit
declarations.  Each of these specific warning options also has a
negative form beginning @samp{-Wno-} to turn off warnings;
for example, @samp{-Wno-implicit}.  This manual lists only one of the
two forms, whichever is not the default.

These options control the amount and kinds of warnings produced by GNU
Fortran:

@table @code
@cindex syntax checking
@cindex -fsyntax-only option
@cindex options, -fsyntax-only
@item -fsyntax-only
Check the code for syntax errors, but don't do anything beyond that.

@cindex -pedantic option
@cindex options, -pedantic
@item -pedantic
Issue warnings for uses of extensions to ANSI FORTRAN 77.
@samp{-pedantic} also applies to C-language constructs where they
occur in GNU Fortran source files, such as use of @samp{\e} in a
character constant within a directive like @samp{#include}.

Valid ANSI FORTRAN 77 programs should compile properly with or without
this option.
However, without this option, certain GNU extensions and traditional
Fortran features are supported as well.
With this option, many of them are rejected.

Some users try to use @samp{-pedantic} to check programs for strict ANSI
conformance.  They soon find that it does not do quite what they want:
it finds some non-ANSI practices, but not all---however, improvements
to @code{g77} in this area are welcome.

@cindex -pedantic-errors option
@cindex options, -pedantic-errors
@item -pedantic-errors
Like @samp{-pedantic}, except that errors are produced rather than
warnings.

@cindex -fpedantic option
@cindex options, -fpedantic
@item -fpedantic
Like @samp{-pedantic}, but applies only to Fortran constructs.

@cindex -w option
@cindex options, -w
@item -w
Inhibit all warning messages.

@cindex -Wimplicit option
@cindex options, -Wimplicit
@item -Wimplicit
@cindex implicit declaration, warning
@cindex warnings, implicit declaration
@cindex -u option
@cindex /WARNINGS=DECLARATIONS switch
@cindex IMPLICIT NONE, similar effect
@cindex effecting IMPLICIT NONE
Warn whenever a variable, array, or function is implicitly
declared.
Has an effect similar to using the @samp{IMPLICIT NONE} statement
in every program unit.
(Some Fortran compilers provide this feature by an option
named @samp{-u} or @samp{/WARNINGS=DECLARATIONS}.)

@cindex -Wunused option
@cindex options, -Wunused
@item -Wunused
@cindex unused variables
@cindex variables, unused
Warn whenever a variable is unused aside from its declaration.

@cindex -Wuninitialized option
@cindex options, -Wuninitialized
@item -Wuninitialized
@cindex uninitialized variables
@cindex variables, uninitialized
Warn whenever an automatic variable is used without first being initialized.

These warnings are possible only in optimizing compilation,
because they require data flow information that is computed only
when optimizing.  If you don't specify @samp{-O}, you simply won't
get these warnings.

These warnings occur only for variables that are candidates for
register allocation.  Therefore, they do not occur for a variable
@c that is declared @code{VOLATILE}, or
whose address is taken, or whose size
is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for
arrays, even when they are in registers.

Note that there might be no warning about a variable that is used only
to compute a value that itself is never used, because such
computations may be deleted by data flow analysis before the warnings
are printed.

These warnings are made optional because GNU Fortran is not smart
enough to see all the reasons why the code might be correct
despite appearing to have an error.  Here is one example of how
this can happen:

@example
SUBROUTINE DISPAT(J)
IF (J.EQ.1) I=1
IF (J.EQ.2) I=4
IF (J.EQ.3) I=5
CALL FOO(I)
END
@end example

@noindent
If the value of @code{J} is always 1, 2 or 3, then @code{I} is
always initialized, but GNU Fortran doesn't know this.  Here is
another common case:

@example
SUBROUTINE MAYBE(FLAG)
LOGICAL FLAG
IF (FLAG) VALUE = 9.4
@dots{}
IF (FLAG) PRINT *, VALUE
END
@end example

@noindent
This has no bug because @code{VALUE} is used only if it is set.

@cindex -Wall option
@cindex options, -Wall
@item -Wall
@cindex all warnings
@cindex warnings, all
The @samp{-Wunused} and @samp{-Wuninitialized} options combined.
These are all the
options which pertain to usage that we recommend avoiding and that we
believe is easy to avoid.
(As more warnings are added to @code{g77}, some might
be added to the list enabled by @samp{-Wall}.)
@end table

The remaining @samp{-W@dots{}} options are not implied by @samp{-Wall}
because they warn about constructions that we consider reasonable to
use, on occasion, in clean programs.

@table @code
@c @item -W
@c Print extra warning messages for these events:
@c 
@c @itemize @bullet
@c @item
@c If @samp{-Wall} or @samp{-Wunused} is also specified, warn about unused
@c arguments.
@c 
@c @end itemize
@c
@cindex -Wsurprising option
@cindex options, -Wsurprising
@item -Wsurprising
Warn about ``suspicious'' constructs that are interpreted
by the compiler in a way that might well be surprising to
someone reading the code.
These differences can result in subtle, compiler-dependent
(even machine-dependent) behavioral differences.
The constructs warned about include:

@itemize @bullet
@item
Expressions having two arithmetic operators in a row, such
as @samp{X*-Y}.
Such a construct is nonstandard, and can produce
unexpected results in more complicated situations such
as @samp{X**-Y*Z}.
@code{g77}, along with many other compilers, interprets
this example differently than many programmers, and a few
other compilers.
Specifically, @code{g77} interprets @samp{X**-Y*Z} as
@samp{(X**(-Y))*Z}, while others might think it should
be interpreted as @samp{X**(-(Y*Z))}.

A revealing example is the constant expression @samp{2**-2*1.},
which @code{g77} evaluates to .25, while others might evaluate
it to 0., the difference being the way precedence affects type
promotion.

(The @samp{-fpedantic} option also warns about expressions
having two arithmetic operators in a row.)

@item
Expressions with a unary minus followed by an operand and then
a binary operator other than plus or minus.
For example, @samp{-2**2} produces a warning, because
the precedence is @samp{-(2**2)}, yielding -4, not
@samp{(-2)**2}, which yields 4, and which might represent
what a programmer expects.

An example of an expression producing different results
in a surprising way is @samp{-I*S}, where @var{I} holds
the value @samp{-2147483648} and @var{S} holds @samp{0.5}.
On many systems, negating @var{I} results in the same
value, not a positive number, because it is already the
lower bound of what an @samp{INTEGER} variable can hold.
So, the expression evaluates to a positive number, while
the ``expected'' interpretation, @samp{(-I)*S}, would
evaluate to a negative number.

Even cases such as @samp{-I*J} produce warnings,
even though, in most configurations and situations,
there is no computational difference between the
results of the two interpretations---the purpose
of this warning is to warn about differing interpretations
and encourage a better style of coding, not to identify
only those places where bugs might exist in the user's
code.

@cindex DO statement
@cindex statements, DO
@item
@samp{DO} loops with @samp{DO} variables that are not
of integral type---that is, using @samp{REAL} or
@samp{DOUBLE PRECISION} variables as loop control
variables.
Although such loops can be written to work in the
``obvious'' way, the way @code{g77} is required by the
Fortran standard to interpret such code is likely to
be quite different from the way many programmers expect.
(This is true of all @samp{DO} loops, but the differences
are pronounced for non-integral loop control variables.)

@xref{Loops}, for more information.
@end itemize

@cindex -Werror option
@cindex options, -Werror
@item -Werror
Make all warnings into errors.

@cindex -W option
@cindex options, -W
@item -W
@cindex extra warnings
@cindex warnings, extra
Turns on ``extra warnings'' and the @samp{uninitialized} option.
(This might change in future versions of @code{g77}.)

``Extra warnings'' are issued for:

@itemize @bullet
@item
@cindex unused parameters
@cindex parameters, unused
@cindex unused arguments
@cindex arguments, unused
@cindex unused dummies
@cindex dummies, unused
Unused parameters to a procedure (when @samp{-Wunused} also is
specified).

@item
@cindex overflow
Overflows involving floating-point constants (not available
for certain configurations?).
@end itemize
@end table

@xref{Warning Options,,Options to Request or Suppress Warnings,
gcc,Using and Porting GNU CC}, for information on more options offered
by the GBE shared by @code{g77}, @code{gcc}, and other GNU compilers.

Some of these have no effect when compiling programs written in Fortran:

@table @code
@cindex -Wcomment option
@cindex options, -Wcomment
@item -Wcomment
@cindex -Wformat option
@cindex options, -Wformat
@item -Wformat
@cindex -Wparentheses option
@cindex options, -Wparentheses
@item -Wparentheses
@cindex -Wswitch option
@cindex options, -Wswitch
@item -Wswitch
@cindex -Wtraditional option
@cindex options, -Wtraditional
@item -Wtraditional
@cindex -Wshadow option
@cindex options, -Wshadow
@item -Wshadow
@cindex -Wid-clash-@var{len} option
@cindex options, -Wid-clash-@var{len}
@item -Wid-clash-@var{len}
@cindex -Wlarger-than-@var{len} option
@cindex options, -Wlarger-than-@var{len}
@item -Wlarger-than-@var{len}
@cindex -Wconversion option
@cindex options, -Wconversion
@item -Wconversion
@cindex -Waggregate-return option
@cindex options, -Waggregate-return
@item -Waggregate-return
@cindex -Wredundant-decls option
@cindex options, -Wredundant-decls
@item -Wredundant-decls
@cindex unsupported warnings
@cindex warnings, unsupported
These options all could have some relevant meaning for
GNU Fortran programs, but are not yet supported.
@end table

@node Debugging Options
@section Options for Debugging Your Program or GNU Fortran
@cindex options, debugging
@cindex debugging information options

GNU Fortran has various special options that are used for debugging
either your program or @code{g77}.

@table @code
@cindex -g option
@cindex options, -g
@item -g
Produce debugging information in the operating system's native format
(stabs, COFF, XCOFF, or DWARF).  GDB can work with this debugging
information.

@cindex COMMON blocks
@cindex EQUIVALENCE areas
@cindex missing debug features
Support for this option in Fortran programs is incomplete.
In particular, names of variables and arrays in common blocks
or that are storage-associated via @samp{EQUIVALENCE} are
unavailable to the debugger.

However, version 0.5.19 of @code{g77} does provide this information
in a rudimentary way, as controlled by the
@samp{-fdebug-kludge} option.

@xref{Code Gen Options,,Options for Code Generation Conventions},
for more information.
@end table

@xref{Debugging Options,,Options for Debugging Your Program or GNU CC,
gcc,Using and Porting GNU CC}, for more information on debugging options.

@node Optimize Options
@section Options That Control Optimization
@cindex optimize options
@cindex options, optimization

Most Fortran users will want to use no optimization when
developing and testing programs, and use @samp{-O} or @samp{-O2} when
compiling programs for late-cycle testing and for production use.

The following flags have particular applicability when
compiling Fortran programs:

@table @code
@cindex -ffloat-store option
@cindex options, -ffloat-store
@item -ffloat-store
@cindex IEEE conformance
@cindex conformance, IEEE
Might help a Fortran program that depends on exact IEEE conformance
on some machines, but might slow down a program that doesn't.

@cindex -fforce-mem option
@cindex options, -fforce-mem
@item -fforce-mem
@cindex -fforce-addr option
@cindex options, -fforce-addr
@item -fforce-addr
@cindex loops, speeding up
@cindex speeding up loops
Might improve optimization of loops.

@cindex -fno-inline option
@cindex options, -fno-inline
@item -fno-inline
@cindex in-line compilation
@cindex compilation, in-line
Don't compile statement functions inline.
Might reduce the size of a program unit---which might be at
expense of some speed (though it should compile faster).
Note that if you are not optimizing, no functions can be expanded inline.

@cindex -ffast-math option
@cindex options, -ffast-math
@item -ffast-math
@cindex IEEE conformance
@cindex conformance, IEEE
Might allow some programs designed to not be too dependent
on IEEE behavior for floating-point to run faster, or die trying.

@cindex -fstrength-reduce option
@cindex options, -fstrength-reduce
@item -fstrength-reduce
@cindex loops, speeding up
@cindex speeding up loops
Might make some loops run faster.

@cindex -frerun-cse-after-loop option
@cindex options, -frerun-cse-after-loop
@item -frerun-cse-after-loop
@cindex -fexpensive-optimizations option
@cindex options, -fexpensive-optimizations
@item -fexpensive-optimizations
@cindex -fdelayed-branch option
@cindex options, -fdelayed-branch
@item -fdelayed-branch
@cindex -fschedule-insns option
@cindex options, -fschedule-insns
@item -fschedule-insns
@cindex -fschedule-insns2 option
@cindex options, -fschedule-insns2
@item -fschedule-insns2
@cindex -fcaller-saves option
@cindex options, -fcaller-saves
@item -fcaller-saves
Might improve performance on some code.

@cindex -funroll-loops option
@cindex options, -funroll-loops
@item -funroll-loops
@cindex loops, unrolling
@cindex unrolling loops
Definitely improves performance on some code.

@cindex -funroll-all-loops option
@cindex options, -funroll-all-loops
@item -funroll-all-loops
Definitely improves performance on some code.

@item -fno-move-all-movables
@item -fno-reduce-all-givs
@item -fno-rerun-loop-opt
Each of these might improve performance on some code.

Analysis of Fortran code optimization and the resulting
optimizations triggered by the above options were
contributed by Toon Moene (@code{toon@@moene.indiv.nluug.nl}).

Please let us know how use of these options affects
the performance of your production code.
We're particularly interested in code that runs faster
when these options are @emph{disabled}, and in
non-Fortran code that benefits when they are
@emph{enabled} via the above @code{gcc} command-line options.
@end table

@xref{Optimize Options,,Options That Control Optimization,
gcc,Using and Porting GNU CC}, for more information on options
to optimize the generated machine code.

@node Preprocessor Options
@section Options Controlling the Preprocessor
@cindex preprocessor options
@cindex options, preprocessor
@cindex cpp program
@cindex programs, cpp

These options control the C preprocessor, which is run on each C source
file before actual compilation.

@xref{Preprocessor Options,,Options Controlling the Preprocessor,
gcc,Using and Porting GNU CC}, for information on C preprocessor options.

@cindex INCLUDE statement
@cindex statements, INCLUDE
Some of these options also affect how @code{g77} processes the
@samp{INCLUDE} statement.
Since this statement is processed even when preprocessing
is not requested, it is not described in this section.
@xref{Directory Options,,Options for Directory Search}, for
information on how @code{g77} processes the @samp{INCLUDE} statement.

@node Directory Options
@section Options for Directory Search
@cindex directory options
@cindex options, directory search
@cindex search path

These options affect how the @code{cpp} preprocessor searches
for files specified via the @samp{#include} directive.
Therefore, when compiling Fortran programs, they are meaningful
when the preproecssor is used.

@cindex INCLUDE statement
@cindex statements, INCLUDE
Some of these options also affect how @code{g77} searches
for files specified via the @samp{INCLUDE} statement.
These options are:

@table @code
@cindex -I- option
@cindex options, -I-
@item -I-
@cindex -Idir option
@cindex options, -Idir
@item -I@var{dir}
@cindex directory search paths for inclusion
@cindex inclusion, directory search paths for
@cindex searching for included files
These affect interpretation of the @samp{INCLUDE} statement
(as well as of the @samp{#include} directive of the @code{cpp}
preprocessor).

Note that @samp{-I@var{dir}} must be specified @emph{without} any
spaces between @samp{-I} and the directory name---that is,
@samp{-Ifoo/bar} is valid, but @samp{-I foo/bar}
is rejected by the @code{g77} compiler (though the preprocessor supports
the latter form).
@c this is due to toplev.c's inflexible option processing
Also note that the general behavior of @samp{-I} and
@samp{INCLUDE} is pretty much the same as of @samp{-I} with
@samp{#include} in the @code{cpp} preprocessor, with regard to
looking for @file{header.gcc} files and other such things.

@xref{Directory Options,,Options for Directory Search,
gcc,Using and Porting GNU CC}, for information on the @samp{-I} option.
@end table

@node Code Gen Options
@section Options for Code Generation Conventions
@cindex code generation conventions
@cindex options, code generation 
@cindex run-time options

These machine-independent options control the interface conventions
used in code generation.

Most of them have both positive and negative forms; the negative form
of @samp{-ffoo} would be @samp{-fno-foo}.  In the table below, only
one of the forms is listed---the one which is not the default.  You
can figure out the other form by either removing @samp{no-} or adding
it.

@table @code
@cindex -fno-automatic option
@cindex options, -fno-automatic
@item -fno-automatic
@cindex SAVE statement
@cindex statements, SAVE
Treat each program unit as if the @code{SAVE} statement was specified
for every local variable and array referenced in it.
Does not affect common blocks.
(Some Fortran compilers provide this option under
the name @samp{-static}.)

@cindex -finit-local-zero option
@cindex options, -finit-local-zero
@item -finit-local-zero
@cindex DATA statement
@cindex statements, DATA
@cindex initialization of local variables
@cindex variables, initialization of
@cindex uninitialized variables
@cindex variables, uninitialized
Specify that variables and arrays that are local to a program unit
(not in a common block and not passed as an argument) are to be initialized
to binary zeros.

Since there is a run-time penalty for initialization of variables
that are not given the @code{SAVE} attribute, it might be a
good idea to also use @samp{-fno-automatic} with @samp{-finit-local-zero}.

@cindex -fno-f2c option
@cindex options, -fno-f2c
@item -fno-f2c
@cindex f2c compatibility
@cindex compatibility, f2c
Do not generate code designed to be compatible with code generated
by @code{f2c}.

This does not affect the generation of code that interfaces with the
@code{libf2c} library.

@strong{Caution:} If @samp{-fno-f2c} is used when compiling any
source file used in a program, it must be used when compiling
@emph{all} Fortran source files used in that program.

@c seems kinda dumb to tell people about an option they can't use -- jcb
@c then again, we want users building future-compatible libraries with it.
@cindex -ff2c-library option
@cindex options, -ff2c-library
@item -ff2c-library
Specify that use of @code{libf2c} is required.
This is the default for the current version of @code{g77}.

Currently it is not
valid to specify @samp{-fno-f2c-library}.
This option is provided so users can specify it in shell
scripts that build programs and libraries that require the
@code{libf2c} library, even when being compiled by future
versions of @code{g77} that might otherwise default to
generating code for an incompatible library.

@cindex -fno-underscoring option
@cindex options, -fno-underscoring
@item -fno-underscoring
@cindex underscores
@cindex symbol names, underscores
@cindex transforming symbol names
@cindex symbol names, transforming
Do not transform names of entities specified in the Fortran
source file by appending underscores to them.

With @samp{-funderscoring} in effect, @code{g77} appends two underscores
to names with underscores and one underscore to external names with
no underscores.  (@code{g77} also appends two underscores to internal
names with underscores to avoid naming collisions with external names.
The @samp{-fno-second-underscore} option disables appending of the
second underscore in all cases.)

This is done to ensure compatibility with code produced by many
UNIX Fortran compilers, including @code{f2c}, which perform the
same transformations.

Use of @samp{-fno-underscoring} is not recommended unless you are
experimenting with issues such as integration of (GNU) Fortran into
existing system environments (vis-a-vis existing libraries, tools, and
so on).

For example, with @samp{-funderscoring}, and assuming other defaults like
@samp{-fcase-lower} and that @samp{j()} and @samp{max_count()} are
external functions while @samp{my_var} and @samp{lvar} are local variables,
a statement like

@smallexample
I = J() + MAX_COUNT (MY_VAR, LVAR)
@end smallexample

@noindent
is implemented as something akin to:

@smallexample
i = j_() + max_count__(&my_var__, &lvar);
@end smallexample

With @samp{-fno-underscoring}, the same statement is implemented as:

@smallexample
i = j() + max_count(&my_var, &lvar);
@end smallexample

Use of @samp{-fno-underscoring} allows direct specification of
user-defined names while debugging and when interfacing @code{g77}-compiled
code with other languages.

Note that just because the names match does @emph{not} mean that the
interface implemented by @code{g77} for an external name matches the
interface implemented by some other language for that same name.
That is, getting code produced by @code{g77} to link to code produced
by some other compiler using this or any other method can be only a
small part of the overall solution---getting the code generated by
both compilers to agree on issues other than naming can require
significant effort, and, unlike naming disagreements, linkers normally
cannot detect disagreements in these other areas.

Also, note that with @samp{-fno-underscoring}, the lack of appended
underscores introduces the very real possibility that a user-defined
external name will conflict with a name in a system library, which
could make finding unresolved-reference bugs quite difficult in some
cases---they might occur at program run time, and show up only as
buggy behavior at run time.

In future versions of @code{g77}, we hope to improve naming and linking
issues so that debugging always involves using the names as they appear
in the source, even if the names as seen by the linker are mangled to
prevent accidental linking between procedures with incompatible
interfaces.

@cindex -fno-second-underscore option
@cindex options, -fno-second-underscore
@item -fno-second-underscore
@cindex underscores
@cindex symbol names, underscores
@cindex transforming symbol names
@cindex symbol names, transforming
Do not append a second underscore to names of entities specified
in the Fortran source file.

This option has no effect if @samp{-fno-underscoring} is
in effect.

Otherwise, with this option, an external name such as @samp{MAX_COUNT}
is implemented as a reference to the link-time external symbol
@samp{max_count_}, instead of @samp{max_count__}.

@cindex -fno-ident option
@cindex options, -fno-ident
@item -fno-ident
Ignore the @samp{#ident} directive.

@cindex -fzeros option
@cindex options, -fzeros
@item -fzeros
Treat initial values of zero as if they were any other value.

As of version 0.5.18, @code{g77} normally treats @samp{DATA} and
other statements that are used specify initial values of zero
for variables and arrays as if no values were actually specified,
in the sense that no diagnostics regarding multiple initializations
are produced.

This is done to speed up compiling of programs that initialize
large arrays to zeros.

Use @samp{-fzeros} to revert to the simpler, slower behavior
that can catch multiple initializations by keeping track of
all initializations, zero or otherwise.

@emph{Caution:} Future versions of @code{g77} might disregard this option
(and its negative form, the default) or interpret it somewhat
differently.
The interpretation changes will affect only non-standard
programs; standard-conforming programs should not be affected.

@cindex -fdebug-kludge option
@cindex options, -fdebug-kludge
@item -fdebug-kludge
Emit information on @samp{COMMON} and @samp{EQUIVALENCE} members
that might help users of debuggers work around lack of proper debugging
information on such members.

As of version 0.5.19, @code{g77} offers this option to emit
information on members of aggregate areas to help users while debugging.
This information consists of establishing the type and contents of each
such member so that, when a debugger is asked to print the contents,
the printed information provides rudimentary debugging information.
This information identifies the name of the aggregate area (either the
@samp{COMMON} block name, or the @code{g77}-assigned name for the
@samp{EQUIVALENCE} name) and the offset, in bytes, of the member from
the beginning of the area.

Using @code{gdb}, this information is not coherently displayed in the Fortran
language mode, so temporarily switching to the C language mode to display the
information is suggested.
Use @samp{set language c} and @samp{set language fortran} to accomplish this.

For example:

@example
      COMMON /X/A,B
      EQUIVALENCE (C,D)
      CHARACTER XX*50
      EQUIVALENCE (I,XX(20:20))
      END

GDB is free software and you are welcome to distribute copies of it
 under certain conditions; type "show copying" to see the conditions.
There is absolutely no warranty for GDB; type "show warranty" for details.
GDB 4.16 (lm-gnits-dwim), Copyright 1996 Free Software Foundation, Inc...
(gdb) b MAIN__
Breakpoint 1 at 0t1200000201120112: file cd.f, line 5.
(gdb) r
Starting program: /home/user/a.out

Breakpoint 1, MAIN__ () at cd.f:5
Current language:  auto; currently fortran
(gdb) set language c
Warning: the current language does not match this frame.
(gdb) p a
$2 = "At (COMMON) `x_' plus 0 bytes"
(gdb) p b
$3 = "At (COMMON) `x_' plus 4 bytes"
(gdb) p c
$4 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes"
(gdb) p d
$5 = "At (EQUIVALENCE) `__g77_equiv_c' plus 0 bytes"
(gdb) p i
$6 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 20 bytes"
(gdb) p xx
$7 = "At (EQUIVALENCE) `__g77_equiv_xx' plus 1 bytes"
(gdb) set language fortran
(gdb) 
@end example

Use @samp{-fdebug-kludge} to generate this information,
which might make some programs noticably larger.

@emph{Caution:} Future versions of @code{g77} might disregard this option
(and its negative form).
Current plans call for this to happen when published versions of @code{g77}
and @code{gdb} exist that provide proper access to debugging information on
@samp{COMMON} and @samp{EQUIVALENCE} members.
@end table

@xref{Code Gen Options,,Options for Code Generation Conventions,
gcc,Using and Porting GNU CC}, for information on more options
offered by the GBE
shared by @code{g77}, @code{gcc}, and other GNU compilers.

Some of these do @emph{not} work when compiling programs written in Fortran:

@table @code
@cindex -fpcc-struct-return option
@cindex options, -fpcc-struct-return
@item -fpcc-struct-return
@cindex -freg-struct-return option
@cindex options, -freg-struct-return
@item -freg-struct-return
You should not use these except strictly the same way as you
used them to build the version of @code{libf2c} with which
you will be linking all code compiled by @code{g77} with the
same option.

@cindex -fshort-double option
@cindex options, -fshort-double
@item -fshort-double
This probably either has no effect on Fortran programs, or
makes them act loopy.

@cindex -fno-common option
@cindex options, -fno-common
@item -fno-common
Do not use this when compiling Fortran programs,
or there will be Trouble.

@cindex -fpack-struct option
@cindex options, -fpack-struct
@item -fpack-struct
This probably will break any calls to the @code{libf2c} library,
at the very least, even if it is built with the same option.
@end table

@node Environment Variables
@section Environment Variables Affecting GNU Fortran
@cindex environment variables

GNU Fortran currently does not make use of any environment
variables to control its operation above and beyond those
that affect the operation of @code{gcc}.

@xref{Environment Variables,,Environment Variables Affecting GNU CC,
gcc,Using and Porting GNU CC}, for information on environment
variables.

@include news.texi

@node Changes
@chapter User-visible Changes
@cindex versions, recent
@cindex recent versions
@cindex changes, user-visible
@cindex user-visible changes

To find out about existing bugs and ongoing plans for GNU
Fortran, on Internet do @samp{finger -l fortran@@gnu.ai.mit.edu}
or whatever is the equivalent on your system.
(You might need to use the address @samp{fortran@@gate-1.gnu.ai.mit.edu}
instead, or use @samp{gate-2}, @samp{gate-3}, @samp{gate-4}, and so on,
instead of @samp{gate-1}.)

Alternatively, retrieve @url{ftp://gnu.ai.mit.edu/g77.plan} via
anonymous ftp, or if you cannot do that, email
@samp{fortran@@gnu.ai.mit.edu} asking for a recent copy of the
GNU Fortran @file{.plan} file.
(The @code{finger} command shown above obtains the most recent
copy of all these methods.)

@heading In 0.5.19:

@itemize @bullet
@item
A temporary kludge option provides bare-bones information on
@samp{COMMON} and @samp{EQUIVALENCE} members at debug time.
@xref{Code Gen Options,,Options for Code Generation Conventions},
for information on the @samp{-fdebug-kludge} option.

@item
New @samp{-fonetrip} option specifies FORTRAN-66-style
one-trip @samp{DO} loops.

@item
New @samp{-fno-silent} option causes names of program units
to be printed as they are compiled, in a fashion similar to
UNIX @samp{f77} and @samp{f2c}.

@item
New @samp{-fugly-assumed} option specifies that arrays
dimensioned via @samp{DIMENSION X(1)}, for example, are to be
treated as assumed-size.

@item
New @samp{-fno-typeless-boz} option specifies that non-decimal-radix
constants using the prefixed-radix form (such as @samp{Z'1234'})
are to be interpreted as @samp{INTEGER} constants.

@item
New @samp{-ff66} option is a ``shorthand'' option that specifies
behaviors considered appropriate for FORTRAN 66 programs.

@item
New @samp{-ff77} option is a ``shorthand'' option that specifies
behaviors considered appropriate for UNIX @samp{f77} programs.

@item
New @samp{-fugly-comma} and @samp{-fugly-logint} options provided
to perform some of what @samp{-fugly} used to do.
@samp{-fugly} and @samp{-fno-ugly} are now ``shorthand'' options,
in that they do nothing more than enable (or disable) other
@samp{-fugly-*} options.

@item
Change code generation for list-directed I/O so it allows
for new versions of @samp{libf2c} that might return non-zero
status codes for some operations previously assumed to always
return zero.

This change not only affects how @samp{IOSTAT=} variables
are set by list-directed I/O, it also affects whether
@samp{END=} and @samp{ERR=} labels are reached by these
operations.

@item
Add intrinsic support for new @samp{FTELL} and @samp{FSEEK}
procedures in @samp{libf2c}.

@item
Add options @samp{--help} and @samp{--version} to the
@code{g77} command, to conform to GNU coding guidelines.
Also add printing of @code{g77} version number when
the @samp{--verbose} (@samp{-v}) option is used.
@end itemize

@heading In 0.5.18:

@itemize @bullet
@item
The @code{BYTE} and @code{WORD} statements now are supported,
to a limited extent.

@item
@samp{INTEGER*1}, @samp{INTEGER*2}, @samp{INTEGER*8},
and their @samp{LOGICAL}
equivalents, now are supported to a limited extent.
Among the missing elements are complete intrinsic and constant
support.

@item
Support automatic arrays in procedures.
For example, @samp{REAL A(N)}, where @samp{A} is
not a dummy argument, specifies that @samp{A} is
an automatic array.
The size of @samp{A} is calculated from the value
of @samp{N} each time the procedure is called,
that amount of space is allocated, and that space
is freed when the procedure returns to its caller.

@item
Add @samp{-fno-zeros} option, enabled by default,
to reduce compile-time CPU and memory usage for
code that provides initial zero values for variables
and arrays.

@item
Introduce three new options that apply to all compilations
by @code{g77}-aware GNU compilers---@samp{-fmove-all-movables},
@samp{-freduce-all-givs}, and @samp{-frerun-loop-opt}---which
can improve the run-time performance of some programs.

@item
Replace much of the existing documentation with a single
Info document.

@item
New option @samp{-fno-second-underscore}.
@end itemize

@heading In 0.5.17:

@itemize @bullet
@item
The @samp{ERF()} and @samp{ERFC()} intrinsics now are generic
intrinsics, mapping to @samp{ERF}/@samp{DERF} and
@samp{ERFC}/@samp{DERFC}, respectively.
@emph{Note:} Use @samp{INTRINSIC ERF,ERFC} in any code that
might reference these as generic intrinsics, to
improve the likelihood of diagnostics (instead of subtle run-time
bugs) when using compilers that don't support these as intrinsics.

@item
New option @samp{-Wsurprising}.

@item
DO loops with non-@samp{INTEGER} variables now diagnosed only when
@samp{-Wsurprising} specified.
Previously, this was diagnosed @emph{unless} @samp{-fpedantic} or
@samp{-fugly} was specified.
@end itemize

@heading In 0.5.16:

@itemize @bullet
@item
@code{libf2c} changed to output a leading zero (0) digit for floating-point
values output via list-directed and formatted output (to bring @code{g77}
more in line with many existing Fortran implementations---the
ANSI FORTRAN 77 standard leaves this choice to the implementation).

@item
@code{libf2c} no longer built with debugging information
intact, making it much smaller.

@item
Automatic installation of the @code{g77} command now works.

@item
Diagnostic messages now more informative, a la @code{gcc},
including messages like @samp{In function `foo':} and @samp{In file
included from...:}.

@item
New group of intrinsics called @samp{unix}, including @samp{ABORT},
@samp{DERF}, @samp{DERFC}, @samp{ERF}, @samp{ERFC}, @samp{EXIT},
@samp{FLUSH}, @samp{GETARG}, @samp{GETENV}, @samp{SIGNAL}, and
@samp{SYSTEM}.

@item
@samp{-funix-intrinsics-@{delete,hide,disable,enable@}}
options added.

@item
@samp{-fno-underscoring} option added.

@item
@samp{--driver} option added to the @code{g77} command.

@item
Support for the @code{gcc} options @samp{-fident} and @samp{-fno-ident}
added.

@item
@samp{g77 -v} returns much more version info, making the submission
of better bug reports easily.

@item
Many improvements to the @code{g77} command to better fulfill its role as
a front-end to the @code{gcc} driver.
For example, @code{g77} now
recognizes @samp{--verbose} as a verbose way of specifying @samp{-v}.

@item
Compiling preprocessed (@file{*.F} and @file{*.fpp}) files now
results in better diagnostics and debugging information, as the
source-location info now is passed all the
way through the compilation process instead of being lost.
@end itemize

@heading In 0.5.15:

@itemize @bullet
@item
@samp{-ffixed-line-length-@var{n}} option introduced.
@end itemize

@heading In 0.5.14:

@itemize @bullet
@item
Support for gcc's @samp{-I} option added.

@item
@samp{-fbackslash} option added.

@item
@samp{-fugly-args} option enabled by default (allows @samp{CALL FOO(4HABCD)}).

@item
@samp{-fugly-init} option added.

@item
@samp{-finit-local-zero} option added.

@item
Support for the @code{gcc} option @samp{-Wimplicit} added.

@item
@samp{-Wall} now implies @samp{-Wunused} and, when @samp{-O} is
specified, @samp{-Wuninitialized}.

@cindex Hollerith constants
@cindex constants, Hollerith
@item
Hollerith constants as actual arguments now are passed by reference
instead of by value---so @samp{CALL FOO(4HABCD)} now is compiled exactly
the same as @samp{CALL FOO(%REF('ABCD'))}, instead of as
@samp{CALL FOO(%VAL('ABCD'))}.

@item
Hollerith constants converted to larger types now are padded on the
right with spaces.
When converted to smaller types, warnings are issued
if non-spaces are truncated on the right.

@item
Format specifications of arrays of types other than @samp{CHARACTER} are
allowed in I/O statements, such as when they contain Hollerith
data.

@cindex typeless constants
@cindex constants, typeless
@item
Typeless constants as actual arguments now are passed by reference
to an @samp{INTEGER} version of the constant instead of by value.

@item
Typeless constants converted to larger types are padded on the left
with zeros.
When converted to smaller types, warnings are issued if non-zero
bits are truncated on the left.

@cindex %DESCR() intrinsic
@cindex intrinsics, %DESCR()
@item
@samp{%DESCR()} of a non-@samp{CHARACTER} expression treats the expression
as if it were @samp{CHARACTER}, passing both a pointer to the expression
and the length of the type of the expression in bytes, by value, in the
``hidden'' list of lengths used for @samp{CHARACTER} arguments.

@item
The @samp{ICHAR()}, @samp{IACHAR()}, and @samp{LEN()} intrinsics now
accept character expressions involving concatenation of assumed-length
dummy arguments.

@item
Block data program units now may contain @samp{NAMELIST}, @samp{EXTERNAL},
@c @samp{INTRINSIC}, and @samp{VOLATILE} statements.
and @samp{INTRINSIC} statements.

@item
Zero-length character expressions now supported.

@item
Support for the @code{f2c} intrinsic @samp{IMAG()} added.

@item
@samp{INCLUDE} statement restrictions, such as no continuation
lines allowed, now lifted.
@end itemize

@node Language
@chapter The GNU Fortran Language

@cindex standard, ANSI FORTRAN 77
@cindex ANSI FORTRAN 77 standard
GNU Fortran supports a variety of extensions to, and dialects
of, the Fortran language.
Its primary base is the ANSI FORTRAN 77 standard, currently available on
the network at @url{http://kumo.swcp.com/fortran/F77_std/f77_std.html}
or in @url{ftp://ftp.ast.cam.ac.uk/pub/michael/}.
It offers some extensions that are popular among users
of UNIX @code{f77} and @code{f2c} compilers, some that
are popular among users of other compilers (such as Digital
products), some that are popular among users of the
newer Fortran 90 standard, and some that are introduced
by GNU Fortran.

Part of what defines a particular implementation of a Fortran
system, such as @code{g77}, is the particular characteristics
of how it supports types, constants, and so on.
Much of this is left up to the implementation by the various
Fortran standards and accepted practice in the industry.

@menu
* Standard Support:: Degree of support for the ANSI FORTRAN 77 standard.
* Extensions::       Extensions to GNU Fortran.
* Types::            Data types.
* Constants::        Constants and their types.
* Source Form::      Form of source files (fixed, free, and so on).
* Pedantic Compilation::  Warnings about non-standard constructs.
* Case Sensitivity:: Uppercase and lowercase in source files.
* Intrinsics::       How intrinsics are grouped for easy management.
* Dialects::         Dialects supported by GNU Fortran.
* Object Compatibility::  Compatibility issues for code generated by @code{g77}.
* Distensions::      Misfeatures supported by GNU Fortran.
@end menu

@node Standard Support
@section ANSI FORTRAN 77 Standard Support
@cindex ANSI FORTRAN 77 support
@cindex standard support
@cindex support for ANSI FORTRAN 77

GNU Fortran supports ANSI FORTRAN 77 with the following caveats:

@itemize @bullet
@item
No passing of an external procedure as an actual argument if the procedure's
type is declared @samp{CHARACTER*(*)}.  For example:

@example
CHARACTER*(*) CFUNC
EXTERNAL CFUNC
CALL FOO(CFUNC)
END
@end example

@noindent
It isn't clear whether the standard considers this conforming.

Note that it is unlikely that any production Fortran code
tries to use this unsupported construct.

@item
No passing of a dummy procedure as an actual argument if the procedure's
type is declared @samp{CHARACTER*(*)}.

@example
SUBROUTINE BAR(CFUNC)
CHARACTER*(*) CFUNC
EXTERNAL CFUNC
CALL FOO(CFUNC)
END
@end example

@noindent
It isn't clear whether the standard considers this conforming.

Note that it is unlikely that any production Fortran code
tries to use this unsupported construct.

@item
The @samp{DO} variable for an implied-@samp{DO} construct in a
@samp{DATA} statement may not be used as the @samp{DO} variable
for an outer implied-@samp{DO} construct.  For example, this
fragment is disallowed by @code{g77}:

@smallexample
DATA ((A(I, I), I= 1, 10), I= 1, 10)/@dots{}/
@end smallexample

@noindent
This also is disallowed by Fortran 90, as it offers no additional
capabilities and would have a variety of possible meanings.

Note that it is @emph{very} unlikely that any production Fortran code
tries to use this unsupported construct.

@item
An array element initializer in an implied-@samp{DO} construct in a
@samp{DATA} statement must contain at least one reference to the @samp{DO}
variables of each outer implied-@samp{DO} construct.  For example,
this fragment is disallowed by @code{g77}:

@example
DATA (A, I= 1, 1)/1./
@end example

@noindent
This also is disallowed by Fortran 90, as FORTRAN 77's more permissive
requirements offer no additional capabilities.
However, @code{g77} doesn't necessarily diagnose all cases
where this requirement is not met.

Note that it is @emph{very} unlikely that any production Fortran code
tries to use this unsupported construct.
@end itemize

In summary, the only ANSI FORTRAN 77 features @code{g77} doesn't
support are those that are probably rarely used in actual code,
some of which are explicitly disallowed by the Fortran 90 standard.

@node Extensions
@section GNU Fortran Extensions
@cindex extensions
@cindex language extensions

GNU Fortran supports ANSI FORTRAN 77 plus:

@itemize @bullet
@cindex LOC() intrinsic
@cindex intrinsics, LOC()
@item
@samp{LOC()}, if @samp{-funix-intrinsics-enable} is in force.

@item
@cindex %LOC() intrinsic
@cindex intrinsics, %LOC()
@cindex %VAL() intrinsic
@cindex intrinsics, %VAL()
@cindex %REF() intrinsic
@cindex intrinsics, %REF()
@cindex %DESCR() intrinsic
@cindex intrinsics, %DESCR()
@samp{%LOC}, @samp{%VAL}, @samp{%REF}, and @samp{%DESCR}---where
@samp{%DESCR} currently means the same thing as passing the argument
as if it were a @samp{CHARACTER} variable (with the phantom
length argument appended to the argument list).

@item
MIL-STD 1753 features (@samp{IAND}, @samp{IOR}, @samp{MVBITS},
@samp{DO WHILE}, @samp{END DO}, and so on).

@cindex NAMELIST statement
@cindex statements, NAMELIST
@item
@samp{NAMELIST}.

@item
Most @code{f2c} intrinsics (@samp{AND}, @samp{OR}, @samp{LSHIFT},
@samp{RSHIFT}, and so on).

@item
@samp{DOUBLE COMPLEX} and related intrinsics (standard and @code{f2c}
varieties).

@item
Various Fortran 90 features, such as @samp{CYCLE}, @samp{EXIT},
@samp{SELECT CASE} (except for @samp{CHARACTER} types).

@item
Various DEC VAX/VMS FORTRAN v4.0 features (loosely called VXT extensions).

@item
Various @code{f2c} features.

@item
Source files that are uppercase-only (enforced), lowercase-only
(enforced), caseless, and various other combinations as chosen via
command-line options.

@item
Arbitrary (limited only by available memory) number of continuation lines.

@item
Use of @samp{&} in column 1 to indicate a continuation line
(as supported by @code{f2c}).

@item
Dollar signs (@samp{$}) in identifiers (other than as the first character)
when the @samp{-fdollar-ok} option is specified.
@end itemize

When @samp{-ff90} is specified, the language dialect changes as follows:

@itemize @bullet
@item
The type of @samp{REAL(Z)}, where @samp{Z} is type
@samp{DOUBLE COMPLEX}, is @samp{DOUBLE PRECISION}
instead of @samp{REAL}.

@item
Zero-length @samp{CHARACTER} entities are accepted,
even when @samp{-fpedantic} is specified.

@item
Zero-size array dimensions (as in @samp{INTEGER I(10,20,4:2)})
are accepted,
although these are not supported by @samp{libf2c}, so diagnostics
are nevertheless produced for @code{g77}.

@item
@samp{DOUBLE COMPLEX} (explicit or implicit) is accepted,
even when @samp{-fpedantic} is specified.

@item
Substrings of constants (as in @samp{'hello'(3:5)}) are
accepted, even when @samp{-fpedantic} is specified.

@item
@samp{DATA} statements are allowed to precede executable statements,
even when @samp{-fpedantic} specified.

Note that this does not allow all possible means of specifying
further attributes via specification statements for a variable
after it has been given an initial value via @samp{DATA} or a
type-declaration statement.
For example,
after @samp{DATA I/1/}, @samp{INTEGER I} is not permitted, but
@samp{INTEGER J} is permitted.

@item
@cindex semicolons
@cindex statements, separated by semicolon
Use of a semicolon (@samp{;}) as a statement separator
is accepted, even when @samp{-fpedantic} specified
(so @samp{CALL FOO; CALL BAR} works).

@item
Underscores (@samp{_}) are accepted in symbol names (except as the
first character, since Fortran 90 provides a different interpretation
for certain cases where that would occur---though @code{g77} does
not yet support that interpretation).
@end itemize

@node Types
@section Types
@cindex types, of data
@cindex data types

Fortran implementations have a fair amount of freedom given them by the
standard as far as how much storage space is used and how much precision
is offered by the various types such as @samp{LOGICAL}, @samp{INTEGER},
@samp{REAL}, @samp{DOUBLE PRECISION}, @samp{COMPLEX}, and @samp{CHARACTER}.
Further, many compilers offer so-called @samp{*@var{n}} notation, but
the interpretation of @var{n} varies across compilers and target architectures.

The standard requires that @samp{LOGICAL}, @samp{INTEGER}, and @samp{REAL}
occupy the same amount of storage space, and that @samp{COMPLEX} and
@samp{DOUBLE PRECISION} take twice as much storage space as @samp{REAL}.
Further, it requires that @samp{COMPLEX}
entities be ordered such that when a @samp{COMPLEX} variable is
storage-associated (such as via @samp{EQUIVALENCE})
with a two-element @samp{REAL} array named @samp{R}, @samp{R(1)}
corresponds to the real element and @samp{R(2)} to the imaginary
element of the @samp{COMPLEX} variable.
No particular requirements as to precision of any of these are placed on
the implementation, nor is the relationship of storage sizes of these
types to the @samp{CHARACTER} type specified by the standard.

@code{g77} follows the above requirements, warning when compiling
a program requires placement of items in memory that contradict the
requirements of the target architecture.
(For example, a program can require placement of a @samp{DOUBLE PRECISION}
on a boundary that is not an even multiple of its size, but still an
even multiple of the size of a @samp{REAL} variable.
On some target architectures, using the canonical
mapping of Fortran types to underlying architectural types, such
placement is prohibited by the machine definition or
the Application Binary Interface (ABI) in force for
the configuration defined for building @code{gcc} and @code{g77}.
@code{g77} warns about such
situations when it encounters them.)

@code{g77} follows consistent rules for configuring the mapping between Fortran
types, including the @samp{*@var{n}} notation, and the underlying architectural
types as accessed by a similarly-configured applicable version of the
@code{gcc} compiler.
These rules offer a widely portable, consistent Fortran/C
environment, although they might well conflict with the expectations of
users of Fortran compilers designed and written for particular
architectures.

These rules are based on the configuration that is in force for the
version of @code{gcc} built in the same release as @code{g77} (and
which was therefore used to build both the @code{g77} compiler
components and the @code{libf2c} run-time library):

@table @code
@cindex REAL type
@cindex types, REAL
@item REAL
Same as @samp{float} type.

@cindex DOUBLE PRECISION type
@cindex types, DOUBLE PRECISION
@item DOUBLE PRECISION
Same as whatever floating-point type that is twice the size
of a @samp{float}---usually, this is a @samp{double}.

@cindex INTEGER type
@cindex types, INTEGER
@item INTEGER
Same as an integral type that is occupies the same amount
of memory storage @samp{float}---usually, this is either
an @samp{int} or a @samp{long int}.

@cindex LOGICAL type
@cindex types, LOGICAL
@item LOGICAL
Same @code{gcc} type as @samp{INTEGER}.

@cindex COMPLEX type
@cindex types, COMPLEX
@item COMPLEX
Two @samp{REAL} scalars (one for the real part followed by
one for the imaginary part).

@cindex DOUBLE COMPLEX type
@cindex types, DOUBLE COMPLEX
@item DOUBLE COMPLEX
Two @samp{DOUBLE PRECISION} scalars.

@cindex *@var{n} notation
@item @var{numeric-type}*@var{n}
(Where @var{numeric-type} is any type other than @samp{CHARACTER}.)
Same as whatever @code{gcc} type occupies @var{n} times the storage
space of a @code{gcc} @samp{char} item.

@cindex KIND= notation
@item @var{numeric-type}(KIND=@var{n})
@var{n}=1 corresponds to @samp{REAL}, @samp{INTEGER}, @samp{LOGICAL},
@samp{COMPLEX}.
@var{n}=2 corresponds to @samp{DOUBLE PRECISION}, @samp{DOUBLE COMPLEX},
and, for integral types, @samp{char} (usually @samp{INTEGER*1}
and @samp{LOGICAL*1}).
@var{n}=3 corresponds to @samp{short} for integral types
(usually @samp{INTEGER*2} and @samp{LOGICAL*2}).
@var{n}=4 corresponds to @samp{long long} for integral types
(this usually means @samp{INTEGER*8} and @samp{LOGICAL*8}).

Note that these are proposed correspondences and might change
in future versions of @code{g77}---avoid writing code depending
on them.
@end table

Other types supported by @code{g77}
are derived from gcc types such as @samp{char}, @samp{short},
@samp{int}, @samp{long int}, @samp{long long int}, @samp{long double},
and so on.
That is, whatever types @samp{gcc} already supports, @code{g77} supports
now or probably will support in a future version.
The rules for the @samp{@var{numeric-type}*@var{n}} notation
apply to these types,
and new values for @samp{@var{numeric-type}(KIND=@var{n})} will be
assigned in a way that encourages clarity, consistency, and portability.

@node Constants
@section Constants
@cindex constants
@cindex types, constants

@code{g77} strictly assigns types to all constants not
documented as ``typeless'' (typeless constants including @samp{'1'Z},
for example).
Context is never a determining factor for the type, and hence
the interpretation, of a typed constant.
Examples: @samp{1} is always type @samp{INTEGER},
@samp{9.435784839284958} is always type @samp{REAL} (even if the
additional precision specified is lost, and even when used in a @samp{DOUBLE
PRECISION} context), @samp{1E0} is always type @samp{REAL}, and @samp{1D0}
is always type @samp{DOUBLE PRECISION}.

Many other Fortran compilers attempt to assign types to typed constants
based on their context.
This results in hard-to-find bugs, nonportable
code, and is not in the spirit (though it strictly follows the letter)
of the 77 and 90 standards.
@code{g77} will not support these dangerous
semantics, but might offer, in a future release, explicit constructs by
which a wider variety of typeless constants may be specified, and/or
user-requested warnings indicating places where @code{g77} might differ
from how other compilers assign types to constants.

@node Source Form
@section Source Form
@cindex source file format
@cindex source form
@cindex files, source
@cindex source code
@cindex code, source
@cindex fixed form
@cindex free form

The @samp{-ffree-form} (aka @samp{-fno-fixed-form}) and @samp{-ffixed-form}
(aka @samp{-fno-free-form}) command-line options govern how the
source file is interpreted.
Fixed form
corresponds to classic ANSI FORTRAN 77 (plus popular extensions, such as
allowing tabs) and Fortran 90's fixed form.
Free form corresponds to
Fortran 90's free form (though possibly not entirely up-to-date, and
without complaining about some things that for which Fortran 90 requires
diagnostics, such as @samp{R = 3 . 1}).

The way a Fortran compiler views source files depends entirely on the
implementation choices made for the compiler.
GNU Fortran currently tries to be somewhat like a few popular compilers
(@code{f2c}, DEC Fortran, and so on), though a cleaner default
definition along with more
flexibility offered by command-line options is likely to be offered
in version 0.6.

Here are some facts regarding the way @code{g77} interprets source lines:

@itemize @bullet
@cindex carriage returns
@item
Carriage returns (@samp{\r}) in source lines are ignored.
This is somewhat different from @code{f2c}, which seems to treat them as
spaces outside character/Hollerith constants, and encodes them as @samp{\r}
inside such constants.

@cindex tab characters
@item
A source line with a @key{TAB} character anywhere in it is treated as
entirely significant---however long it is---instead of ending in
column 72 (for fixed-form source) or 132 (for free-form source).
This also is different from @code{f2c}, which encodes tabs as
@samp{\t} (the ASCII @key{TAB} character) inside character
and Hollerith constants, but nevertheless seems to treat the column
position as if it had been affected by the canonical tab positioning.

@code{g77} effectively
translates tabs to the appropriate number of spaces (a la the default
for the UNIX @code{expand} command) before doing any other processing, other
than (currently) noting whether a tab was found on a line and using this
info to decide how to interpret the length of the line and continued
constants.

Note that this default behavior probably will change for version 0.6,
when it will presumably be available via a command-line option.
The default as of version 0.6 is planned to be a ``pure visual''
model, where tabs are immediately
converted to spaces and otherwise have no effect, so the way a typical
user sees source lines produces a consistent result no matter how the
spacing in those source lines is actually implemented via tabs, spaces,
and trailing tabs/spaces before newline.
Command-line options are likely to be added to specify whether all or
just-tabbed lines are to be extended to 132 or full input-line length,
and perhaps even an option will be added to specify the truncated-line
behavior to which some Digital compilers default (and which affects
the way continued character/Hollerith constants are interpreted).

@item
Source lines shorter than the applicable fixed length are treated as
if they were padded with spaces to that length.

This affects only
continued character and Hollerith constants, and is a different
interpretation than provided by some other popular compilers
(although a bit more consistent with the traditional punched-card
basis of Fortran and the way the Fortran standard expressed fixed
source form).

@code{g77} might someday offer an option to warn about cases where differences
might be seen as a result of this treatment, and perhaps an option to
specify the alternate behavior as well.

Note that this padding cannot apply to lines that are effectively of
infinite length---such lines are specified using command-line options
like @samp{-ffixed-line-length-none}, for example.
@end itemize

@node Pedantic Compilation
@section Pedantic Compilation
@cindex pedantic compilation
@cindex compilation, pedantic

The @samp{-fpedantic} command-line option specifies that @code{g77}
is to warn about certain non-standard constructs.
This is useful for finding
some extensions @code{g77} accepts that other compilers might not accept.
(Note that the @samp{-pedantic} and @samp{-pedantic-errors} options
always imply @samp{-fpedantic}.)

With @samp{-ff90} in force along with @samp{-fpedantic}, some constructs are
accepted that result in diagnostics when @samp{-fno-f90} and
@samp{-fpedantic} are both in force.
@xref{Extensions,,GNU Fortran Extensions}, for information on those constructs.

The constructs for which @code{g77} issues diagnostics when @samp{-fpedantic}
and @samp{-fno-f90} are in force are:

@itemize @bullet
@item
Automatic arrays, as in @samp{REAL A(N)}, where @samp{A}
is not a dummy argument.

@item
@samp{READ (5), I} and @samp{WRITE (10), J}---the standard disallows the
comma in each case, while allowing it in @samp{READ 10, I}, but many
compilers (including @code{f2c}) allow the superfluous comma.

@item
@samp{DOUBLE COMPLEX}, either explicitly (via explicit or @samp{IMPLICIT}
statement) or implicitly (as in @samp{C*D}, where @samp{C} is @samp{COMPLEX}
and @samp{D} is @samp{DOUBLE PRECISION}, which is prohibited by the
standard because it should produce a non-standard @samp{DOUBLE COMPLEX}
result).

@item
Automatic conversion of numeric
expressions to @samp{INTEGER} in contexts such as:

@itemize --
@item
Array-reference indexes.
@item
Alternate-return values.
@item
Computed @samp{GOTO}.
@item
@samp{FORMAT} run-time expressions (not yet supported).
@item
Dimension lists in specification statements.
@item
Numbers for I/O statements (such as @samp{READ (UNIT=3.2), I})
@item
Sizes of @samp{CHARACTER} entities in specification statements.
@item
Kind types in specification entities (a Fortran 90 feature).
@item
Initial, terminal, and incrementation parameters for implied-@samp{DO}
constructs in @samp{DATA} statements.
@end itemize

@item
Automatic conversion of @samp{LOGICAL} expressions to @samp{INTEGER}
in contexts such as arithmetic @samp{IF} (where @samp{COMPLEX}
expressions are disallowed anyway).

@item
Substring operators applied to character constants and named
constants (such as @samp{PRINT *,'hello'(3:5)}, which would print @samp{llo}).

@item
Null argument passed to statement function (as in @samp{PRINT *,FOO(,3)}).

@item
Differences between program units regarding whether a given @samp{COMMON}
area is @samp{SAVE}d (for targets where program units in a single source
file are ``glued'' together as they typically are for UNIX development
environments).

@item
Differences between named-@samp{COMMON}-block sizes between program units.

@item
Specification statements following first @samp{DATA} statement (normally
@samp{DATA I/1/} may be followed by @samp{INTEGER J}, though not
@samp{INTEGER I}, but @samp{-fpedantic} disables use of both cases.

@item
Semicolon as statement separator (as in @samp{CALL FOO; CALL BAR}).
@c
@c @item
@c Comma before list of I/O items in @samp{WRITE}
@c  @c, @samp{ENCODE}, @samp{DECODE}, and @samp{REWRITE}
@c statements, as with @samp{READ} (as explained above).

@item
Use of @samp{&} in column 1 of fixed-form source (indicates continuation).

@item
Use of @samp{CHARACTER} constants to initialize numeric entities, and vice
versa.

@item
Expressions having two arithmetic operators in a row, such
as @samp{X*-Y}.
@end itemize

If @samp{-fpedantic} is specified along with @samp{-ff90}, the
following constructs result in diagnostics:

@itemize @bullet
@item
Use of semicolons on line with INCLUDE statement.
@end itemize

@node Case Sensitivity
@section Case Sensitivity
@cindex case sensitivity
@cindex source file format
@cindex code, source
@cindex source code
@cindex uppercase letters
@cindex lowercase letters
@cindex letters, uppercase
@cindex letters, lowercase

GNU Fortran offers the programmer way too much flexibility in deciding
how source files are to be treated vis-a-vis uppercase and lowercase
characters.
There are 66 useful settings that affect case sensitivity, plus 10
settings that are nearly useless, with the remaining 116 settings
being either redundant or useless.

None of these settings have any effect on the contents of comments
(the text after a @samp{c} or @samp{C} in Column 1, for example)
or of character or Hollerith constants.
Note that things like the @samp{E} in the statement
@samp{CALL FOO(3.2E10)} and the @samp{TO} in @samp{ASSIGN 10 TO LAB}
are considered built-in keywords.

Low-level switches are identified in this discussion thusly:

@itemize @w{}
@item A
Source Case Conversion:

@itemize @w{}
@item 0
Preserve (see Note 1)
@item 1
Convert to Upper Case
@item 2
Convert to Lower Case
@end itemize

@item B
Built-in Keyword Matching:

@itemize @w{}
@item 0
Match Any Case (per-character basis)
@item 1
Match Upper Case Only
@item 2
Match Lower Case Only
@item 3
Match InitialCaps Only (see tables for spellings)
@end itemize

@item C
Built-in Intrinsic Matching:

@itemize @w{}
@item 0
Match Any Case (per-character basis)
@item 1
Match Upper Case Only
@item 2
Match Lower Case Only
@item 3
Match InitialCaps Only (see tables for spellings)
@end itemize

@item D
User-defined Symbol Possibilities (warnings only):

@itemize @w{}
@item 0
Allow Any Case (per-character basis)
@item 1
Allow Upper Case Only
@item 2
Allow Lower Case Only
@item 3
Allow InitialCaps Only (see Note 2)
@end itemize
@end itemize

Note 1: @code{g77} eventually will support @samp{NAMELIST} in a manner that is
consistent with these source switches---in the sense that input will be
expected to meet the same requirements as source code in terms
of matching symbol names and keywords (for the exponent letters).

Currently, however, @samp{NAMELIST} is supported @samp{libf2c},
which uppercases @samp{NAMELIST} input and symbol names for matching.
This means not only that @samp{NAMELIST} output currently shows symbol
(and keyword) names in uppercase even if lower-case source
conversion (option A2) is selected, but that @samp{NAMELIST} cannot be
adequately supported when source case preservation (option A0)
is selected.

If A0 is selected, a warning message will be
output for each @samp{NAMELIST} statement to this effect.
The behavior
of the program is undefined at run time if two or more symbol names
appear in a given @samp{NAMELIST} such that the names are identical
when converted to upper case (e.g. @samp{NAMELIST /X/ VAR, Var, var}).
For complete and total elegance, perhaps there should be a warning
when option A2 is selected, since the output of NAMELIST is currently
in uppercase but will someday be lowercase (when a @samp{libg77} is written),
but that seems to be overkill for a product in beta test.

Note 2: Rules for InitialCaps names are:

@itemize --
@item
Must be a single uppercase letter, @strong{or}
@item
Must start with an uppercase letter and contain at least one
lowercase letter.
@end itemize

So @samp{A}, @samp{Ab}, @samp{ABc}, @samp{AbC}, and @samp{Abc} are
valid InitialCaps names, but @samp{AB}, @samp{A2}, and @samp{ABC} are
not.
Note that most, but not all, built-in names meet these
requirements---the exceptions are some of the two-letter format
specifiers, such as @samp{BN} and @samp{BZ}.

Here are the names of the corresponding command-line options:

@smallexample
A0: -fsource-case-preserve
A1: -fsource-case-upper
A2: -fsource-case-lower

B0: -fmatch-case-any
B1: -fmatch-case-upper
B2: -fmatch-case-lower
B3: -fmatch-case-initcap

C0: -fintrin-case-any
C1: -fintrin-case-upper
C2: -fintrin-case-lower
C3: -fintrin-case-initcap

D0: -fsymbol-case-any
D1: -fsymbol-case-upper
D2: -fsymbol-case-lower
D3: -fsymbol-case-initcap
@end smallexample

Useful combinations of the above settings, along with abbreviated
option names that set some of these combinations all at once:

@smallexample
 1: A0--  B0---  C0---  D0---    -fcase-preserve
 2: A0--  B0---  C0---  D-1--
 3: A0--  B0---  C0---  D--2-
 4: A0--  B0---  C0---  D---3
 5: A0--  B0---  C-1--  D0---
 6: A0--  B0---  C-1--  D-1--
 7: A0--  B0---  C-1--  D--2-
 8: A0--  B0---  C-1--  D---3
 9: A0--  B0---  C--2-  D0---
10: A0--  B0---  C--2-  D-1--
11: A0--  B0---  C--2-  D--2-
12: A0--  B0---  C--2-  D---3
13: A0--  B0---  C---3  D0---
14: A0--  B0---  C---3  D-1--
15: A0--  B0---  C---3  D--2-
16: A0--  B0---  C---3  D---3
17: A0--  B-1--  C0---  D0---
18: A0--  B-1--  C0---  D-1--
19: A0--  B-1--  C0---  D--2-
20: A0--  B-1--  C0---  D---3
21: A0--  B-1--  C-1--  D0---
22: A0--  B-1--  C-1--  D-1--    -fcase-strict-upper
23: A0--  B-1--  C-1--  D--2-
24: A0--  B-1--  C-1--  D---3
25: A0--  B-1--  C--2-  D0---
26: A0--  B-1--  C--2-  D-1--
27: A0--  B-1--  C--2-  D--2-
28: A0--  B-1--  C--2-  D---3
29: A0--  B-1--  C---3  D0---
30: A0--  B-1--  C---3  D-1--
31: A0--  B-1--  C---3  D--2-
32: A0--  B-1--  C---3  D---3
33: A0--  B--2-  C0---  D0---
34: A0--  B--2-  C0---  D-1--
35: A0--  B--2-  C0---  D--2-
36: A0--  B--2-  C0---  D---3
37: A0--  B--2-  C-1--  D0---
38: A0--  B--2-  C-1--  D-1--
39: A0--  B--2-  C-1--  D--2-
40: A0--  B--2-  C-1--  D---3
41: A0--  B--2-  C--2-  D0---
42: A0--  B--2-  C--2-  D-1--
43: A0--  B--2-  C--2-  D--2-    -fcase-strict-lower
44: A0--  B--2-  C--2-  D---3
45: A0--  B--2-  C---3  D0---
46: A0--  B--2-  C---3  D-1--
47: A0--  B--2-  C---3  D--2-
48: A0--  B--2-  C---3  D---3
49: A0--  B---3  C0---  D0---
50: A0--  B---3  C0---  D-1--
51: A0--  B---3  C0---  D--2-
52: A0--  B---3  C0---  D---3
53: A0--  B---3  C-1--  D0---
54: A0--  B---3  C-1--  D-1--
55: A0--  B---3  C-1--  D--2-
56: A0--  B---3  C-1--  D---3
57: A0--  B---3  C--2-  D0---
58: A0--  B---3  C--2-  D-1--
59: A0--  B---3  C--2-  D--2-
60: A0--  B---3  C--2-  D---3
61: A0--  B---3  C---3  D0---
62: A0--  B---3  C---3  D-1--
63: A0--  B---3  C---3  D--2-
64: A0--  B---3  C---3  D---3    -fcase-initcap
65: A-1-  B01--  C01--  D01--    -fcase-upper
66: A--2  B0-2-  C0-2-  D0-2-    -fcase-lower
@end smallexample

Number 22 is the ``strict'' ANSI FORTRAN 77 model wherein all input
(except comments, character constants, and Hollerith strings) must
be entered in uppercase.
Use @samp{-fcase-strict-upper} to specify this
combination.

Number 43 is like Number 22 except all input must be lowercase.  Use
@samp{-fcase-strict-lower} to specify this combination.

Number 65 is the ``classic'' ANSI FORTRAN 77 model as implemented on many
non-UNIX machines whereby all the source is translated to uppercase.
Use @samp{-fcase-upper} to specify this combination.

Number 66 is the ``canonical'' UNIX model whereby all the source is
translated to lowercase.
Use @samp{-fcase-lower} to specify this combination.

There are a few nearly useless combinations:

@smallexample
67: A-1-  B01--  C01--  D--2-
68: A-1-  B01--  C01--  D---3
69: A-1-  B01--  C--23  D01--
70: A-1-  B01--  C--23  D--2-
71: A-1-  B01--  C--23  D---3
72: A--2  B01--  C0-2-  D-1--
73: A--2  B01--  C0-2-  D---3
74: A--2  B01--  C-1-3  D0-2-
75: A--2  B01--  C-1-3  D-1--
76: A--2  B01--  C-1-3  D---3
@end smallexample

The above allow some programs to be compiled but with restrictions that
make most useful programs impossible: Numbers 67 and 72 warn about
@emph{any} user-defined symbol names (such as @samp{SUBROUTINE FOO});
Numbers
68 and 73 warn about any user-defined symbol names longer than one
character that don't have at least one non-alphabetic character after
the first;
Numbers 69 and 74 disallow any references to intrinsics;
and Numbers 70, 71, 75, and 76 are combinations of the restrictions in
67+69, 68+69, 72+74, and 73+74, respectively.

All redundant combinations are shown in the above tables anyplace
where more than one setting is shown for a low-level switch.
For example, @samp{B0-2-} means either setting 0 or 2 is valid for switch B.
The ``proper'' setting in such a case is the one that copies the setting
of switch A---any other setting might slightly reduce the speed of
the compiler, though possibly to an unmeasurable extent.

All remaining combinations are useless in that they prevent successful
compilation of non-null source files (source files with something other
than comments).

@node Intrinsics
@section Intrinsics
@cindex groups of intrinsics
@cindex intrinsics, groups

A given specific intrinsic belongs in one or more groups.
Each group
is deleted, disabled, hidden, or enabled by default or a command-line
option.  The meaning of each term follows.

@table @b
@cindex deleted intrinsics
@cindex intrinsics, deleted
@item Deleted
No intrinsics are recognized as belonging to that group.

@cindex disabled intrinsics
@cindex intrinsics, disabled
@item Disabled
Intrinsics are recognized as belonging to the group, but
references to them (other than via the @samp{INTRINSIC} statement)
are disallowed through that group.

@cindex hidden intrinsics
@cindex intrinsics, hidden
@item Hidden
Intrinsics in that group are recognized and enabled (if implemented)
@emph{only} if the first mention of the actual name of an intrinsic
in a program unit is in an @samp{INTRINSIC} statement.

@cindex enabled intrinsics
@cindex intrinsics, enabled
@item Enabled
Intrinsics in that group are recognized and enabled (if implemented).
@end table

The distinction between deleting and disabling a group is illustrated
by the following example.
Assume intrinsic @samp{FOO} belongs only to group @samp{FGR}.
If group @samp{FGR} is deleted, the following program unit will
successfully compile, because @samp{FOO()} will be seen as a
reference to an external function named @samp{FOO}:

@example
PRINT *, FOO()
END
@end example

@noindent
If group @samp{FGR} is disabled, compiling the above program will produce
diagnostics, either because the @samp{FOO} intrinsic is improperly invoked
or, if properly invoked, it is not enabled.
To change the above program so it references an external function @samp{FOO}
instead of the disabled @samp{FOO} intrinsic,
add the following line to the top:

@example
EXTERNAL FOO
@end example

@noindent
So, deleting a group tells @code{g77} to pretend as though the intrinsics in
that group do not exist at all, whereas disabling it tells @code{g77} to
recognize them as (disabled) intrinsics in intrinsic-like contexts.

Hiding a group is like enabling it, but the intrinsic must be first
named in an @samp{INTRINSIC} statement to be considered a reference to the
intrinsic rather than to an external procedure.
This might be the ``safest'' way to treat a new group of intrinsics
when compiling old
code, because it allows the old code to be generally written as if
those new intrinsics never existed, but to be changed to use them
by inserting @samp{INTRINSIC} statements in the appropriate places.
However, it should be the goal of development to use @samp{EXTERNAL}
for all names of external procedures that might be intrinsic names.

If an intrinsic is in more than one group, it is enabled if any of its
containing groups are enabled; if not so enabled, it is hidden if
any of its containing groups are hidden; if not so hidden, it is disabled
if any of its containing groups are disabled; if not so disabled, it is
deleted.
This extra complication is necessary because some intrinsics,
such as @samp{IBITS}, belong to more than one group, and hence should be
enabled if any of the groups to which they belong are enabled, and so
on.

The groups are:

@cindex intrinsics, groups of
@cindex groups of intrinsics
@table @code
@item dcp
@samp{DOUBLE COMPLEX} intrinsics from the standards (F77, F90).
@item f2c
Intrinsics supported by AT&T's @code{f2c} converter and/or @code{libf2c}.
@item f90
Fortran 90 intrinsics.
@item mil
MIL-STD 1753 intrinsics (@samp{MVBITS}, @samp{IAND}, @samp{BTEST}, and so on).
@item unix
UNIX intrinsics (@samp{IARGC}, @samp{EXIT}, @samp{ERF}, and so on).
@item vxt
VAX/VMS FORTRAN (current as of v4) intrinsics.
@end table

@node Dialects
@section GNU Fortran Dialects
@cindex language dialects
@cindex dialects of language
@cindex Fortran 90 features
@cindex VXT features

The @samp{-fvxt-not-f90} and @samp{-ff90-not-vxt} command-line options
control how @code{g77} interprets certain tokens and constructs that
have different meanings in VAX FORTRAN (circa v4) and Fortran 90.
@cindex VXT extensions
@cindex extensions, VXT
(Generally, this manual uses the invented acronym VXT to refer
to many popular VAX FORTRAN extensions, though not necessarily
those that are specific to the VAX processor architecture or the
VMS operating system.
An extension offered by a Digital Fortran product that also is
offered by several other Fortran products for different kinds of
systems is probably going to be considered for inclusion in @code{g77}
someday, and is considered a VXT extension.)

When @samp{-ff90-not-vxt} is specified, the following interpretations are made
(and, when @samp{-fvxt-not-f90} is in effect, the opposite interpretations
are made):

@itemize @bullet
@cindex double quotes
@cindex character constants
@cindex constants, character
@cindex octal constants
@cindex constants, octal
@item
Double-quote character (@samp{"}) delimits character constant just as does
apostrophe (@samp{'}), rather than beginning an octal constant of
@samp{INTEGER} type.

@cindex exclamation points
@cindex continuation character
@cindex characters, continuation
@cindex comment character
@cindex characters, comment
@item
An exclamation point (@samp{!}) in column 5 of fixed-form source file
treated as a continuation character rather than the beginning of a comment
(as it does in any other column).

@cindex TYPE statement
@cindex statements, TYPE
@item
@samp{TYPE FOO} and @samp{TYPE (FOO), BAR}
statements are recognized as the Fortran 90 variety, not I/O statements.
(However, the F90 variety is @emph{not} supported, so this really just
ensures that @code{g77} will produce a diagnostic instead of trying to
implement the VXT @samp{TYPE} statement---which currently is not supported
either.)
@end itemize

@node Object Compatibility
@section Object Compatibility
@cindex object code
@cindex code, object
@cindex compatibility, @code{f2c}
@cindex f2c compatibility
@cindex compilers, compatibility

An individual Fortran source file can be compiled to
an object (@file{*.o}) file instead of to the final
program executable.
This allows several portions of a program to be compiled
at different times and linked together whenever a new
version of the program is needed.
However, it introduces the issue of @dfn{object compatibility}
across the various object files (and libraries, or @file{*.a}
files) that are linked together to produce any particular
exectable file.

Object compatibility is an issue when combining, in one
program, Fortran code compiled by more than one compiler
(or more than one configuration of a compiler).
If the compilers
disagree on how to transform the names of procedures, there
will normally be errors when linking such programs.
Worse, if the compilers agree on naming, but disagree on issues
like how to pass parameters, return arguments, and lay out
@samp{COMMON} areas, the earliest detected errors might be the
incorrect results produced by the program (and that assumes
these errors are detected, which is not always the case).

Normally, @code{g77} generates code that is
object-compatible with code generated by a version of
@code{f2c} configured (with, for example, @file{f2c.h} definitions)
to be generally compatible with @code{g77} as built by @code{gcc}.
(Normally, @code{f2c} will, by default, conform to the appropriate
configuration, but it is possible that older or perhaps even newer
versions of @code{f2c}, or versions having certain configuration changes
to @code{f2c} internals, will produce object files that are
incompatible with @code{g77}.)

For example, a Fortran string subroutine
argument will become two arguments on the C side: a @samp{char *}
and an @samp{int} length.

Much of this compatibility results from the fact that
@code{g77} uses the same run-time library, @code{libf2c}, used by
@code{f2c}.

Other compilers might or might not generate code that
is object-compatible with @code{libf2c} and current @code{g77},
and some might offer such compatibility only when explicitly
selected via a command-line option to the compiler.

@menu
* Dropping f2c Compatibility::  When speed is more important.
* Other Compilers::             Interoperation with code from other compilers.
@end menu

@node Dropping f2c Compatibility
@subsection Dropping f2c Compatibility

Specifying @samp{-fno-f2c} allows @code{g77} to generate, in
some cases, faster code, by not needing to allow to the possibility
of linking with code compiled by @code{f2c}.

For example, this affects how @samp{REAL}, @samp{COMPLEX}, and
@samp{DOUBLE COMPLEX} functions are called.
With @samp{-fno-f2c}, they are
compiled as returning the appropriate @code{gcc} type
(@samp{float}, @samp{__complex__ float}, @samp{__complex__ double},
in many configurations).

With @samp{-ff2c} in force, they
are compiled differently (with perhaps slower run-time performance)
to accommodate the restrictions inherent in @code{f2c}'s use of K&R
C as an intermediate language---@samp{REAL} functions return double,
while @samp{COMPLEX} functions return
@samp{void} and use an extra argument pointing to a place for the functions to
return their values.

It is possible that, in some cases, leaving @samp{-ff2c} in force
might produce faster code than using @samp{-fno-f2c}.
Feel free to experiment, but remember to experiment with changing the way
@emph{entire programs and their Fortran libraries are compiled} at
a time, since this sort of experimentation affects the interface
of code generated for a Fortran source file---that is, it affects
object compatibility.

Note that @code{f2c} compatibility is a fairly static target to achieve,
though not necessarily perfectly so, since, like @code{g77}, it is
still being improved.
However, specifying @samp{-fno-f2c} causes @code{g77}
to generate code that will probably be incompatible with code
generated by future versions of @code{g77} when the same option
is in force.
You should make sure you are always able to recompile complete
programs from source code when upgrading to new versions of @code{g77}
or @code{f2c}, especially when using options such as @samp{-fno-f2c}.

Therefore, if you are using @code{g77} to compile libraries and other
object files for possible future use and you don't want to require
recompilation for future use with subsequent versions of @code{g77},
you might want to stick with @code{f2c} compatibility for now, and
carefully watch for any announcements about changes to the
@code{f2c}/@code{libf2c} interface that might affect existing programs
(thus requiring recompilation).

It is probable that a future version of @code{g77} will not,
by default, generate object files compatible with @code{f2c} and not
use @code{libf2c}.
If you expect to depend on this compatibility in the
long term, use the options @samp{-ff2c -ff2c-library} when compiling
all of the applicable code.
This should either cause @code{g77} to produce compatible code
(at the expense of the availability of some features and
performance), or at the very least trigger
compiler warning messages, in future versions of @code{g77}.

@node Other Compilers
@subsection Other Compilers

On systems with Fortran compilers other than @code{f2c} and @code{g77},
code compiled by @code{g77} is not expected to work
well with code compiled by the native compiler.
(This is true for @code{f2c}-compiled objects as well.)
Libraries compiled with the native compiler probably will have
to be recompiled with @code{g77} to be used with @code{g77}-compiled code.

Reasons for such incompatibilities include:

@itemize @bullet
@item
There might be differences in the way names of Fortran procedures
are translated for use in the system's object-file format.
For example, the statement @samp{CALL FOO} might be compiled
by @code{g77} to call a procedure the linker @code{ld} sees
given the name @samp{_foo_}, while the apparently corresponding
statement @samp{SUBROUTINE FOO} might be compiled by the
native compiler to define the linker-visible name @samp{_foo},
or @samp{_FOO_}, and so on.

@item
There might be subtle type mismatches which cause subroutine arguments
and function return values to get corrupted.

This is why simply getting @code{g77} to
transform procedure names the same way a native
compiler does is not usually a good idea---unless
some effort has been made to ensure that, aside
from the way the two compilers transform procedure
names, everything else about the way they generate
code for procedure interfaces is identical.

@item
Native compilers
use libraries of private I/O routines which will not be available
at link time unless you have the native compiler---and you would
have to explicitly ask for them.

For example, on the Sun you
would have to add @samp{-L/usr/lang/SCx.x -lF77 -lV77} to the link
command.
@end itemize

@node Distensions
@section Distensions
@cindex distensions
@cindex ugly features
@cindex features, ugly

The @samp{-fugly-*} command-line options determine whether certain
features supported by VAX FORTRAN and other such compilers, but considered
too ugly to be in code that can be changed to use safer and/or more
portable constructs, are accepted.
These are humorously referred to as ``distensions'',
extensions that just plain look ugly in the harsh light of day.

@menu
* Ugly Implicit Argument Conversion::  Disabled via @samp{-fno-ugly-args}.
* Ugly Assumed-Size Arrays::           Enabled via @samp{-fugly-assumed}.
* Ugly Null Arguments::                Enabled via @samp{-fugly-comma}.
* Ugly Conversion of Initializers::    Disabled via @samp{-fno-ugly-init}.
* Ugly Integer Conversions::           Enabled via @samp{-fugly-logint}.
@end menu

@node Ugly Implicit Argument Conversion
@subsection Implicit Argument Conversion

The construct disabled via @samp{-fno-ugly-args} is:

@itemize @bullet
@cindex Hollerith constants
@cindex constants, Hollerith
@item
Passing of typeless and Hollerith constants as actual arguments
in procedure invocations.

For example, @samp{CALL FOO(4HABCD)}.

This construct can be too easily used to create non-portable
code, but is not considered as ``ugly'' as others.
Further, it is widely used in existing Fortran source code
in ways that often are quite portable.
Therefore, it is enabled by default.
@end itemize

@cindex arrays, assumed-size
@cindex assumed-size arrays
@cindex DIMENSION X(1)
@node Ugly Assumed-Size Arrays
@subsection Ugly Assumed-Size Arrays

The construct enabled via @samp{-fugly-assumed} is:

@itemize @bullet
@item
Treatment of any array with a final dimension specified as @samp{1}
as an assumed-size array, as if @samp{*} had been specified
instead.

For example, @samp{DIMENSION X(1)} is treated as if it
had read @samp{DIMENSION X(*)}.

Use an explicit lower bound to avoid this interpretation.
For example, @samp{DIMENSION X(1:1)} is never treated as if
it had read @samp{DIMENSION X(*)} or @samp{DIMENSION X(1:*)}.

This option prevents a warning being issued about an apparent
out-of-bounds reference such as @samp{X(2) = 99}.

It also prevents the array from being used in contexts that
disallow assumed-size arrays, such as @samp{PRINT *,X}.

This construct is used only in very old code that pre-exists
the widespread acceptance of adjustable and assumed-size
arrays in the Fortran community.
@end itemize

@cindex trailing commas
@cindex commas, trailing
@cindex null arguments
@cindex arguments, null
@node Ugly Null Arguments
@subsection Ugly Null Arguments

The construct enabled via @samp{-fugly-comma} is:

@itemize @bullet
@item
Use of a single trailing comma to mean ``pass an extra trailing null
argument'' in a list of actual arguments to a procedure other than a
statement function, and an empty list of arguments to
mean ``pass a single null argument''.

@cindex omitting arguments
@cindex arguments, omitting
(Null arguments often are used in some procedure-calling
schemes to indicate omitted arguments.)

For example, @samp{CALL FOO(,)} means ``pass
two null arguments'', rather than ``pass one null argument''.
Also, @samp{CALL BAR()} means ``pass one null argument''.

This construct is considered ``ugly'' because it does not
provide an elegant way to pass a single null argument
that is syntactically distinct from passing no arguments.
That is, this construct changes the meaning of code that
makes no use of the construct.

So, with @samp{-fugly-comma} in force, @samp{CALL FOO()}
and @samp{I = JFUNC()} pass a single null argument, instead
of passing no arguments as required by the Fortran 77 and
90 standards.

@emph{Note:} Many systems gracefully allow the case
where a procedure call passes one extra argument that the
called procedure does not expect.

So, in practice, there might be no difference in
the behavior of a program that does @samp{CALL FOO()}
or @samp{I = JFUNC()} and is compiled with @samp{-fugly-comma}
in force as compared to its behavior when compiled
with the default, @samp{-fno-ugly-comma}, in force,
assuming @samp{FOO} and @samp{JFUNC} do not expect any
arguments to be passed.
@end itemize

@node Ugly Conversion of Initializers
@subsection Ugly Conversion of Initializers

The constructs disabled by @samp{-fno-ugly-init} are:

@itemize @bullet
@cindex Hollerith constants
@cindex constants, Hollerith
@item
Use of Hollerith and typeless constants in contexts where they set
initial (compile-time) values for variables, arrays, and named
constants---that is, @samp{DATA} and @samp{PARAMETER} statements, plus
type-declaration statements specifying initial values.

Here are some sample initializations that are disabled by the
@samp{-fno-ugly-init} option:

@example
PARAMETER (VAL='9A304FFE'X)
REAL*8 STRING/8HOUTPUT00/
DATA VAR/4HABCD/
@end example

@cindex character constants
@cindex constants, character
@item
In the same contexts as above, use of character constants to initialize
numeric items and vice versa (one constant per item).

Here are more sample initializations that are disabled by the
@samp{-fno-ugly-init} option:

@example
INTEGER IA
CHARACTER BELL
PARAMETER (IA = 'A')
PARAMETER (BELL = 7)
@end example

@item
Use of Hollerith and typeless constants on the right-hand side
of assignment statements to numeric types, and in other
contexts (such as passing arguments in invocations of
intrinsic procedures and statement functions) that
are treated as assignments to known types (the dummy
arguments, in these cases).

Here are sample statements that are disabled by the
@samp{-fno-ugly-init} option:

@example
IVAR = 4HABCD
PRINT *, IMAX0(2HAB, 2HBA)
@end example
@end itemize

The above constructs, when used,
can tend to result in non-portable code.
But, they are widely used in existing Fortran code in ways
that often are quite portable.
Therefore, they are enabled by default.

@node Ugly Integer Conversions
@subsection Ugly Integer Conversions

The constructs enabled via @samp{-fugly-logint} are:

@itemize @bullet
@item
Automatic conversion between @samp{INTEGER} and @samp{LOGICAL} as
dictated by
context (typically implies nonportable dependencies on how a
particular implementation encodes @samp{.TRUE.} and @samp{.FALSE.}).

@item
Use of a @samp{LOGICAL} variable in @samp{ASSIGN} and assigned-@samp{GOTO}
statements.
@end itemize

The above constructs are disabled by default because use
of them tends to lead to non-portable code.
Even existing Fortran code that uses that often turns out
to be non-portable, if not outright buggy.

Some of this is due to differences among implementations as
far as how @samp{.TRUE.} and @samp{.FALSE.} are encoded as
@samp{INTEGER} values---Fortran code that assumes a particular
coding is likely to use one of the above constructs, and is
also likely to not work correctly on implementations using
different encodings.

@xref{Equivalence Versus Equality}, for more information.

@include install.texi

@node Debugging and Interfacing
@chapter Debugging and Interfacing
@cindex debugging
@cindex interfacing
@cindex calling C routines
@cindex C routines calling Fortran
@cindex f2c compatibility

GNU Fortran currently generates code that is object-compatible with
the @code{f2c} converter.
Also, it avoids limitations in the current GBE, such as the
inability to generate a procedure with
multiple entry points, by generating code that is structured
differently (in terms of procedure names, scopes, arguments, and
so on) than might be expected.

As a result, writing code in other languages that calls on, is
called by, or shares in-memory data with @code{g77}-compiled code generally
requires some understanding of the way @code{g77} compiles code for
various constructs.

Similarly, using a debugger to debug @code{g77}-compiled
code, even if that debugger supports native Fortran debugging, generally
requires this sort of information.

This section describes some of the basic information on how
@code{g77} compiles code for constructs involving interfaces to other
languages and to debuggers.

@emph{Caution:} Much or all of this information pertains to only the current
release of @code{g77}, sometimes even to using certain compiler options
with @code{g77} (such as @samp{-fno-f2c}).
Do not write code that depends on this
information without clearly marking said code as nonportable and
subject to review for every new release of @code{g77}.
This information
is provided primarily to make debugging of code generated by this
particular release of @code{g77} easier for the user, and partly to make
writing (generally nonportable) interface code easier.
Both of these
activities require tracking changes in new version of @code{g77} as they
are installed, because new versions can change the behaviors
described in this section.

@menu
* Names::              Naming of user-defined variables, procedures, etc.
* Main Program Unit::  How @code{g77} compiles a main program unit.
* Arrays::             Dealing with (possibly multi-dimensional) arrays.
* Procedures::         How @code{g77} constructs parameter lists
                       for procedures.
* Adjustable Arrays::  Special consideration for adjustable arrays.
* Alternate Returns::  How @code{g77} handles alternate returns.
* Functions::          Functions returning floating-point or character data.
* Common Blocks::      Accessing common variables while debugging.
* Local Equivalence Areas::  Accessing @samp{EQUIVALENCE} while debugging.
* Alternate Entry Points::  How @code{g77} implements alternate @samp{ENTRY}.
* Assigned Statement Labels::  How @code{g77} handles @samp{ASSIGN}.
@end menu

@node Names
@section Names
@cindex symbol names
@cindex transformation of symbol names

Fortran permits each implementation to decide how to represent
names as far as how they're seen in other contexts, such as debuggers
and when interfacing to other languages, and especially as far
as how casing is handled.

External names---names of entities that are public, or ``accessible'',
to all modules in a program---normally have an underscore (@samp{_})
appended by @code{g77}, to generate code that is compatible with f2c.
External names include names of Fortran things like common blocks,
external procedures (subroutines and functions, but not including
statement functions, which are internal procedures), and entry point
names.

However, use of the @samp{-fno-underscoring} option
disables this kind of transformation of external names (though inhibiting
the transformation certainly improves the chances of colliding with
incompatible externals written in other languages---but that
might be intentional.

@cindex -fno-underscoring
@cindex -fno-second-underscore
When @samp{-funderscoring} is in force, any name (external or local)
that already has at least one underscore in it is
implemented by @code{g77} by appending two underscores.
(This second underscore can be disabled via the
@samp{-fno-second-underscore} option.)
External names are changed this way for @code{f2c} compatibility.
Local names are changed this way to avoid collisions with external names
that are different in the source code---@code{f2c} does the same thing, but
there's no compatibility issue there except for user expectations while
debugging.

For example:

@example
Max_Cost = 0
@end example

@noindent
Here, a user would, in the debugger, refer to this variable using the
name @samp{max_cost__} (or @samp{MAX_COST__} or @samp{Max_Cost__},
as described below).
(We hope to improve @code{g77} in this regard in the future---don't
write scripts depending on this behavior!
Also, consider experimenting with the @samp{-fno-underscoring}
option to try out debugging without having to massage names by
hand like this.)

@code{g77} provides a number of command-line options that allow the user
to control how case mapping is handled for source files.
The default is the traditional UNIX model for Fortran compilers---names
are mapped to lower case.
Other command-line options can be specified to map names to upper
case, or to leave them exactly as written in the source file.

For example:

@example
Foo = 9.436
@end example

@noindent
Here, it is normally the case that the variable assigned will be named
@samp{foo}.
This would be the name to enter when using a debugger to
access the variable.

However, depending on the command-line options specified, the
name implemented by @code{g77} might instead be @samp{FOO} or even
@samp{Foo}, thus affecting how debugging is done.

Also:

@example
Call Foo
@end example

@noindent
This would normally call a procedure that, if it were in a separate C program,
be defined starting with the line:

@example
void foo_()
@end example

@noindent
However, @code{g77} command-line options could be used to change the casing
of names, resulting in the name @samp{FOO_} or @samp{Foo_} being given to the
procedure instead of @samp{foo_}, and the @samp{-fno-underscoring} option
could be used to inhibit the appending of the underscore to the name.

@node Main Program Unit
@section Main Program Unit (PROGRAM)
@cindex PROGRAM statement
@cindex statements, PROGRAM

When @code{g77} compiles a main program unit, it gives it the public
procedure name @samp{MAIN__}.
The @code{libf2c} library has the actual @samp{main()} procedure
as is typical of C-based environments, and
it is this procedure that performs some initial start-up
activity and then calls @samp{MAIN__}.

Generally, @code{g77} and @code{libf2c} are designed so that you need not
include a main program unit written in Fortran in your program---it
can be written in C or some other language.
Especially for I/O handling, this is the case, although @code{g77-0.5.16}
includes a bug fix for @code{libf2c} that solved a problem with using the
@samp{OPEN} statement as the first Fortran I/O activity in a program
without a Fortran main program unit.

However, if you don't intend to use @code{g77} (or @code{f2c}) to compile
your main program unit---that is, if you intend to compile a @samp{main()}
procedure using some other language---you should carefully
examine the code for @samp{main()} in @code{libf2c}, found in the source
file @file{gcc/f/runtime/libF77/main.c}, to see what kinds of things
might need to be done by your @samp{main()} in order to provide the
Fortran environment your Fortran code is expecting.

@cindex IARGC() intrinsic
@cindex intrinsics, IARGC()
@cindex GETARG() intrinsic
@cindex intrinsics, GETARG()
For example, @code{libf2c}'s @samp{main()} sets up the information used by
the @samp{IARGC} and @samp{GETARG} intrinsics.
Bypassing @code{libf2c}'s @samp{main()}
without providing a substitute for this activity would mean
that invoking @samp{IARGC} and @samp{GETARG} would produce undefined
results.

@cindex debugging
@cindex main program unit, debugging
@cindex main()
@cindex MAIN__()
When debugging, one implication of the fact that @samp{main()}, which
is the place where the debugged program ``starts'' from the
debugger's point of view, is in @code{libf2c} is that you won't be
starting your Fortran program at a point you recognize as your
Fortran code.

The standard way to get around this problem is to set a break
point (a one-time, or temporary, break point will do) at
the entrance to @samp{MAIN__}, and then run the program.

After doing this, the debugger will see the current execution
point of the program as at the beginning of the main program
unit of your program.

Of course, if you really want to set a break point at some
other place in your program and just start the program
running, without first breaking at @samp{MAIN__},
that should work fine.

@node Arrays
@section Arrays (DIMENSION)
@cindex DIMENSION statement
@cindex statements, DIMENSION
@cindex array ordering
@cindex ordering, array
@cindex column-major ordering
@cindex row-major ordering
@cindex arrays

Fortran uses ``column-major ordering'' in its arrays.
This differs from other languages, such as C, which use ``row-major ordering''.
The difference is that, with Fortran, array elements adjacent to
each other in memory differ in the @emph{first} subscript instead of
the last; @samp{A(5,10,20)} immediately follows @samp{A(4,10,20)},
whereas with row-major ordering it would follow @samp{A(5,10,19)}.

This consideration
affects not only interfacing with and debugging Fortran code,
it can greatly affect how code is designed and written, especially
when code speed and size is a concern.

Fortran also differs from C, a popular language for interfacing and
to support directly in debuggers, in the way arrays are treated.
In C, arrays are single-dimensional and have interesting relationships
to pointers, neither of which is true for Fortran.
As a result, dealing with Fortran arrays from within
an environment limited to C concepts can be challenging.

For example, accessing the array element @samp{A(5,10,20)} is easy enough
in Fortran (use @samp{A(5,10,20)}), but in C some difficult machinations
are needed.
First, C would treat the A array as a single-dimension array.
Second, C does not understand low bounds for arrays as does Fortran.
Third, C assumes a low bound of zero (0), while Fortran defaults to a
low bound of one (1) and can supports an arbitrary low bound.
Therefore, calculations must be done
to determine what the C equivalent of @samp{A(5,10,20)} would be, and these
calculations require knowing the dimensions of @samp{A}.

For @samp{DIMENSION A(2:11,21,0:29)}, the calculation of the offset of
@samp{A(5,10,20)} would be:

@example
  (5-2)
+ (10-1)*(11-2+1)
+ (20-0)*(11-2+1)*(21-1+1)
= 4293
@end example

@noindent
So the C equivalent in this case would be @samp{a[4293]}.

When using a debugger directly on Fortran code, the C equivalent
might not work, because some debuggers cannot understand the notion
of low bounds other than zero.  However, unlike @code{f2c}, @code{g77}
does inform the GBE that a multi-dimensional array (like @samp{A}
in the above example) is really multi-dimensional, rather than a
single-dimensional array, so at least the dimensionality of the array
is preserved.

Debuggers that understand Fortran should have no trouble with
non-zero low bounds, but for non-Fortran debuggers, especially
C debuggers, the above example might have a C equivalent of
@samp{a[4305]}.
This calculation is arrived at by eliminating the subtraction
of the lower bound in the first parenthesized expression on each
line---that is, for @samp{(5-2)} substitute @samp{(5)}, for @samp{(10-1)}
substitute @samp{(10)}, and for @samp{(20-0)} substitute @samp{(20)}.
Actually, the implication of
this can be that the expression @samp{*(&a[2][1][0] + 4293)} works fine,
but that @samp{a[20][10][5]} produces the equivalent of
@samp{*(&a[0][0][0] + 4305)} because of the missing lower bounds.

Come to think of it, perhaps
the behavior is due to the debugger internally compensating for
the lower bounds by offsetting the base address of @samp{a}, leaving
@samp{&a} set lower, in this case, than @samp{&a[2][1][0]} (the address of
its first element as identified by subscripts equal to the
corresponding lower bounds).

You know, maybe nobody really needs to use arrays.

@node Procedures
@section Procedures (SUBROUTINE and FUNCTION)
@cindex procedures
@cindex SUBROUTINE statement
@cindex statements, SUBROUTINE
@cindex FUNCTION statement
@cindex statements, FUNCTION
@cindex signature of procedures

Procedures that accept @samp{CHARACTER} arguments are implemented by
@code{g77} so that each @samp{CHARACTER} argument has two actual arguments.

The first argument occupies the expected position in the
argument list and has the user-specified name.
This argument
is a pointer to an array of characters, passed by the caller.

The second argument is appended to the end of the user-specified
calling sequence and is named @samp{__g77_length_@var{x}}, where @var{x}
is the user-specified name.
This argument is of the C type @samp{ftnlen}
(see @file{gcc/f/runtime/f2c.h.in} for information on that type) and
is the number of characters the caller has allocated in the
array pointed to by the first argument.

A procedure will ignore the length argument if @samp{X} is not declared
@samp{CHARACTER*(*)}, because for other declarations, it knows the
length.
Not all callers necessarily ``know'' this, however, which
is why they all pass the extra argument.

The contents of the @samp{CHARACTER} argument are specified by the
address passed in the first argument (named after it).
The procedure can read or write these contents as appropriate.

When more than one @samp{CHARACTER} argument is present in the argument
list, the length arguments are appended in the order
the orginal arguments appear.
So @samp{CALL FOO('HI','THERE')} is implemented in
C as @samp{foo("hi","there",2,5);}, ignoring the fact that @code{g77}
does not provide the trailing null bytes on the constant
strings (@code{f2c} does provide them, but they are unnecessary in
a Fortran environment, and you should not expect them to be
there).

Note that the above information applies to @samp{CHARACTER} variables and
arrays @strong{only}.
It does @strong{not} apply to external @samp{CHARACTER}
functions or to intrinsic @samp{CHARACTER} functions.
That is, no second length argument is passed to @samp{FOO} in this case:

@example
CHARACTER X
EXTERNAL X
CALL FOO(X)
@end example

@noindent
Nor does @samp{FOO} expect such an argument in this case:

@example
SUBROUTINE FOO(X)
CHARACTER X
EXTERNAL X
@end example

Because of this implementation detail, if a program has a bug
such that there is disagreement as to whether an argument is
a procedure, and the type of the argument is @samp{CHARACTER}, subtle
symptoms might appear.

@node Adjustable Arrays
@section Adjustable Arrays (DIMENSION)
@cindex arrays, adjustable
@cindex adjustable arrays
@cindex arrays, automatic
@cindex automatic arrays
@cindex DIMENSION statement
@cindex statements, DIMENSION
@cindex dimensioning arrays
@cindex arrays, dimensioning

Adjustable and automatic arrays in Fortran require the implementation
(in this
case, the @code{g77} compiler) to ``memorize'' the expressions that
dimension the arrays each time the procedure is invoked.
This is so that subsequent changes to variables used in those
expressions, made during execution of the procedure, do not
have any effect on the dimensions of those arrays.

For example:

@example
REAL ARRAY(5)
DATA ARRAY/5*2/
CALL X(ARRAY, 5)
END
SUBROUTINE X(A, N)
DIMENSION A(N)
N = 20
PRINT *, N, A
END
@end example

@noindent
Here, the implementation should, when running the program, print something
like:

@example
20   2.  2.  2.  2.  2.
@end example

@noindent
Note that this shows that while the value of @samp{N} was successfully
changed, the size of the @samp{A} array remained at 5 elements.

To support this, @code{g77} generates code that executes before any user
code (and before the internally generated computed @samp{GOTO} to handle
alternate entry points, as described below) that evaluates each
(nonconstant) expression in the list of subscripts for an
array, and saves the result of each such evaluation to be used when
determining the size of the array (instead of re-evaluating the
expressions).

So, in the above example, when @samp{X} is first invoked, code is
executed that copies the value of @samp{N} to a temporary.
And that same temporary serves as the actual high bound for the single
dimension of the @samp{A} array (the low bound being the constant 1).
Since the user program cannot (legitimately) change the value
of the temporary during execution of the procedure, the size
of the array remains constant during each invocation.

For alternate entry points, the code @code{g77} generates takes into
account the possibility that a dummy adjustable array is not actually
passed to the actual entry point being invoked at that time.
In that case, the public procedure implementing the entry point
passes to the master private procedure implementing all the
code for the entry points a @samp{NULL} pointer where a pointer to that
adjustable array would be expected.
The @code{g77}-generated code
doesn't attempt to evaluate any of the expressions in the subscripts
for an array if the pointer to that array is @samp{NULL} at run time in
such cases.
(Don't depend on this particular implementation
by writing code that purposely passes @samp{NULL} pointers where the
callee expects adjustable arrays, even if you know the callee
won't reference the arrays---nor should you pass @samp{NULL} pointers
for any dummy arguments used in calculating the bounds of such
arrays or leave undefined any values used for that purpose in
COMMON---because the way @code{g77} implements these things might
change in the future!)

@node Alternate Returns
@section Alternate Returns (SUBROUTINE and RETURN)
@cindex subroutines
@cindex alternate returns
@cindex SUBROUTINE statement
@cindex statements, SUBROUTINE
@cindex RETURN statement
@cindex statements, RETURN

Subroutines with alternate returns (e.g. @samp{SUBROUTINE X(*)} and
@samp{CALL X(*50)}) are implemented by @code{g77} as functions returning
the C @samp{int} type.
The actual alternate-return arguments are omitted from the calling sequence.
Instead, the caller uses
the return value to do a rough equivalent of the Fortran
computed-@samp{GOTO} statement, as in @samp{GOTO (50), X()} in the
example above (where @samp{X} is quietly declared as an @samp{INTEGER}
function), and the callee just returns whatever integer
is specified in the @samp{RETURN} statement for the subroutine
For example, @samp{RETURN 1} is implemented as @samp{X = 1} followed
by @samp{RETURN}
in C, and @samp{RETURN} by itself is @samp{X = 0} and @samp{RETURN}).

@node Functions
@section Functions (FUNCTION and RETURN)
@cindex functions
@cindex FUNCTION statement
@cindex statements, FUNCTION
@cindex RETURN statement
@cindex statements, RETURN
@cindex return type of functions

@code{g77} handles in a special way functions that return the following
types:

@itemize @bullet
@item
@samp{CHARACTER}
@item
@samp{COMPLEX} (and @samp{DOUBLE COMPLEX})
@item
@samp{REAL}
@end itemize

For @samp{CHARACTER}, @code{g77} implements a subroutine (a C function
returning @samp{void})
with two arguments prepended: @samp{__g77_result}, which the caller passes
as a pointer to a @samp{char} array expected to hold the return value,
and @samp{__g77_length}, which the caller passes as an @samp{ftnlen} value
specifying the length of the return value as declared in the calling
program.
For @samp{CHARACTER}*(*), the called function uses @samp{__g77_length}
to determine the size of the array that @samp{__g77_result} points to;
otherwise, it ignores that argument.

For @samp{COMPLEX} and @samp{DOUBLE COMPLEX}, when @samp{-ff2c} is in
force, @code{g77} implements
a subroutine with one argument prepended: @samp{__g77_result}, which the
caller passes as a pointer to a variable of the type of the function.
The called function writes the return value into this variable instead
of returning it as a function value.
When @samp{-fno-f2c} is in force,
@code{g77} implements a @samp{COMPLEX} function as @code{gcc}'s
@samp{__complex__ float} function,
returning the result of the function in the same way as @code{gcc} would,
and implements a @samp{DOUBLE COMPLEX} function similarly.

For @samp{REAL}, when @samp{-ff2c} is in force, @code{g77} implements
a function that actually returns @samp{DOUBLE PRECISION} (usually
C's @samp{double} type).
When @samp{-fno-f2c} is in force, @samp{REAL} functions return @samp{float}.

@node Common Blocks
@section Common Blocks (COMMON)
@cindex common blocks
@cindex COMMON statement
@cindex statements, COMMON

@code{g77} names and lays out @samp{COMMON} areas the same way f2c does,
for compatibility with f2c.

Currently, @code{g77} does not emit ``true'' debugging information for
members of a @samp{COMMON} area, due to an apparent bug in the GBE.

(As of Version 0.5.19, @code{g77} emits debugging information for such
members in the form of a constant string specifying the base name of
the aggregate area and the offset of the member in bytes from the start
of the area.
Use the @samp{-fdebug-kludge} option to enable this behavior.
In @code{gdb}, use @samp{set language c} before printing the value
of the member, then @samp{set language fortran} to restore the default
language, since @code{gdb} doesn't provide a way to print a readable
version of a character string in Fortran language mode.

This kludge will be removed in a future version of @code{g77} that,
in conjunction with a contemporary version of @code{gdb},
properly supports Fortran-language debugging, including access
to members of @samp{COMMON} areas.)

@xref{Code Gen Options,,Options for Code Generation Conventions},
for information on the @samp{-fdebug-kludge} option.

Moreover, @code{g77} currently implements a @samp{COMMON} area such that its
type is an array of the C @samp{char} data type.

So, when debugging, you must know the offset into a @samp{COMMON} area
for a particular item in that area, and you have to take into
account the appropriate multiplier for the respective sizes
of the types (as declared in your code) for the items preceding
the item in question as compared to the size of the @samp{char} type.

For example, using default implicit typing, the statement

@example
COMMON I(15), R(20), T
@end example

@noindent
results in a public 144-byte @samp{char} array named @samp{_BLNK__}
with @samp{I} placed at @samp{_BLNK__[0]}, @samp{R} at @samp{_BLNK__[60]},
and @samp{T} at @samp{_BLNK__[140]}.
(This is assuming that the target machine for
the compilation has 4-byte @samp{INTEGER} and @samp{REAL} types.)

@node Local Equivalence Areas
@section Local Equivalence Areas (EQUIVALENCE)
@cindex equivalence areas
@cindex local equivalence areas
@cindex EQUIVALENCE statement
@cindex statements, EQUIVALENCE

@code{g77} treats storage-associated areas involving a @samp{COMMON}
block as explained in the section on common blocks.

A local @samp{EQUIVALENCE} area is a collection of variables and arrays
connected to each other in any way via @samp{EQUIVALENCE}, none of which are
listed in a @samp{COMMON} statement.

Currently, @code{g77} does not emit ``true'' debugging information for
members in a local @samp{EQUIVALENCE} area, due to an apparent bug in the GBE.

(As of Version 0.5.19, @code{g77} does emit debugging information for such
members in the form of a constant string specifying the base name of
the aggregate area and the offset of the member in bytes from the start
of the area.
Use the @samp{-fdebug-kludge} option to enable this behavior.
In @code{gdb}, use @samp{set language c} before printing the value
of the member, then @samp{set language fortran} to restore the default
language, since @code{gdb} doesn't provide a way to print a readable
version of a character string in Fortran language mode.

This kludge will be removed in a future version of @code{g77} that,
in conjunction with a contemporary version of @code{gdb},
properly supports Fortran-language debugging, including access
to members of @samp{EQUIVALENCE} areas.)

@xref{Code Gen Options,,Options for Code Generation Conventions},
for information on the @samp{-fdebug-kludge} option.

Moreover, @code{g77} implements a local @samp{EQUIVALENCE} area such that its
type is an array of the C @samp{char} data type.

The name @code{g77} gives this array of @samp{char} type is @samp{__g77_equiv_@var{x}},
where @var{x} is the name of the item that is placed at the beginning (offset 0)
of this array.
If more than one such item is placed at the beginning, @var{x} is
the name that sorts to the top in an alphabetical sort of the list of
such items.

When debugging, you must therefore access members of @samp{EQUIVALENCE}
areas by specifying the appropriate @samp{__g77_equiv_@var{x}}
array section with the appropriate offset.
See the explanation of debugging @samp{COMMON} blocks
for info applicable to debugging local @samp{EQUIVALENCE} areas.

(@emph{Note:} @code{g77} version 0.5.18 and earlier chose the name
for @var{x} using a different method when more than one name was
in the list of names of entities placed at the beginning of the
array.
Though the documentation specified that the first name listed in
the @samp{EQUIVALENCE} statements was chosen for @var{x}, @code{g77}
in fact chose the name using a method that was so complicated,
it seemed easier to change it to an alphabetical sort than to describe the
previous method in the documentation.)

@node Alternate Entry Points
@section Alternate Entry Points (ENTRY)
@cindex alternate entry points
@cindex entry points
@cindex ENTRY statement
@cindex statements, ENTRY

The GBE does not understand the general concept of
alternate entry points as Fortran provides via the ENTRY statement.
@code{g77} gets around this by using an approach to compiling procedures
having at least one @samp{ENTRY} statement that is almost identical to the
approach used by @code{f2c}.
(An alternate approach could be used that
would probably generate faster, but larger, code that would also
be a bit easier to debug.)

Information on how @code{g77} implements @samp{ENTRY} is provided for those
trying to debug such code.
The choice of implementation seems
unlikely to affect code (compiled in other languages) that interfaces
to such code.

@code{g77} compiles exactly one public procedure for the primary entry
point of a procedure plus each @samp{ENTRY} point it specifies, as usual.
That is, in terms of the public interface, there is no difference
between

@example
SUBROUTINE X
END
SUBROUTINE Y
END
@end example

@noindent
and:

@example
SUBROUTINE X
ENTRY Y
END
@end example

The difference between the above two cases lies in the code compiled
for the @samp{X} and @samp{Y} procedures themselves, plus the fact that,
for the second case, an extra internal procedure is compiled.

For every Fortran procedure with at least one @samp{ENTRY}
statement, @code{g77} compiles an extra procedure
named @samp{__g77_masterfun_@var{x}}, where @var{x} is
the name of the primary entry point (which, in the above case,
using the standard compiler options, would be @samp{x_} in C).

This extra procedure is compiled as a private procedure---that is,
a procedure not accessible by name to separately compiled modules.
It contains all the code in the program unit, including the code
for the primary entry point plus for every entry point.
(The code for each public procedure is quite short, and explained later.)

The extra procedure has some other interesting characteristics.

The argument list for this procedure is invented by @code{g77}.
It contains
a single integer argument named @samp{__g77_which_entrypoint},
passed by value (as in Fortran's @samp{%VAL()} intrinsic), specifying the
entry point index---0 for the primary entry point, 1 for the
first entry point (the first @samp{ENTRY} statement encountered), 2 for
the second entry point, and so on.

It also contains, for functions returning @samp{CHARACTER} and
(when @samp{-ff2c} is in effect) @samp{COMPLEX} functions,
and for functions returning different types among the
@samp{ENTRY} statements (e.g. @samp{REAL FUNCTION R()}
containing @samp{ENTRY I()}), an argument named @samp{__g77_result} that
is expected at run time to contain a pointer to where to store
the result of the entry point.
For @samp{CHARACTER} functions, this
storage area is an array of the appropriate number of characters;
for @samp{COMPLEX} functions, it is the appropriate area for the return
type (currently either @samp{COMPLEX} or @samp{DOUBLE COMPLEX}); for multiple-
return-type functions, it is a union of all the supported return
types (which cannot include @samp{CHARACTER}, since combining @samp{CHARACTER}
and non-@samp{CHARACTER} return types via @samp{ENTRY} in a single function
is not supported by @code{g77}).

For @samp{CHARACTER} functions, the @samp{__g77_result} argument is followed
by yet another argument named @samp{__g77_length} that, at run time,
specifies the caller's expected length of the returned value.
Note that only @samp{CHARACTER*(*)} functions and entry points actually
make use of this argument, even though it is always passed by
all callers of public @samp{CHARACTER} functions (since the caller does not
generally know whether such a function is @samp{CHARACTER*(*)} or whether
there are any other callers that don't have that information).

The rest of the argument list is the union of all the arguments
specified for all the entry points (in their usual forms, e.g.
@samp{CHARACTER} arguments have extra length arguments, all appended at
the end of this list).
This is considered the ``master list'' of
arguments.

The code for this procedure has, before the code for the first
executable statement, code much like that for the following Fortran
statement:

@smallexample
       GOTO (100000,100001,100002), __g77_which_entrypoint
100000 @dots{}code for primary entry point@dots{}
100001 @dots{}code immediately following first ENTRY statement@dots{}
100002 @dots{}code immediately following second ENTRY statement@dots{}
@end smallexample

@noindent
(Note that invalid Fortran statement labels and variable names
are used in the above example to highlight the fact that it
represents code generated by the @code{g77} internals, not code to be
written by the user.)

It is this code that, when the procedure is called, picks which
entry point to start executing.

Getting back to the public procedures (@samp{x} and @samp{Y} in the original
example), those procedures are fairly simple.
Their interfaces
are just like they would be if they were self-contained procedures
(without @samp{ENTRY}), of course, since that is what the callers
expect.
Their code consists of simply calling the private
procedure, described above, with the appropriate extra arguments
(the entry point index, and perhaps a pointer to a multiple-type-
return variable, local to the public procedure, that contains
all the supported returnable non-character types).
For arguments
that are not listed for a given entry point that are listed for
other entry points, and therefore that are in the ``master list''
for the private procedure, null pointers (in C, the @samp{NULL} macro)
are passed.
Also, for entry points that are part of a multiple-type-
returning function, code is compiled after the call of the private
procedure to extract from the multi-type union the appropriate result,
depending on the type of the entry point in question, returning
that result to the original caller.

When debugging a procedure containing alternate entry points, you
can either set a break point on the public procedure itself (e.g.
a break point on @samp{X} or @samp{Y}) or on the private procedure that
contains most of the pertinent code (e.g. @samp{__g77_masterfun_@var{x}}).
If you do the former, you should use the debugger's command to
``step into'' the called procedure to get to the actual code; with
the latter approach, the break point leaves you right at the
actual code, skipping over the public entry point and its call
to the private procedure (unless you have set a break point there
as well, of course).

Further, the list of dummy arguments that is visible when the
private procedure is active is going to be the expanded version
of the list for whichever particular entry point is active,
as explained above, and the way in which return values are
handled might well be different from how they would be handled
for an equivalent single-entry function.

@node Assigned Statement Labels
@section Assigned Statement Labels (ASSIGN and GOTO)
@cindex assigned statement labels
@cindex statement labels, assigned
@cindex ASSIGN statement
@cindex statements, ASSIGN
@cindex GOTO statement
@cindex statements, GOTO

For portability to machines where a pointer (such as to a label,
which is how @code{g77} implements @samp{ASSIGN} and its cousin, the assigned
@samp{GOTO}) is wider (bitwise) than an @samp{INTEGER}, @code{g77} does not
necessarily use
the same memory location to hold the @samp{ASSIGN}ed value of a variable
as it does the numerical value in that variable, unless the
variable is wide enough (can hold enough bits).

In particular, while @code{g77} implements

@example
I = 10
@end example

@noindent
as, in C notation, @samp{i = 10;}, it might implement

@example
ASSIGN 10 TO I
@end example

@noindent
as, in GNU's extended C notation (for the label syntax),
@samp{__g77_ASSIGN_I = &&L10;} (where @samp{L10} is just a massaging
of the Fortran label @samp{10} to make the syntax C-like; @code{g77} doesn't
actually generate the name @samp{L10} or any other name like that,
since debuggers cannot access labels anyway).

While this currently means that an @samp{ASSIGN} statement might not
overwrite the numeric contents of its target variable, @emph{do not}
write any code depending on this feature.
@code{g77} has already changed this implementation across
versions and might do so in the future.
This information is provided only to make debugging Fortran programs
compiled with the current version of @code{g77} somewhat easier.
If there's no debugger-visible variable named @samp{__g77_ASSIGN_I}
in a program unit that does @samp{ASSIGN 10 TO I}, that probably
means @code{g77} has decided it can store the pointer to the label directly
into @samp{I} itself.

(Currently, @code{g77} always chooses to make the separate variable,
to improve the likelihood that @samp{-O -Wuninitialized} will
diagnose failures to do things like @samp{GOTO I} without
@samp{ASSIGN 10 TO I} despite doing @samp{I=5}.)

@node Collected Fortran Wisdom
@chapter Collected Fortran Wisdom
@cindex wisdom
@cindex legacy code
@cindex code, legacy
@cindex writing code
@cindex code, writing

Most users of @code{g77} can be divided into two camps:

@itemize @bullet
@item
Those writing new Fortran code to be compiled by @code{g77}.

@item
Those using @code{g77} to compile existing, ``legacy'' code.
@end itemize

Users writing new code generally understand most of the necessary
aspects of Fortran to write ``mainstream'' code, but often need
help deciding how to handle problems, such as the construction
of libraries containing @samp{BLOCK DATA}.

Users dealing with ``legacy'' code sometimes don't have much
experience with Fortran, but believe that the code they're compiling
already works when compiled by other compilers (and might
not understand why, as is sometimes the case, it doesn't work
when compiled by @code{g77}).

The following information is designed to help users do a better job
coping with existing, ``legacy'' Fortran code, and with writing
new code as well.

@menu
* Overly Convenient Options::  Temptations to avoid, habits to not form.
* Block Data and Libraries::   How @code{g77} solves a common problem.
* Faster Programs::            Everybody wants these, but at what cost?
* Working Programs::           Getting programs to work should be done first.
* Loops::                      Fortran @samp{DO} loops surprise many people.
* Advantages Over f2c::        If @code{f2c} is so great, why @code{g77}?
@end menu

@node Overly Convenient Options
@section Overly Convenient Command-line Options
@cindex overly convenient options
@cindex options, overly convenient

These options should be used only as a quick-and-dirty way to determine
how well your program will run under different compilation models
without having to change the source.
Some are more problematic
than others, depending on how portable and maintainable you want the
program to be (and, of course, whether you are allowed to change it
at all is crucial).

You should not continue to use these command-line options to compile
a given program, but rather should make changes to the source code:

@table @code
@cindex -finit-local-zero option
@cindex options, -finit-local-zero
@item -finit-local-zero
(This option specifies that any uninitialized local variables
and arrays have default initialization to binary zeros.)

Many other compilers do this automatically, which means lots of
Fortran code developed with those compilers depends on it.

It is safer (and probably
would produce a faster program) to find the variables and arrays that
need such initialization and provide it explicitly via @samp{DATA}, so that
@samp{-finit-local-zero} is not needed.

Consider using @samp{-Wuninitialized} (which requires @samp{-O}) to
find likely candidates, but
do not specify @samp{-finit-local-zero} or @samp{-fno-automatic},
or this technique won't work.

@cindex -fno-automatic option
@cindex options, -fno-automatic
@item -fno-automatic
(This option specifies that all local variables and arrays
are to be treated as if they were named in @samp{SAVE} statements.)

Many other compilers do this automatically, which means lots of
Fortran code developed with those compilers depends on it.

The effect of this is that all non-automatic variables and arrays
are made static, that is, not placed on the stack or in heap storage.
This might cause a buggy program to appear to work better.
If so, rather than relying on this command-line option (and hoping all
compilers provide the equivalent one), add @samp{SAVE}
statements to some or all program unit sources, as appropriate.
Consider using @samp{-Wuninitialized} (which requires @samp{-O})
to find likely candidates, but
do not specify @samp{-finit-local-zero} or @samp{-fno-automatic},
or this technique won't work.

The default is @samp{-fautomatic}, which tells @code{g77} to try
and put variables and arrays on the stack (or in fast registers)
where possible and reasonable.
This tends to make programs faster.

@cindex automatic arrays
@cindex arrays, automatic
@emph{Note:} Automatic variables and arrays are not affected
by this option.
These are variables and arrays that are @emph{necessarily} automatic,
either due to explicit statements, or due to the way they are
declared.
Examples include local variables and arrays not given the
@samp{SAVE} attribute in procedures declared @samp{RECURSIVE},
and local arrays declared with non-constant bounds (automatic
arrays).
Currently, @code{g77} supports only automatic arrays, not
@samp{RECURSIVE} procedures or other means of explicitly
specifying that variables or arrays are automatic.

@cindex -fugly option
@cindex options, -fugly
@item -fugly
Fix the source code so that @samp{-fno-ugly} will work.
Note that, for many programs, it is difficult to practically
avoid using the features enabled via @samp{-fugly-init}, and these
features pose the lowest risk of writing nonportable code, among the
various ``ugly'' features.

@cindex -f@var{group}-intrinsics-hide option
@cindex options, -f@var{group}-intrinsics-hide
@item -f@var{group}-intrinsics-hide
Change the source code to use @samp{EXTERNAL} for any external procedure
that might be the name of an intrinsic.
It is easy to find these using @samp{-f@var{group}-intrinsics-disable}.
@end table

@node Block Data and Libraries
@section Block Data and Libraries
@cindex block data and libraries
@cindex BLOCK DATA statement
@cindex statements, BLOCK DATA
@cindex libraries, containing BLOCK DATA
@cindex f2c compatibility
@cindex compatibility

To ensure that block data program units are linked, especially a concern
when they are put into libraries, give each one a name (as in
@samp{BLOCK DATA FOO}) and make sure there is an @samp{EXTERNAL FOO}
statement in every program unit that uses any common block
initialized by the corresponding @samp{BLOCK DATA}.
@code{g77} currently compiles a @samp{BLOCK DATA} as if it were a
@samp{SUBROUTINE},
that is, it generates an actual procedure having the appropriate name.
The procedure does nothing but return immediately if it happens to be
called.
For @samp{EXTERNAL FOO}, where @samp{FOO} is not otherwise referenced in the
same program unit, @code{g77} assumes there exists a @samp{BLOCK DATA FOO}
in the program and ensures that by generating a
reference to it so the linker will make sure it is present.
(Specifically, @code{g77} outputs in the data section a static pointer to the
external name @samp{FOO}.)

The implementation @code{g77} currently uses to make this work is
one of the few things not compatible with @code{f2c} as currently
shipped.
@code{f2c} currently does nothing with @samp{EXTERNAL FOO} except
issue a warning that @samp{FOO} is not otherwise referenced, and for
@samp{BLOCK DATA FOO}, f2c doesn't generate a dummy procedure with the
name @samp{FOO}.
The upshot is that you shouldn't mix @samp{f2c} and @code{g77} in
this particular case.
If you use f2c to compile @samp{BLOCK DATA FOO},
then any @code{g77}-compiled program unit that says @samp{EXTERNAL FOO}
will result in an unresolved reference when linked.
If you do the
opposite, then @samp{FOO} might not be linked in under various
circumstances (such as when @samp{FOO} is in a library, or you're
using a ``clever'' linker---so clever, it produces a broken program
with little or no warning by omitting initializations of global data
because they are contained in unreferenced procedures).

The changes you make to your code to make @code{g77} handle this situation,
however, appear to be a widely portable way to handle it.
That is, many systems permit it (as they should, since the
FORTRAN 77 standard permits @samp{EXTERNAL FOO} when @samp{FOO}
is a block data program unit), and of the ones
that might not link @samp{BLOCK DATA FOO} under some circumstances, most of
them appear to do so once @samp{EXTERNAL FOO} is present in the appropriate
program units.

@node Faster Programs
@section Faster Programs
@cindex speeding up programs
@cindex programs, speeding up

Aside from the usual @samp{gcc} options, such as @samp{-O},
@samp{-ffast-math}, and so on, consider trying:

@table @code
@cindex -fno-f2c option
@cindex options, -fno-f2c
@item -fno-f2c
@cindex f2c compatibility
@cindex compatibility
Use this if you aren't linking with any code compiled using
@code{f2c}.
(Note that @code{libf2c} is @emph{not} an example of code
that is compiled using @code{f2c}---it is compiled by a C
compiler, usually @code{gcc}.)
@end table

If you're using @samp{-fno-automatic} already, you probably
should change your code to allow compilation with @samp{-fautomatic}
(the default), to allow the program to run faster.

Similarly, you should be able to use @samp{-fno-init-local-zero}
(the default) instead of @samp{-finit-local-zero}.
This is because it is rare that every variable affected by these
options in a given program actually needs to
be so affected.

For example, @samp{-fno-automatic}, which effectively @samp{SAVE}s
every local non-automatic variable and array, affects even things like
@samp{DO} iteration
variables, which rarely need to be @samp{SAVE}d, and this often reduces
run-time performances.
Similarly, @samp{-fno-init-local-zero} forces such
variables to be initialized to zero---when @samp{SAVE}d (such as when
@samp{-fno-automatic}), this by itself generally affects only
startup time for a program, but when not @samp{SAVE}d,
it can slow down the procedure every time it is called.

@xref{Overly Convenient Options,,Overly Convenient Command-Line Options},
for information on the @samp{-fno-automatic} and
@samp{-finit-local-zero} options and how to convert
their use into selective changes in your own code.

@node Working Programs
@section Working Programs

Getting Fortran programs to work in the first place can be
quite a challenge---even when the programs already work on
other systems, or when using other compilers.

@code{g77} offers some options that might be useful for
tracking down bugs in such programs.
@xref{Option Summary}, for a summary of these and other
options, and cross-references for each such option to
the pertinent material in this manual.

@table @code
@item -finit-local-zero
A program that works better when compiled with this option
is depending on a particular system's, or compiler's, tendency
to initialize some variables to zero.
It might be worthwhile finding such cases and fixing them.

@item -fno-automatic
A program that works better when compiled with this option
is depending on not having to use the @samp{SAVE} statement
as required by the Fortran standard.
It might be worthwhile finding such cases and fixing them.

@item -Wimplicit
This might catch failures to properly specify the types of
variables, arrays, and functions in the code.
However, in code that makes heavy use of Fortran's
implicit-typing facility, this option might produce so
many warnings about cases that are working, it would be
hard to find the one or two that represent bugs.

@item -Wunused
This can find bugs involving implicitly typing, sometimes
more easily than using -Wimplicit in code that makes
heavy use of implicit typing.
An unused variable or array might indicate that the
spelling for its declaration is different from that of
its intended uses.

@item -Wuninitialized
This can find bugs involving uninitialized variables, which
can in turn result from misspellings in declaration statements.

@item -Wsurprising
This can find bugs involving expression evaluation or in
the way @samp{DO} loops with non-integral iteration variables
are handled.
Cases found by this option might indicate a difference of
interpretation between the author of the code involved, and
a standard-conforming compiler such as @code{g77}.
Such a difference might produce actual bugs.

In any case, changing the code to explicitly do what the
programmer might have expected it to do, so @code{g77} and
other compilers are more likely to follow the programmer's
expectations, might be worthwhile, especially if such changes
make the program work better.

@item -W
It is possible that the ``extra'' warnings enabled by this
option could expose bugs in the code.
@end table

@node Loops
@section Loops
@cindex DO statement
@cindex statements, DO
@cindex trips, number of
@cindex number of trips

The meaning of a @samp{DO} loop in Fortran is precisely specified
in the Fortran standard@dots{}and is quite different from what
many programmers might expect.

In particular, Fortran @samp{DO} loops are implemented as if
the number of trips through the loop is calculated @emph{before}
the loop is entered.

The number of trips for a loop is calculated from the @var{start},
@var{end}, and @var{increment} values specified in a statement such as:

@example
DO @var{iter} = @var{start}, @var{end}, @var{increment}
@end example

The trip count is evaluated using a fairly simple formula
based on the three values following the @samp{=} in the
statement, and it is that trip count that is effectively
decremented during each iteration of the loop.
If, at the beginning of an iteration of the loop, the
trip count is zero or negative, the loop terminates.
The per-loop-iteration modifications to @var{iter} are not
related to determining whether to terminate the loop.

There are two important things to remember about the trip
count:

@itemize @bullet
@item
It can be @emph{negative}, in which case it is
treated as if it was zero---meaning the loop is
not executed at all.

@item
The type used to @emph{calculate} the trip count
the same type as @var{iter}, but the final
calculation, and thus the type of the trip
count itself, always is @samp{INTEGER}.
@end itemize

These two items mean that there are loops that cannot
be written in straightforward fashion using the Fortran @samp{DO}.

For example, on a system with the canonical 32-bit two's-complement
implementation of @samp{INTEGER}, the following loop will not work:

@example
DO I = -2000000000, 2000000000
@end example

@noindent
Although the @var{start} and @var{end} values are well within
the range of @samp{INTEGER}, the @emph{trip count} is not.
The expected trip count is 40000000001, which is outside
the range of @samp{INTEGER} on many systems.

Instead, the above loop should be constructed this way:

@example
I = -2000000000
DO
  IF (I .GT. 2000000000) EXIT
  @dots{}
  I = I + 1
END DO
@end example

@noindent
The simple @samp{DO} construct and the @samp{EXIT} statement
(used to leave the innermost loop)
are F90 features that @code{g77} supports.

Some Fortran compilers have buggy implementations of @samp{DO},
in that they don't follow the standard.
They implement @samp{DO} as a straightforward translation
to what, in C, would be a @samp{for} statement.
Instead of creating a temporary variable to hold the trip count
as calculated at run time, these compilers
use the iteration variable @var{iter} to control
whether the loop continues at each iteration.

The bug in such an implementation shows up when the
trip count is within the range of the type of @var{iter},
but the magnitude of @samp{ABS(@var{end}) + ABS(@var{incr})}
exceeds that range.  For example:

@example
DO I = 2147483600, 2147483647
@end example

@noindent
A loop started by the above statement will work as implemented
by @code{g77}, but the use, by some compilers, of a
more C-like implementation akin to

@example
for (i = 2147483600; i <= 2147483647; ++i)
@end example

@noindent
produces a loop that does not terminate, because @samp{i}
can never be greater than 2147483647, since incrementing it
beyond that value overflows @samp{i}, setting it to -2147483648.
This is a large, negative number that still is less than 2147483647.

Another example of unexpected behavior of @samp{DO} involves
using a nonintegral iteration variable @var{iter}, such as
a @samp{REAL} or @samp{DOUBLE PRECISION} variable.
Consider the following program:

@smallexample
      DATA BEGIN, END, STEP /.1, .31, .007/
      DO 10 R = BEGIN, END, STEP
         IF (R .GT. END) PRINT *, R, ' .GT. ', END, '!!'
         PRINT *,R
10    CONTINUE
      PRINT *,'LAST = ',R
      IF (R .LE. END) PRINT *, R, ' .LE. ', END, '!!'
      END
@end smallexample

@noindent
A C-like view of @samp{DO} would hold that the two ``exclamatory''
@samp{PRINT} are never executed.
However, this is the output of running the above program
as compiled by @code{g77} on a GNU/Linux ix86 system:

@smallexample
 .100000001
 .107000001
 .114
 .120999999
 @dots{}
 .289000005
 .296000004
 .303000003
LAST =   .310000002
 .310000002 .LE.   .310000002!!
@end smallexample

Note that one of the two checks in the program turned up
an apparent violation of the programmer's expectation---yet,
the loop is correctly implemented by @code{g77}, in that
it has 30 iterations.
This trip count of 30 is correct when evaluated using
the floating-point representations for the @var{begin},
@var{end}, and @var{incr} values (.1, .31, .007) on GNU/Linux
ix86 are used.
On other systems, an apparently more accurate trip count
of 31 might result, but, nevertheless, @code{g77} is
faithfully following the Fortran standard, and the result
is not what the author of the sample program above
apparently expected.
(Such other systems might, for different values in the @samp{DATA}
statement, violate the other programmer's expectation,
for example.)

Due to this combination of imprecise representation
of floating-point values and the often-misunderstood
interpretation of @samp{DO} by standard-conforming
compilers such as @code{g77}, use of @samp{DO} loops
with @samp{REAL} or @samp{DOUBLE PRECISION} iteration
variables is not recommended.
Such use can be caught by specifying @samp{-Wsurprising}.
@xref{Warning Options}, for more information on this
option.

@node Advantages Over f2c
@section Advantages Over f2c

Without @code{f2c}, @code{g77} would have taken much longer to
do and probably not been as good for quite a while.
Sometimes people who notice how much @code{g77} depends on, and
documents encouragement to use, @code{f2c} ask why @code{g77}
was created if @code{f2c} already existed.

This section gives some basic answers to these questions, though it
is not intended to be comprehensive.

@menu
* Language Extensions::  Features used by Fortran code.
* Compiler Options::     Features helpful during development.
* Compiler Speed::       Speed of the compilation process.
* Program Speed::        Speed of the generated, optimized code.
* Ease of Debugging::    Debugging ease-of-use at the source level.
* Character and Hollerith Constants::  A byte saved is a byte earned.
@end menu

@node Language Extensions
@subsection Language Extensions

@code{g77} offers several extensions to the Fortran language that @code{f2c}
doesn't.

However, @code{f2c} offers a few that @code{g77} doesn't, like
fairly complete support for @samp{INTEGER*2}.
It is expected that @code{g77} will offer some or all of these missing
features at some time in the future.
(Version 0.5.18 of @code{g77} offers some rudimentary support for some
of these features.)

@node Compiler Options
@subsection Compiler Options

@code{g77} offers a whole bunch of compiler options that @code{f2c} doesn't.

However, @code{f2c} offers a few that @code{g77} doesn't, like an
option to generate code to check array subscripts at run time.
It is expected that @code{g77} will offer some or all of these
missing options at some time in the future.

@node Compiler Speed
@subsection Compiler Speed

Saving the steps of writing and then rereading C code is a big reason
why @code{g77} should be able to compile code much faster than using
@code{f2c} in conjunction with the equivalent invocation of @code{gcc}.

However, due to @code{g77}'s youth, lots of self-checking is still being
performed.
As a result, this improvement is as yet unrealized
(though the potential seems to be there for quite a big speedup
in the future).
It is possible that, as of version 0.5.18, @code{g77}
is noticably faster compiling many Fortran source files than using
@code{f2c} in conjunction with @code{gcc}.

@node Program Speed
@subsection Program Speed

@code{g77} has the potential to better optimize code than @code{f2c},
even when @code{gcc} is used to compile the output of @code{f2c},
because @code{f2c} must necessarily
translate Fortran into a somewhat lower-level language (C) that cannot
preserve all the information that is potentially useful for optimization,
while @code{g77} can gather, preserve, and transmit that information directly
to the GBE.

For example, @code{g77} implements @samp{ASSIGN} and assigned
@samp{GOTO} using direct assignment of pointers to labels and direct
jumps to labels, whereas @code{f2c} maps the assigned labels to
integer values and then uses a C @samp{switch} statement to encode
the assigned @samp{GOTO} statements.

However, as is typical, theory and reality don't quite match, at least
not in all cases, so it is still the case that @code{f2c} plus @code{gcc}
can generate code that is faster than @code{g77}.

It is hoped that version 0.5.18 of @code{g77} will offer default
settings and options that allow for better program speed, though
it is not yet known whether these same options, when applied to
a @code{gcc} compilation of @code{f2c} output, will improve the
speed of programs compiled using that method as well.

@node Ease of Debugging
@subsection Ease of Debugging

Because @code{g77} compiles directly to assembler code like @code{gcc},
instead of translating to an intermediate language (C) as does @code{f2c},
support for debugging can be better for @code{g77} than @code{f2c}.

However, although @code{g77} might be somewhat more ``native'' in terms of
debugging support than @code{f2c} plus @code{gcc}, there still are a lot
of things ``not quite right''.
Many of the important ones should be resolved in the near future.

For example, @code{g77} doesn't have to worry about reserved names
like @code{f2c} does.
Given @samp{FOR = WHILE}, @code{f2c} must necessarily
translate this to something @emph{other} than
@samp{for = while;}, because C reserves those words.

However, @code{g77} does still uses things like an extra level of indirection
for @samp{ENTRY}-laden procedures---in this case, because the back end doesn't
yet support multiple entry points.

Another example is that, given

@example
COMMON A, B
EQUIVALENCE (B, C)
@end example

@noindent
the @code{g77} user should be able to access the variables directly, by name,
without having to traverse C-like structures and unions, while @code{f2c}
is unlikely to ever offer this ability (due to limitations in the
C language).

However, due to apparent bugs in the back end, @code{g77} currently doesn't
take advantage of this facility at all---it doesn't emit any debugging
information for @samp{COMMON} and @samp{EQUIVALENCE} areas,
other than information
on the array of @samp{char} it creates (and, in the case
of local @samp{EQUIVALENCE}, names) for each such area.

Yet another example is arrays.
@code{g77} represents them to the debugger
using the same ``dimensionality'' as in the source code, while @code{f2c}
must necessarily convert them all to one-dimensional arrays to fit
into the confines of the C language.
However, the level of support
offered by debuggers for interactive Fortran-style access to arrays
as compiled by @code{g77} can vary widely.
In some cases, it can actually
be an advantage that @code{f2c} converts everything to widely supported
C semantics.

In fairness, @code{g77} could do many of the things @code{f2c} does
to get things working at least as well as @code{f2c}---for now,
the maintainers have tended to prefer making @code{g77} work the
way they think it is supposed to, and find help improving the
other products (the GBE of @code{gcc}; @code{gdb}; and so on)
to get things working properly.

@node Character and Hollerith Constants
@subsection Character and Hollerith Constants
@cindex character constants
@cindex constants, character
@cindex Hollerith constants
@cindex constants, Hollerith
@cindex trailing null byte
@cindex null byte, trailing
@cindex zero byte, trailing

To avoid the extensive hassle that would be needed to avoid this,
@code{f2c} uses C character constants to encode character and Hollerith
constants.
That means a constant like @samp{'HELLO'} is translated to
@samp{"hello"} in C, which further means that an extra null byte is
present at the end of the constant.
This null byte is superfluous.

@code{g77} does not generate such null bytes.
This represents significant
savings of resources, such as on systems where @file{/dev/null} or
@file{/dev/zero} represent bottlenecks in the systems' performance,
because @code{g77} simply asks for fewer zeros from the operating
system than @code{f2c}.

@node Trouble
@chapter Known Causes of Trouble with GNU Fortran
@cindex bugs, known
@cindex installation trouble
@cindex known causes of trouble

This section describes known problems that affect users of GNU Fortran.
Most of these are not GNU Fortran bugs per se---if they were, we would
fix them.
But the result for a user might be like the result of a bug.

Some of these problems are due to bugs in other software, some are
missing features that are too much work to add, and some are places
where people's opinions differ as to what is best.

Information on bugs that show up when configuring, porting, building,
or installing @code{g77} is not provided here.
@xref{Problems Installing}.

(Note that some of this portion of the manual is lifted
directly from the @code{gcc} manual, with minor modifications
to tailor it to users of @code{g77}.
Anytime a bug seems to have more to do with the @code{gcc}
portion of @code{g77},
@xref{Trouble,,Known Causes of Trouble with GNU CC,
gcc,Using and Porting GNU CC}.)

@menu
* But-bugs::         Bugs really in other programs.
* Actual Bugs::      Bugs and misfeatures we will fix later.
* Missing Features:: Features we already know we want to add later.
* Disappointments::  Regrettable things we can't change.
* Non-bugs::         Things we think are right, but some others disagree.
* Warnings and Errors::  Which problems in your code get warnings,
                         and which get errors.
@end menu

@node But-bugs
@section Bugs Not In GNU Fortran
@cindex but-bugs

These are bugs to which the maintainers often have to reply,
``but that isn't a bug in @code{g77}@dots{}''.
Some of these already are fixed in new versions of other
software; some still need to be fixed; some are problems
with how @code{g77} is installed or is being used;
some just cannot be addressed at this time until more
is known about the problem.

Please don't re-report these bugs to the @code{g77} maintainers---if
you must remind someone how important it is to you that the problem
be fixed, talk to the people responsible for the other products
identified below, but preferably only after you've tried the
latest versions of those products.
The @code{g77} maintainers have their hands full working on
just fixing and improving @code{g77}, without serving as a
clearinghouse for all bugs that happen to affect @code{g77}
users.

@xref{Collected Fortran Wisdom}, for information on behavior
of Fortran programs, and the programs that compile them, that
might be @emph{thought} to indicate bugs.

@itemize @bullet
@item
@cindex common blocks, large
@cindex large common blocks
@cindex linker errors
@cindex ld errors
@cindex errors, linker
On some older GNU/Linux systems, programs with common blocks larger
than 16MB cannot be linked without some kind of error
message being produced.

This is a bug in older versions of @code{ld}, fixed in
more recent versions of @code{binutils}, such as version 2.6.

@cindex @code{gdb} support
@cindex support, @code{gdb}
@item
There are some known problems when using @code{gdb} on code
compiled by @code{g77}.
Inadequate investigation as of the release of 0.5.16 results in not
knowing which products are the culprit, but @file{gdb-4.14} definitely
crashes when, for example, an attempt is made to print the contents
of a @samp{COMPLEX*16} dummy array, on at least some GNU/Linux machines, plus
some others.

@item
@cindex unresolved reference (various)
@cindex linking error for user code
@cindex code, user
@cindex ld error for user code
@cindex ld can't find strange names
On some systems, perhaps just those with out-of-date (shared?)
libraries, unresolved-reference errors happen when linking @code{g77}-compiled
programs (which should be done using @code{g77}).

If this happens to you, try appending @samp{-lc} to the command you
use to link the program, e.g. @samp{g77 foo.f -lc}.
@code{g77} already specifies @samp{-lf2c -lm} when it calls the linker,
but it cannot also specify @samp{-lc} because not all systems have a
file named @file{libc.a}.

It is unclear at this point whether there are legitimately installed
systems where @samp{-lf2c -lm} is insufficient to resolve code produced
by @code{g77}.

@item
@cindex undefined reference (_main)
@cindex linking error for user code
@cindex ld error for user code
@cindex code, user
@cindex ld can't find _main
If your program doesn't link, due to unresolved references to names
like @samp{_main}, make sure you're using the @code{g77} command to do the
link, since this command ensures that the necessary libraries are
loaded by specifying @samp{-lf2c -lm} when it invokes the @code{gcc}
command to do the actual link.
(Use the @samp{-v} option to discover
more about what actually happens when you use the @code{g77} and @code{gcc}
commands.)

Also, try specifying @samp{-lc} as the last item on the @code{g77}
command line, because some systems need it and @code{g77} doesn't do it
automatically.

@item
Developers of Fortran code on NeXTStep (all architectures) have to
watch out for the following problem when writing programs with
large, statically allocated (i.e. non-stack based) data structures
(common blocks, saved arrays).

Due to the way the native loader (@file{/bin/ld}) lays out
data structures in virtual memory, it is very easy to create an
executable wherein the @samp{__DATA} segment overlaps (has addresses in
common) with the @samp{UNIX STACK} segment.

This leads to all sorts of trouble, from the executable simply not
executing, to bus errors.
The NeXTStep command line tool @code{ebadexec} points to
the problem as follows:

@smallexample
% @kbd{/bin/ebadexec a.out}
/bin/ebadexec: __LINKEDIT segment (truncated address = 0x3de000
rounded size = 0x2a000) of executable file: a.out overlaps with UNIX
STACK segment (truncated address = 0x400000 rounded size =
0x3c00000) of executable file: a.out
@end smallexample

(In the above case, it is the @samp{__LINKEDIT} segment that overlaps the
stack segment.)

This can be cured by assigning the @samp{__DATA} segment
(virtual) addresses beyond the stack segment.
A conservative
estimate for this is from address 6000000 (hexadecimal) onwards---this
has always worked for me [Toon Moene]:

@smallexample
% @kbd{g77 -segaddr __DATA 6000000 test.f}
% @kbd{ebadexec a.out}
ebadexec: file: a.out appears to be executable
%
@end smallexample

Browsing through @file{gcc/f/Makefile.in},
you will find that the @code{f771} program itself also has to be
linked with these flags---it has large statically allocated
data structures.
(Version 0.5.18 reduces this somewhat, but probably
not enough.)

(The above item was contributed by Toon Moene
(@code{toon@@moene.indiv.nluug.nl}).)

@item
@code{g77} rejects some particularly nonportable,
silent data-type conversions such as @samp{LOGICAL}
to @samp{REAL} (as in @samp{A=.FALSE.}, where @samp{A}
is type @samp{REAL}), that other compilers might
quietly accept.

Some of these conversions are accepted by @code{g77}
when the @samp{-fugly} option is specified.

@cindex stack overflow
@cindex segmentation violation
@item
@code{g77} code might fail at runtime (probably with a ``segmentation
violation'') due to overflowing the stack.
This happens most often on systems with an environment
that provides substantially more heap space (for use
when arbitrarily allocating and freeing memory) than stack
space.

Often this can be cured by
increasing or removing your shell's limit on stack usage, typically
using @kbd{limit stacksize} (in @code{csh} and derivatives) or
@kbd{ulimit -s} (in @code{sh} and derivatives).

Increasing the allowed stack size might, however, require
changing some operating system or system configuration parameters.

You might be able to work around the problem by compiling with the
@samp{-fno-automatic} option to reduce stack usage, probably at the
expense of speed.

@xref{Maximum Stackable Size}, for information on patching
@code{g77} to use different criteria for placing local
non-automatic variables and arrays on the stack.

@cindex automatic arrays
@cindex arrays, automatic
However, if your program uses large automatic arrays
(for example, has declarations like @samp{REAL A(N)} where
@samp{A} is a local array and @samp{N} is a dummy or
@samp{COMMON} variable that can have a large value),
neither use of @samp{-fno-automatic},
nor changing the cut-off point for @code{g77} for using the stack,
will solve the problem by changing the placement of these
large arrays, as they are @emph{necessarily} automatic.

@code{g77} currently provides no means to specify that
automatic arrays are to be allocated on the heap instead
of the stack.
So, other than increasing the stack size, your best bet is to
change your source code to avoid large automatic arrays.
Methods for doing this currently are outside the scope of
this document.

(@emph{Note:} If your system puts stack and heap space in the
same memory area, such that they are effectively combined, then
a stack overflow probably indicates a program that is either
simply too large for the system, or buggy.)

@cindex segmentation violation
@cindex bus error
@cindex overwritten data
@cindex data, overwritten
@item
@code{g77} code might fail at runtime with ``segmentation violation'',
``bus error'', or even something as subtle as a procedure call
overwriting a variable or array element that it is not supposed
to touch.

These can be symptoms of a wide variety of actual bugs that
occurred earlier during the program's run, but manifested
themselves as @emph{visible} problems some time later.

Overflowing the bounds of an array---usually by writing beyond
the end of it---is one of two kinds of bug that often occurs
in Fortran code.

The other kind of bug is a mismatch between the actual arguments
passed to a procedure and the dummy arguments as declared by that
procedure.

Both of these kinds of bugs, and some others as well, can be
difficult to track down, because the bug can change its behavior,
or even appear to not occur, when using a debugger.

That is, these bugs can be quite sensitive to data, including
data representing the placement of other data in memory (that is,
pointers, such as the placement of stack frames in memory).

Plans call for improving @code{g77} so that it can offer the
ability to catch and report some of these problems at compile, link, or
run time, such as by generating code to detect references to
beyond the bounds of an array, or checking for agreement between
calling and called procedures.

In the meantime, finding and fixing the programming
bugs that lead to these behaviors is, ultimately, the user's
responsibility, as difficult as that task can sometimes be.
@end itemize

@include bugs.texi

@node Missing Features
@section Missing Features

This section lists features we know are missing from @code{g77},
and which we want to add someday.
(There is no priority implied in the ordering below.)

@itemize @bullet
@item
@cindex Fortran 90 support
@cindex support, Fortran 90
@code{g77} does not support many of the features that
distinguish Fortran 90 (and, now, Fortran 95) from
ANSI FORTRAN 77.

Some Fortran 90 features are listed here, because they
make sense to offer even to die-hard users of F77.
For example, many of them codify various ways F77 has
been extended to meet users' needs during its tenure,
so @code{g77} might as well offer them as the primary
way to meet those same needs, even if it offers compatibility
with one or more of the ways those needs were met
by other F77 compilers in the industry.

Still, many important F90 features are not listed here,
because no attempt has been made to research each and
every feature and assess its viability in @code{g77}.
In the meantime, users who need those features must
use Fortran 90 compilers anyway, and the best approach
to adding some F90 features to GNU Fortran might well be
to fund a comprehensive project to create GNU Fortran 95.

@item
@cindex AND intrinsic
@cindex intrinsics, AND
@cindex OR intrinsic
@cindex intrinsics, OR
@cindex SHIFT intrinsic
@cindex intrinsics, SHIFT
@code{g77} does not allow @samp{REAL} and other non-integral types for
arguments to intrinsics like @samp{AND}, @samp{OR}, and @samp{SHIFT}.

@item
@cindex INTEGER*2 support
@cindex LOGICAL*1 support
@code{g77} doesn't support @samp{INTEGER*2}, @samp{LOGICAL*1}, and similar.
Version 0.6 will provide full support for this extremely
important set of features.
In the meantime, version 0.5.18 provides rudimentary support
for them.

@item
@code{g77} rejects things other compilers accept,
like @samp{INTRINSIC SQRT,SQRT}.
As time permits in the future, some of these things that are easy for
humans to read and write and unlikely to be intended to mean something
else will be accepted by @code{g77} (though @samp{-fpedantic} should
trigger warnings about such non-standard constructs).

In the meantime, you might as well fix your code
to be more standard-conforming and portable.

The kind of case that is important to except from the
recommendation to change your code is one where following
good coding rules would force you to write non-standard
code that nevertheless has a clear meaning.

For example, when writing an @samp{INCLUDE} file that
defines a common block, it might be appropriate to
include a @samp{SAVE} statement for the common block
(such as @samp{SAVE /CBLOCK/}), so that variables
defined in the common block retain their values even
when all procedures declaring the common block become
inactive (return to their callers).

However, putting @samp{SAVE} statements in an @samp{INCLUDE}
file would prevent otherwise standard-conforming code
from also specifying the @samp{SAVE} statement, by itself,
to indicate that all local variables and arrays are to
have the @samp{SAVE} attribute.

For this reason, @code{g77} already has been changed to
allow this combination, because although the general
problem of gratuitously rejecting unambiguous and
``safe'' constructs still exists in @code{g77}, this
particular construct was deemed useful enough that
it was worth fixing @code{g77} for just this case.

So, while there is no need to change your code
to avoid using this particular construct, there
might be other, equally appropriate but non-standard
constructs, that you shouldn't have to stop using
just because @code{g77} (or any other compiler)
gratuitously rejects it.

Until the general problem is solved, if you have
any such construct you believe is worthwhile
using (e.g. not just an arbitrary, redundant
specification of an attribute), please submit a
bug report with an explanation, so we can consider
fixing @code{g77} just for cases like yours.

@item
@cindex PARAMETER statement
@cindex statements, PARAMETER
@code{g77} doesn't accept @samp{PARAMETER I=1}.
Supporting this obsolete form of
the @samp{PARAMETER} statement would not be particularly hard, as most of the
parsing code is already in place and working.

Until time/money is
spent implementing it, you might as well fix your code to use the
standard form, @samp{PARAMETER (I=1)} (possibly needing
@samp{INTEGER I} preceding the @samp{PARAMETER} statement as well,
otherwise, in the obsolete form of @samp{PARAMETER}, the
type of the variable is set from the type of the constant being
assigned to it).

@item
@cindex POINTER statement
@cindex statements, POINTER
@cindex Cray pointers
@code{g77} doesn't support pointers or allocatable objects.
This set of features is
probably considered just behind @samp{INTEGER*2} and intrinsics
in @samp{PARAMETER} statements on the list of large,
important things to add to @code{g77}.

@cindex TYPE statement
@cindex statements, TYPE
@cindex ACCEPT statement
@cindex statements, ACCEPT
@item
@code{g77} doesn't support the I/O statements @samp{TYPE} and
@samp{ACCEPT}.
These are common extensions that should be easy to support,
but also are fairly easy to work around in user code.

@cindex STRUCTURE statement
@cindex statements, STRUCTURE
@cindex UNION statement
@cindex statements, UNION
@cindex RECORD statement
@cindex statements, RECORD
@cindex MAP statement
@cindex statements, MAP
@item
@code{g77} doesn't support @samp{STRUCTURE}, @samp{UNION}, @samp{RECORD},
@samp{MAP}.
This set of extensions is quite a bit
lower on the list of large, important things to add to @code{g77}, partly
because it requires a great deal of work either upgrading or
replacing @code{libf2c}.

@cindex ENCODE statement
@cindex statements, ENCODE
@cindex DECODE statement
@cindex statements, DECODE
@item
@code{g77} doesn't support @samp{ENCODE} or @samp{DECODE}.

These statements are best replaced by READ and WRITE statements
involving internal files (CHARACTER variables and arrays).

For example, replace a code fragment like

@example
      INTEGER*1 LINE(80)
@dots{}
      DECODE (80, 9000, LINE) A, B, C
@dots{}
9000  FORMAT (1X, 3(F10.5))
@end example

with:

@example
      CHARACTER*80 LINE
@dots{}
      READ (UNIT=LINE, FMT=9000) A, B, C
@dots{}
9000  FORMAT (1X, 3(F10.5))
@end example

Similarly, replace a code fragment like

@example
      INTEGER*1 LINE(80)
@dots{}
      ENCODE (80, 9000, LINE) A, B, C
@dots{}
9000  FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
@end example

with:

@example
      CHARACTER*80 LINE
@dots{}
      WRITE (UNIT=LINE, FMT=9000) A, B, C
@dots{}
9000  FORMAT (1X, 'OUTPUT IS ', 3(F10.5))
@end example

It is entirely possible that @samp{ENCODE} and @samp{DECODE} will
be supported by a future version of @code{g77}.

@cindex disposition of files
@cindex OPEN statement
@cindex statements, OPEN
@cindex CLOSE statement
@cindex statements, CLOSE
@cindex INQUIRE statement
@cindex statements, INQUIRE
@item
There is no support for keywords such as @samp{DISP='DELETE'} in
the @samp{OPEN}, @samp{CLOSE}, and @samp{INQUIRE} statements.
These extensions are easy to add to @code{g77} itself, but
require much more work on @code{libf2c}.

@cindex PARAMETER statement
@cindex statements, PARAMETER
@item
@code{g77} doesn't allow intrinsics in @samp{PARAMETER} statements.
This feature is considered to be absolutely vital, even though it
is not standard-conforming, and is scheduled for version 0.6.

Related to this, @code{g77} doesn't allow non-integral
exponentiation in @samp{PARAMETER} statements, such as
@samp{PARAMETER (R=2**.25)}.
It is unlikely @code{g77} will ever support this feature,
as doing it properly requires complete emulation of
a target computer's floating-point facilities when
building @code{g77} as a cross-compiler.
But, if the @code{gcc} back end is enhanced to provide
such a facility, @code{g77} will likely use that facility
in implementing this feature soon afterwards.

@cindex FORMAT statement
@cindex statements, FORMAT
@item
@code{g77} doesn't support @samp{FORMAT(I<J>)} and the like.
Supporting this requires a significant redesign or replacement
of @code{libf2c}.

@cindex RECURSIVE keyword
@cindex keywords, RECURSIVE
@cindex recursion, lack of
@cindex lack of recursion
@item
@code{g77} doesn't support the @samp{RECURSIVE} keyword that
F90 compilers do.
Nor does it provide any means for compiling procedures
designed to do recursion.

@cindex automatic arrays
@cindex arrays, automatic
@item
Automatic arrays are always allocated on the stack.
For situations where the stack cannot be made large enough,
@code{g77} should offer a compiler option that specifies
allocation of automatic arrays in heap storage.

@cindex threads
@cindex parallel processing
@item
Neither the code produced by @code{g77} nor the @code{libf2c} library
are thread-safe, nor does @code{g77} have support for parallel processing
(other than the instruction-level parallelism available on some
processors).
A package such as PVM might help here.

@item
Need option to suppress information messages (notes).
@samp{-w} does this but also suppresses warnings.
The default should be to suppress info messages.

@item
Provide some way, a la @code{gcc}, for @code{g77} code to specify assembler
code.

@item
Support @samp{INTEGER}, @samp{REAL}, and @samp{COMPLEX} equivalents
for all applicable back-end-supported types (@samp{char}, @samp{short int},
@samp{int}, @samp{long int}, @samp{long long int}, and @samp{long double}).
This means providing intrinsic support, and maybe constant
support (using F90 syntax) as well, and, for most
machines will result in automatic support of @samp{INTEGER*1},
@samp{INTEGER*2}, @samp{INTEGER*8}, and so on.
This is scheduled for version 0.6.

@item
Provide as the default source-line model a ``pure visual'' mode, where
the interpretation of a source program in this mode can be accurately
determined by a user looking at a traditionally displayed rendition
of the program (assuming the user knows whether the program is fixed
or free form).

That is, assume the user cannot tell tabs from spaces
and cannot see trailing spaces on lines, but has canonical tab stops
and, for fixed-form source, has the ability to always know exactly
where column 72 is.

This would change the default treatment of fixed-form source
to not treat lines with tabs as if they were infinitely long---instead,
they would end at column 72 just as if the tabs were replaced
by spaces in the canonical way.

As part of this, provide common alternate models (Digital, @code{f2c},
and so on) via command-line options.
This includes allowing arbitrarily long
lines for free-form source as well as fixed-form source and providing
various limits and diagnostics as appropriate.

@cindex array elements, in adjustable array bounds
@cindex function references, in adjustable array bounds
@cindex array bounds, adjustable
@cindex DIMENSION statement
@cindex statements, DIMENSION
@item
Support more general expressions to dimension
arrays, such as array element references, function
references, etc.

@item
A @samp{FLUSH} statement that does what many systems provide via
@samp{CALL FLUSH},
but that supports @samp{*} as the unit designator (same unit as for
@samp{PRINT}).

@item
Character-type selector/cases for @samp{SELECT CASE}.

@item
Option to initialize everything not explicitly initialized to ``weird''
(machine-dependent) values, e.g. NANs, bad (non-@samp{NULL}) pointers, and
largest-magnitude integers.

@item
Add run-time bounds-checking of array/subscript references a la @code{f2c}.

@item
Output labels for use by debuggers that know how to support them.
Same with weirder things like construct names.
It is not yet known if any debug formats or debuggers support these.

@item
Support the POSIX standard for Fortran.

@item
Support Digital-style lossage of virtual blanks at end of source line
if some command-line option specified.

This affects cases where
a character constant is continued onto the next line in a fixed-form
source file, as in the following example:

@example
10    PRINT *,'HOW MANY
     1 SPACES?'
@end example

@code{g77}, and many other compilers, virtually extend
the continued line through column 72 with blanks that become part
of the character constant, but Digital Fortran normally didn't,
leaving only one space between @samp{MANY} and @samp{SPACES?}
in the output of the above statement.

Fairly recently, at least one version of Digital Fortran
was enhanced to provide the other behavior when a
command-line option is specified, apparently due to demand
from readers of the USENET group @file{comp.lang.fortran}
to offer conformance to this widespread practice in the
industry.
@code{g77} should return the favor by offering conformance
to Digital's approach to handling the above example.

@item
Consider a preprocessor designed specifically for Fortran to replace
@samp{cpp -traditional}.
There are several out there worth evaluating, at least.

@item
Have @samp{-Wunused} warn about unused labels.

@item
Warn about assigned @samp{GOTO}/@samp{FORMAT} usage without any
@samp{ASSIGN} to variable.
(Actually, use of @samp{-O -Wuninitialized} should
take care of most of these.)

@item
Add @samp{-Wintrinsics} to warn about use of
non-standard intrinsics without explicit @samp{INTRINSIC} statements for them
(to help find code that might fail silently when ported to another
compiler).

@item
Support @samp{-fpedantic} more thoroughly, and use it only to generate
warnings instead of rejecting constructs outright.
Have it warn:
if a variable that dimensions an array is not a dummy or placed
explicitly in @samp{COMMON} (F77 does not allow it to be
placed in @samp{COMMON} via @samp{EQUIVALENCE}); if specification statements
follow statement-function-definition statements; about all sorts of
syntactic extensions.

@item
Warn about modifying @samp{DO} variables via @samp{EQUIVALENCE}.
(This test might be useful in setting the
internal ``doiter'' flag for a variable or even array
reference within a loop, since that might produce faster code someday.)

@item
Add @samp{-Wpromotions} to warn if source code appears
to expect automatic, silent, and
somewhat dangerous compiler-assisted conversion of @samp{REAL}
constants to @samp{DOUBLE PRECISION} based on context.

For example, warn about cases like this:

@example
DOUBLE PRECISION FOO
PARAMETER (TZPHI = 9.435784839284958)
FOO = TZPHI * 3D0
@end example

@item
Generally continue processing for warnings and recoverable (user)
errors whenever possible---don't gratuitously make bad code.

For example:

@example
INTRINSIC ZABS
CALL FOO(ZABS)
END
@end example

When compiling the above with @samp{-ff2c-intrinsics-disable},
@code{g77} should indeed complain about passing @samp{ZABS},
but it still should compile, instead of rejecting
the entire @samp{CALL} statement.
(Some of this is related to improving
the compiler internals to improve how statements are analyzed.)

@item
If @samp{-fno-ugly}, reject badly designed trailing-radix quoted (typeless)
numbers, such as @samp{'123'O}.

@item
Add @samp{-Wugly*}, @samp{-Wautomatic}, @samp{-Wvxt-not-f90}, @samp{-Wf90},
and so on.
These would warn about places in the user's source where ambiguities
are found.

One especially interesting case that @samp{-Wf90} would catch
is use of @samp{REAL(Z)}, where @samp{Z} is @samp{DOUBLE COMPLEX}.
Apparently, traditional extended F77 compilers treat this as
what all compilers should agree is @samp{REAL(REAL(Z))}, while
F90 compilers are required to treat @samp{REAL(Z)} as the same
as @samp{DBLE(Z)}, returning a @samp{DOUBLE PRECISION} result
rather than a @samp{REAL} result.

@item
@samp{-Wconversion} and related should flag places where non-standard
conversions are found.
Perhaps much of this would be part of @samp{-Wugly*}.

@item
Complain when list of dummies containing an adjustable dummy array does
not also contain every variable listed in the dimension list of the
adjustable array.

Currently, @code{g77} does complain about a variable that
dimensions an array but doesn't appear in any dummy list or @samp{COMMON}
area, but this needs to be extended to catch cases where it doesn't appear in
every dummy list that also lists any arrays it dimensions.

@item
Make sure things like @samp{RETURN 2HAB} are invalid in both source forms
(must be @samp{RETURN (2HAB)},
which probably still makes no sense but at least can
be reliably parsed).
Fixed form rejects it, but not free form, except
in a way that is a bit difficult to understand.

@item
The sort of routines usually found in the BSD-ish @code{libU77} should be
provided in addition to the few utility routines in @code{libf2c}.
Much of this work has already been done, and is awaiting
integration into @code{g77}.

@cindex floating point exceptions
@cindex exceptions, floating point
@cindex FPE handling
@cindex NaN values
@item
The GCC backend and, consequently, @code{g77} currently provides no
control over whether or not floating point exceptions are trapped or
ignored.
(Ignoring them typically results in NaN values being
propagated in systems that conform to IEEE 754).
The behaviour is inherited from the system-dependent startup code.

Most systems provide some C-callable mechanism to change this; this can
be invoked at startup using GCC's @samp{constructor} attribute.
For example, just compiling and linking the following C with your
program will turn on exception trapping for the ``common'' exceptions
on an x86-based GNU system:

@smallexample
#include <fpu_control.h>
void __attribute__ ((constructor))
trapfpe () @{
  (void) __setfpucw (_FPU_DEFAULT &
                     ~(_FPU_MASK_IM | _FPU_MASK_ZM | _FPU_MASK_OM));
@}
@end smallexample
@end itemize

@node Disappointments
@section Disappointments and Misunderstandings

These problems are perhaps regrettable, but we don't know any practical
way around them for now.

@menu
* Limitation on Implicit Declarations::     No @samp{IMPLICIT CHARACTER*(*)}.
* Multiple Definitions of External Names::  No doing both @samp{COMMON /FOO/}
                                              and @samp{SUBROUTINE FOO}.
* Mangling of Names::                       @samp{SUBROUTINE FOO} is given
                                              external name @samp{foo_}.
@end menu

@cindex IMPLICIT CHARACTER*(*) statement
@cindex statements, IMPLICIT CHARACTER*(*)
@node Limitation on Implicit Declarations
@subsection Limitation on Implicit Declarations

@code{g77} disallows @samp{IMPLICIT CHARACTER*(*)}.
This is not standard-conforming.

@cindex block data
@cindex BLOCK DATA statement
@cindex statements, BLOCK DATA
@cindex COMMON statement
@cindex statements, COMMON
@cindex naming conflicts
@node Multiple Definitions of External Names
@subsection Multiple Definitions of External Names

@code{g77} doesn't allow a common block and an external procedure or
@samp{BLOCK DATA} to have the same name.
Some systems allow this, but @code{g77} does not,
to be compatible with @code{f2c}.

@code{g77} could special-case the way it handles
@samp{BLOCK DATA}, since it is not compatible with @code{f2c} in this
particular area (necessarily, since @code{g77} offers an
important feature here), but
it is likely that such special-casing would be very annoying to people
with programs that use @samp{EXTERNAL FOO}, with no other mention of
@samp{FOO} in the same program unit, to refer to external procedures, since
the result would be that @code{g77} would treat these references as requests to
force-load BLOCK DATA program units.

In that case, if @code{g77} modified
names of @samp{BLOCK DATA} so they could have the same names as
@samp{COMMON}, users
would find that their programs wouldn't link because the @samp{FOO} procedure
didn't have its name translated the same way.

(Strictly speaking,
@code{g77} could emit a null-but-externally-satisfying definition of
@samp{FOO} with its name transformed as if it had been a
@samp{BLOCK DATA}, but that probably invites more trouble than it's
worth.)

@cindex naming issues
@cindex external names
@cindex COMMON block names
@cindex name space
@cindex underscores
@node Mangling of Names
@subsection Mangling of Names in Source Code

The current external-interface design, which includes naming of
external procedures, COMMON blocks, and the library interface,
has various usability problems, including things like adding
underscores where not really necessary (and preventing easier
inter-language operability) and yet not providing complete
namespace freedom for user C code linked with Fortran apps (due
to the naming of functions in the library, among other things).

Project GNU should at least get all this ``right'' for systems
it fully controls, such as the Hurd, and provide defaults and
options for compatibility with existing systems and interoperability
with popular existing compilers.

@node Non-bugs
@section Certain Changes We Don't Want to Make

This section lists changes that people frequently request, but which
we do not make because we think GNU Fortran is better without them.

@menu
* Backslash in Constants::           Why @samp{'\\'} is a constant that
                                       is one, not two, characters long.
* Context-Sensitive Constants::      Why @samp{9.435784839284958} is a
                                       single-precision (@samp{REAL}) constant,
                                       and might be interpreted as
                                       @samp{9.435785} or similar.
* Equivalence Versus Equality::      Why @samp{.TRUE. .EQ. .TRUE.} won't work.
* Context-Sensitive Intrinsicness::  Why @samp{CALL SQRT} won't work.
* Initializing Before Specifying::   Why @samp{DATA VAR/1/} can't precede
                                       @samp{COMMON VAR}.
* Order of Side Effects::            Why @samp{J = IFUNC() - IFUNC()} might
                                       not behave as expected.
@end menu

@cindex backslash
@cindex f77 support
@cindex support, f77
@node Backslash in Constants
@subsection Backslash in Constants

In the opinion of many experienced Fortran users,
@samp{-fno-backslash} should be the default, not @samp{-fbackslash},
as currently set by @code{g77}.

First of all, you can always specify
@samp{-fno-backslash} to turn off this processing.

Despite not being within the spirit (though apparently within the
letter) of the ANSI FORTRAN 77 standard, @code{g77} defaults to
@samp{-fbackslash} because that is what most UNIX @code{f77} commands
default to, and apparently lots of code depends on this feature.

This is a particularly troubling issue.
The use of a C construct in the midst of Fortran code
is bad enough, worse when it makes existing Fortran
programs stop working (as happens when programs written
for non-UNIX systems are ported to UNIX systems with
compilers that provide the @samp{-fbackslash} feature
as the default---sometimes with no option to turn it off).

The author of GNU Fortran wished, for reasons of linguistic
purity, to make @samp{-fno-backslash} the default for GNU
Fortran and thus require users of UNIX @code{f77} and @code{f2c}
to specify @samp{-fbackslash} to get the UNIX behavior.

However, the realization that @code{g77} is intended as
a replacement for @emph{UNIX} @code{f77}, caused the author
to choose to make @code{g77} as compatible with
@code{f77} as feasible, which meant making @samp{-fbackslash}
the default.

The primary focus on compatibility is at the source-code
level, and the question became ``What will users expect
a replacement for @code{f77} to do, by default?''
Although at least one UNIX @code{f77} does not provide
@samp{-fbackslash} as a default, it appears that
the majority of them do, which suggests that
the majority of code that is compiled by UNIX @code{f77}
compilers expects @samp{-fbackslash} to be the default.

It is probably the case that more code exists
that would @emph{not} work with @samp{-fbackslash}
in force than code that requires it be in force.

However, most of @emph{that} code is not being compiled
with @code{f77},
and when it is, new build procedures (shell scripts,
makefiles, and so on) must be set up anyway so that
they work under UNIX.
That makes a much more natural and safe opportunity for
non-UNIX users to adapt their build procedures for
@code{g77}'s default of @samp{-fbackslash} than would
exist for the majority of UNIX @code{f77} users who
would have to modify existing, working build procedures
to explicitly specify @samp{-fbackslash} if that was
not the default.

One suggestion has been to configure the default for
@samp{-fbackslash} (and perhaps other options as well)
based on the configuration of @code{g77}.

This is technically quite straightforward, but will be avoided
even in cases where not configuring defaults to be
dependent on a particular configuration greatly inconveniences
some users of legacy code.

Many users appreciate the GNU compilers because they provide an
environment that is uniform across machines.
These users would be
inconvenienced if the compiler treated things like the
format of the source code differently on certain machines.

Occasionally users write programs intended only for a particular machine
type.
On these occasions, the users would benefit if the GNU Fortran compiler
were to support by default the same dialect as the other compilers on
that machine.
But such applications are rare.
And users writing a
program to run on more than one type of machine cannot possibly benefit
from this kind of compatibility.
(This is consistent with the design goals for @code{gcc}.
To change them for @code{g77}, you must first change them
for @code{gcc}.
Do not ask the maintainers of @code{g77} to do this for you,
or to disassociate @code{g77} from the widely understood, if
not widely agreed-upon, goals for GNU compilers in general.)

This is why GNU Fortran does and will treat backslashes in the same
fashion on all types of machines (by default).

Of course, users strongly concerned about portability should indicate
explicitly in their build procedures which options are expected
by their source code, or write source code that has as few such
expectations as possible.

For example, avoid writing code that depends on backslash (@samp{\})
being interpreted either way in particular, such as by
starting a program unit with:

@example
CHARACTER BACKSL
PARAMETER (BACKSL = '\\')
@end example

Then, use concatenation of @samp{BACKSL} anyplace a backslash
is desired.
(However, this technique does not work for Hollerith constants---which
is good, since the only generally portable uses for Hollerith
constants are in places where character constants can and should
be used instead, for readability.)

In this way, users can write programs which have the same meaning
in many Fortran dialects.

@cindex constants, context-sensitive
@cindex context-sensitive constants
@node Context-Sensitive Constants
@subsection Context-Sensitive Constants

@code{g77} does not use context to determine the types of
constants or named constants (@samp{PARAMETER}), except
for (non-standard) typeless constants such as @samp{'123'O}.

For example, consider the following statement:

@example
PRINT *, 9.435784839284958 * 2D0
@end example

@code{g77} will interpret the (truncated) constant
@samp{9.435784839284958} as a @samp{REAL}, not @samp{DOUBLE PRECISION},
constant, because the suffix @samp{D0} is not specified.

As a result, the output of the above statement when
compiled by @code{g77} will appear to have ``less precision''
than when compiled by other compilers.

In these and other cases, some compilers detect the
fact that a single-precision constant is used in
a double-precision context and therefore interpret the
single-precision constant as if it was @emph{explicitly}
specified as a double-precision constant.
(This has the effect of appending @emph{decimal}, not
@emph{binary}, zeros to the fractional part of the
number---producing different computational results.)

The reason this misfeature is dangerous is that a slight,
apparently innocuous change to the source code can change
the computational results.  Consider:

@example
REAL ALMOST, CLOSE
DOUBLE PRECISION FIVE
PARAMETER (ALMOST = 5.000000000001)
FIVE = 5
CLOSE = 5.000000000001
PRINT *, 5.000000000001 - FIVE
PRINT *, ALMOST - FIVE
PRINT *, CLOSE - FIVE
END
@end example

Running the above program should
result in the same value being
printed three times.
With @code{g77} as the compiler,
it does.

However, compiled by many other compilers,
running the above program would print
two or three distinct values, because
in two or three of the statements, the
constant @samp{5.000000000001}, which
on most systems is exactly equal to @samp{5.}
when interpreted as a single-precision constant,
is instead interpreted as a double-precision
constant, preserving the represented
precision.
However, this ``clever'' promotion of
type does not extend to variables or,
in some compilers, to named constants.

Since programmers often are encouraged to replace manifest
constants or permanently-assigned variables with named
constants (@samp{PARAMETER} in Fortran), and might need
to replace some constants with variables having the same
values for pertinent portions of code,
it is important that compilers treat code so modified in the
same way so that the results of such programs are the same.
@code{g77} helps in this regard by treating constants just
the same as variables in terms of determining their types
in a context-independent way.

Still, there is a lot of existing Fortran code that has
been written to depend on the way other compilers freely
interpret constants' types based on context, so anything
@code{g77} can do to help flag cases of this in such code
could be very helpful.

@cindex .EQV., with integer operands
@cindex comparing logical expressions
@cindex logical expressions, comparing
@node Equivalence Versus Equality
@subsection Equivalence Versus Equality

Use of @samp{.EQ.} and @samp{.NE.} on @samp{LOGICAL} operands
is not supported, except via @samp{-fugly}, which is not
recommended except for legacy code (where the behavior expected
by the @emph{code} is assumed).

Legacy code should be changed, as resources permit, to use @samp{.EQV.}
and @samp{.NEQV.} instead, as these are permitted by the various
Fortran standards.

New code should never be written expecting @samp{.EQ.} or @samp{.NE.}
to work if either of its operands is @samp{LOGICAL}.

The problem with supporting this ``feature'' is that there is
unlikely to be consensus on how it works, as illustrated by the
following sample program:

@example
LOGICAL L,M,N
DATA L,M,N /3*.FALSE./
IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N'
END
@end example

The issue raised by the above sample program is, what is the
precedence of @samp{.EQ.} (and @samp{.NE.}) when applied to
@samp{LOGICAL} operands?

Some programmers will argue that it is the same as the precedence
for @samp{.EQ.} when applied to numeric (such as @samp{INTEGER})
operands.
By this interpretation, the subexpression @samp{M.EQ.N} must be
evaluated first in the above program, resulting in a program that,
when run, does not execute the @samp{PRINT} statement.

Other programmers will argue that the precedence is the same as
the precedence for @samp{.EQV.}, which is restricted by the standards
to @samp{LOGICAL} operands.
By this interpretation, the subexpression @samp{L.AND.M} must be
evaluated first, resulting in a program that @emph{does} execute
the @samp{PRINT} statement.

Assigning arbitrary semantic interpretations to syntactic expressions
that might legitimately have more than one ``obvious'' interpretation
is generally unwise.

The creators of the various Fortran standards have done a good job
in this case, requiring a distinct set of operators (which have their
own distinct precedence) to compare @samp{LOGICAL} operands.
This requirement results in expression syntax with more certain
precedence (without requiring substantial context), making it easier
for programmers to read existing code.
@code{g77} will avoid muddying up elements of the Fortran language
that were well-designed in the first place.

(Ask C programmers about the precedence of expressions such as
@samp{(a) & (b)} and @samp{(a) - (b)}---they cannot even tell
you, without knowing more context, whether the @samp{&} and @samp{-}
operators are infix (binary) or unary!)

@cindex intrinsics, context-sensitive
@cindex context-sensitive intrinsics
@node Context-Sensitive Intrinsicness
@subsection Context-Sensitive Intrinsicness

@code{g77} treats procedure references to @emph{possible} intrinsic
names as always enabling their intrinsic nature, regardless of
whether the @emph{form} of the reference is valid for that
intrinsic.

For example, @samp{CALL SQRT} is interpreted by @code{g77} as
an invalid reference to the @samp{SQRT} intrinsic function,
because the reference is a subroutine invocation.

First, @code{g77} recognizes the statement @samp{CALL SQRT}
as a reference to a @emph{procedure} named @samp{SQRT}, not
to a @emph{variable} with that name (as it would for a statement
such as @samp{V = SQRT}).

Next, @code{g77} establishes that, in the program unit being compiled,
@samp{SQRT} is an intrinsic---not a subroutine that
happens to have the same name as an intrinsic (as would be
the case if, for example, @samp{EXTERNAL SQRT} was present).

Finally, @code{g77} recognizes that the @emph{form} of the
reference is invalid for that particular intrinsic.
That is, it recognizes that it is invalid for an intrinsic
@emph{function}, such as @samp{SQRT}, to be invoked as
a @emph{subroutine}.

At that point, @code{g77} issues a diagnostic.

Some users claim that it is ``obvious'' that @samp{CALL SQRT}
references an external subroutine of their own, not an
intrinsic function.

However, @code{g77} knows about intrinsic
subroutines, not just functions, and is able to support both having
the same names, for example.

As a result of this, @code{g77} rejects calls
to intrinsics that are not subroutines, and function invocations
of intrinsics that are not functions, just as it (and most compilers)
rejects invocations of intrinsics with the wrong number (or types)
of arguments.

So, use the @samp{EXTERNAL SQRT} statement in a program unit that calls
a user-written subroutine named @samp{SQRT}.

@cindex initialization, statement placement
@cindex placing initialization statements
@node Initializing Before Specifying
@subsection Initializing Before Specifying

@code{g77} does not allow @samp{DATA VAR/1/} to appear in the
source code before @samp{COMMON VAR},
@samp{DIMENSION VAR(10)}, @samp{INTEGER VAR}, and so on.
In general, @code{g77} requires initialization of a variable
or array to be specified @emph{after} all other specifications
of attributes (type, size, placement, and so on) of that variable
or array are specified (though @emph{confirmation} of data type is
permitted).

It is @emph{possible} @code{g77} will someday allow all of this,
even though it is not allowed by the FORTRAN 77 standard.

Then again, maybe it is better to have
@code{g77} always require placement of @samp{DATA}
so that it can possibly immediately write constants
to the output file, thus saving time and space.

That is, @samp{DATA A/1000000*1/} should perhaps always
be immediately writable to canonical assembler, unless it's already known
to be in a @samp{COMMON} area following as-yet-uninitialized stuff,
and to do this it cannot be followed by @samp{COMMON A}.

@cindex side effects, order of evaluation
@cindex order of evaluation, side effects
@node Order of Side Effects
@subsection Order of Side Effects

@code{g77} does not necessarily produce code that, when run, performs
side effects (such as those performed by function invocations)
in the same order as in some other compiler---or even in the same
order as another version, port, or invocation (using different
command-line options) of @code{g77}.

It is never safe to depend on the order of evaluation of side effects.
For example, an expression like this may very well behave differently
from one compiler to another:

@example
J = IFUNC() - IFUNC()
@end example

There is no guarantee that @samp{IFUNC} will be evaluated in any particular
order.
Either invocation might happen first.
If @samp{IFUNC} returns 5 the first time it is invoked, and
returns 12 the second time, @samp{J} might end up with the
value @samp{7}, or it might end up with @samp{-7}.

Generally, in Fortran, procedures with side-effects intended to
be visible to the caller are best designed as @emph{subroutines},
not functions.
Examples of such side-effects include:

@itemize @bullet
@item
The generation of random numbers
that are intended to influence return values.

@item
Performing I/O
(other than internal I/O to local variables).

@item
Updating information in common blocks.
@end itemize

An example of a side-effect that is not intended to be visible
to the caller is a function that maintains a cache of recently
calculated results, intended solely to speed repeated invocations
of the function with identical arguments.
Such a function can be safely used in expressions, because
if the compiler optimizes away one or more calls to the
function, operation of the program is unaffected (aside
from being speeded up).

@node Warnings and Errors
@section Warning Messages and Error Messages

@cindex error messages
@cindex warnings vs errors
@cindex messages, warning and error
The GNU compiler can produce two kinds of diagnostics: errors and
warnings.
Each kind has a different purpose:

@itemize @w{}
@item 
@emph{Errors} report problems that make it impossible to compile your
program.
GNU Fortran reports errors with the source file name, line
number, and column within the line where the problem is apparent.

@item
@emph{Warnings} report other unusual conditions in your code that
@emph{might} indicate a problem, although compilation can (and does)
proceed.
Warning messages also report the source file name, line number,
and column information,
but include the text @samp{warning:} to distinguish them
from error messages.
@end itemize

Warnings might indicate danger points where you should check to make sure
that your program really does what you intend; or the use of obsolete
features; or the use of nonstandard features of GNU Fortran.
Many warnings are issued only if you ask for them, with one of the
@samp{-W} options (for instance, @samp{-Wall} requests a variety of
useful warnings).

@emph{Note:} Currently, the text of the line and a pointer to the column
is printed in most @code{g77} diagnostics.
Probably, as of version 0.6, @code{g77} will
no longer print the text of the source line, instead printing
the column number following the file name and line number in
a form that GNU Emacs recognizes.
This change is expected to speed up and reduce the memory usage
of the @code{g77} compiler.
@c
@c Say this when it is true -- hopefully 0.6, maybe 0.7 or later.  --burley
@c
@c GNU Fortran always tries to compile your program if possible; it never
@c gratuitously rejects a program whose meaning is clear merely because
@c (for instance) it fails to conform to a standard.  In some cases,
@c however, the Fortran standard specifies that certain extensions are
@c forbidden, and a diagnostic @emph{must} be issued by a conforming
@c compiler.  The @samp{-pedantic} option tells GNU Fortran to issue warnings
@c in such cases; @samp{-pedantic-errors} says to make them errors instead.
@c This does not mean that @emph{all} non-ANSI constructs get warnings
@c or errors.

@xref{Warning Options,,Options to Request or Suppress Warnings}, for
more detail on these and related command-line options.

@node Open Questions
@chapter Open Questions

Please consider offering useful answers to these questions!

@itemize @bullet
@item
@samp{LOC()} and other intrinsics are probably somewhat misclassified.
Is the a need for more precise classification of intrinsics, and if so,
what are the appropriate groupings?
Is there a need to individually
enable/disable/delete/hide intrinsics from the command line?
@end itemize

@node Bugs
@chapter Reporting Bugs
@cindex bugs
@cindex reporting bugs

Your bug reports play an essential role in making GNU Fortran reliable.

When you encounter a problem, the first thing to do is to see if it is
already known.
@xref{Trouble}.
If it isn't known, then you should report the problem.

Reporting a bug might help you by bringing a solution to your problem, or
it might not.
(If it does not, look in the service directory; see
@ref{Service}.)
In any case, the principal function of a bug report is
to help the entire community by making the next version of GNU Fortran work
better.
Bug reports are your contribution to the maintenance of GNU Fortran.

Since the maintainers are very overloaded, we cannot respond to every
bug report.
However, if the bug has not been fixed, we are likely to
send you a patch and ask you to tell us whether it works. 

In order for a bug report to serve its purpose, you must include the
information that makes for fixing the bug.

@menu
* Criteria:  Bug Criteria.   Have you really found a bug?
* Where: Bug Lists.	     Where to send your bug report.
* Reporting: Bug Reporting.  How to report a bug effectively.
* Patches: Sending Patches.  How to send a patch for GNU Fortran.
* Known: Trouble.            Known problems.
* Help: Service.             Where to ask for help.
@end menu

@node Bug Criteria
@section Have You Found a Bug?
@cindex bug criteria

If you are not sure whether you have found a bug, here are some guidelines:

@itemize @bullet
@cindex fatal signal
@cindex core dump
@item
If the compiler gets a fatal signal, for any input whatever, that is a
compiler bug.
Reliable compilers never crash---they just remain obsolete.

@cindex invalid assembly code
@cindex assembly code, invalid
@item
If the compiler produces invalid assembly code, for any input whatever,
@c (except an @code{asm} statement),
that is a compiler bug, unless the
compiler reports errors (not just warnings) which would ordinarily
prevent the assembler from being run.

@cindex undefined behavior
@cindex undefined function value
@item
If the compiler produces valid assembly code that does not correctly
execute the input source code, that is a compiler bug.

However, you must double-check to make sure, because you might have run
into an incompatibility between GNU Fortran and traditional Fortran.
@c (@pxref{Incompatibilities}).
These incompatibilities might be considered
bugs, but they are inescapable consequences of valuable features.

Or you might have a program whose behavior is undefined, which happened
by chance to give the desired results with another Fortran compiler.
It is best to check the relevant Fortran standard thoroughly if
it is possible that the program indeed does something undefined.

After you have localized the error to a single source line, it should
be easy to check for these things.
If your program is correct and well defined, you have found
a compiler bug.

It might help if, in your submission, you identified the specific
language in the relevant Fortran standard that specifies the
desired behavior, if it isn't likely to be obvious and agreed-upon
by all Fortran users.

@item
If the compiler produces an error message for valid input, that is a
compiler bug.

@cindex invalid input
@item
If the compiler does not produce an error message for invalid input,
that is a compiler bug.
However, you should note that your idea of
``invalid input'' might be someone else's idea
of ``an extension'' or ``support for traditional practice''.

@item
If you are an experienced user of Fortran compilers, your suggestions
for improvement of GNU Fortran are welcome in any case.
@end itemize

@node Bug Lists
@section Where to Report Bugs
@cindex bug report mailing lists
@kindex fortran@@gnu.ai.mit.edu
Send bug reports for GNU Fortran to @samp{fortran@@gnu.ai.mit.edu}.

Often people think of posting bug reports to a newsgroup instead of
mailing them.
This sometimes appears to work, but it has one problem which can be
crucial: a newsgroup posting does not contain a mail path back to the
sender.
Thus, if maintainers need more information, they might be unable
to reach you.  For this reason, you should always send bug reports by
mail to the proper mailing list.

As a last resort, send bug reports on paper to:

@example
GNU Compiler Bugs
Free Software Foundation
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA
@end example

@node Bug Reporting
@section How to Report Bugs
@cindex compiler bugs, reporting

The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}.
If you are not sure whether to state a
fact or leave it out, state it!

Often people omit facts because they think they know what causes the
problem and they conclude that some details don't matter.
Thus, you might
assume that the name of the variable you use in an example does not matter.
Well, probably it doesn't, but one cannot be sure.
Perhaps the bug is a
stray memory reference which happens to fetch from the location where that
name is stored in memory; perhaps, if the name were different, the contents
of that location would fool the compiler into doing the right thing despite
the bug.
Play it safe and give a specific, complete example.
That is the
easiest thing for you to do, and the most helpful.

Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known.
It isn't very important what happens if
the bug is already known.
Therefore, always write your bug reports on
the assumption that the bug is not known.

Sometimes people give a few sketchy facts and ask, ``Does this ring a
bell?''
This cannot help us fix a bug, so it is rarely helpful.
We respond by asking for enough details to enable us to investigate.
You might as well expedite matters by sending them to begin with.
(Besides, there are enough bells ringing around here as it is.)

Try to make your bug report self-contained.
If we have to ask you for
more information, it is best if you include all the previous information
in your response, as well as the information that was missing.

Please report each bug in a separate message.
This makes it easier for
us to track which bugs have been fixed and to forward your bugs reports
to the appropriate maintainer.

Do not compress and encode any part of your bug report using programs
such as @file{uuencode}.
If you do so it will slow down the processing
of your bug.
If you must submit multiple large files, use @file{shar},
which allows us to read your message without having to run any
decompression programs.

(As a special exception for GNU Fortran bug-reporting, at least
for now, if you are sending more than a few lines of code, if
your program's source file format contains ``interesting'' things
like trailing spaces or strange characters, or if you need to
include binary data files, it is acceptable to put all the
files together in a @code{tar} archive, and, whether you need to
do that, it is acceptable to then compress the single file (@code{tar}
archive or source file)
using @code{gzip} and encode it via @code{uuencode}.
Do not use any MIME stuff---the current maintainer can't decode this.
Using @code{compress} instead of @code{gzip} is acceptable, assuming
you have licensed the use of the patented algorithm in
@code{compress} from Unisys.)

To enable someone to investigate the bug, you should include all these
things:

@itemize @bullet
@item
The version of GNU Fortran.
You can get this by running @code{g77} with the @samp{-v} option.
(Ignore any error messages that might be displayed
when the linker is run.)

Without this, we won't know whether there is any point in looking for
the bug in the current version of GNU Fortran.

@item
@cindex preprocessor
@cindex cpp program
@cindex programs, cpp
A complete input file that will reproduce the bug.
If the bug is in the compiler proper (@file{f771}) and
you are using the C preprocessor, run your
source file through the C preprocessor by doing @samp{g77 -E
@var{sourcefile} > @var{outfile}}, then include the contents of
@var{outfile} in the bug report.  (When you do this, use the same
@samp{-I}, @samp{-D} or @samp{-U} options that you used in actual
compilation.)

A single statement is not enough of an example.
In order to compile it,
it must be embedded in a complete file of compiler input; and the bug
might depend on the details of how this is done.

Without a real example one can compile, all anyone can do about your bug
report is wish you luck.  It would be futile to try to guess how to
provoke the bug.  For example, bugs in register allocation and reloading
frequently depend on every little detail of the function they happen in.

@item
@cindex included files
@cindex INCLUDE statement
@cindex statements, INCLUDE
Note that you should include with your bug report any files
included by the source file (via the @samp{INCLUDE} statement)
that you send, and any files they @samp{INCLUDE},
and so on.

It is not necessary to replace the @samp{INCLUDE} statements
with the actual files in the version of the source file that
you send, but it might make submitting the bug report easier
in the end.
However, be sure to @emph{reproduce} the bug using the @emph{exact}
version of the source material you submit, to avoid wild-goose
chases.

@item
The command arguments you gave GNU Fortran to compile that example
and observe the bug.  For example, did you use @samp{-O}?  To guarantee
you won't omit something important, list all the options.

If we were to try to guess the arguments, we would probably guess wrong
and then we would not encounter the bug.

@item
The type of machine you are using, and the operating system name and
version number.
(Much of this information is printed by @samp{g77 -v}---if you
include that, send along any additional info you have that you
don't see clearly represented in that output.)

@item
The operands you gave to the @code{configure} command when you installed
the compiler.

@item
A complete list of any modifications you have made to the compiler
source.  (We don't promise to investigate the bug unless it happens in
an unmodified compiler.  But if you've made modifications and don't tell
us, then you are sending us on a wild-goose chase.)

Be precise about these changes.  A description in English is not
enough---send a context diff for them.

Adding files of your own (such as a machine description for a machine we
don't support) is a modification of the compiler source.

@item
Details of any other deviations from the standard procedure for installing
GNU Fortran.

@item
A description of what behavior you observe that you believe is
incorrect.  For example, ``The compiler gets a fatal signal,'' or,
``The assembler instruction at line 208 in the output is incorrect.''

Of course, if the bug is that the compiler gets a fatal signal, then one
can't miss it.  But if the bug is incorrect output, the maintainer might
not notice unless it is glaringly wrong.  None of us has time to study
all the assembler code from a 50-line Fortran program just on the chance that
one instruction might be wrong.  We need @emph{you} to do this part!

Even if the problem you experience is a fatal signal, you should still
say so explicitly.  Suppose something strange is going on, such as, your
copy of the compiler is out of synch, or you have encountered a bug in
the C library on your system.  (This has happened!)  Your copy might
crash and the copy here would not.  If you @i{said} to expect a crash,
then when the compiler here fails to crash, we would know that the bug
was not happening.  If you don't say to expect a crash, then we would
not know whether the bug was happening.  We would not be able to draw
any conclusion from our observations.

If the problem is a diagnostic when building GNU Fortran with some other
compiler, say whether it is a warning or an error.

Often the observed symptom is incorrect output when your program is run.
Sad to say, this is not enough information unless the program is short
and simple.  None of us has time to study a large program to figure out
how it would work if compiled correctly, much less which line of it was
compiled wrong.  So you will have to do that.  Tell us which source line
it is, and what incorrect result happens when that line is executed.  A
person who understands the program can find this as easily as finding a
bug in the program itself.

@item
If you send examples of assembler code output from GNU Fortran,
please use @samp{-g} when you make them.  The debugging information
includes source line numbers which are essential for correlating the
output with the input.

@item
If you wish to mention something in the GNU Fortran source, refer to it by
context, not by line number.

The line numbers in the development sources don't match those in your
sources.  Your line numbers would convey no convenient information to the
maintainers.

@item
Additional information from a debugger might enable someone to find a
problem on a machine which he does not have available.  However, you
need to think when you collect this information if you want it to have
any chance of being useful.

@cindex backtrace for bug reports
For example, many people send just a backtrace, but that is never
useful by itself.  A simple backtrace with arguments conveys little
about GNU Fortran because the compiler is largely data-driven; the same
functions are called over and over for different RTL insns, doing
different things depending on the details of the insn.

Most of the arguments listed in the backtrace are useless because they
are pointers to RTL list structure.  The numeric values of the
pointers, which the debugger prints in the backtrace, have no
significance whatever; all that matters is the contents of the objects
they point to (and most of the contents are other such pointers).

In addition, most compiler passes consist of one or more loops that
scan the RTL insn sequence.  The most vital piece of information about
such a loop---which insn it has reached---is usually in a local variable,
not in an argument.

@findex debug_rtx
What you need to provide in addition to a backtrace are the values of
the local variables for several stack frames up.  When a local
variable or an argument is an RTX, first print its value and then use
the GDB command @code{pr} to print the RTL expression that it points
to.  (If GDB doesn't run on your machine, use your debugger to call
the function @code{debug_rtx} with the RTX as an argument.)  In
general, whenever a variable is a pointer, its value is no use
without the data it points to.
@end itemize

Here are some things that are not necessary:

@itemize @bullet
@item
A description of the envelope of the bug.

Often people who encounter a bug spend a lot of time investigating
which changes to the input file will make the bug go away and which
changes will not affect it.

This is often time consuming and not very useful, because the way we
will find the bug is by running a single example under the debugger with
breakpoints, not by pure deduction from a series of examples.  You might
as well save your time for something else.

Of course, if you can find a simpler example to report @emph{instead} of
the original one, that is a convenience.  Errors in the output will be
easier to spot, running under the debugger will take less time, etc.
Most GNU Fortran bugs involve just one function, so the most straightforward
way to simplify an example is to delete all the function definitions
except the one where the bug occurs.  Those earlier in the file may be
replaced by external declarations if the crucial function depends on
them.  (Exception: inline functions might affect compilation of functions
defined later in the file.)

However, simplification is not vital; if you don't want to do this,
report the bug anyway and send the entire test case you used.

@item
In particular, some people insert conditionals @samp{#ifdef BUG} around
a statement which, if removed, makes the bug not happen.  These are just
clutter; we won't pay any attention to them anyway.  Besides, you should
send us preprocessor output, and that can't have conditionals.

@item
A patch for the bug.

A patch for the bug is useful if it is a good one.  But don't omit the
necessary information, such as the test case, on the assumption that a
patch is all we need.  We might see problems with your patch and decide
to fix the problem another way, or we might not understand it at all.

Sometimes with a program as complicated as GNU Fortran it is very hard to
construct an example that will make the program follow a certain path
through the code.  If you don't send the example, we won't be able to
construct one, so we won't be able to verify that the bug is fixed.

And if we can't understand what bug you are trying to fix, or why your
patch should be an improvement, we won't install it.  A test case will
help us to understand.

@xref{Sending Patches}, for guidelines on how to make it easy for us to
understand and install your patches.

@item
A guess about what the bug is or what it depends on.

Such guesses are usually wrong.  Even the maintainer can't guess right
about such things without first using the debugger to find the facts.

@item
A core dump file.

We have no way of examining a core dump for your type of machine
unless we have an identical system---and if we do have one,
we should be able to reproduce the crash ourselves.
@end itemize

@node Sending Patches,, Bug Reporting, Bugs
@section Sending Patches for GNU Fortran

If you would like to write bug fixes or improvements for the GNU Fortran
compiler, that is very helpful.
Send suggested fixes to the bug report
mailing list, @code{fortran@@gnu.ai.mit.edu}.

Please follow these guidelines so we can study your patches efficiently.
If you don't follow these guidelines, your information might still be
useful, but using it will take extra work.  Maintaining GNU Fortran is a lot
of work in the best of circumstances, and we can't keep up unless you do
your best to help.

@itemize @bullet
@item
Send an explanation with your changes of what problem they fix or what
improvement they bring about.  For a bug fix, just include a copy of the
bug report, and explain why the change fixes the bug.

(Referring to a bug report is not as good as including it, because then
we will have to look it up, and we have probably already deleted it if
we've already fixed the bug.)

@item
Always include a proper bug report for the problem you think you have
fixed.  We need to convince ourselves that the change is right before
installing it.  Even if it is right, we might have trouble judging it if
we don't have a way to reproduce the problem.

@item
Include all the comments that are appropriate to help people reading the
source in the future understand why this change was needed.

@item
Don't mix together changes made for different reasons.
Send them @emph{individually}.

If you make two changes for separate reasons, then we might not want to
install them both.  We might want to install just one.  If you send them
all jumbled together in a single set of diffs, we have to do extra work
to disentangle them---to figure out which parts of the change serve
which purpose.  If we don't have time for this, we might have to ignore
your changes entirely.

If you send each change as soon as you have written it, with its own
explanation, then the two changes never get tangled up, and we can
consider each one properly without any extra work to disentangle them.

Ideally, each change you send should be impossible to subdivide into
parts that we might want to consider separately, because each of its
parts gets its motivation from the other parts.

@item
Send each change as soon as that change is finished.  Sometimes people
think they are helping us by accumulating many changes to send them all
together.  As explained above, this is absolutely the worst thing you
could do.

Since you should send each change separately, you might as well send it
right away.  That gives us the option of installing it immediately if it
is important.

@item
Use @samp{diff -c} to make your diffs.  Diffs without context are hard
for us to install reliably.  More than that, they make it hard for us to
study the diffs to decide whether we want to install them.  Unidiff
format is better than contextless diffs, but not as easy to read as
@samp{-c} format.

If you have GNU diff, use @samp{diff -cp}, which shows the name of the
function that each change occurs in.
(The maintainer of GNU Fortran currently uses @samp{diff -rcp2N}.)

@item
Write the change log entries for your changes.  We get lots of changes,
and we don't have time to do all the change log writing ourselves.

Read the @file{ChangeLog} file to see what sorts of information to put
in, and to learn the style that we use.  The purpose of the change log
is to show people where to find what was changed.  So you need to be
specific about what functions you changed; in large functions, it's
often helpful to indicate where within the function the change was.

On the other hand, once you have shown people where to find the change,
you need not explain its purpose.  Thus, if you add a new function, all
you need to say about it is that it is new.  If you feel that the
purpose needs explaining, it probably does---but the explanation will be
much more useful if you put it in comments in the code.

If you would like your name to appear in the header line for who made
the change, send us the header line.

@item
When you write the fix, keep in mind that we can't install a change that
would break other systems.

People often suggest fixing a problem by changing machine-independent
files such as @file{toplev.c} to do something special that a particular
system needs.  Sometimes it is totally obvious that such changes would
break GNU Fortran for almost all users.  We can't possibly make a change like
that.  At best it might tell us how to write another patch that would
solve the problem acceptably.

Sometimes people send fixes that @emph{might} be an improvement in
general---but it is hard to be sure of this.  It's hard to install
such changes because we have to study them very carefully.  Of course,
a good explanation of the reasoning by which you concluded the change
was correct can help convince us.

The safest changes are changes to the configuration files for a
particular machine.  These are safe because they can't create new bugs
on other machines.

Please help us keep up with the workload by designing the patch in a
form that is good to install.
@end itemize

@node Service
@chapter How To Get Help with GNU Fortran

If you need help installing, using or changing GNU Fortran, there are two
ways to find it:

@itemize @bullet
@item
Look in the service directory for someone who might help you for a fee.
The service directory is found in the file named @file{SERVICE} in the
GNU CC distribution.

@item
Send a message to @code{fortran@@gnu.ai.mit.edu}.
@end itemize

@end ifset
@ifset INTERNALS
@node Adding Options
@chapter Adding Options
@cindex options, adding
@cindex adding options

To add a new command-line option to @code{g77}, first decide
what kind of option you wish to add.
Search the @code{g77} and @code{gcc} documentation for one
or more options that is most closely like the one you want to add
(in terms of what kind of effect it has, and so on) to
help clarify its nature.

@itemize @bullet
@item
@emph{Fortran options} are options that apply only
when compiling Fortran programs.
They are accepted by @code{g77} and @code{gcc}, but
they apply only when compiling Fortran programs.

@item
@emph{Compiler options} are options that apply
when compiling most any kind of program.
@end itemize

@emph{Fortran options} are listed in the file
@file{gcc/f/lang-options.h},
which is used during the build of @code{gcc} to
build a list of all options that are accepted by
at least one language's compiler.
This list goes into the @samp{lang_options} array
in @file{gcc/toplev.c}, which uses this array to
determine whether a particular option should be
offered to the linked-in front end for processing
by calling @samp{lang_option_decode}, which, for
@code{g77}, is in @file{gcc/f/com.c} and just
calls @samp{ffe_decode_option}.

If the linked-in front end ``rejects'' a
particular option passed to it, @file{toplev.c}
just ignores the option, because @emph{some}
language's compiler is willing to accept it.

This allows commands like @samp{gcc -fno-asm foo.c bar.f}
to work, even though Fortran compilation does
not currently support the @samp{-fno-asm} option;
even though the @code{f771} version of @samp{lang_decode_option}
rejects @samp{-fno-asm}, @file{toplev.c} doesn't
produce a diagnostic because some other language (C)
does accept it.

This also means that commands like
@samp{g77 -fno-asm foo.f} yield no diagnostics,
despite the fact that no phase of the command was
able to recognize and process @samp{-fno-asm}---perhaps
a warning about this would be helpful if it were
possible.

Code that processes Fortran options is found in
@file{gcc/f/top.c}, function @samp{ffe_decode_option}.
This code needs to check positive and negative forms
of each option.

The defaults for Fortran options are set in their
global definitions, also found in @file{gcc/f/top.c}.
Many of these defaults are actually macros defined
in @file{gcc/f/target.h}, since they might be
machine-specific.
However, since, in practice, GNU compilers
should behave the same way on all configurations
(especially when it comes to language constructs),
the practice of setting defaults in @file{target.h}
is likely to be deprecated and, ultimately, stopped
in future versions of @code{g77}.

Accessor macros for Fortran options, used by code
in the @code{g77} FFE, are defined in @file{gcc/f/top.h}.

@emph{Compiler options} are listed in @file{gcc/toplev.c}
in the array @samp{f_options}.
An option not listed in @samp{lang_options} is
looked up in @samp{f_options} and handled from there.

The defaults for compiler options are set in the
global definitions for the corresponding variables,
some of which are in @file{gcc/toplev.c}.

You can set different defaults for @emph{Fortran-oriented}
or @emph{Fortran-reticent} compiler options by changing
the way @code{f771} handles the @samp{-fset-g77-defaults}
option, which is always provided as the first option when
called by @code{g77} or @code{gcc}.

This code is in @samp{ffe_decode_options} in @file{gcc/f/top.c}.
Have it change just the variables that you want to default
to a different setting for Fortran compiles compared to
compiles of other languages.

The @samp{-fset-g77-defaults} option is passed to @code{f771}
automatically because of the specification information
kept in @file{gcc/f/lang-specs.h}.
This file tells the @code{gcc} command how to recognize,
in this case, Fortran source files (those to be preprocessed,
and those that are not), and further, how to invoke the
appropriate programs (including @code{f771}) to process
those source files.

It is in @file{gcc/f/lang-specs.h} that @samp{-fset-g77-defaults},
@samp{-fversion}, and other options are passed, as appropriate,
even when the user has not explicitly specified them.
Other ``internal'' options such as @samp{-quiet} also
are passed via this mechanism.

@node Projects
@chapter Projects
@cindex projects

If you want to contribute to @code{g77} by doing research,
design, specification, documentation, coding, or testing,
the following information should give you some ideas.

@menu
* Efficiency::               Make @code{g77} itself compile code faster.
* Better Optimization::      Teach @code{g77} to generate faster code.
* Simplify Porting::         Make @code{g77} easier to configure, build,
                             and install.
* More Extensions::          Features many users won't know to ask for.
* Machine Model::            @code{g77} should better leverage @code{gcc}.
* Internals Documentation::  Make maintenance easier.
* Internals Improvements::   Make internals more robust.
* Better Diagnostics::       Make using @code{g77} on new code easier.
@end menu

@node Efficiency
@section Improve Efficiency
@cindex efficiency

Don't bother doing any performance analysis until most of the
following items are taken care of, because there's no question
they represent serious space/time problems, although some of
them show up only given certain kinds of (popular) input.

@itemize @bullet
@item
Improve @samp{malloc} package and its uses to specify more info about
memory pools and, where feasible, use obstacks to implement them.

@item
Skip over uninitialized portions of aggregate areas (arrays,
@samp{COMMON} areas, @samp{EQUIVALENCE} areas) so zeros need not be output.
This would reduce memory usage for large initialized aggregate
areas, even ones with only one initialized element.

As of version 0.5.18, a portion of this item has already been
accomplished.

@item
Prescan the statement (in @file{sta.c}) so that the nature of the statement
is determined as much as possible by looking entirely at its form,
and not looking at any context (previous statements, including types
of symbols).
This would allow ripping out of the statement-confirmation,
symbol retraction/confirmation, and diagnostic inhibition
mechanisms.
Plus, it would result in much-improved diagnostics.
For example, @samp{CALL some-intrinsic(...)}, where the intrinsic
is not a subroutine intrinsic, would result actual error instead of the
unimplemented-statement catch-all.

@item
Throughout @code{g77}, don't pass line/column pairs where
a simple @samp{ffewhere} type, which points to the error as much as is
desired by the configuration, will do, and don't pass @samp{ffelexToken} types
where a simple @samp{ffewhere} type will do.
Then, allow new default
configuration of @samp{ffewhere} such that the source line text is not
preserved, and leave it to things like Emacs' next-error function
to point to them (now that @samp{next-error} supports column,
or, perhaps, character-offset, numbers).
The change in calling sequences should improve performance somewhat,
as should not having to save source lines.
(Whether this whole
item will improve performance is questionable, but it should
improve maintainability.)

@item
Handle @samp{DATA (A(I),I=1,1000000)/1000000*2/} more efficiently, especially
as regards the assembly output.
Some of this might require improving
the back end, but lots of improvement in space/time required in @code{g77}
itself can be fairly easily obtained without touching the back end.
Maybe type-conversion, where necessary, can be speeded up as well in
cases like the one shown (converting the @samp{2} into @samp{2.}).

@item
If analysis shows it to be worthwhile, optimize @samp{lex.c}.

@item
Consider redesigning @file{lex.c} to not need any feedback
during tokenization, by keeping track of enough parse state on its
own.
@end itemize

@node Better Optimization
@section Better Optimization
@cindex optimization, better
@cindex code generation, improving

Much of this work should be put off until after @code{g77} has
all the features necessary for its widespread acceptance as a
useful F77 compiler.
However, perhaps this work can be done in parallel during
the feature-adding work.

@itemize @bullet
@item
Get the back end to produce at least as good code involving array
references as does @code{f2c} plus @code{gcc}.
(@emph{Note:} 0.5.18, with its improvements to the GBE for
versions 2.7.1 and 2.7.2 of @code{gcc}, should succeed at
doing this.
Please submit any cases where @code{g77} cannot be made to
generate as optimal code as @code{f2c} in combination with
the same version of @code{gcc}, but only for versions 2.7.1 and
greater of @code{gcc}.)

@item
Do the equivalent of the trick of putting @samp{extern inline} in front
of every function definition in @code{libf2c} and #include'ing the resulting
file in @code{f2c}+@code{gcc}---that is, inline all run-time-library functions
that are at all worth inlining.
(Some of this has already been done, such as for integral exponentiation.)

@item
When doing @samp{CHAR_VAR = CHAR_FUNC(@dots{})},
and it's clear that types line up
and @samp{CHAR_VAR} is addressable or not a @samp{VAR_DECL},
make @samp{CHAR_VAR}, not a
temporary, be the receiver for @samp{CHAR_FUNC}.
(This is now done for @samp{COMPLEX} variables.)

@item
Design and implement Fortran-specific optimizations that don't
really belong in the back end, or where the front end needs to
give the back end more info than it currently does.

@item
Design and implement a new run-time library interface, with the
code going into @code{libgcc} so no special linking is required to
link Fortran programs using standard language features.
This library
would speed up lots of things, from I/O (using precompiled formats,
doing just one, or, at most, very few, calls for arrays or array sections,
and so on) to general computing (array/section implementations of
various intrinsics, implementation of commonly performed loops that
aren't likely to be optimally compiled otherwise, etc.).

Among
the important things the library would do are:

@itemize @bullet
@item
Be a one-stop-shop-type
library, hence shareable and usable by all, in that what are now
library-build-time options in @code{libf2c} would be moved at least to the
@code{g77} compile phase, if not to finer grains (such as choosing how
list-directed I/O formatting is done by default at @samp{OPEN} time, for
preconnected units via options or even statements in the main program
unit, maybe even on a per-I/O basis with appropriate pragma-like
devices).
@end itemize

@item
Probably requiring the new library design, change interface to
normally have @samp{COMPLEX} functions return their values in the way
@code{gcc} would if they were declared @samp{__complex__ float},
rather than using
the mechanism currently used by @samp{CHARACTER} functions (whereby the
functions are compiled as returning void and their first arg is
a pointer to where to store the result).
(Don't append underscores to
external names for @samp{COMPLEX} functions in some cases once @code{g77} uses
@code{gcc} rather than @code{f2c} calling conventions.)

@item
Do something useful with @samp{doiter} references where possible.
For example, @samp{CALL FOO(I)} cannot modify @samp{I} if within
a @samp{DO} loop that uses @samp{I} as the
iteration variable, and the back end might find that info useful
in determining whether it needs to read @samp{I} back into a register after
the call.
(It normally has to do that, unless it knows @samp{FOO} never
modifies its passed-by-reference argument, which is rarely the case
for Fortran-77 code.)
@end itemize

@node Simplify Porting
@section Simplify Porting
@cindex porting, simplify
@cindex simplify porting

Making @code{g77} easier to configure, port, build, and install, either
as a single-system compiler or as a cross-compiler, would be
very useful.

@itemize @bullet
@item
A new library (replacing @code{libf2c}) should improve portability as well as
produce more optimal code.
Further, @code{g77} and the new library should
conspire to simplify naming of externals, such as by removing unnecessarily
added underscores, and to reduce/eliminate the possibility of naming
conflicts, while making debugger more straightforward.

Also, it should
make multi-language applications more feasible, such as by providing
Fortran intrinsics that get Fortran unit numbers given C @samp{FILE *}
descriptors.

@item
Possibly related to a new library, @code{g77} should produce the equivalent
of a @code{gcc} @samp{main(argc, argv)} function when it compiles a
main program unit, instead of compiling something that must be
called by a library
implementation of @samp{main()}.

This would do many useful things such as
provide more flexibility in terms of setting up exception handling,
not requiring programmers to start their debugging sessions with
@kbd{breakpoint MAIN__} followed by @kbd{run}, and so on.

@item
The GBE needs to understand the difference between alignment
requirements and desires.
For example, on Intel x86 machines, @code{g77} currently imposes
overly strict alignment requirements, due to the back end, but it
would be useful for Fortran and C programmers to be able to override
these @emph{recommendations} as long as they don't violate the actual
processor @emph{requirements}.
@end itemize

@node More Extensions
@section More Extensions
@cindex extensions, more

These extensions are not the sort of things users ask for ``by name'',
but they might improve the usability of @code{g77}, and Fortran in
general, in the long run.
Some of these items really pertain to improving @code{g77} internals
so that some popular extensions can be more easily supported.

@itemize @bullet
@item
Consider adding a @samp{NUMERIC} type to designate typeless numeric constants,
named and unnamed.
The idea is to provide a forward-looking, effective
replacement for things like the old-style @samp{PARAMETER} statement
when people
really need typelessness in a maintainable, portable, clearly documented
way.
Maybe @samp{TYPELESS} would include @samp{CHARACTER}, @samp{POINTER},
and whatever else might come along.
(This is not really a call for polymorphism per se, just
an ability to express limited, syntactic polymorphism.)

@item
Support @samp{OPEN(...,KEY=(...),...)}.

@item
@samp{OPEN(NOSPANBLOCKS,@dots{})} is treated as
@samp{OPEN(UNIT=NOSPANBLOCKS,@dots{})}, so a
later @samp{UNIT=} in the first example is invalid.
Make sure this is what users of this feature would expect.

@item
Currently @code{g77} disallows @samp{READ(1'10)} since
it is an obnoxious syntax, but
supporting it might be pretty easy if needed.
More details are needed, such
as whether general expressions separated by an apostrophe are supported,
or maybe the record number can be a general expression, and so on.

@item
Support @samp{STRUCTURE}, @samp{UNION}, @samp{MAP}, and @samp{RECORD}
fully.
Currently there is no support at all
for @samp{%FILL} in @samp{STRUCTURE} and related syntax,
whereas the rest of the
stuff has at least some parsing support.
This requires either major
changes to @code{libf2c} or its replacement.

@item
F90 and @code{g77} probably disagree about label scoping relative to
@samp{INTERFACE} and @samp{END INTERFACE}, and their contained
procedure interface bodies (blocks?).

@item
@samp{ENTRY} doesn't support F90 @samp{RESULT()} yet,
since that was added after S8.112.

@item
Empty-statement handling (10 ;;CONTINUE;;) probably isn't consistent
with the final form of the standard (it was vague at S8.112).

@item
It seems to be an ``open'' question whether a file, immediately after being
@samp{OPEN}ed,is positioned at the beginning, the end, or wherever---it
might be nice to offer an option of opening to ``undefined'' status, requiring
an explicit absolute-positioning operation to be performed before any
other (besides @samp{CLOSE}) to assist in making applications port to systems
(some IBM?) that @samp{OPEN} to the end of a file or some such thing.
@end itemize

@node Machine Model
@section Machine Model

This items pertain to generalizing @code{g77}'s view of
the machine model to more fully accept whatever the GBE
provides it via its configuration.

@itemize @bullet
@item
Switch to using @samp{REAL_VALUE_TYPE} to represent floating-point constants
exclusively so the target float format need not be required.
This
means changing the way @code{g77} handles initialization of aggregate areas
having more than one type, such as @samp{REAL} and @samp{INTEGER},
because currently
it initializes them as if they were arrays of @samp{char} and uses the
bit patterns of the constants of the various types in them to determine
what to stuff in elements of the arrays.

@item
Rely more and more on back-end info and capabilities, especially in the
area of constants (where having the @code{g77} front-end's IL just store
the appropriate tree nodes containing constants might be best).

@item
Suite of C and Fortran programs that a user/administrator can run on a
machine to help determine the configuration for @code{g77} before building
and help determine if the compiler works (especially with whatever
libraries are installed) after building.
@end itemize

@node Internals Documentation
@section Internals Documentation

Better info on how @code{g77} works and how to port it is needed.

@node Internals Improvements
@section Internals Improvements

Some more items that would make @code{g77} more reliable
and easier to maintain:

@itemize @bullet
@item
Generally make expression handling focus
more on critical syntax stuff, leaving semantics to callers.
For example,
anything a caller can check, semantically, let it do so, rather
than having @file{expr.c} do it.
(Exceptions might include things like
diagnosing @samp{FOO(I--K:)=BAR} where @samp{FOO} is a @samp{PARAMETER}---if
it seems
important to preserve the left-to-right-in-source order of production
of diagnostics.)

@item
Come up with better naming conventions for @samp{-D} to establish requirements
to achieve desired implementation dialect via @file{proj.h}.

@item
Clean up used tokens and @samp{ffewhere}s in @samp{ffeglobal_terminate_1}.

@item
Replace @file{sta.c} @samp{outpooldisp} mechanism with @samp{malloc_pool_use}.

@item
Check for @samp{opANY} in more places in @file{com.c}, @file{std.c},
and @file{ste.c}, and get rid of the @samp{opCONVERT(opANY)} kludge
(after determining if there is indeed no real need for it).

@item
Utility to read and check @file{bad.def} messages and their references in the
code, to make sure calls are consistent with message templates.

@item
Search and fix @samp{&ffe@dots{}} and similar so that
@samp{ffe@dots{}ptr@dots{}} macros are
available instead (a good argument for wishing this could have written all
this stuff in C++, perhaps).
On the other hand, it's questionable whether this sort of
improvement is really necessary, given the availability of
tools such as Emacs and perl, which making finding any
address-taking of structure members easy enough?

@item
Some modules truly export the member names of their structures (and the
structures themselves), maybe fix this, and fix other modules that just
appear to as well (by appending @samp{_}, though it'd be ugly and probably
not worth the time).

@item
Implement C macros @samp{RETURNS(value)} and @samp{SETS(something,value)}
in @file{proj.h}
and use them throughout @code{g77} source code (especially in the definitions
of access macros in @samp{.h} files) so they can be tailored
to catch code writing into a @samp{RETURNS()} or reading from a @samp{SETS()}.

@item
Decorate throughout with @samp{const} and other such stuff.

@item
All F90 notational derivations in the source code are still based
on the S8.112 version of the draft standard.
Probably should update
to the official standard, or put documentation of the rules as used
in the code...uh...in the code.

@item
Some @samp{ffebld_new} calls (those outside of @file{ffeexpr.c} or
inside but invoked via paths not involving @samp{ffeexpr_lhs} or
@samp{ffeexpr_rhs}) might be creating things
in improper pools, leading to such things staying around too long or
(doubtful, but possible and dangerous) not long enough.

@item
Some @samp{ffebld_list_new} (or whatever) calls might not be matched by
@samp{ffebld_list_bottom} (or whatever) calls, which might someday matter.
(It definitely is not a problem just yet.)

@item
Probably not doing clean things when we fail to @samp{EQUIVALENCE} something
due to alignment/mismatch or other problems---they end up without
@samp{ffestorag} objects, so maybe the backend (and other parts of the front
end) can notice that and handle like an @samp{opANY} (do what it wants, just
don't complain or crash).
Most of this seems to have been addressed
by now, but a code review wouldn't hurt.
@end itemize

@node Better Diagnostics
@section Better Diagnostics

These are things users might not ask about, or that need to
be looked into, before worrying about.
Also here are items that involve reducing unnecessary diagnostic
clutter.

@itemize @bullet
@item
Implement non-F90 messages (especially avoid mentioning F90 things @code{g77}
doesn't yet support).
Much of this has been done as of 0.5.14.

@item
When @samp{FUNCTION} and @samp{ENTRY} point types disagree (@samp{CHARACTER}
lengths, type classes, and so on),
@samp{ANY}-ize the offending @samp{ENTRY} point and any @emph{new} dummies
it specifies.

@item
Speed up and improve error handling for data when repeat-count is
specified.
For example, don't output 20 unnecessary messages after the
first necessary one for:

@example
INTEGER X(20)
CONTINUE
DATA (X(I), J= 1, 20) /20*5/
END
@end example

(The @samp{CONTINUE} statement ensures the @samp{DATA} statement
is processed in the context of executable, not specification,
statements.)
@end itemize
@end ifset

@node Index
@unnumbered Index

@printindex cp
@summarycontents
@contents
@bye