freebsd/contrib/gcc/README.g77

1998-08-11

This directory contains the egcs variant of version 0.5.24 of the
GNU Fortran compiler (g77).  The GNU Fortran compiler is free software.
See the file COPYING.g77 for copying permission.

Currently, two variants of g77 exist.  One is the Free Software Foundation
(FSF) variant.  The other is the egcs variant.  As of egcs version 1.1,
these variants are kept fairly similar in most respects.  Pertinent
differences, such as the layout of the source code, are specified below.

Below, `[FSF]' denotes information applicable to only the FSF variant of
g77, while `[egcs]' denotes egcs-only information.


* IMPORTANT: Things you *must* do (or avoid) are marked with a * at the
  beginning of the line in this file!!!


The email address to which bugs are to be reported is either
[FSF] <fortran@gnu.org> or [egcs] <egcs-bugs@cygnus.com>.

* *DO NOT* send any email (reporting bugs, asking questions, etc.) to
  either of these addresses without *first* reading the g77 documentation.
  Use `info', Info mode in GNU Emacs, or a text viewer such as `more' to
  do this.

  The g77 documentation is in the source files named `g77.info',
  `g77.info-1', `g77.info-2', and so on in the `f' subdirectory.  If these
  files are not present or you can't find them, contact the person or
  organization that put together the g77 distribution you are using (probably
  not the FSF or egcs), or ask your system administrator for help.


This README applies to only the g77-specific portions of the source-code
tree that contains it.  These portions include:

  -  The README.g77 and [FSF] COPYING.g77 files, in this directory, "this
     directory" being [FSF] the top-level directory containing a g77
     distribution or [egcs] the gcc/ subdirectory of an egcs distribution.

  -  The g77 front end, in the f/ subdirectory of this directory.

  -  The libg2c library, in [FSF] the f/runtime/ subdirectory of this
     directory or [egcs] the libf2c/ directory under the top-level
     directory of the egcs distribution.


* To build g77, you must have a source distribution of [FSF] gcc
  version 2.8 or [egcs] egcs version 1.1.  Do not attempt to use
  any other version of gcc or egcs, because this version of g77 is
  designed to work with only those versions.

  Note that you must have *source* copies of the gcc or egcs distribution!
  You cannot build g77 just using binaries of gcc or egcs.  Also, unless
  you are an expert, avoid using any distribution of gcc or egcs not
  identical to the ones distributed by the FSF and Cygnus Support,
  respectively.  The primary FSF distribution site is:

    <ftp://ftp.gnu.org/pub/gnu/>

  The primary egcs distribution site is:

    <ftp://ftp.cygnus.com/pub/egcs/>

  Both of these sites have approved mirror sites from which valid
  distributions also may be obtained.

* Do not attempt to combine the egcs version of g77 with the FSF
  gcc distribution, or the FSF version of g77 with the egcs gcc
  distribution.  Although the differences are minor, they might
  be sufficient to prevent g77 from building properly, or from
  working properly if the build appears to succeed.

[FSF] g77 is distributed as g77-<version>/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
source directory, before configuring, building, and installing g77.

[FSF] 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.

* [FSF] Read and follow the instructions in f/INSTALL that
  explain how to merge a g77 source directory into a gcc source
  directory.  You can use Info to read the same installation
  instructions via:

    info -f f/g77.info -n Unpacking

[FSF] The resulting directory layout includes the following, where gcc/
might be a link to, for example, gcc-2.8.1/:

    gcc/                    Non-g77 files in gcc
    gcc/COPYING.g77         A copy of the GPL, under which g77 is licensed
    gcc/README.g77          This file
    gcc/f/                  GNU Fortran front end
    gcc/f/runtime/          libg2c configuration and g2c.h file generation
    gcc/f/runtime/libF77/   Non-I/O portion of libg2c
    gcc/f/runtime/libI77/   I/O portion of libg2c
    gcc/f/runtime/libU77/   Additional interfaces to libc for libg2c

[FSF] Applying g77 patches in the form of .diff files is done by typing
`patch -p1 -d gcc' (where gcc/ contains the f/ subdirectory).  That is,
g77 patches are distributed in the same form, and at the same directory
level, as patches to the gcc distribution.  (Note: make sure you're
using GNU patch, version 2.5 or later!  Other versions of patch
have trouble with g77-related patches.)

[egcs] The egcs version of g77 is distributed already merged with
the rest of egcs (such as the gcc back end).

[egcs] The resulting directory layout includes the following, where egcs/
might be a link to, for example, egcs-1.1/:

    egcs/gcc/               Non-g77 files in gcc
    egcs/gcc/README.g77     This file
    egcs/gcc/f/             GNU Fortran front end
    egcs/libf2c/            libg2c configuration and g2c.h file generation
    egcs/libf2c/libF77/     Non-I/O portion of libg2c
    egcs/libf2c/libI77/     I/O portion of libg2c
    egcs/libf2c/libU77/     Additional interfaces to libc for libg2c

[egcs] Applying g77-specific patches to egcs is done the same way as
applying other egcs patches.


Below, `libf2c/' shall denote [FSF] gcc/f/runtime/ or [egcs] egcs/libf2c/,
while `f/' shall denote [FSF] the rest of gcc/f/ or [egcs] egcs/gcc/f/.


Components of note in g77 are described below.

f/ as a whole contains the program GNU Fortran (g77), while libf2c/
contains a portion of the separate program f2c.  Note: The libf2c
code is not part of the program g77, just distributed with it.

f/ contains text files that document the Fortran compiler, source
files for the GNU Fortran Front End (FFE), and some other stuff.
The g77 compiler code is placed in f/ because it, along with its contents,
is designed to be a subdirectory of a GNU CC (gcc) source directory, gcc/,
which is structured so that language-specific front ends can be "dropped
in" as subdirectories.  The C++ front end (g++), is an example of this --
it resides in the cp/ subdirectory.  Note that the C front end (also
referred to as gcc) is an exception to this, as its source files reside
in the gcc/ directory itself.

libf2c/ contains the run-time libraries for the f2c program, also used
by g77.  These libraries normally referred to collectively as libf2c.
When built as part of g77, libf2c is installed under the name libg2c to avoid
conflict with any existing version of libf2c, and thus is often referred
to as libg2c when the g77 version is specifically being referred to.

The netlib version of libf2c/ contains two distinct libraries, libF77 and
libI77, each in their own subdirectories.  In g77, this distinction is not
made, beyond maintaining the subdirectory structure in the source-code tree.

libf2c/ is not part of the program g77, just distributed with it.  It
contains files not present in the official (netlib) version of libf2c,
and also contains some minor changes made from libf2c, to fix some bugs,
and to facilitate automatic configuration, building, and installation of
libf2c (as libg2c) for use by g77 users.

* See libf2c/README for more information, including licensing conditions
  governing distribution of programs containing code from libg2c.

libg2c, g77's version of libf2c, adds Dave Love's implementation of
libU77, in the libf2c/libU77/ directory.  This library is distributed
under the GNU Library General Public License (LGPL) -- see the
file libf2c/libU77/COPYING.LIB for more information, as this license
governs distribution conditions for programs containing code from
this portion of the library.


Files of note in g77 are described below.

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

  info -f f/g77.info -n "Actual Bugs"

f/ChangeLog lists recent changes to g77 internals.

libf2c/ChangeLog lists recent changes to libg2c internals.

[FSF] f/INSTALL describes how to build and install GNU Fortran.  Or:

  info -f f/g77.info -n Installation

f/NEWS contains the per-release changes.  These include the user-visible
changes described under "Changes" in the g77 documentation, plus internal
changes of import.  Or:

  info -f f/g77.info -n News

* All users of g77 (not just installers) should read f/g77.info*
  as well, using the `more' command if neither the `info' command,
  nor GNU Emacs (with its Info mode), are available, or if they
  aren't yet accustomed to using these tools.  Read f/BUGS and f/NEWS
  plus, if you are planning on building or installing the FSF version
  of g77, f/INSTALL, at the very least!  All of these files are
  readable as "plain text" files.

* Also see <ftp://alpha.gnu.org/g77.plan> for up-to-date information
  regarding g77 bug reports, known bugs, bug-fixes, and new versions.


The rest of this file is of note to only those who wish to
debug, modify, or test the FFE (in conjunction with the gcc back end).

If you want to explore the FFE code, which lives entirely in f/, here
are a few clues.  The file g77spec.c contains the g77-specific source code
for the `g77' command only -- this just forms a variant of the `gcc'
command, so, just as the `gcc' command itself does not contain
the C front end, the `g77' command does not contain the Fortran front
end (FFE).  The FFE code ends up in an executable named `f771', which
does the actual compiling, so it contains the FFE plus the gcc back end
(the latter to do most of the optimization, and the code generation).

The file parse.c is the source file for main() for a stand-alone FFE and
yyparse() for f771.  (Stand-alone building of the FFE doesn't work these days.)
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 (such as 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?  Read the g77 documentation!