path: root/gnu/usr.bin/gcc/f/INSTALL

This file contains installation information for the GNU Fortran
compiler.  Copyright (C) 1995, 1996 Free Software Foundation, Inc.  You
may copy, distribute, and modify it freely as long as you preserve this
copyright notice and permission notice.

Installing GNU Fortran
**********************

   The following information describes how to install `g77'.

   The information in this file generally pertains to dealing with
*source* distributions of `g77' and `gcc'.  It is possible that some of
this information will be applicable to some *binary* distributions of
these products--however, since these distributions are not made by the
maintainers of `g77', responsibility for binary distributions rests with
whoever built and first distributed them.

   Nevertheless, efforts to make `g77' easier to both build and install
from source and package up as a binary distribution are ongoing.

Prerequisites
=============

   The procedures described to unpack, configure, build, and install
`g77' assume your system has certain programs already installed.

   The following prerequisites should be met by your system before you
follow the `g77' installation instructions:

`gzip'
     To unpack the `gcc' and `g77' distributions, you'll need the
     `gunzip' utility in the `gzip' distribution.  Most UNIX systems
     already have `gzip' installed.  If yours doesn't, you can get it
     from the FSF.

     Note that you'll need `tar' and other utilities as well, but all
     UNIX systems have these.  There are GNU versions of all these
     available--in fact, a complete GNU UNIX system can be put together
     on most systems, if desired.

`gcc-2.7.2.tar.gz'
     You need to have this, or some other applicable, version of `gcc'
     on your system.  The version should be an exact copy of a
     distribution from the FSF.  It is approximately 7MB large.

     If you've already unpacked `gcc-2.7.2.tar.gz' into a directory
     (named `gcc-2.7.2') called the "source tree" for `gcc', you can
     delete the distribution itself, but you'll need to remember to
     skip any instructions to unpack this distribution.

     Without an applicable `gcc' source tree, you cannot build `g77'.
     You can obtain an FSF distribution of `gcc' from the FSF.

`g77-0.5.19.tar.gz'
     You probably have already unpacked this distribution, or you are
     reading an advanced copy of this manual, which is contained in
     this distribution.  This distribution approximately 1MB large.

     You can obtain an FSF distribution of `g77' from the FSF, the same
     way you obtained `gcc'.

100MB disk space
     For a complete "bootstrap" build, about 100MB of disk space is
     required for `g77' by the author's current GNU/Linux system.

     Some juggling can reduce the amount of space needed; during the
     bootstrap process, once Stage 3 starts, during which the version
     of `gcc' that has been copied into the `stage2/' directory is used
     to rebuild the system, you can delete the `stage1/' directory to
     free up some space.

     It is likely that many systems don't require the complete
     bootstrap build, as they already have a recent version of `gcc'
     installed.  Such systems might be able to build `g77' with only
     about 75MB of free space.

`patch'
     Although you can do everything `patch' does yourself, by hand,
     without much trouble, having `patch' installed makes installation
     of new versions of GNU utilities such as `g77' so much easier that
     it is worth getting.  You can obtain `patch' the same way you
     obtained `gcc' and `g77'.

     In any case, you can apply patches by hand--patch files are
     designed for humans to read them.

`make'
     Your system must have `make', and you will probably save yourself
     a lot of trouble if it is GNU `make' (sometimes referred to as
     `gmake').

`cc'
     Your system must have a working C compiler.

     *Note Installing GNU CC: (gcc)Installation, for more information
     on prerequisites for installing `gcc'.

`bison'
     If you do not have `bison' installed, you can usually work around
     any need for it, since `g77' itself does not use it, and `gcc'
     normally includes all files generated by running it in its
     distribution.  You can obtain `bison' the same way you obtained
     `gcc' and `g77'.

     *Note Missing bison?::, for information on how to work around not
     having `bison'.

`makeinfo'
     If you are missing `makeinfo', you can usually work around any
     need for it.  You can obtain `makeinfo' the same way you obtained
     `gcc' and `g77'.

     *Note Missing makeinfo?::, for information on getting around the
     lack of `makeinfo'.

`root' access
     To perform the complete installation procedures on a system, you
     need to have `root' access to that system, or equivalent access.

     Portions of the procedure (such as configuring and building `g77')
     can be performed by any user with enough disk space and virtual
     memory.

     However, these instructions are oriented towards less-experienced
     users who want to install `g77' on their own personal systems.

     System administrators with more experience will want to determine
     for themselves how they want to modify the procedures described
     below to suit the needs of their installation.

Problems Installing
===================

   This is a list of problems (and some apparent problems which don't
really mean anything is wrong) that show up when configuring, building,
installing, or porting GNU Fortran.

   *Note Installation Problems: (gcc)Installation Problems, for more
information on installation problems that can afflict either `gcc' or
`g77'.

General Problems
----------------

   * On SunOS systems, linking the `f771' program produces an error
     message concerning an undefined symbol named `_strtoul'.

     This is not a `g77' bug.  *Note Patching GNU Fortran::, for
     information on a workaround provided by `g77'.

     The proper fix is either to upgrade your system to one that
     provides a complete ANSI C environment, or improve `gcc' so that
     it provides one for all the languages and configurations it
     supports.

     *Note:* In earlier versions of `g77', an automated workaround for
     this problem was attempted.  It worked for systems without
     `_strtoul', substituting the incomplete-yet-sufficient version
     supplied with `g77' for those systems.  However, the automated
     workaround failed mysteriously for systems that appeared to have
     conforming ANSI C environments, and it was decided that, lacking
     resources to more fully investigate the problem, it was better to
     not punish users of those systems either by requiring them to work
     around the problem by hand or by always substituting an incomplete
     `strtoul()' implementation when their systems had a complete,
     working one.  Unfortunately, this meant inconveniencing users of
     systems not having `strtoul()', but they're using obsolete (and
     generally unsupported) systems anyway.

   * It'd be helpful if `g77''s `Makefile.in' or `Make-lang.in' would
     create the various `stageN' directories and their subdirectories,
     so expert installers wouldn't have to reconfigure after cleaning
     up.

   * Improvements to the way `libf2c' is built could make building
     `g77' as a cross-compiler easier--for example, passing and using
     `LD' and `AR' in the appropriate ways.

   * `g77' currently requires application of a patch file to the gcc
     compiler tree.  The necessary patches should be folded in to the
     mainline gcc distribution.

     Some combinations of versions of `g77' and `gcc' might actually
     *require* no patches, but the patch files will be provided anyway
     as long as there are more changes expected in subsequent releases.
     These patch files might contain unnecessary, but possibly helpful,
     patches.  As a result, it is possible this issue might never be
     resolved, except by eliminating the need for the person
     configuring `g77' to apply a patch by hand, by going to a more
     automated approach (such as configure-time patching).

   * It should be possible to build the runtime without building `cc1'
     and other non-Fortran items, but, for now, an easy way to do that
     is not yet established.

   * Compiling `g77' requires GNU C, not just ANSI C.  Fixing this
     wouldn't be very hard (just tedious), but the code using GNU
     extensions to the C language is expected to be rewritten for 0.6
     anyway, so there are no plans for an interim fix.

Cross-compiler Problems
-----------------------

   `g77' has been in alpha testing since September of 1992, and in
public beta testing since February of 1995.  Alpha testing was done by
a small number of people worldwide on a fairly wide variety of
machines, involving self-compilation in most or all cases.  Beta
testing has been done primarily via self-compilation, but in more and
more cases, cross-compilation (and "criss-cross compilation", where a
version of a compiler is built on one machine to run on a second and
generate code that runs on a third) has been tried and has succeeded,
to varying extents.

   Generally, `g77' can be ported to any configuration to which `gcc',
`f2c', and `libf2c' can be ported and made to work together, aside from
the known problems described in this manual.  If you want to port `g77'
to a particular configuration, you should first make sure `gcc' and
`libf2c' can be ported to that configuration before focusing on `g77',
because `g77' is so dependent on them.

   Even for cases where `gcc' and `libf2c' work, you might run into
problems with cross-compilation on certain machines, for several
reasons.

   * There is one known bug (a design bug to be fixed in 0.6) that
     prevents configuration of `g77' as a cross-compiler in some cases,
     though there are assumptions made during configuration that
     probably make doing non-self-hosting builds a hassle, requiring
     manual intervention.

   * `gcc' might still have some trouble being configured for certain
     combinations of machines.  For example, it might not know how to
     handle floating-point constants.

   * There are still some challenges putting together the right
     run-time libraries (needed by `libf2c') for a target system,
     depending on the systems involved in the configuration.  (This is
     a general problem with cross-compilation, and with `gcc' in
     particular.)

Quick Start
===========

   This procedure configures, builds, and installs `g77' "out of the
box" and works on most UNIX systems.  Each command is identified by a
unique number, used in the explanatory text that follows.  For the most
part, the output of each command is not shown, though indications of
the types of responses are given in a few cases.

   To perform this procedure, the installer must be logged in as user
`root'.  Much of it can be done while not logged in as `root', and
users experienced with UNIX administration should be able to modify the
procedure properly to do so.

   Following traditional UNIX conventions, it is assumed that the
source trees for `g77' and `gcc' will be placed in `/usr/src'.  It also
is assumed that the source distributions themselves already reside in
`/usr/FSF', a naming convention used by the author of `g77' on his own
system:

     /usr/FSF/gcc-2.7.2.tar.gz
     /usr/FSF/g77-0.5.19.tar.gz

   Users of the following systems should not blindly follow these
quick-start instructions, because of problems their systems have coping
with straightforward installation of `g77':

   * SunOS

   * Alpha

   Instead, see *Note Complete Installation::, for detailed information
on how to configure, build, and install `g77' for your particular
system.  Also, see *Note Known Causes of Trouble with GNU Fortran:
Trouble, for information on bugs and other problems known to afflict the
installation process, and how to report newly discovered ones.

   If your system is *not* on the above list, and *is* a UNIX system or
one of its variants, you should be able to follow the instructions
below.  If you vary *any* of the steps below, you might run into
trouble, including possibly breaking existing programs for other users
of your system.  Before doing so, it is wise to review the explanations
of some of the steps.  These explanations follow this list of steps.

     sh[ 1]# cd /usr/src
     
     sh[ 2]# gunzip -c < /usr/FSF/gcc-2.7.2.tar.gz | tar xf -
     
     [Might say "Broken pipe"...that is normal on some systems.]
     sh[ 3]# gunzip -c < /usr/FSF/g77-0.5.19.tar.gz | tar xf -
     
     ["Broken pipe" again possible.]
     sh[ 4]# ln -s gcc-2.7.2 gcc
     
     sh[ 5]# ln -s g77-0.5.19 g77
     
     sh[ 6]# mv -i g77/* gcc
     
     [No questions should be asked by mv here; or, you made a mistake.]
     sh[ 7]# patch -p1 -V t -d gcc-2.7.2 < gcc-2.7.2/f/gbe/2.7.2.diff
     
     [Unless patch complains about rejected patches, this step worked.]
     sh[ 8]# cd gcc
     sh[ 9]# touch f77-install-ok
     
     [Do not do the above if your system already has an f77
     command, unless you've checked that overwriting it
     is okay.]
     sh[10]# touch f2c-install-ok
     
     [Do not do the above if your system already has an f2c
     command, unless you've checked that overwriting it
     is okay.  Else, touch f2c-exists-ok.]
     sh[11]# ./configure --prefix=/usr
     
     [Do not do the above if gcc is not installed in /usr/bin.
     You might need a different --prefix=..., as
     described below.]
     sh[12]# make bootstrap
     
     [This takes a long time, and is where most problems occur.]
     sh[13]# rm -fr stage1
     
     sh[14]# make -k install
     
     [The actual installation.]
     sh[15]# g77 -v
     
     [Verify that g77 is installed, obtain version info.]
     sh[16]#

   *Note Updating Your Info Directory: Updating Documentation, for
information on how to update your system's top-level `info' directory
to contain a reference to this manual, so that users of `g77' can
easily find documentation instead of having to ask you for it.

   Elaborations of many of the above steps follows:

Step 1: `cd /usr/src'
     You can build `g77' pretty much anyplace.  By convention, this
     manual assumes `/usr/src'.  It might be helpful if other users on
     your system knew where to look for the source code for the
     installed version of `g77' and `gcc' in any case.

Step 4: `ln -s gcc-2.7.2 gcc'
Step 5: `ln -s g77-0.5.19 g77'
     These commands mainly help reduce typing, and help reduce visual
     clutter in examples in this manual showing what to type to install
     `g77'.

     *Note Unpacking::, for information on using distributions of `g77'
     made by organizations other than the FSF.

Step 6: `mv -i g77/* gcc'
     After doing this, you can, if you like, type `rm g77' and `rmdir
     g77-0.5.19' to remove the empty directory and the symbol link to
     it.  But, it might be helpful to leave them around as quick
     reminders of which version(s) of `g77' are installed on your
     system.

     *Note Unpacking::, for information on the contents of the `g77'
     directory (as merged into the `gcc' directory).

Step 7: `patch -p1 ...'
     This can produce a wide variety of printed output, from `Hmm, I
     can't seem to find a patch in there anywhere...' to long lists of
     messages indicated that patches are being found, applied
     successfully, and so on.

     If messages about "fuzz", "offset", or especially "reject files"
     are printed, it might mean you applied the wrong patch file.  If
     you believe this is the case, it is best to restart the sequence
     after deleting (or at least renaming to unused names) the
     top-level directories for `g77' and `gcc' and their symbolic links.

     After this command finishes, the `gcc' directory might have old
     versions of several files as saved by `patch'.  To remove these,
     after `cd gcc', type `rm -i *.~*~'.

     *Note Merging Distributions::, for more information.

Step 9: `touch f77-install-ok'
     Don't do this if you don't want to overwrite an existing version
     of `f77' (such as a native compiler, or a script that invokes
     `f2c').  Otherwise, installation will overwrite the `f77' command
     and the `f77' man pages with copies of the corresponding `g77'
     material.

     *Note Installing `f77': Installing f77, for more information.

Step 10: `touch f2c-install-ok'
     Don't do this if you don't want to overwrite an existing
     installation of `libf2c' (though, chances are, you do).  Instead,
     `touch f2c-exists-ok' to allow the installation to continue
     without any error messages about `/usr/lib/libf2c.a' already
     existing.

     *Note Installing `f2c': Installing f2c, for more information.

Step 11: `./configure --prefix=/usr'
     This is where you specify that the `g77' executable is to be
     installed in `/usr/bin/', the `libf2c.a' library is to be
     installed in `/usr/lib/', and so on.

     You should ensure that any existing installation of the `gcc'
     executable is in `/usr/bin/'.  Otherwise, installing `g77' so that
     it does not fully replace the existing installation of `gcc' is
     likely to result in the inability to compile Fortran programs.

     *Note Where in the World Does Fortran (and GNU C) Go?: Where to
     Install, for more information on determining where to install
     `g77'.  *Note Configuring gcc::, for more information on the
     configuration process triggered by invoking the `./configure'
     script.

Step 12: `make bootstrap'
     *Note Installing GNU CC: (gcc)Installation, for information on the
     kinds of diagnostics you should expect during this procedure.

     *Note Building gcc::, for complete `g77'-specific information on
     this step.

Step 13: `rm -fr stage1'
     You don't need to do this, but it frees up disk space.

Step 14: `make -k install'
     If this doesn't seem to work, try:

          make -k install install-libf77 install-f2c-all

     *Note Installation of Binaries::, for more information.

     *Note Updating Your Info Directory: Updating Documentation, for
     information on entering this manual into your system's list of
     texinfo manuals.

Complete Installation
=====================

   Here is the complete `g77'-specific information on how to configure,
build, and install `g77'.

Unpacking
---------

   The `gcc' source distribution is a stand-alone distribution.  It is
designed to be unpacked (producing the `gcc' source tree) and built as
is, assuming certain prerequisites are met (including the availability
of compatible UNIX programs such as `make', `cc', and so on).

   However, before building `gcc', you will want to unpack and merge
the `g77' distribution in with it, so that you build a Fortran-capable
version of `gcc', which includes the `g77' command, the necessary
run-time libraries, and this manual.

   Unlike `gcc', the `g77' source distribution is *not* a stand-alone
distribution.  It is designed to be unpacked and, afterwards,
immediately merged into an applicable `gcc' source tree.  That is, the
`g77' distribution *augments* a `gcc' distribution--without `gcc',
generally only the documentation is immediately usable.

   A sequence of commands typically used to unpack `gcc' and `g77' is:

     sh# cd /usr/src
     sh# gunzip -d < /usr/FSF/gcc-2.7.2.tar.gz | tar xf -
     sh# gunzip -d < /usr/FSF/g77-0.5.19.tar.gz | tar xf -
     sh# ln -s gcc-2.7.2 gcc
     sh# ln -s g77-0.5.19 g77
     sh# mv -i g77/* gcc

   *Notes:* The commands beginning with `gunzip...' might print `Broken
pipe...' as they complete.  That is nothing to worry about, unless you
actually *hear* a pipe breaking.  The `ln' commands are helpful in
reducing typing and clutter in installation examples in this manual.
Hereafter, the top level of `gcc' source tree is referred to as `gcc',
and the top level of just the `g77' source tree (prior to issuing the
`mv' command, above) is referred to as `g77'.

   There are three top-level names in a `g77' distribution:

     g77/COPYING.g77
     g77/README.g77
     g77/f

   All three entries should be moved (or copied) into a `gcc' source
tree (typically named after its version number and as it appears in the
FSF distributions--e.g. `gcc-2.7.2').

   `g77/f' is the subdirectory containing all of the code,
documentation, and other information that is specific to `g77'.  The
other two files exist to provide information on `g77' to someone
encountering a `gcc' source tree with `g77' already present, who has
not yet read these installation instructions and thus needs help
understanding that the source tree they are looking at does not come
from a single FSF distribution.  They also help people encountering an
unmerged `g77' source tree for the first time.

   *Note:* 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, are 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.

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

   After merging the `g77' source tree into the `gcc' source tree, the
final merge step is done by applying the pertinent patches the `g77'
distribution provides for the `gcc' source tree.

   Read the file `gcc/f/gbe/README', 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 an old, unsupported version, or a release one that is
newer than the newest `gcc' version supported by the version of `g77'
you have.

   As of version 0.5.18, `g77' modifies the version number of `gcc' via
the pertinent patches.  This is done because the resulting version of
`gcc' is deemed sufficiently different from the vanilla distribution to
make it worthwhile to present, to the user, information signaling the
fact that there are some differences.

   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/gbe/'), 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 applying the `g77' patch that is for the newest version of
`gcc' having the same MAJOR and MINOR fields, as this is likely to work.

   So, for example, if a particular version of `g77' has support for
`gcc' 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.diff' patch file provided with
`g77' (aside from some offsets reported by `patch', which usually are
harmless).

   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 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, `g77' often requires changes to contemporary versions of
`gcc'.  Also, 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).

   It is hoped that the GBE interface, and the `gcc' and `g77' products
in general, will stabilize sufficiently for the need for hand-patching
to disappear.

   Invoking `patch' as described in `gcc/f/gbe/README' can produce a
wide variety of printed output, from `Hmm, I can't seem to find a patch
in there anywhere...' to long lists of messages indicated that patches
are being found, applied successfully, and so on.

   If messages about "fuzz", "offset", or especially "reject files" are
printed, it might mean you applied the wrong patch file.  If you
believe this is the case, it is best to restart the sequence after
deleting (or at least renaming to unused names) the top-level
directories for `g77' and `gcc' and their symbolic links.  That is
because `patch' might have partially patched some `gcc' source files,
so reapplying the correct patch file might result in the correct
patches being applied incorrectly (due to the way `patch' necessarily
works).

   After `patch' finishes, the `gcc' directory might have old versions
of several files as saved by `patch'.  To remove these, after `cd gcc',
type `rm -i *.~*~'.

   *Note:* `g77''s configuration file `gcc/f/config-lang.in' ensures
that the source code for the version of `gcc' being configured has at
least one indication of being patched as required specifically by `g77'.
This configuration-time checking should catch failure to apply the
correct patch and, if so caught, should abort the configuration with an
explanation.  *Please* do not try to disable the check, otherwise `g77'
might well appear to build and install correctly, and even appear to
compile correctly, but could easily produce broken code.

   `diff -rcp2N' is used to create the patch files in `gcc/f/gbe/'.

Installing `f77'
----------------

   You should 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' does not do this by default.

   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.

   Usually, this means that, after typing `cd gcc', you would type
`touch f77-install-ok'.

   When you enable installation of `f77', either a link to or a direct
copy of the `g77' command is made.  Similarly, `f77.1' is installed as
a man page.

   (The `uninstall' target in the `gcc/Makefile' also tests this macro
and file, when invoked, to determine whether to delete the installed
copies of `f77' and `f77.1'.)

   *Note:* No attempt is yet made to install a program (like a shell
script) that provides compatibility with any other `f77' programs.
Only the most rudimentary invocations of `f77' will work the same way
with `g77'.

Installing `f2c'
----------------

   Currently, `g77' does not include `f2c' itself in its distribution.
However, it does include a modified version of the `libf2c'.  This
version is normally compatible with `f2c', but has been modified to
meet the needs of `g77' in ways that might possibly be incompatible
with some versions or configurations of `f2c'.

   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.

   Usually, this means that, after typing `cd gcc', you would type
`touch f2c-install-ok'.

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

Patching GNU Fortran
--------------------

   If you're using a SunOS system, you'll need to make the following
change to `gcc/f/proj.h': edit the line reading

     #define FFEPROJ_STRTOUL 1  ...

by replacing the `1' with `0'.  Or, you can avoid editing the source by
adding
     CFLAGS='-DFFEPROJ_STRTOUL=0 -g'
   to the command line for `make' when you invoke it.  (`-g' is the
default for `CFLAGS'.)

   This causes a minimal version of `strtoul()' provided as part of the
`g77' distribution to be compiled and linked into whatever `g77'
programs need it, since some systems (like SunOS) do not provide this
function in their system libraries.

   Similarly, a minimal version of `bsearch()' is available and can be
enabled by editing a line similar to the one for `strtoul()' above in
`gcc/f/proj.h', if your system libraries lack `bsearch()'.  The method
of overriding `X_CFLAGS' may also be used.

   These are not problems with `g77', which requires an ANSI C
environment.  You should upgrade your system to one that provides a
full ANSI C environment, or encourage the maintainers of `gcc' to
provide one to all `gcc'-based compilers in future `gcc' distributions.

   *Note Problems Installing::, for more information on why `strtoul()'
comes up missing and on approaches to dealing with this problem that
have already been tried.

Where in the World Does Fortran (and GNU C) 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 necessarily requires installation of a
`g77'-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 `g77'
being unable to compile Fortran source files, because when it calls on
`gcc' to do the actual compilation, `gcc' 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 `bin/gcc', and the
entire `lib/' directory, before you perform the actual installation (as
described in this manual).

   Existing `gcc' installations 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 /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.  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.)

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

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
`libf2c', which uses a variation of the GNU `autoconf' configuration
system.

   Generally, you shouldn't have to be concerned with either `g77' or
`libf2c' configuration, unless you're configuring `g77' as a
cross-compiler.  In this case, the `libf2c' 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 straight
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 is known to work
with GNU `make', but it is not known to 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 issues a warning message about this when you
configure for building binaries outside the source directory.

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 `libf2c'
automatically, you're ready to start the actual build by invoking
`make'.

   *Note:* You *must* have 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.

   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.

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.

   *Note:* If you do build Stage 3 and you compare the object files
produced by various stages, the file `gcc/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 `gcc/f/zzz.c' doesn't contain any actual
code.  It does allow you to override its use of `__DATE__' and
`__TIME__' by defining macros for the compilation--see the source code
for details.

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

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 C and Fortran compilers and the necessary run-time
libraries, issue the following command:

     make -k CC=gcc LANGUAGES=f77 all g77

   (The `g77' target is necessary because the `gcc' build procedures
apparently do not automatically build command drivers for languages in
subdirectories.  It's the `all' target that triggers building
everything except, apparently, the `g77' command itself.)

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

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 --driver=./xgcc -B./ -v
      ./xgcc -B./ -v -fnull-version -o /tmp/gfa03648 ...
     Reading specs from ./specs
     gcc version 2.7.1
      ./cpp -lang-c -v -isystem ./include -undef ...
     GNU CPP version 2.7.1 (80386, BSD syntax)
     #include "..." search starts here:
     #include <...> search starts here:
      ./include
      /usr/include
      /usr/i486-unknown-linuxaout/include
      /usr/lib/gcc-lib/i486-unknown-linuxaout/2.7.1/include
      /usr/include
     End of search list.
      ./f771 /tmp/cca03648.i -quiet -dumpbase null.F -version ...
     GNU F77 version 2.7.1 (80386, BSD syntax) compiled ...
     GNU Fortran Front End version 0.5.19 compiled: ...
      as -o /tmp/cca036481.o /tmp/cca03648.s
      ld -m i386linux -o /tmp/gfa03648 /usr/lib/crt0.o -L. ...
     /usr/lib/crt0.o(.text+0x35): undefined reference to `main'
     sh# ./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone
     Reading specs from ./specs
     gcc version 2.7.1
      ./cpp -lang-c -v -isystem ./include -undef ...
     GNU CPP version 2.7.1 (80386, BSD syntax)
     #include "..." search starts here:
     #include <...> search starts here:
      ./include
      /usr/include
      /usr/i486-unknown-linuxaout/include
      /usr/lib/gcc-lib/i486-unknown-linuxaout/2.7.1/include
      /usr/include
     End of search list.
      ./cc1 /tmp/cca03659.i -quiet -dumpbase null.c -version ...
     GNU C version 2.7.1 (80386, BSD syntax) compiled ...
      as -o /tmp/cca036591.o /tmp/cca03659.s
      ld -m i386linux -o /tmp/delete-me /usr/lib/crt0.o -L. ...
     /usr/lib/crt0.o(.text+0x35): 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 (even though
there is an undefined reference due to there being no main program
unit), and so on.

   If the output you get from either of the above two commands is
noticably 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 --driver=/usr/src/gcc/xgcc -B/usr/src/gcc/ ...

   To invoke `gcc', type:

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

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 LANGUAGES=f77 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 `libf2c.a' as expected, try
this:

     make -k ... install install-libf77 install-f2c-all

   We don't know why some non-GNU versions of `make' sometimes require
this alternate command, but they do.  (Remember to supply the
appropriate definitions for `CC' and `LANGUAGES' 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.

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

   As part of installing `g77', you should make sure users of `info'
can easily access this manual on-line.  Do this by making sure a line
such as the following exists in `/usr/info/dir', or in whatever file is
the top-level file in the `info' directory on your system (perhaps
`/usr/local/info/dir':

     * g77: (g77).           The GNU Fortran programming language.

   If the menu in `dir' is organized into sections, `g77' probably
belongs in a section with a name such as the following:

   * Writing Programs

   * Programming Languages

   * Languages Other Than C

   * Scientific/Engineering Tools

   * GNU Compilers

Missing `bison'?
----------------

   If you cannot install `bison', make sure you have started with a
*fresh* distribution of `gcc', do *not* do `make maintainer-clean' (in
other versions of `gcc', this was called `make realclean'), 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#

   These commands update the date-time-modified information for all the
files produced by the various invocations of `bison' in the current
versions of `gcc', so that `make' no longer believes it needs to update
them.  All of these files should already exist in a `gcc' distribution,
but the application of patches to upgrade to a newer version can leave
the modification information set such that the `bison' input files look
more "recent" than the corresponding output files.

   *Note:* New versions of `gcc' might change the set of files it
generates by invoking `bison'--if you cannot figure out for yourself
how to handle such a situation, try an older version of `gcc' until you
find someone who can (or until you obtain and install `bison').

Missing `makeinfo'?
-------------------

   If you cannot install `makeinfo', either use the `-k' option when
invoking make to specify any of the `install' or related targets, or
specify `MAKEINFO=echo' on the `make' command line.

   If you fail to do one of these things, some files, like `libf2c.a',
might not be installed, because the failed attempt by `make' to invoke
`makeinfo' causes it to cancel any further processing.

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

   (Make sure you clearly document, in the "advertising" for 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 are
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 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:

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

`bin/gcc'
     This is the command all users use to compile Fortran, either
     directly or indirectly via the `g77' command.  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.

`bin/f77'
     In installations with no non-GNU native Fortran compiler, this is
     the same as `bin/g77'.  Otherwise, it should be omitted from the
     distribution, so the one on already on a particular system does
     not get overwritten.

`info/g77.info*'
     This is the documentation for `g77'.

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

`man/man1/f77.1'
     In installations where `f77' is the same as `g77', this is the
     same as `man/man1/g77.1'.  Otherwise, it should be omitted from
     the distribution, so the one already on a particular system does
     not get overwritten.

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

`lib/gcc-lib/.../libf2c.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, 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 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 picking up 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.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.

Changing Settings Before Building
=================================

   Here are some internal `g77' settings that can be changed by editing
source files in `gcc/f/' before building.

   This information, and perhaps even these settings, represent
stop-gap solutions to problems people doing various ports of `g77' have
encountered.  As such, none of the following information is expected to
be pertinent in future versions of `g77'.

Maximum Stackable Size
----------------------

   `g77', on most machines, puts many 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, as it presents more opportunities for the GBE to
optimize the generated code).

   *Note:* Putting more variables and arrays on the stack might cause
problems due to system-dependent limits on stack size.  Also, the value
of `FFECOM_sizeMAXSTACKITEM' has no effect on automatic variables and
arrays.  *Note But-bugs::, for more information.

Floating-point Bit Patterns
---------------------------

   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/9.43578/'.)

Initialization of Large Aggregate Areas
---------------------------------------

   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 currently is quite small, since `g77' currently has a
known bug requiring too much memory and time to handle such cases.  In
`gcc/f/data.c', the macro `FFEDATA_sizeTOO_BIG_INIT_' is defined to the
minimum size for the warning to appear.  The size is specified in
storage units, which can be bytes, words, or whatever, on a
case-by-case basis.

   After changing this macro definition, you must (of course) rebuild
and reinstall `g77' for the change to take effect.

   Note that, as of version 0.5.18, improvements have reduced the scope
of the problem for *sparse* initialization of large arrays, especially
those with large, contiguous uninitialized areas.  However, the warning
is issued at a point prior to when `g77' knows whether the
initialization is sparse, and delaying the warning could mean it is
produced too late to be helpful.

   Therefore, the macro definition should not be adjusted to reflect
sparse cases.  Instead, adjust it to generate the warning when densely
initialized arrays begin to cause responses noticably slower than
linear performance would suggest.

Alpha Problems
--------------

   `g77' might warn when it is used to compile Fortran code for a
target configuration that is not basically a 32-bit machine (such as an
Alpha, which is a 64-bit machine, especially if it has a 64-bit
operating system running on it).  This is because `g77' is known to not
work properly on such configurations.  This is expected to be
completely fixed at 0.6, at which point the warning would be dropped.

   (Version 0.5.20 is expected to solve most of these problems, though,
as of this writing, work is still progressing in this area.)