+++ /dev/null
-This is g77.info, produced by makeinfo version 4.5 from g77.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* g77: (g77). The GNU Fortran compiler.
-END-INFO-DIR-ENTRY
- This file documents the use and the internals of the GNU Fortran
-(`g77') compiler. It corresponds to the GCC-3.2.3 version of `g77'.
-
- Published by the Free Software Foundation 59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1995,1996,1997,1998,1999,2000,2001,2002 Free Software
-Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
- Contributed by James Craig Burley (<craig@jcb-sc.com>). Inspired by
-a first pass at translating `g77-0.5.16/f/DOC' that was contributed to
-Craig by David Ronis (<ronis@onsager.chem.mcgill.ca>).
-
-\1f
-File: g77.info, Node: Multiple Definitions of External Names, Next: Limitation on Implicit Declarations, Prev: Mangling of Names, Up: Disappointments
-
-Multiple Definitions of External Names
---------------------------------------
-
- `g77' doesn't allow a common block and an external procedure or
-`BLOCK DATA' to have the same name. Some systems allow this, but `g77'
-does not, to be compatible with `f2c'.
-
- `g77' could special-case the way it handles `BLOCK DATA', since it
-is not compatible with `f2c' in this particular area (necessarily,
-since `g77' offers an important feature here), but it is likely that
-such special-casing would be very annoying to people with programs that
-use `EXTERNAL FOO', with no other mention of `FOO' in the same program
-unit, to refer to external procedures, since the result would be that
-`g77' would treat these references as requests to force-load BLOCK DATA
-program units.
-
- In that case, if `g77' modified names of `BLOCK DATA' so they could
-have the same names as `COMMON', users would find that their programs
-wouldn't link because the `FOO' procedure didn't have its name
-translated the same way.
-
- (Strictly speaking, `g77' could emit a
-null-but-externally-satisfying definition of `FOO' with its name
-transformed as if it had been a `BLOCK DATA', but that probably invites
-more trouble than it's worth.)
-
-\1f
-File: g77.info, Node: Limitation on Implicit Declarations, Prev: Multiple Definitions of External Names, Up: Disappointments
-
-Limitation on Implicit Declarations
------------------------------------
-
- `g77' disallows `IMPLICIT CHARACTER*(*)'. This is not
-standard-conforming.
-
-\1f
-File: g77.info, Node: Non-bugs, Next: Warnings and Errors, Prev: Disappointments, Up: Trouble
-
-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 `'\\'' is a constant that
- is one, not two, characters long.
-* Initializing Before Specifying:: Why `DATA VAR/1/' can't precede
- `COMMON VAR'.
-* Context-Sensitive Intrinsicness:: Why `CALL SQRT' won't work.
-* Context-Sensitive Constants:: Why `9.435784839284958' is a
- single-precision constant,
- and might be interpreted as
- `9.435785' or similar.
-* Equivalence Versus Equality:: Why `.TRUE. .EQ. .TRUE.' won't work.
-* Order of Side Effects:: Why `J = IFUNC() - IFUNC()' might
- not behave as expected.
-
-\1f
-File: g77.info, Node: Backslash in Constants, Next: Initializing Before Specifying, Up: Non-bugs
-
-Backslash in Constants
-----------------------
-
- In the opinion of many experienced Fortran users, `-fno-backslash'
-should be the default, not `-fbackslash', as currently set by `g77'.
-
- First of all, you can always specify `-fno-backslash' to turn off
-this processing.
-
- Despite not being within the spirit (though apparently within the
-letter) of the ANSI FORTRAN 77 standard, `g77' defaults to
-`-fbackslash' because that is what most UNIX `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 `-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 `-fno-backslash' the default for GNU Fortran and thus require
-users of UNIX `f77' and `f2c' to specify `-fbackslash' to get the UNIX
-behavior.
-
- However, the realization that `g77' is intended as a replacement for
-_UNIX_ `f77', caused the author to choose to make `g77' as compatible
-with `f77' as feasible, which meant making `-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 `f77' to
-do, by default?" Although at least one UNIX `f77' does not provide
-`-fbackslash' as a default, it appears that the majority of them do,
-which suggests that the majority of code that is compiled by UNIX `f77'
-compilers expects `-fbackslash' to be the default.
-
- It is probably the case that more code exists that would _not_ work
-with `-fbackslash' in force than code that requires it be in force.
-
- However, most of _that_ code is not being compiled with `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 `g77''s default of `-fbackslash' than would exist
-for the majority of UNIX `f77' users who would have to modify existing,
-working build procedures to explicitly specify `-fbackslash' if that was
-not the default.
-
- One suggestion has been to configure the default for `-fbackslash'
-(and perhaps other options as well) based on the configuration of `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 `gcc'. To change them for `g77', you must
-first change them for `gcc'. Do not ask the maintainers of `g77' to do
-this for you, or to disassociate `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). *Note Direction of
-Language Development::, for more information on this overall philosophy
-guiding the development of the GNU Fortran language.
-
- 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 (`\')
-being interpreted either way in particular, such as by starting a
-program unit with:
-
- CHARACTER BACKSL
- PARAMETER (BACKSL = '\\')
-
-Then, use concatenation of `BACKSL' anyplace a backslash is desired.
-In this way, users can write programs which have the same meaning in
-many Fortran dialects.
-
- (However, this technique does not work for Hollerith constants--which
-is just as well, since the only generally portable uses for Hollerith
-constants are in places where character constants can and should be
-used instead, for readability.)
-
-\1f
-File: g77.info, Node: Initializing Before Specifying, Next: Context-Sensitive Intrinsicness, Prev: Backslash in Constants, Up: Non-bugs
-
-Initializing Before Specifying
-------------------------------
-
- `g77' does not allow `DATA VAR/1/' to appear in the source code
-before `COMMON VAR', `DIMENSION VAR(10)', `INTEGER VAR', and so on. In
-general, `g77' requires initialization of a variable or array to be
-specified _after_ all other specifications of attributes (type, size,
-placement, and so on) of that variable or array are specified (though
-_confirmation_ of data type is permitted).
-
- It is _possible_ `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 `g77' always require
-placement of `DATA' so that it can possibly immediately write constants
-to the output file, thus saving time and space.
-
- That is, `DATA A/1000000*1/' should perhaps always be immediately
-writable to canonical assembler, unless it's already known to be in a
-`COMMON' area following as-yet-uninitialized stuff, and to do this it
-cannot be followed by `COMMON A'.
-
-\1f
-File: g77.info, Node: Context-Sensitive Intrinsicness, Next: Context-Sensitive Constants, Prev: Initializing Before Specifying, Up: Non-bugs
-
-Context-Sensitive Intrinsicness
--------------------------------
-
- `g77' treats procedure references to _possible_ intrinsic names as
-always enabling their intrinsic nature, regardless of whether the
-_form_ of the reference is valid for that intrinsic.
-
- For example, `CALL SQRT' is interpreted by `g77' as an invalid
-reference to the `SQRT' intrinsic function, because the reference is a
-subroutine invocation.
-
- First, `g77' recognizes the statement `CALL SQRT' as a reference to
-a _procedure_ named `SQRT', not to a _variable_ with that name (as it
-would for a statement such as `V = SQRT').
-
- Next, `g77' establishes that, in the program unit being compiled,
-`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, `EXTERNAL
-SQRT' was present).
-
- Finally, `g77' recognizes that the _form_ of the reference is
-invalid for that particular intrinsic. That is, it recognizes that it
-is invalid for an intrinsic _function_, such as `SQRT', to be invoked as
-a _subroutine_.
-
- At that point, `g77' issues a diagnostic.
-
- Some users claim that it is "obvious" that `CALL SQRT' references an
-external subroutine of their own, not an intrinsic function.
-
- However, `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, `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 `EXTERNAL SQRT' statement in a program unit that calls a
-user-written subroutine named `SQRT'.
-
-\1f
-File: g77.info, Node: Context-Sensitive Constants, Next: Equivalence Versus Equality, Prev: Context-Sensitive Intrinsicness, Up: Non-bugs
-
-Context-Sensitive Constants
----------------------------
-
- `g77' does not use context to determine the types of constants or
-named constants (`PARAMETER'), except for (non-standard) typeless
-constants such as `'123'O'.
-
- For example, consider the following statement:
-
- PRINT *, 9.435784839284958 * 2D0
-
-`g77' will interpret the (truncated) constant `9.435784839284958' as a
-`REAL(KIND=1)', not `REAL(KIND=2)', constant, because the suffix `D0'
-is not specified.
-
- As a result, the output of the above statement when compiled by
-`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
-_explicitly_ specified as a double-precision constant. (This has the
-effect of appending _decimal_, not _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:
-
- 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
-
-Running the above program should result in the same value being printed
-three times. With `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 `5.000000000001', which on most systems is
-exactly equal to `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 (`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. `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 `g77' can do to help flag cases of this
-in such code could be very helpful.
-
-\1f
-File: g77.info, Node: Equivalence Versus Equality, Next: Order of Side Effects, Prev: Context-Sensitive Constants, Up: Non-bugs
-
-Equivalence Versus Equality
----------------------------
-
- Use of `.EQ.' and `.NE.' on `LOGICAL' operands is not supported,
-except via `-fugly-logint', which is not recommended except for legacy
-code (where the behavior expected by the _code_ is assumed).
-
- Legacy code should be changed, as resources permit, to use `.EQV.'
-and `.NEQV.' instead, as these are permitted by the various Fortran
-standards.
-
- New code should never be written expecting `.EQ.' or `.NE.' to work
-if either of its operands is `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:
-
- LOGICAL L,M,N
- DATA L,M,N /3*.FALSE./
- IF (L.AND.M.EQ.N) PRINT *,'L.AND.M.EQ.N'
- END
-
- The issue raised by the above sample program is: what is the
-precedence of `.EQ.' (and `.NE.') when applied to `LOGICAL' operands?
-
- Some programmers will argue that it is the same as the precedence
-for `.EQ.' when applied to numeric (such as `INTEGER') operands. By
-this interpretation, the subexpression `M.EQ.N' must be evaluated first
-in the above program, resulting in a program that, when run, does not
-execute the `PRINT' statement.
-
- Other programmers will argue that the precedence is the same as the
-precedence for `.EQV.', which is restricted by the standards to
-`LOGICAL' operands. By this interpretation, the subexpression
-`L.AND.M' must be evaluated first, resulting in a program that _does_
-execute the `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 `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. `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 `(a)
-& (b)' and `(a) - (b)'--they cannot even tell you, without knowing more
-context, whether the `&' and `-' operators are infix (binary) or unary!)
-
- Most dangerous of all is the fact that, even assuming consensus on
-its meaning, an expression like `L.AND.M.EQ.N', if it is the result of
-a typographical error, doesn't _look_ like it has such a typo. Even
-experienced Fortran programmers would not likely notice that
-`L.AND.M.EQV.N' was, in fact, intended.
-
- So, this is a prime example of a circumstance in which a quality
-compiler diagnoses the code, instead of leaving it up to someone
-debugging it to know to turn on special compiler options that might
-diagnose it.
-
-\1f
-File: g77.info, Node: Order of Side Effects, Prev: Equivalence Versus Equality, Up: Non-bugs
-
-Order of Side Effects
----------------------
-
- `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 `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:
-
- J = IFUNC() - IFUNC()
-
-There is no guarantee that `IFUNC' will be evaluated in any particular
-order. Either invocation might happen first. If `IFUNC' returns 5 the
-first time it is invoked, and returns 12 the second time, `J' might end
-up with the value `7', or it might end up with `-7'.
-
- Generally, in Fortran, procedures with side-effects intended to be
-visible to the caller are best designed as _subroutines_, not functions.
-Examples of such side-effects include:
-
- * The generation of random numbers that are intended to influence
- return values.
-
- * Performing I/O (other than internal I/O to local variables).
-
- * Updating information in common blocks.
-
- 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).
-
-\1f
-File: g77.info, Node: Warnings and Errors, Prev: Non-bugs, Up: Trouble
-
-Warning Messages and Error Messages
-===================================
-
- The GNU compiler can produce two kinds of diagnostics: errors and
-warnings. Each kind has a different purpose:
-
- _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.
-
- _Warnings_ report other unusual conditions in your code that
- _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 `warning:' to
- distinguish them from error messages.
-
- 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 `-W'
-options (for instance, `-Wall' requests a variety of useful warnings).
-
- _Note:_ Currently, the text of the line and a pointer to the column
-is printed in most `g77' diagnostics.
-
- *Note Options to Request or Suppress Warnings: Warning Options, for
-more detail on these and related command-line options.
-
-\1f
-File: g77.info, Node: Open Questions, Next: Bugs, Prev: Trouble, Up: Top
-
-Open Questions
-**************
-
- Please consider offering useful answers to these questions!
-
- * `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?
-
-\1f
-File: g77.info, Node: Bugs, Next: Service, Prev: Open Questions, Up: Top
-
-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. *Note 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 *Note 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.
-
- *Note Known Causes of Trouble with GNU Fortran: Trouble, for
-information on problems we already know about.
-
- *Note How To Get Help with GNU Fortran: Service, for information on
-where to ask for help.
-
-\1f
-File: g77.info, Node: Bug Criteria, Next: Bug Lists, Up: Bugs
-
-Have You Found a Bug?
-=====================
-
- If you are not sure whether you have found a bug, here are some
-guidelines:
-
- * If the compiler gets a fatal signal, for any input whatever, that
- is a compiler bug. Reliable compilers never crash--they just
- remain obsolete.
-
- * If the compiler produces invalid assembly code, for any input
- whatever, that is a compiler bug, unless the compiler reports
- errors (not just warnings) which would ordinarily prevent the
- assembler from being run.
-
- * 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. 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.
-
- * If the compiler produces an error message for valid input, that is
- a compiler bug.
-
- * 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".
-
- * If you are an experienced user of Fortran compilers, your
- suggestions for improvement of GNU Fortran are welcome in any case.
-
- Many, perhaps most, bug reports against `g77' turn out to be bugs in
-the user's code. While we find such bug reports educational, they
-sometimes take a considerable amount of time to track down or at least
-respond to--time we could be spending making `g77', not some user's
-code, better.
-
- Some steps you can take to verify that the bug is not certainly in
-the code you're compiling with `g77':
-
- * Compile your code using the `g77' options `-W -Wall -O'. These
- options enable many useful warning; the `-O' option enables flow
- analysis that enables the uninitialized-variable warning.
-
- If you investigate the warnings and find evidence of possible bugs
- in your code, fix them first and retry `g77'.
-
- * Compile your code using the `g77' options `-finit-local-zero',
- `-fno-automatic', `-ffloat-store', and various combinations
- thereof.
-
- If your code works with any of these combinations, that is not
- proof that the bug isn't in `g77'--a `g77' bug exposed by your
- code might simply be avoided, or have a different, more subtle
- effect, when different options are used--but it can be a strong
- indicator that your code is making unwarranted assumptions about
- the Fortran dialect and/or underlying machine it is being compiled
- and run on.
-
- *Note Overly Convenient Command-Line Options: Overly Convenient
- Options, for information on the `-fno-automatic' and
- `-finit-local-zero' options and how to convert their use into
- selective changes in your own code.
-
- * Validate your code with `ftnchek' or a similar code-checking tool.
- `ftnchek' can be found at `ftp://ftp.netlib.org/fortran' or
- `ftp://ftp.dsm.fordham.edu'.
-
- Here are some sample `Makefile' rules using `ftnchek' "project"
- files to do cross-file checking and `sfmakedepend' (from
- `ftp://ahab.rutgers.edu/pub/perl/sfmakedepend') to maintain
- dependencies automatically. These assume the use of GNU `make'.
-
- # Dummy suffix for ftnchek targets:
- .SUFFIXES: .chek
- .PHONY: chekall
-
- # How to compile .f files (for implicit rule):
- FC = g77
- # Assume `include' directory:
- FFLAGS = -Iinclude -g -O -Wall
-
- # Flags for ftnchek:
- CHEK1 = -array=0 -include=includes -noarray
- CHEK2 = -nonovice -usage=1 -notruncation
- CHEKFLAGS = $(CHEK1) $(CHEK2)
-
- # Run ftnchek with all the .prj files except the one corresponding
- # to the target's root:
- %.chek : %.f ; \
- ftnchek $(filter-out $*.prj,$(PRJS)) $(CHEKFLAGS) \
- -noextern -library $<
-
- # Derive a project file from a source file:
- %.prj : %.f ; \
- ftnchek $(CHEKFLAGS) -noextern -project -library $<
-
- # The list of objects is assumed to be in variable OBJS.
- # Sources corresponding to the objects:
- SRCS = $(OBJS:%.o=%.f)
- # ftnchek project files:
- PRJS = $(OBJS:%.o=%.prj)
-
- # Build the program
- prog: $(OBJS) ; \
- $(FC) -o $ $(OBJS)
-
- chekall: $(PRJS) ; \
- ftnchek $(CHEKFLAGS) $(PRJS)
-
- prjs: $(PRJS)
-
- # For Emacs M-x find-tag:
- TAGS: $(SRCS) ; \
- etags $(SRCS)
-
- # Rebuild dependencies:
- depend: ; \
- sfmakedepend -I $(PLTLIBDIR) -I includes -a prj $(SRCS1)
-
- * Try your code out using other Fortran compilers, such as `f2c'.
- If it does not work on at least one other compiler (assuming the
- compiler supports the features the code needs), that is a strong
- indicator of a bug in the code.
-
- However, even if your code works on many compilers _except_ `g77',
- that does _not_ mean the bug is in `g77'. It might mean the bug
- is in your code, and that `g77' simply exposes it more readily
- than other compilers.
-
-\1f
-File: g77.info, Node: Bug Lists, Next: Bug Reporting, Prev: Bug Criteria, Up: Bugs
-
-Where to Report Bugs
-====================
-
- Send bug reports for GNU Fortran to <gcc-bugs@gcc.gnu.org or
-bug-gcc@gnu.org>.
-
- 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:
-
- GNU Compiler Bugs
- Free Software Foundation
- 59 Temple Place - Suite 330
- Boston, MA 02111-1307, USA
-
-\1f
-File: g77.info, Node: Bug Reporting, Prev: Bug Lists, Up: Bugs
-
-How to Report Bugs
-==================
-
- The fundamental principle of reporting bugs usefully is this:
-*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 `uuencode'. If you do so it will slow down the processing of
-your bug. If you must submit multiple large files, use `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 `tar'
-archive, and, whether you need to do that, it is acceptable to then
-compress the single file (`tar' archive or source file) using `gzip'
-and encode it via `uuencode'. Do not use any MIME stuff--the current
-maintainer can't decode this. Using `compress' instead of `gzip' is
-acceptable, assuming you have licensed the use of the patented
-algorithm in `compress' from Unisys.)
-
- To enable someone to investigate the bug, you should include all
-these things:
-
- * The version of GNU Fortran. You can get this by running `g77'
- with the `-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.
-
- * A complete input file that will reproduce the bug.
-
- If your source file(s) require preprocessing (for example, their
- names have suffixes like `.F', `.fpp', `.FPP', and `.r'), and the
- bug is in the compiler proper (`f771') or in a subsequent phase of
- processing, run your source file through the C preprocessor by
- doing `g77 -E SOURCEFILE > NEWFILE'. Then, include the contents
- of NEWFILE in the bug report. (When you do this, use the same
- preprocessor options--such as `-I', `-D', and `-U'--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. 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 can depend on every little detail of the
- source and include files that trigger them.
-
- * Note that you should include with your bug report any files
- included by the source file (via the `#include' or `INCLUDE'
- directive) that you send, and any files they include, and so on.
-
- It is not necessary to replace the `#include' and `INCLUDE'
- directives 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 _reproduce_ the bug using the
- _exact_ version of the source material you submit, to avoid
- wild-goose chases.
-
- * The command arguments you gave GNU Fortran to compile that example
- and observe the bug. For example, did you use `-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.
-
- * The type of machine you are using, and the operating system name
- and version number. (Much of this information is printed by `g77
- -v'--if you include that, send along any additional info you have
- that you don't see clearly represented in that output.)
-
- * The operands you gave to the `configure' command when you installed
- the compiler.
-
- * 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.
-
- * Details of any other deviations from the standard procedure for
- installing GNU Fortran.
-
- * 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 _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 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.
-
- * If you send examples of assembler code output from GNU Fortran,
- please use `-g' when you make them. The debugging information
- includes source line numbers which are essential for correlating
- the output with the input.
-
- * 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.
-
- * 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.
-
- 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.
-
- 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 `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 `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.
-
- Here are some things that are not necessary:
-
- * 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 _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.
-
- * In particular, some people insert conditionals `#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.
-
- * 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.
-
- See `http://gcc.gnu.org/contribute.html' for guidelines on how to
- make it easy for us to understand and install your patches.
-
- * 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.
-
- * 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.
-
-\1f
-File: g77.info, Node: Service, Next: Adding Options, Prev: Bugs, Up: Top
-
-How To Get Help with GNU Fortran
-********************************
-
- If you need help installing, using or changing GNU Fortran, there
-are two ways to find it:
-
- * Look in the service directory for someone who might help you for a
- fee. The service directory is found in the file named `SERVICE'
- in the GNU CC distribution.
-
- * Send a message to <gcc-help@gcc.gnu.org>.
-
-\1f
-File: g77.info, Node: Adding Options, Next: Projects, Prev: Service, Up: Top
-
-Adding Options
-**************
-
- To add a new command-line option to `g77', first decide what kind of
-option you wish to add. Search the `g77' and `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.
-
- * _Fortran options_ are options that apply only when compiling
- Fortran programs. They are accepted by `g77' and `gcc', but they
- apply only when compiling Fortran programs.
-
- * _Compiler options_ are options that apply when compiling most any
- kind of program.
-
- _Fortran options_ are listed in the file `gcc/gcc/f/lang-options.h',
-which is used during the build of `gcc' to build a list of all options
-that are accepted by at least one language's compiler. This list goes
-into the `documented_lang_options' array in `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
-`lang_option_decode', which, for `g77', is in `gcc/gcc/f/com.c' and just
-calls `ffe_decode_option'.
-
- If the linked-in front end "rejects" a particular option passed to
-it, `toplev.c' just ignores the option, because _some_ language's
-compiler is willing to accept it.
-
- This allows commands like `gcc -fno-asm foo.c bar.f' to work, even
-though Fortran compilation does not currently support the `-fno-asm'
-option; even though the `f771' version of `lang_decode_option' rejects
-`-fno-asm', `toplev.c' doesn't produce a diagnostic because some other
-language (C) does accept it.
-
- This also means that commands like `g77 -fno-asm foo.f' yield no
-diagnostics, despite the fact that no phase of the command was able to
-recognize and process `-fno-asm'--perhaps a warning about this would be
-helpful if it were possible.
-
- Code that processes Fortran options is found in `gcc/gcc/f/top.c',
-function `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 `gcc/gcc/f/top.c'. Many of these defaults
-are actually macros defined in `gcc/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 `target.h' is
-likely to be deprecated and, ultimately, stopped in future versions of
-`g77'.
-
- Accessor macros for Fortran options, used by code in the `g77' FFE,
-are defined in `gcc/gcc/f/top.h'.
-
- _Compiler options_ are listed in `gcc/toplev.c' in the array
-`f_options'. An option not listed in `lang_options' is looked up in
-`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 `gcc/toplev.c'.
-
- You can set different defaults for _Fortran-oriented_ or
-_Fortran-reticent_ compiler options by changing the source code of
-`g77' and rebuilding. How to do this depends on the version of `g77':
-
-`G77 0.5.24 (EGCS 1.1)'
-`G77 0.5.25 (EGCS 1.2 - which became GCC 2.95)'
- Change the `lang_init_options' routine in `gcc/gcc/f/com.c'.
-
- (Note that these versions of `g77' perform internal consistency
- checking automatically when the `-fversion' option is specified.)
-
-`G77 0.5.23'
-`G77 0.5.24 (EGCS 1.0)'
- Change the way `f771' handles the `-fset-g77-defaults' option,
- which is always provided as the first option when called by `g77'
- or `gcc'.
-
- This code is in `ffe_decode_options' in `gcc/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 `-fset-g77-defaults' option is passed to `f771' automatically
- because of the specification information kept in
- `gcc/gcc/f/lang-specs.h'. This file tells the `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 `f771') to process those
- source files.
-
- It is in `gcc/gcc/f/lang-specs.h' that `-fset-g77-defaults',
- `-fversion', and other options are passed, as appropriate, even
- when the user has not explicitly specified them. Other "internal"
- options such as `-quiet' also are passed via this mechanism.
-
-\1f
-File: g77.info, Node: Projects, Next: Front End, Prev: Adding Options, Up: Top
-
-Projects
-********
-
- If you want to contribute to `g77' by doing research, design,
-specification, documentation, coding, or testing, the following
-information should give you some ideas. More relevant information
-might be available from `ftp://alpha.gnu.org/gnu/g77/projects/'.
-
-* Menu:
-
-* Efficiency:: Make `g77' itself compile code faster.
-* Better Optimization:: Teach `g77' to generate faster code.
-* Simplify Porting:: Make `g77' easier to configure, build,
- and install.
-* More Extensions:: Features many users won't know to ask for.
-* Machine Model:: `g77' should better leverage `gcc'.
-* Internals Documentation:: Make maintenance easier.
-* Internals Improvements:: Make internals more robust.
-* Better Diagnostics:: Make using `g77' on new code easier.
-
projects / msp430-gcc.git / blobdiff