This file describes the installation of the GNU Fortran compiler.
Copyright (C) 1995 Free Software Foundation, Inc.  You may copy,
distribute, and modify it freely as long as you preserve this copyright
notice and permission notice.  Contributed by James Craig Burley
(burley@gnu.ai.mit.edu).

1995-08-22

Please read all of this information before configuring, building,
and installing g77.

Contents:
  *BUILDING GNU FORTRAN*
  *BUILDING BINARIES FOR DISTRIBUTION*
  *OBSCURE CONFIGURATION INFORMATION*

*BUILDING GNU FORTRAN*

1.  The g77 sources are intended to live in a subdirectory "f" of a
    gcc source tree.  For example, the g77 sources for g77-2.6.3-0.5.14
    are intended to have names such as gcc-2.6.3/f/proj.h.  Ensure
    that you have a gcc source tree with an "f" directory containing
    the g77 sources (such as this file, named INSTALL).

    Please use only gcc and g77 source trees as distributed by the FSF.
    Use of modified versions, such as the Pentium-specific-optimization
    port of gcc, is likely to result in problems that appear to be
    in the g77 code but in fact is not.  Do not use such modified versions
    unless you understand all the differences between them and the versions
    the FSF distributes -- in which case you should be able to modify the
    g77 (or gcc) source trees appropriately so g77 and gcc can coexist
    as they do in the stock FSF distributions.

2.  Read the file f/gbe/README, if it exists, and apply the appropriate
    patch file for the version of the GNU CC compiler you have, if
    that exists.  If the directory exists but the appropriate file
    does not exist, you are using either too old a release, or one that
    is in advance of the release corresponding to the version of g77
    you have.  If the information in f/gbe/README doesn't provide
    adequate information, the latter is more likely, and you should wait
    for a new release of g77 that provides explicit support for the
    new version.  Note that a new version of gcc that differs only
    in the third field from a version g77 already supports is likely
    to be well-supported by g77 using that supported version.  So,
    for example, if g77 has support for versions 2.7.0 and 2.7.1, it
    is likely that gcc-2.7.2 would work well with g77 by using the
    2.7.1 patch file provided with g77 (aside from some offsets
    reported by `patch').  However, gcc-2.8.0 would almost certainly
    not work with that version of g77 no matter which patch file was
    used, so a new version of g77 would be needed (and you should
    wait for it rather than bothering the author!).

    NOTE: g77's configuration file gcc/f/config-lang.in tries to
    detect whether at least one necessary patch "hunk" has been
    applied and, if not, aborts the configuration with an explanation.
    PLEASE do not try to fool this code by applying just the patch
    hunk it looks for, because then g77 might well appear to build
    and install correctly, and even appear to compile correctly,
    but could easily produce broken code.  (If someone does this and
    reports a bug that takes time to track down to this kind of
    incident, g77 developers will have to waste further time
    by adding more code to g77 to ensure all the patches have been
    made, instead of using that time to improve g77!  So behave.)

    ALSO NOTE: If you don't have `patch', you can obtain it from
    the usual GNU distribution sites.  You can also apply the
    patches by hand -- patch files were originally designed for
    humans to read them, because the tool that creates them,
    `diff', existed before `patch'.  `diff -rcp2N' is typically
    used to create the patch files, if that helps.

3.  Decide whether you want installation of g77 to also install
    an `f77' command.  On systems with a native f77, this is not
    normally desired, so g77 as shipped does not do this.

    If you want `f77' installed, create the file `f77-install-ok'
    (e.g. via the UNIX command `touch f77-install-ok') in the
    source or build top-level directory (the same directory in
    which the g77 `f' directory resides, not the `f' directory
    itself), or edit gcc/f/Make-lang.in and change the definition
    of the F77_INSTALL_FLAG macro appropriately.

    When you enable installation of `f77', either a link to or a
    direct copy of the `g77' command is made.  No attempt is made
    to install a program (like a shell script) that provides
    compatibility with any other f77 programs.

    Note that invoking the `uninstall' target also tests this
    macro/file at that time to determine whether to delete the
    installed copy of `f77'.

4.  Decide how installation of g77 should affect any existing installation
    of f2c on your system.

    If you do not have f2c on your system (e.g. no /usr/bin/f2c, no
    /usr/include/f2c.h, and no /usr/lib/libf2c.a, /usr/lib/libF77.a,
    or /usr/lib/libI77.a), you don't need to be concerned with this
    item.

    If you do have f2c on your system, you need to decide how users
    of f2c will be affected by your installing g77.  Since g77 is
    currently designed to be object-code-compatible with f2c (with
    very few, clear exceptions), users of f2c might want to combine
    f2c-compiled object files with g77-compiled object files in a
    single executable.

    To do this, users of f2c should use the same copies of f2c.h and
    libf2c.a that g77 uses (and that get built as part of g77).

    If you do nothing here, the g77 installation process will not
    overwrite the include/f2c.h and lib/libf2c.a files with its
    own versions, and in fact will not even install libf2c.a for use
    with the newly installed versions of gcc and g77 if it sees
    that lib/libf2c.a exists -- instead, it will print an explanatory
    message and skip this part of the installation.

    To install g77's versions of f2c.h and libf2c.a in the appropriate
    places, create the file `f2c-install-ok' (e.g. via the UNIX
    command `touch f2c-install-ok') in the source or build top-level
    directory (the same directory in which the g77 `f' directory
    resides, not the `f' directory itself), or edit gcc/f/Make-lang.in
    and change the definition of the F2C_INSTALL_FLAG macro appropriately.

    Make sure that when you enable the overwriting of f2c.h and libf2c.a
    as used by f2c, you have a recent and properly configured version of
    bin/f2c so that it generates code that is compatible with g77.

    If you don't want installation of g77 to overwrite f2c's existing
    installation, but you do want g77 installation to proceed with
    installation of its own versions of f2c.h and libf2c.a in places
    where gcc/g77 will pick them up (even when linking f2c-compiled
    object files -- which might lead to incompatibilities), create
    the file `f2c-exists-ok' (e.g. via the UNIX command
    `touch f2c-exists-ok') in the source or build top-level directory,
    or edit gcc/f/Make-lang.in and change the definition of the
    F2CLIBOK macro appropriately.

5.  Follow the directions in the INSTALL file in the gcc source
    tree (such as running ./configure, doing "make ...", and so on --
    you MUST run ./configure 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!!).

    Because the `gcc' command is necessarily modified by the GNU
    Fortran patches, so that it recognizes Fortran source files,
    make sure the configuration you select will result in the
    proper installation of `gcc'.  For example, if `gcc'
    lives in `/usr/bin/gcc' on your system, you have to make sure
    installation of GNU Fortran causes that old version of `gcc'
    to get overwritten by the new one, by doing:

      ./configure --prefix=/usr

    You might want to back up your existing copy of `bin/gcc', and
    perhaps even the entire `lib/gcc-lib' directory, first.  These
    typically are found in `/usr' or `/usr/local'.  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 /dev/null -xc /dev/null -xnone

    Just building GNU Fortran should not overwrite any installed
    programs -- but obviously after you build g77, you will want
    to install it, so backing up anything it might overwrite is
    a good idea (for any package, not just g77, though in this case
    it is intentional that g77 overwrites gcc if it is already
    installed).

WARNING: If you follow the procedure to build successive "stages"
and you compare the object files produced by various stages,
the file f/zzz.o WILL be different.  That is because it
contains a string with an expansion of the __TIME__ macro,
which expands to the current time of day.  It is nothing
to worry about, since f/zzz.c doesn't contain any actual code.
This file does allow you to override its use of __DATE__ and
__TIME__ by defining macros for the compilation -- see the
source code for details.

NOTE:  Configuring with the --srcdir argument is only known
to work with GNU make.  Irix5.2 and SunOS4.1 makes definitely
won't work outside the source directory at present.  g77's
portion of the `configure' script issues a warning message
about this (when you configure for building binaries outside
the source directory).

ALSO NOTE:  If you have the appropriate version of gcc
already installed on your system, doing

  make -k CC=gcc LANGUAGES=f77 g77 install

should suffice to build and install just g77 and gcc, without building
any of the other GNU compilers.  HOWEVER, if this approach fails
miserably, you should be able to do the installation by following
the usual gcc installation method.  (If libf2c.a is not installed
as expected, try specifying the install-libf77 and install-f2c-all
targets explicitly.  These shouldn't have to be separately specified,
but might need to be when using non-GNU versions of make.  We don't
know why this is, yet.)  Using the "-k" option makes it continue after
installation problems like not having makeinfo installed on your system,
and the `g77' target ensures that the g77 command driver is built and
thus installed.

ALSO**2 NOTE: It seems that building g77 might require bison and
makeinfo to be installed.  g77 itself has no need for these, but
other portions of gcc might, so before you start building gcc or
g77, make sure bison and makeinfo are installed.

IF YOU CANNOT INSTALL bison: make sure you start with a _fresh_
distribution of gcc, do _not_ do "make realclean", and to be safe,
type these commands to convince make not to try rebuilding them
from the bison input files:

  cd gcc-2.6.2  # or 2.6.3
  touch bi-parser.c bi-parser.h c-parse.c c-parse.h cexp.c
  touch cp/parse.c cp/parse.h objc-parse.c

IF YOU CANNOT INSTALL makeinfo: either use the -k option when
invoking make to specify the install or install-libf77 targets,
or specify "MAKEINFO=echo" on the make command line.  If you fail
to do one of these, some things like libf2c.a will fail to be
installed after the attempt to use makeinfo fails.

ALSO**3 NOTE: Most of gcc/f/*.c is compiled using the `-W -Wall'
options.  There are some prototype declarations in gcc/f/com.h that
get around the lack of them in the back-end code in gcc/*.c, but
turning on strict checking of prototypes and such has not yet
been tried.

ALSO**4 NOTE: g77 currently requires GNU C, not just ANSI C, to
build it.  This is expected to be fixed in 0.6.  If you use a
non-GNU C compiler, syntax errors are likely to be reported for
source files like gcc/f/expr.c.  As of 0.5.16, an explicit
`#error' directive is used to catch use of a non-gcc compiler
in a friendlier, self-documenting way.

ALSO**5 NOTE: g77 _does_ require a working ANSI C environment
to build it.  In particular, some systems are missing strtoul(),
bsearch(), etc in their libraries.  See gcc/f/proj.h for information
on how to temporarily work around the bugs on these systems.
(These are emphatically _not_ g77 bugs.  DO NOT REPORT THEM
TO THE g77 AUTHOR!!!)

*BUILDING BINARIES FOR DISTRIBUTION*

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 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.  E.g. 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' -- just make an empty file named `f77-install-ok' in
the source or build directory (the one in which the `f' directory
resides, not the `f' directory itself) when you specify one of the
`install' or `uninstall' targets in a `make' command.

For a system that might already have f2c installed, you definitely
will want to make another empty file (in the same directory) named
either `f2c-exists-ok' or `f2c-install-ok'.  Use the former if you
don't want your distribution to overwrite f2c-related files in existing
systems; use the latter 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.

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 copy of g77 named `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 not only the `g77' and `f771'
executables in bin/, plus the `libf2c.a' library in lib/, but
the new (updated) version of the `gcc' executable in bin/.
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, and it is possible
they'll fix back-end bugs that can be demonstrated using front
ends other than GNU Fortran's.  Please assure users that unless
their version of the `gcc' command is older than, say, 2.6.2,
they are unlikely to experience any problems by overwriting
it with your version -- though they could certainly protect
themselves by making backup copies first!

Further, PLEASE find a way to include the `gcc/f/DOC' and
`gcc/f/BUGS' files in your distribution, so users have some way
to read the documentation.  There is a `g77.1' file for
installation in man/, but this is incredibly incomplete.  There
is plenty of room for improvement in g77 documentation, but
at least the DOC and BUGS files have important information even
though in a primitive form (straight text).  If you can help out
the GNU Fortran project by converting these files (plus this
one, INSTALL) into canonical GNU documentation formats (.texi,
info, whatever), please offer this to `fortran@gnu.ai.mit.edu'.

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.ai.mit.edu' has received a fair amount 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.

*OBSCURE CONFIGURATION INFORMATION*

g77 now, on most machines, puts more variables and arrays on the stack
where possible, and can be configured (by changing FFECOM_sizeMAXSTACKITEM
in gcc/f/com.c) to force smaller-sized entities into static storage (saving
on stack space) or permit larger-sized entities to be put on the
stack (which can improve run-time performance).

The g77 build will crash if an attempt is made to build it as a cross-compiler
for a target when g77 cannot reliably determine the bit pattern of
floating-point constants for the target.  Planned improvements for g77-0.6
will give it the capabilities it needs to not have to crash the build
but rather generate correct code for the target.  (Currently, g77
would generate bad code under such circumstances if it didn't crash
during the build, e.g. when compiling a source file that does
something like EQUIVALENCE (I,R) and DATA R/3.1415926535/.)

A warning message is issued when g77 sees code that provides
initial values (e.g. via DATA) to an aggregate area (COMMON or
EQUIVALENCE, or even a large enough array or CHARACTER variable)
that is large enough to increase g77's compile time by roughly
a factor of 10.  This size is currently quite small, since g77
currently has a known bug (see f/BUGS) requiring too much memory
and time to handle such cases.  See f/data.c macro
FFEDATA_sizeTOO_BIG_INIT_ for the minimum size (in storage units,
which can be bytes, words, or whatever, on a case-by-case basis).

As of 0.5.16, g77 warns when it is used to compile Fortran code
for a target configuration that is not basically a 32-bit
machine (e.g. an Alpha).  This is because g77 is known to not work
properly on such configurations.  This is expected to be fixed
at 0.6, at which point the warning would be dropped.
