This is Info file f/g77.info, produced by Makeinfo version 1.68 from
the input file ../../gcc/f/g77.texi.

   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-1997 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.

   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'" 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'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.

   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>).

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* g77: (g77).                  The GNU Fortran compiler.
END-INFO-DIR-ENTRY


File: g77.info,  Node: Merging Distributions,  Next: Where to Install,  Prev: Unpacking,  Up: Complete Installation

Merging Distributions
---------------------

   After merging the `g77' source tree into the `gcc' source tree, you
have put together a complete `g77' source tree.

   As of version 0.5.23, `g77' no longer modifies the version number of
`gcc', nor does it patch `gcc' itself.

   `g77' still depends on being merged with an appropriate version of
`gcc'.  For version 0.5.24 of `g77', the specific version of `gcc'
supported is 2.8.1.

   However, other versions of `gcc' might be suitable "hosts" for this
version of `g77'.

   GNU version numbers make it easy to figure out whether a particular
version of a distribution is newer or older than some other version of
that distribution.  The format is, generally, MAJOR.MINOR.PATCH, with
each field being a decimal number.  (You can safely ignore leading
zeros; for example, 1.5.3 is the same as 1.5.03.)  The MAJOR field only
increases with time.  The other two fields are reset to 0 when the
field to their left is incremented; otherwise, they, too, only increase
with time.  So, version 2.6.2 is newer than version 2.5.8, and version
3.0 is newer than both.  (Trailing `.0' fields often are omitted in
announcements and in names for distributions and the directories they
create.)

   If your version of `gcc' is older than the oldest version supported
by `g77' (as casually determined by listing the contents of
`gcc/f/INSTALL/', which contains these installation instructions in
plain-text format), you should obtain a newer, supported version of
`gcc'.  (You could instead obtain an older version of `g77', or try and
get your `g77' to work with the old `gcc', but neither approach is
recommended, and you shouldn't bother reporting any bugs you find if you
take either approach, because they're probably already fixed in the
newer versions you're not using.)

   If your version of `gcc' is newer than the newest version supported
by `g77', it is possible that your `g77' will work with it anyway.  If
the version number for `gcc' differs only in the PATCH field, you might
as well try that version of `gcc'.  Since it has the same MAJOR and
MINOR fields, the resulting combination is likely to work.

   So, for example, if a particular version of `g77' has support for
`gcc' versions 2.8.0 and 2.8.1, it is likely that `gcc-2.8.2' would
work well with `g77'.

   However, `gcc-2.9.0' would almost certainly not work with that
version of `g77' without appropriate modifications, so a new version of
`g77' would be needed (and you should wait for it rather than bothering
the maintainers--*note User-Visible Changes: Changes.).

   This complexity is the result of `gcc' and `g77' being separate
distributions.  By keeping them separate, each product is able to be
independently improved and distributed to its user base more frequently.

   However, the GBE interface defined by `gcc' typically undergoes some
incompatible changes at least every time the MINOR field of the version
number is incremented, and such changes require corresponding changes to
the `g77' front end (FFE).


File: g77.info,  Node: Where to Install,  Next: Configuring gcc,  Prev: Merging Distributions,  Up: Complete Installation

Where in the World Does Fortran (and GNU CC) Go?
------------------------------------------------

   Before configuring, you should make sure you know where you want the
`g77' and `gcc' binaries to be installed after they're built, because
this information is given to the configuration tool and used during the
build itself.

   A `g77' installation normally includes installation of a
Fortran-aware version of `gcc', so that the `gcc' command recognizes
Fortran source files and knows how to compile them.

   For this to work, the version of `gcc' that you will be building as
part of `g77' *must* be installed as the "active" version of `gcc' on
the system.

   Sometimes people make the mistake of installing `gcc' as
`/usr/local/bin/gcc', leaving an older, non-Fortran-aware version in
`/usr/bin/gcc'.  (Or, the opposite happens.)  This can result in `gcc'
being unable to compile Fortran source files, because when the older
version of `gcc' is invoked, it complains that it does not recognize
the language, or the file name suffix.

   So, determine whether `gcc' already is installed on your system,
and, if so, *where* it is installed, and prepare to configure the new
version of `gcc' you'll be building so that it installs over the
existing version of `gcc'.

   You might want to back up your existing copy of `/usr/bin/gcc', and
the entire `/usr/lib' directory, before you perform the actual
installation (as described in this manual).

   Existing `gcc' installations typically are found in `/usr' or
`/usr/local'.  (This means the commands are installed in `/usr/bin' or
`/usr/local/bin', the libraries in `/usr/lib' or `/usr/local/lib', and
so on.)

   If you aren't certain where the currently installed version of `gcc'
and its related programs reside, look at the output of this command:

     gcc -v -o /tmp/delete-me -xc /dev/null -xnone

   All sorts of interesting information on the locations of various
`gcc'-related programs and data files should be visible in the output
of the above command.  (The output also is likely to include a
diagnostic from the linker, since there's no `main_()' function.)
However, you do have to sift through it yourself; `gcc' currently
provides no easy way to ask it where it is installed and where it looks
for the various programs and data files it calls on to do its work.

   Just *building* `g77' should not overwrite any installed
programs--but, usually, after you build `g77', you will want to install
it, so backing up anything it might overwrite is a good idea.  (This is
true for any package, not just `g77', though in this case it is
intentional that `g77' overwrites `gcc' if it is already installed--it
is unusual that the installation process for one distribution
intentionally overwrites a program or file installed by another
distribution, although, in this case, `g77' is an augmentation of the
`gcc' distribution.)

   Another reason to back up the existing version first, or make sure
you can restore it easily, is that it might be an older version on
which other users have come to depend for certain behaviors.  However,
even the new version of `gcc' you install will offer users the ability
to specify an older version of the actual compilation programs if
desired, and these older versions need not include any `g77' components.
*Note Specifying Target Machine and Compiler Version: (gcc)Target
Options, for information on the `-V' option of `gcc'.


File: g77.info,  Node: Configuring gcc,  Next: Building gcc,  Prev: Where to Install,  Up: Complete Installation

Configuring GNU CC
------------------

   `g77' is configured automatically when you configure `gcc'.  There
are two parts of `g77' that are configured in two different
ways--`g77', which "camps on" to the `gcc' configuration mechanism, and
`libg2c', which uses a variation of the GNU `autoconf' configuration
system.

   Generally, you shouldn't have to be concerned with either `g77' or
`libg2c' configuration, unless you're configuring `g77' as a
cross-compiler.  In this case, the `libg2c' configuration, and possibly
the `g77' and `gcc' configurations as well, might need special
attention.  (This also might be the case if you're porting `gcc' to a
whole new system--even if it is just a new operating system on an
existing, supported CPU.)

   To configure the system, see *Note Installing GNU CC:
(gcc)Installation, following the instructions for running `./configure'.
Pay special attention to the `--prefix=' option, which you almost
certainly will need to specify.

   (Note that `gcc' installation information is provided as a
plain-text file in `gcc/INSTALL'.)

   The information printed by the invocation of `./configure' should
show that the `f' directory (the Fortran language) has been configured.
If it does not, there is a problem.

   *Note:* Configuring with the `--srcdir' argument, or by starting in
an empty directory and typing a command such as `../gcc/configure' to
build with separate build and source directories, is known to work with
GNU `make', but it is known to not work with other variants of `make'.
Irix5.2 and SunOS4.1 versions of `make' definitely won't work outside
the source directory at present.

   `g77''s portion of the `configure' script used to issue a warning
message about this when configuring for building binaries outside the
source directory, but no longer does this as of version 0.5.23.

   Instead, `g77' simply rejects most common attempts to build it using
a non-GNU `make' when the build directory is not the same as the source
directory, issuing an explanatory diagnostic.


File: g77.info,  Node: Building gcc,  Next: Pre-installation Checks,  Prev: Configuring gcc,  Up: Complete Installation

Building GNU CC
---------------

   Building `g77' requires building enough of `gcc' that these
instructions assume you're going to build all of `gcc', including
`g++', `protoize', and so on.  You can save a little time and disk
space by changes the `LANGUAGES' macro definition in `gcc/Makefile.in'
or `gcc/Makefile', but if you do that, you're on your own.  One change
is almost *certainly* going to cause failures: removing `c' or `f77'
from the definition of the `LANGUAGES' macro.

   After configuring `gcc', which configures `g77' and `libg2c'
automatically, you're ready to start the actual build by invoking
`make'.

   *Note:* You *must* have run the `configure' script in `gcc' before
you run `make', even if you're using an already existing `gcc'
development directory, because `./configure' does the work to recognize
that you've added `g77' to the configuration.

   There are two general approaches to building GNU CC from scratch:

"bootstrap"
     This method uses minimal native system facilities to build a
     barebones, unoptimized `gcc', that is then used to compile
     ("bootstrap") the entire system.

"straight"
     This method assumes a more complete native system exists, and uses
     that just once to build the entire system.

   On all systems without a recent version of `gcc' already installed,
the bootstrap method must be used.  In particular, `g77' uses
extensions to the C language offered, apparently, only by `gcc'.

   On most systems with a recent version of `gcc' already installed,
the straight method can be used.  This is an advantage, because it
takes less CPU time and disk space for the build.  However, it does
require that the system have fairly recent versions of many GNU
programs and other programs, which are not enumerated here.

* Menu:

* Bootstrap Build::  For all systems.
* Straight Build::   For systems with a recent version of `gcc'.


File: g77.info,  Node: Bootstrap Build,  Next: Straight Build,  Up: Building gcc

Bootstrap Build
...............

   A complete bootstrap build is done by issuing a command beginning
with `make bootstrap ...', as described in *Note Installing GNU CC:
(gcc)Installation.  This is the most reliable form of build, but it
does require the most disk space and CPU time, since the complete system
is built twice (in Stages 2 and 3), after an initial build (during
Stage 1) of a minimal `gcc' compiler using the native compiler and
libraries.

   You might have to, or want to, control the way a bootstrap build is
done by entering the `make' commands to build each stage one at a time,
as described in the `gcc' manual.  For example, to save time or disk
space, you might want to not bother doing the Stage 3 build, in which
case you are assuming that the `gcc' compiler you have built is
basically sound (because you are giving up the opportunity to compare a
large number of object files to ensure they're identical).

   To save some disk space during installation, after Stage 2 is built,
you can type `rm -fr stage1' to remove the binaries built during Stage
1.

   Also, *Note Installing GNU CC: (gcc)Installation, for important
information on building `gcc' that is not described in this `g77'
manual.  For example, explanations of diagnostic messages and whether
they're expected, or indicate trouble, are found there.


File: g77.info,  Node: Straight Build,  Prev: Bootstrap Build,  Up: Building gcc

Straight Build
..............

   If you have a recent version of `gcc' already installed on your
system, and if you're reasonably certain it produces code that is
object-compatible with the version of `gcc' you want to build as part
of building `g77', you can save time and disk space by doing a straight
build.

   To build just the compilers along with the necessary run-time
libraries, issue the following command:

     make -k CC=gcc

   If you run into problems using this method, you have two options:

   * Abandon this approach and do a bootstrap build.

   * Try to make this approach work by diagnosing the problems you're
     running into and retrying.

   Especially if you do the latter, you might consider submitting any
solutions as bug/fix reports.  *Note Known Causes of Trouble with GNU
Fortran: Trouble.

   However, understand that many problems preventing a straight build
from working are not `g77' problems, and, in such cases, are not likely
to be addressed in future versions of `g77'.  Consider treating them as
`gcc' bugs instead.


File: g77.info,  Node: Pre-installation Checks,  Next: Installation of Binaries,  Prev: Building gcc,  Up: Complete Installation

Pre-installation Checks
-----------------------

   Before installing the system, which includes installing `gcc', you
might want to do some minimum checking to ensure that some basic things
work.

   Here are some commands you can try, and output typically printed by
them when they work:

     sh# cd /usr/src/gcc
     sh# ./g77 -B./ -v
     g77 version 0.5.24
     Driving: ./g77 -B./ -v -c -xf77-version /dev/null -xnone
     Reading specs from ./specs
     gcc version 2.8.1
      cpp -lang-c -v -isystem ./include -undef -D__GNUC__=2 ...
     GNU CPP version 2.8.1 (Alpha GNU/Linux with ELF)
     #include "..." search starts here:
     #include <...> search starts here:
      include
      /usr/alpha-linux/include
      /usr/lib/gcc-lib/alpha-linux/2.8.1/include
      /usr/include
     End of search list.
      ./f771 -fnull-version -quiet -dumpbase g77-version.f -version ...
     GNU F77 version 2.8.1 (alpha-linux) compiled ...
     GNU Fortran Front End version 0.5.24
      as -nocpp -o /tmp/cca14485.o /tmp/cca14485.s
      ld -m elf64alpha -G 8 -O1 -dynamic-linker /lib/ld-linux.so.2 ...
      /tmp/cca14485
     __G77_LIBF77_VERSION__: 0.5.24
     @(#)LIBF77 VERSION 19970919
     __G77_LIBI77_VERSION__: 0.5.24
     @(#) LIBI77 VERSION pjw,dmg-mods 19980405
     __G77_LIBU77_VERSION__: 0.5.24
     @(#) LIBU77 VERSION 19970919
     sh# ./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone
     Reading specs from ./specs
     gcc version 2.8.1
      ./cpp -lang-c -v -isystem ./include -undef ...
     GNU CPP version 2.8.1 (Alpha GNU/Linux with ELF)
     #include "..." search starts here:
     #include <...> search starts here:
      include
      /usr/alpha-linux/include
      /usr/lib/gcc-lib/alpha-linux/2.8.1/include
      /usr/include
     End of search list.
      ./cc1 /tmp/cca18063.i -quiet -dumpbase null.c -version ...
     GNU C version 2.8.1 (alpha-linux) compiled ...
      as -nocpp -o /tmp/cca180631.o /tmp/cca18063.s
      ld -m elf64alpha -G 8 -O1 -dynamic-linker /lib/ld-linux.so.2 ...
     /usr/lib/crt1.o: In function `_start':
     ../sysdeps/alpha/elf/start.S:77: undefined reference to `main'
     ../sysdeps/alpha/elf/start.S:77: undefined reference to `main'
     sh#

   (Note that long lines have been truncated, and `...'  used to
indicate such truncations.)

   The above two commands test whether `g77' and `gcc', respectively,
are able to compile empty (null) source files, whether invocation of
the C preprocessor works, whether libraries can be linked, and so on.

   If the output you get from either of the above two commands is
noticeably different, especially if it is shorter or longer in ways
that do not look consistent with the above sample output, you probably
should not install `gcc' and `g77' until you have investigated further.

   For example, you could try compiling actual applications and seeing
how that works.  (You might want to do that anyway, even if the above
tests work.)

   To compile using the not-yet-installed versions of `gcc' and `g77',
use the following commands to invoke them.

   To invoke `g77', type:

     /usr/src/gcc/g77 -B/usr/src/gcc/ ...

   To invoke `gcc', type:

     /usr/src/gcc/xgcc -B/usr/src/gcc/ ...


File: g77.info,  Node: Installation of Binaries,  Next: Updating Documentation,  Prev: Pre-installation Checks,  Up: Complete Installation

Installation of Binaries
------------------------

   After configuring, building, and testing `g77' and `gcc', when you
are ready to install them on your system, type:

     make -k CC=gcc install

   As described in *Note Installing GNU CC: (gcc)Installation, the
values for the `CC' and `LANGUAGES' macros should be the same as those
you supplied for the build itself.

   So, the details of the above command might vary if you used a
bootstrap build (where you might be able to omit both definitions, or
might have to supply the same definitions you used when building the
final stage) or if you deviated from the instructions for a straight
build.

   If the above command does not install `libg2c.a' as expected, try
this:

     make -k ... install install-libf77

   We don't know why some non-GNU versions of `make' sometimes require
this alternate command, but they do.  (Remember to supply the
appropriate definition for `CC' where you see `...' in the above
command.)

   Note that using the `-k' option tells `make' to continue after some
installation problems, like not having `makeinfo' installed on your
system.  It might not be necessary for your system.

   *Note:* `g77' no longer installs files not directly part of `g77',
such as `/usr/bin/f77', `/usr/lib/libf2c.a', and `/usr/include/f2c.h',
or their `/usr/local' equivalents.

   *Note Distributing Binaries::, for information on how to accommodate
systems with no existing non-`g77' `f77' compiler and systems with
`f2c' installed.


File: g77.info,  Node: Updating Documentation,  Next: Missing tools?,  Prev: Installation of Binaries,  Up: Complete Installation

Updating Your Info Directory
----------------------------

   As part of installing `g77', you should make sure users of `info'
can easily access this manual on-line.

   `g77' does this automatically by invoking the `install-info' command
when you use `make install' to install `g77'.

   If that fails, or if the `info' directory it updates is not the one
normally accessed by users, consider invoking it yourself.  For example:

     install-info --info-dir=/usr/info /usr/info/g77.info

   The above example assumes the `g77' documentation already is
installed in `/usr/info' and that `/usr/info/dir' is the file you wish
to update.  Adjust the command accordingly, if those assumptions are
wrong.


File: g77.info,  Node: Missing tools?,  Prev: Updating Documentation,  Up: Complete Installation

Missing tools?
--------------

   A build of `gcc' might fail due to one or more tools being called
upon by `make' (during the build or install process), when those tools
are not installed on your system.

   This situation can result from any of the following actions
(performed by you or someone else):

   * Changing the source code or documentation yourself (as a developer
     or technical writer).

   * Applying a patch that changes the source code or documentation
     (including, sometimes, the official patches distributed by the
     FSF).

   * Deleting the files that are created by the (missing) tools.

     The `make maintainer-clean' command is supposed to delete these
     files, so invoking this command without having all the appropriate
     tools installed is not recommended.

   * Creating the source directory using a method that does not
     preserve the date-time-modified information in the original
     distribution.

     For example, the UNIX `cp -r' command copies a directory tree
     without preserving the date-time-modified information.  Use `cp
     -pr' instead.

   The reason these activities cause `make' to try and invoke tools
that it probably wouldn't when building from a perfectly "clean" source
directory containing `gcc' and `g77' is that some files in the source
directory (and the corresponding distribution) aren't really source
files, but *derived* files that are produced by running tools with the
corresponding source files as input.  These derived files "depend", in
`make' terminology, on the corresponding source files.

   `make' determines that a file that depends on another needs to be
updated if the date-time-modified information for the source file shows
that it is newer than the corresponding information for the derived
file.

   If it makes that determination, `make' runs the appropriate commands
(specified in the "Makefile") to update the derived file, and this
process typically calls upon one or more installed tools to do the work.

   The "safest" approach to dealing with this situation is to recreate
the `gcc' and `g77' source directories from complete `gcc' and `g77'
distributions known to be provided by the FSF.

   Another fairly "safe" approach is to simply install the tools you
need to complete the build process.  This is especially appropriate if
you've changed the source code or applied a patch to do so.

   However, if you're certain that the problem is limited entirely to
incorrect date-time-modified information, that there are no
discrepancies between the contents of source files and files derived
from them in the source directory, you can often update the
date-time-modified information for the derived files to work around the
problem of not having the appropriate tools installed.

   On UNIX systems, the simplest way to update the date-time-modified
information of a file is to use the use the `touch' command.

   How to use `touch' to update the derived files updated by each of
the tools is described below.  *Note:* New versions of `g77' might
change the set of files it generates by invoking each of these tools.
If you cannot figure out for yourself how to handle such a situation,
try an older version of `g77' until you find someone who can (or until
you obtain and install the relevant tools).

* Menu:

* autoconf: Missing autoconf?.
* bison: Missing bison?.
* gperf: Missing gperf?.
* makeinfo: Missing makeinfo?.


File: g77.info,  Node: Missing autoconf?,  Next: Missing bison?,  Up: Missing tools?

Missing `autoconf'?
...................

   If you cannot install `autoconf', make sure you have started with a
*fresh* distribution of `gcc' and `g77', do *not* do `make
maintainer-clean', and, to ensure that `autoconf' is not invoked by
`make' during the build, type these commands:

     sh# cd gcc/f/runtime
     sh# touch configure libU77/configure
     sh# cd ../../..
     sh#


File: g77.info,  Node: Missing bison?,  Next: Missing gperf?,  Prev: Missing autoconf?,  Up: Missing tools?

Missing `bison'?
................

   If you cannot install `bison', make sure you have started with a
*fresh* distribution of `gcc', do *not* do `make maintainer-clean',
and, to ensure that `bison' is not invoked by `make' during the build,
type these commands:

     sh# cd gcc
     sh# touch bi-parser.c bi-parser.h c-parse.c c-parse.h cexp.c
     sh# touch cp/parse.c cp/parse.h objc-parse.c
     sh# cd ..
     sh#


File: g77.info,  Node: Missing gperf?,  Next: Missing makeinfo?,  Prev: Missing bison?,  Up: Missing tools?

Missing `gperf'?
................

   If you cannot install `gperf', make sure you have started with a
*fresh* distribution of `gcc', do *not* do `make maintainer-clean',
and, to ensure that `gperf' is not invoked by `make' during the build,
type these commands:

     sh# cd gcc
     sh# touch c-gperf.h
     sh# cd ..
     sh#


File: g77.info,  Node: Missing makeinfo?,  Prev: Missing gperf?,  Up: Missing tools?

Missing `makeinfo'?
...................

   If `makeinfo' is needed but unavailable when installing (via `make
install'), some files, like `libg2c.a', might not be installed, because
once `make' determines that it cannot invoke `makeinfo', it cancels any
further processing.

   If you cannot install `makeinfo', an easy work-around is to specify
`MAKEINFO=true' on the `make' command line, or to specify the `-k'
option (`make -k install').

   Another approach is to force the relevant files to be up-to-date by
typing these commands and then re-trying the installation step:

     sh# cd gcc
     sh# touch f/g77.info f/BUGS f/INSTALL f/NEWS
     sh# cd ..
     sh#


File: g77.info,  Node: Distributing Binaries,  Prev: Complete Installation,  Up: Installation

Distributing Binaries
=====================

   If you are building `g77' for distribution to others in binary form,
first make sure you are aware of your legal responsibilities (read the
file `gcc/COPYING' thoroughly).

   Then, consider your target audience and decide where `g77' should be
installed.

   For systems like GNU/Linux that have no native Fortran compiler (or
where `g77' could be considered the native compiler for Fortran and
`gcc' for C, etc.), you should definitely configure `g77' for
installation in `/usr/bin' instead of `/usr/local/bin'.  Specify the
`--prefix=/usr' option when running `./configure'.

   You might also want to set up the distribution so the `f77' command
is a link to `g77', although a script that accepts "classic" UNIX `f77'
options and translates the command-line to the appropriate `g77'
command line would be more appropriate.  If you do this, *please* also
provide a "man page" in `man/man1/f77.1' describing the command.  (A
link to `man/man1/g77.1' is appropriate if `bin/f77' is a link to
`bin/g77'.)

   For a system that might already have `f2c' installed, consider
whether inter-operation with `g77' will be important to users of `f2c'
on that system.  If you want to improve the likelihood that users will
be able to use both `f2c' and `g77' to compile code for a single program
without encountering link-time or run-time incompatibilities, make sure
that, whenever they intend to combine `f2c'-produced code with
`g77'-produced code in an executable, they:

   * Use the `lib/gcc-lib/.../include/g2c.h' file generated by the
     `g77' build in place of the `f2c.h' file that normally comes with
     `f2c' (or versions of `g77' prior to 0.5.23) when compiling *all*
     of the `f2c'-produced C code

   * Link to the `lib/gcc-lib/.../libg2c.a' library built by the `g77'
     build instead of the `libf2c.a' library that normally comes with
     `f2c' (or versions of `g77' prior to 0.5.23)

   How you choose to effect the above depends on whether the existing
installation of `f2c' must be maintained.

   In any case, it is important to try and ensure that the installation
keeps working properly even after subsequent re-installation of `f2c',
which probably involves overwriting `/usr/local/lib/libf2c.a' and
`/usr/local/include/f2c.h', or similar.

   At least, copying `libg2c.a' and `g2c.h' into the appropriate
"public" directories allows users to more easily select the version of
`libf2c' they wish to use for a particular build.  The names are
changed by `g77' to make this coexistence easier to maintain; even if
`f2c' is installed later, the `g77' files normally installed by its
installation process aren't disturbed.  Use of symbolic links from one
set of files to another might result in problems after a subsequent
reinstallation of either `f2c' or `g77', so be sure to alert users of
your distribution accordingly.

   (Make sure you clearly document, in the description of your
distribution, how installation of your distribution will affect
existing installations of `gcc', `f2c', `f77', `libf2c.a', and so on.
Similarly, you should clearly document any requirements you assume will
be met by users of your distribution.)

   For other systems with native `f77' (and `cc') compilers, configure
`g77' as you (or most of your audience) would configure `gcc' for their
installations.  Typically this is for installation in `/usr/local', and
would not include a new version of `/usr/bin/f77' or
`/usr/local/bin/f77', so users could still use the native `f77'.

   In any case, for `g77' to work properly, you *must* ensure that the
binaries you distribute include:

`bin/g77'
     This is the command most users use to compile Fortran.

`bin/gcc'
     This is the command some users use to compile Fortran, typically
     when compiling programs written in other languages at the same
     time.  The `bin/gcc' executable file must have been built from a
     `gcc' source tree into which a `g77' source tree was merged and
     configured, or it will not know how to compile Fortran programs.

`info/g77.info*'
     This is the documentation for `g77'.  If it is not included, users
     will have trouble understanding diagnostics messages and other
     such things, and will send you a lot of email asking questions.

     Please edit this documentation (by editing `gcc/f/*.texi' and
     doing `make doc' from the `/usr/src/gcc' directory) to reflect any
     changes you've made to `g77', or at least to encourage users of
     your binary distribution to report bugs to you first.

     Also, whether you distribute binaries or install `g77' on your own
     system, it might be helpful for everyone to add a line listing
     this manual by name and topic to the top-level `info' node in
     `/usr/info/dir'.  That way, users can find `g77' documentation more
     easily.  *Note Updating Your Info Directory: Updating
     Documentation.

`man/man1/g77.1'
     This is the short man page for `g77'.  It is not always kept
     up-to-date, but you might as well include it for people who really
     like "man" pages.

`lib/gcc-lib'
     This is the directory containing the "private" files installed by
     and for `gcc', `g77', `g++', and other GNU compilers.

`lib/gcc-lib/.../f771'
     This is the actual Fortran compiler.

`lib/gcc-lib/.../libg2c.a'
     This is the run-time library for `g77'-compiled programs.

   Whether you want to include the slightly updated (and possibly
improved) versions of `cc1', `cc1plus', and whatever other binaries get
rebuilt with the changes the GNU Fortran distribution makes to the GNU
back end, is up to you.  These changes are highly unlikely to break any
compilers, because they involve doing things like adding to the list of
acceptable compiler options (so, for example, `cc1plus' accepts, and
ignores, options that only `f771' actually processes).

   Please assure users that unless they have a specific need for their
existing, older versions of `gcc' command, they are unlikely to
experience any problems by overwriting it with your version--though
they could certainly protect themselves by making backup copies first!

   Otherwise, users might try and install your binaries in a "safe"
place, find they cannot compile Fortran programs with your distribution
(because, perhaps, they're invoking their old version of the `gcc'
command, which does not recognize Fortran programs), and assume that
your binaries (or, more generally, GNU Fortran distributions in
general) are broken, at least for their system.

   Finally, *please* ask for bug reports to go to you first, at least
until you're sure your distribution is widely used and has been well
tested.  This especially goes for those of you making any changes to
the `g77' sources to port `g77', e.g. to OS/2.  <fortran@gnu.org> has
received a fair number of bug reports that turned out to be problems
with other peoples' ports and distributions, about which nothing could
be done for the user.  Once you are quite certain a bug report does not
involve your efforts, you can forward it to us.


File: g77.info,  Node: Debugging and Interfacing,  Next: Collected Fortran Wisdom,  Prev: Installation,  Up: Top

Debugging and Interfacing
*************************

   GNU Fortran currently generates code that is object-compatible with
the `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 `g77'-compiled code generally
requires some understanding of the way `g77' compiles code for various
constructs.

   Similarly, using a debugger to debug `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 `g77'
compiles code for constructs involving interfaces to other languages
and to debuggers.

   *Caution:* Much or all of this information pertains to only the
current release of `g77', sometimes even to using certain compiler
options with `g77' (such as `-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 `g77'.  This
information is provided primarily to make debugging of code generated
by this particular release of `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 `g77' as
they are installed, because new versions can change the behaviors
described in this section.

* Menu:

* Main Program Unit::  How `g77' compiles a main program unit.
* Procedures::         How `g77' constructs parameter lists
                       for procedures.
* Functions::          Functions returning floating-point or character data.
* Names::              Naming of user-defined variables, procedures, etc.
* Common Blocks::      Accessing common variables while debugging.
* Local Equivalence Areas::  Accessing `EQUIVALENCE' while debugging.
* Complex Variables::  How `g77' performs complex arithmetic.
* Arrays::             Dealing with (possibly multi-dimensional) arrays.
* Adjustable Arrays::  Special consideration for adjustable arrays.
* Alternate Entry Points::  How `g77' implements alternate `ENTRY'.
* Alternate Returns::  How `g77' handles alternate returns.
* Assigned Statement Labels::  How `g77' handles `ASSIGN'.
* Run-time Library Errors::  Meanings of some `IOSTAT=' values.


File: g77.info,  Node: Main Program Unit,  Next: Procedures,  Up: Debugging and Interfacing

Main Program Unit (PROGRAM)
===========================

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

   Generally, `g77' and `libg2c' 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 `g77' version 0.5.16 includes a bug fix for
`libg2c' that solved a problem with using the `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 `g77' (or `f2c') to compile your
main program unit--that is, if you intend to compile a `main()'
procedure using some other language--you should carefully examine the
code for `main()' in `libg2c', found in the source file
`egcs/libf2c/libF77/main.c', to see what kinds of things might need to
be done by your `main()' in order to provide the Fortran environment
your Fortran code is expecting.

   For example, `libg2c''s `main()' sets up the information used by the
`IARGC' and `GETARG' intrinsics.  Bypassing `libg2c''s `main()' without
providing a substitute for this activity would mean that invoking
`IARGC' and `GETARG' would produce undefined results.

   When debugging, one implication of the fact that `main()', which is
the place where the debugged program "starts" from the debugger's point
of view, is in `libg2c' 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
`MAIN__', and then run the program.  A convenient way to do so is to
add the `gdb' command

     tbreak MAIN__

to the file `.gdbinit' in the directory in which you're debugging
(using `gdb').

   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 `MAIN__', that should work fine.


File: g77.info,  Node: Procedures,  Next: Functions,  Prev: Main Program Unit,  Up: Debugging and Interfacing

Procedures (SUBROUTINE and FUNCTION)
====================================

   Currently, `g77' passes arguments via reference--specifically, by
passing a pointer to the location in memory of a variable, array, array
element, a temporary location that holds the result of evaluating an
expression, or a temporary or permanent location that holds the value
of a constant.

   Procedures that accept `CHARACTER' arguments are implemented by
`g77' so that each `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 `__g77_length_X', where X is the
user-specified name.  This argument is of the C type `ftnlen' (see
`egcs/libf2c/g2c.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 `X' is not declared
`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 `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 `CHARACTER' argument is present in the argument
list, the length arguments are appended in the order the original
arguments appear.  So `CALL FOO('HI','THERE')' is implemented in C as
`foo("hi","there",2,5);', ignoring the fact that `g77' does not provide
the trailing null bytes on the constant strings (`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 `CHARACTER' variables and
arrays *only*.  It does *not* apply to external `CHARACTER' functions
or to intrinsic `CHARACTER' functions.  That is, no second length
argument is passed to `FOO' in this case:

     CHARACTER X
     EXTERNAL X
     CALL FOO(X)

Nor does `FOO' expect such an argument in this case:

     SUBROUTINE FOO(X)
     CHARACTER X
     EXTERNAL X

   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 `CHARACTER', subtle symptoms might
appear.


File: g77.info,  Node: Functions,  Next: Names,  Prev: Procedures,  Up: Debugging and Interfacing

Functions (FUNCTION and RETURN)
===============================

   `g77' handles in a special way functions that return the following
types:

   * `CHARACTER'

   * `COMPLEX'

   * `REAL(KIND=1)'

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

   For `COMPLEX', when `-ff2c' is in force, `g77' implements a
subroutine with one argument prepended: `__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 `-fno-f2c' is in force,
`g77' implements a `COMPLEX' function as `gcc''s `__complex__ float' or
`__complex__ double' function (or an emulation thereof, when
`-femulate-complex' is in effect), returning the result of the function
in the same way as `gcc' would.

   For `REAL(KIND=1)', when `-ff2c' is in force, `g77' implements a
function that actually returns `REAL(KIND=2)' (typically C's `double'
type).  When `-fno-f2c' is in force, `REAL(KIND=1)' functions return
`float'.


File: g77.info,  Node: Names,  Next: Common Blocks,  Prev: Functions,  Up: Debugging and Interfacing

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 (`_') appended
by `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 `-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.

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

   For example:

     Max_Cost = 0

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

   `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:

     Foo = 9.436

Here, it is normally the case that the variable assigned will be named
`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 `g77' might instead be `FOO' or even `Foo', thus
affecting how debugging is done.

   Also:

     Call Foo

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

     void foo_()

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


File: g77.info,  Node: Common Blocks,  Next: Local Equivalence Areas,  Prev: Names,  Up: Debugging and Interfacing

Common Blocks (COMMON)
======================

   `g77' names and lays out `COMMON' areas the same way `f2c' does, for
compatibility with `f2c'.

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

   (As of Version 0.5.19, `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 `-fdebug-kludge' option to enable this behavior.
In `gdb', use `set language c' before printing the value of the member,
then `set language fortran' to restore the default language, since
`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 `g77' that, in
conjunction with a contemporary version of `gdb', properly supports
Fortran-language debugging, including access to members of `COMMON'
areas.)

   *Note Options for Code Generation Conventions: Code Gen Options, for
information on the `-fdebug-kludge' option.

   Moreover, `g77' currently implements a `COMMON' area such that its
type is an array of the C `char' data type.

   So, when debugging, you must know the offset into a `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 `char' type.

   For example, using default implicit typing, the statement

     COMMON I(15), R(20), T

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


File: g77.info,  Node: Local Equivalence Areas,  Next: Complex Variables,  Prev: Common Blocks,  Up: Debugging and Interfacing

Local Equivalence Areas (EQUIVALENCE)
=====================================

   `g77' treats storage-associated areas involving a `COMMON' block as
explained in the section on common blocks.

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

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

   (As of Version 0.5.19, `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 `-fdebug-kludge' option to enable this behavior.
In `gdb', use `set language c' before printing the value of the member,
then `set language fortran' to restore the default language, since
`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 `g77' that, in
conjunction with a contemporary version of `gdb', properly supports
Fortran-language debugging, including access to members of
`EQUIVALENCE' areas.)

   *Note Options for Code Generation Conventions: Code Gen Options, for
information on the `-fdebug-kludge' option.

   Moreover, `g77' implements a local `EQUIVALENCE' area such that its
type is an array of the C `char' data type.

   The name `g77' gives this array of `char' type is `__g77_equiv_X',
where 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, 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 `EQUIVALENCE'
areas by specifying the appropriate `__g77_equiv_X' array section with
the appropriate offset.  See the explanation of debugging `COMMON'
blocks for info applicable to debugging local `EQUIVALENCE' areas.

   (*Note:* `g77' version 0.5.18 and earlier chose the name for 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 `EQUIVALENCE'
statements was chosen for X, `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.)

