950519

This directory contains the version 0.5.15 release of the GNU Fortran
compiler.  The GNU Fortran compiler is free software.  See the file
COPYING.g77 for copying permission.

* IMPORTANT: Things you _must_ do are marked with a * at the beginning of
  the line in this file!!!

This README is for GNU Fortran, and describes the files in the f/
directory.  The f/ directory is intended to be a subdirectory of a
gcc source tree.  These directories are referred to below as gcc/,
which is the top-level directory containing the gcc back end, the
gcc C front end, and other non-Fortran files, and gcc/f/, which
contains all of the Fortran files.

* To build GNU Fortran, you must have a recent gcc distribution,
  such as version 2.6.2 or 2.6.3.

If you have just unpacked the g77 distribution, before proceeding,
you must merge the contents of the g77 distribution with the appropriate
gcc distribution on your system before proceeding.  Using sample
versions of 2.6.3 for gcc and 0.5.15 for g77, the process of unpacking
and merging both distributions would be done as follows (where # is the
shell prompt):

    # tar xf gcc-2.6.3.tar         # Creates ./gcc-2.6.3/
    # tar xf g77-0.5.15.tar        # Creates ./g77-0.5.15/
*   # mv g77-0.5.15/* gcc-2.6.3/   # Merges gcc and g77 into ./gcc-2.6.3/
    # rmdir g77-0.5.15             # Remove empty ./g77-0.5.15/

Another approach is to do the following:

    # tar xf gcc-2.6.3.tar         # Creates ./gcc-2.6.3/
    # ln -s gcc-2.6.3 g77-0.5.15   # Make g77-0.5.15 a link to gcc-2.6.3
    # tar xf g77-0.5.15.tar        # Unpacks g77 into gcc-2.6.3

The latter approach leaves the symbolic link, which might help others
keep track of where an installed version of g77 comes from.

(There are other ways to combine the gcc and g77 distributions, but
the above are the only ones recommended.  Try others only at your
own peril, and if you run into problems, please restart from scratch
using one of the methods documented above.  Report a bug only if a
problem occurs using one of the above methods.)

The resulting directory layout is as follows, where gcc/ might be,
for example, gcc-0.5.15/:

    gcc/                    Non-Fortran files in gcc (not part of g77*.tar)
    gcc/README.g77          This file
    gcc/f/                  GNU Fortran front end
    gcc/f/gbe/              Patches required for gcc back end versions
    gcc/f/runtime/          libf2c configuration and f2c.h file generation
    gcc/f/runtime/libF77/   Non-I/O portion of libf2c
    gcc/f/runtime/libI77/   I/O portion of libf2c

gcc/f/ as a whole contains the program GNU Fortran (g77), plus a portion
of the separate program f2c, which is in gcc/f/runtime.  NOTE: The f2c
code is not part of the program g77, just distributed with it.

This directory is named gcc/f/ because it, along with its contents, is
designed to be a subdirectory of a GNU CC (gcc) development directory.  I.e.
when a gcc distribution is unpacked into a directory (named gcc/ for
example), it typically contains subdirectories like gcc/config/ and
gcc/cp/.  The latter is the subdirectory for the GNU C++ (g++) program.

Similarly, the g77 directory f/ is designed to be placed in gcc/ so that
it becomes the subdirectory gcc/f/.  g77 is distributed as g77-someversion/f/
so that unpacking the g77 distribution is done in the normal GNU way,
resulting in a directory having the version number in the name.  However,
to build g77, the g77 distribution must be merged with an appropriate gcc
distribution, normally in a gcc directory, before configuring, building,
and installing g77.

Applying g77 patches in the form of .diff files is done by typing
"patch -p1 -d gcc" (where gcc/f/ is the active version).  That is,
g77 patches are distributed in the same form, and at the same directory
level, as patches to the gcc distribution.

gcc/f/ has text files that document the Fortran compiler, source
files for the GNU Fortran Front End (FFE), and some other stuff.

gcc/f/gbe/ has patch files for various versions of gcc, primarily
needed to patch the GNU compiler Back End (GBE) to fix and improve it
for use with g77.  If a patch file exists for the version of gcc you
want to build along with g77, you MUST apply the patch before building
g77 with that version or g77 will not build or work properly.*

* Read gcc/f/gbe/README for more information.

gcc/f/runtime/ contains the run-time libraries for the f2c program, also used
by g77, and referred to as libf2c (though libf2c is really a combination of
two distinct libraries, libF77 and libI77 -- in g77, this distinction is
not made).  This separate subdirectory is not part of the program g77, just
distributed with it.  Some new files have been added to this subdirectory
and some minor changes made to the files contained therein, to fix some
bugs and facilitate automatic configuration, building, and installation of
libf2c for use by g77 users.  See gcc/f/runtime/README for more information.

gcc/f/BUGS lists some important bugs known to be in g77.

gcc/f/ChangeLog lists recent changes to g77 internals.

gcc/f/CREDITS lists people and organizations that have helped make g77 happen.

gcc/f/DOC provides some rudimentary documentation for g77, including
user-visible changes made to recent releases.

gcc/f/INSTALL describes how to build and install GNU Fortran.

gcc/f/NEWS contains the per-release changes (not just user-visible ones
seen in gcc/f/DOC) listed in the ~fortran/.plan file.

gcc/f/PROJECTS contains various lists of things still needing to be done
to g77 to improve it in various ways.

* Read gcc/f/BUGS, gcc/f/DOC, and gcc/f/INSTALL at the very least!

If you want to get into the FFE code, which lives entirely in gcc/f/, here
are a few clues.  The file parse.c is the source file for main() for a
stand-alone FFE and yyparse() for g77.

The file top.c contains the top-level FFE function ffe_file and it (along
with top.h) define all ffe_[a-z].*, ffe[A-Z].*, and FFE_[A-Za-z].* symbols.
The file fini.c is a main() program that is used when building the FFE to
generate C header and source files for recognizing keywords.  The files
malloc.c and malloc.h comprise a memory manager that defines all
malloc_[a-z].*, malloc[A-Z].*, and MALLOC_[A-Za-z].* symbols.  All other
modules named <xyz> are comprised of all files named <xyz>*.<ext> and
define all ffe<xyz>_[a-z].*, ffe<xyz>[A-Z].*, and FFE<XYZ>_[A-Za-z].* symbols.
If you understand all this, congratulations -- it's easier for me to remember
how it works than to type in these grep patterns (such as they are).  But it
does make it easy to find where a symbol is defined -- for example,
the symbol "ffexyz_set_something" would be defined in xyz.h and implemented
there (if it's a macro) or in xyz.c.

The "porting" files of note currently are: proj.h, which defines the
"language" used by all the other source files (the language being
Standard C plus some useful things like ARRAY_SIZE and such) -- change
this file when you find your system doesn't properly define a Standard C
macro or function, for example; target.h and target.c, which describe
the target machine in terms of what data types are supported, how they are
denoted (what C type does an INTEGER*8 map to, for example), how to convert
between them, and so on (though as of 0.5.3, more and more of this information
is being dynamically configured by ffecom_init_0); com.h and com.c, which
interface to the target back end (currently only FFE stand-alone and the GBE);
ste.c, which contains code for implementing recognized executable statements
in the target back end (again currently either FFE or GBE); src.h and src.c,
which describe information on the format(s) of source files (like whether
they are never to be processed as case-insensitive with regard to Fortran
keywords); and proj.c, which contains whatever code is needed to support
the language defined by proj.h.

If you want to debug the f771 executable, for example if it crashes,
note that the global variables "lineno" and "input_filename" are set
to reflect the current line being read by the lexer during the first-pass
analysis of a program unit and to reflect the current line being
processed during the second-pass compilation of a program unit.  If
an invocation of the function ffestd_exec_end() is on the stack,
the compiler is in the second pass, otherwise it is in the first.
(This information might help you reduce a test case and/or work around
a bug in g77 until a fix is available.)

Any questions or comments on these topics, email fortran@gnu.ai.mit.edu.
