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.

     See Installing GNU CC (Using and Porting GNU CC), 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.

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

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

See Installation Problems (Using and Porting GNU CC), 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. See 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 Complete Installation, for detailed information on how to configure, build, and install g77 for your particular system. Also, see Known Causes of Trouble with GNU Fortran, 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]#

See Updating Your Info Directory, 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.

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

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

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

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

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

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

Step 12: make bootstrap
     See Installing GNU CC (Using and Porting GNU CC), for information on the kinds of diagnostics you should expect during this procedure.

     See 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

     See Installation of Binaries, for more information.

     See Updating Your Info Directory, 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---see User-Visible 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.

See 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. See Specifying Target Machine and Compiler Version (Using and Porting GNU CC), 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 Installing GNU CC (Using and Porting GNU CC), 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 Installing GNU CC (Using and Porting GNU CC). 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.

See Installing GNU CC (Using and Porting GNU CC), 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. See Known Causes of Trouble with GNU Fortran.

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 Installing GNU CC (Using and Porting GNU CC), 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. See Updating Your Info Directory.

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