     [file root.texi not included]

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.

The following information was last updated on 1999-07-17:

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 and tar
     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.

     The version of GNU gzip used to package this release is 1.2.4. (The version of GNU tar used to package this release is 1.12.)

gcc-version-gcc.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. Its size is approximately 8.4MB.

     If you've already unpacked gcc-version-gcc.tar.gz into a directory (named gcc-version-gcc) 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-version-g77.tar.gz
     You probably have already unpacked this package, or you are reading an advance copy of these installation instructions, which are contained in this distribution. The size of this package is approximately 1.4MB.

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

Enough disk space
     The amount of disk space needed to unpack, build, install, and use g77 depends on the type of system you're using, how you build g77, and how much of it you install (primarily, which languages you install).

     The sizes shown below assume all languages distributed in gcc-version-gcc, plus g77, will be built and installed. These sizes are indicative of GNU/Linux systems on Intel x86 running COFF and on Digital Alpha (AXP) systems running ELF. These should be fairly representative of 32-bit and 64-bit systems, respectively.

     Note that all sizes are approximate and subject to change without notice! They are based on preliminary releases of g77 made shortly before the public beta release.

       --- gcc and g77 distributions occupy 10MB packed, 40MB unpacked. These consist of the source code and documentation, plus some derived files (mostly documentation), for gcc and g77. Any deviations from these numbers for different kinds of systems are likely to be very minor.

       --- A ``bootstrap'' build requires an additional 91MB for a total of 132MB on an ix86, and an additional 136MB for a total of 177MB on an Alpha.

       --- Removing gcc/stage1 after the build recovers 13MB for a total of 119MB on an ix86, and recovers 21MB for a total of 155MB on an Alpha.

          After doing this, the integrity of the build can still be verified via make compare, and the gcc compiler modified and used to build itself for testing fairly quickly, using the copy of the compiler kept in gcc/stage2.

       --- Removing gcc/stage2 after the build further recovers 39MB for a total of 80MB, and recovers 57MB for a total of 98MB on an Alpha.

          After doing this, the compiler can still be installed, especially if GNU make is used to avoid gratuitous rebuilds (or, the installation can be done by hand).

       --- Installing gcc and g77 copies 23MB onto the --prefix disk for a total of 103MB on an ix86, and copies 31MB onto the --prefix disk for a total of 130MB on an Alpha.

     After installation, if no further modifications and builds of gcc or g77 are planned, the source and build directory may be removed, leaving the total impact on a system's disk storage as that of the amount copied during installation.

     Systems with the appropriate version of gcc installed don't require the complete bootstrap build. Doing a ``straight build'' requires about as much space as does a bootstrap build followed by removing both the gcc/stage1 and gcc/stage2 directories.

     Installing gcc and g77 over existing versions might require less new disk space, but note that, unlike many products, gcc installs itself in a way that avoids overwriting other installed versions of itself, so that other versions may easily be invoked (via gcc -V VERSION).

     So, the amount of space saved as a result of having an existing version of gcc and g77 already installed is not much---typically only the command drivers (gcc, g77, g++, and so on, which are small) and the documentation is overwritten by the new installation. The rest of the new installation is done without replacing existing installed versions (assuming they have different version numbers).

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). In particular, you probably need GNU make to build outside the source directory (with configure's --srcdir option.)

     The version of GNU make used to develop this release is 3.76.1.

cc
     Your system must have a working C compiler. If it doesn't, you might be able to obtain a prebuilt binary of some version of gcc from the network or on CD-ROM, perhaps from the FSF. The best source of information about binaries is probably a system-specific Usenet news group, initially via its FAQ.

     See Installing GNU CC (Using and Porting GNU CC), for more information on prerequisites for installing gcc.

sed
     All UNIX systems have sed, but some have a broken version that cannot handle configuring, building, or installing gcc or g77.

     The version of GNU sed used to develop this release is 2.05. (Note that GNU sed version 3.0 was withdrawn by the FSF---if you happen to have this version installed, replace it with version 2.05 immediately. See a GNU distribution site for further explanation.)

root access or equivalent
     To perform the complete installation procedures on a system, you need to have root access to that system, or equivalent access to the --prefix directory tree specified on the configure command line.

     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.

autoconf
     The version of GNU autoconf used to develop this release is 2.12.

     autoconf is not needed in the typical case of installing gcc and g77. See Missing tools?, for information on when it might be needed and how to work around not having it.

bison
     The version of GNU bison used to develop this release is 1.25.

     bison is not needed in the typical case of installing gcc and g77. See Missing tools?, for information on when it might be needed and how to work around not having it.

gperf
     The version of GNU gperf used to develop this release is 2.5.

     gperf is not needed in the typical case of installing gcc and g77. See Missing tools?, for information on when it might be needed and how to work around not having it.

makeinfo
     The version of GNU makeinfo used to develop this release is 1.68.

     makeinfo is part of the GNU texinfo package; makeinfo version 1.68 is distributed as part of GNU texinfo version 3.12.

     makeinfo is not needed in the typical case of installing gcc and g77. See Missing tools?, for information on when it might be needed and how to work around not having it.

     An up-to-date version of GNU makeinfo is still convenient when obtaining a new version of a GNU distribution such as gcc or g77, as it allows you to obtain the .diff.gz file instead of the entire .tar.gz distribution (assuming you have installed patch).

patch
     The version of GNU patch used to develop this release is 2.5.

     Beginning with g77 version 0.5.23, it is no longer necessary to patch the gcc back end to build g77.

     An up-to-date version of GNU patch is still convenient when obtaining a new version of a GNU distribution such as gcc or g77, as it allows you to obtain the .diff.gz file instead of the entire .tar.gz distribution (assuming you have installed the tools needed to rebuild derived files, such as makeinfo).

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

These problems can occur on most or all systems.

GNU C Required
..............

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.

This requirement does not mean you must already have gcc installed to build g77. As long as you have a working C compiler, you can use a ``bootstrap'' build to automate the process of first building gcc using the working C compiler you have, then building g77 and rebuilding gcc using that just-built gcc, and so on.

Patching GNU CC
...............

g77 no longer requires application of a patch file to the gcc compiler tree. In fact, no such patch file is distributed with g77. This is as of version 0.5.23 and egcs version 1.0.

Building GNU CC Necessary
.........................

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.

Missing strtoul or bsearch
..........................

On SunOS4 systems, linking the f771 program used to produce an error message concerning an undefined symbol named _strtoul, because the strtoul library function is not provided on that system.

Other systems have, in the past, been reported to not provide their own strtoul or bsearch function.

Some versions g77 tried to default to providing bare-bones versions of bsearch and strtoul automatically, but every attempt at this has failed for at least one kind of system.

To limit the failures to those few systems actually missing the required routines, the bare-bones versions are still provided, in path-g77/proj.c, if the appropriate macros are defined. These are NEED_BSEARCH for bsearch and NEED_STRTOUL for NEED_STRTOUL.

Therefore, if you are sure your system is missing bsearch or strtoul in its library, define the relevant macro(s) before building g77. This can be done by editing path-g77/proj.c and inserting either or both of the following #define statements before the comment shown:

     /* Insert #define statements here.  */

     #define NEED_BSEARCH
     #define NEED_STRTOUL

Then, continue configuring and building g77 as usual.

Or, you can define these on the make command line. To build with the bundled cc on SunOS4, for example, try:

     make bootstrap BOOT_CFLAGS='-O2 -g -DNEED_STRTOUL'

If you then encounter problems compiling path-g77/proj.c, it might be due to a discrepancy between how bsearch or strtoul are defined by that file and how they're declared by your system's header files.

In that case, you'll have to use some basic knowledge of C to work around the problem, perhaps by editing path-g77/proj.c somewhat.

Cleanup Kills Stage Directories
...............................

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

That help has arrived as of version 0.5.23 of g77 and version 1.1 of egcs. Configuration itself no longer creates any particular directories that are unique to g77. The build procedures in Make-lang.in take care of that, on demand.

LANGUAGES Macro Ignored
.......................

Prior to version 0.5.23 of g77 and version 1.1 of egcs, g77 would sometimes ignore the absence of f77 and F77 in the LANGUAGES macro definition used for the make command being processed.

As of g77 version 0.5.23 and egcs version 1.1, g77 now obeys this macro in all relevant situations.

However, in versions of gcc through 2.8.1, non-g77 portions of gcc, such as g++, are known to go ahead and perform various language-specific activities when their respective language strings do not appear in the LANGUAGES macro in effect during that invocation of make.

It is expected that these remaining problems will be fixed in a future version of gcc.

System-specific Problems
------------------------

A linker bug on some versions of AIX 4.1 might prevent building when g77 is built within gcc. It might also occur when building within egcs.

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.

  * Improvements to the way libg2c is built could make building g77 as a cross-compiler easier---for example, passing and using $(LD) and $(AR) in the appropriate ways. (This is improved in the egcs version of g77, especially as of version 1.1.)

  * There are still some challenges putting together the right run-time libraries (needed by libg2c) 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.)

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

Here are some internal g77 settings that can be changed by editing source files in path-g77/ 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.

Larger File Unit Numbers
------------------------

As distributed, whether as part of f2c or g77, libf2c accepts file unit numbers only in the range 0 through 99. For example, a statement such as WRITE (UNIT=100) causes a run-time crash in libf2c, because the unit number, 100, is out of range.

If you know that Fortran programs at your installation require the use of unit numbers higher than 99, you can change the value of the MXUNIT macro, which represents the maximum unit number, to an appropriately higher value.

To do this, edit the file path-libf2c/libI77/fio.h in your g77 source tree, changing the following line:

     #define MXUNIT 100

Change the line so that the value of MXUNIT is defined to be at least one greater than the maximum unit number used by the Fortran programs on your system.

(For example, a program that does WRITE (UNIT=255) would require MXUNIT set to at least 256 to avoid crashing.)

Then build or rebuild g77 as appropriate.

Note: Changing this macro has no effect on other limits your system might place on the number of files open at the same time. That is, the macro might allow a program to do WRITE (UNIT=100), but the library and operating system underlying libf2c might disallow it if many other files have already been opened (via OPEN or implicitly via READ, WRITE, and so on). Information on how to increase these other limits should be found in your system's documentation.

Always Flush Output
-------------------

Some Fortran programs require output (writes) to be flushed to the operating system (under UNIX, via the fflush() library call) so that errors, such as disk full, are immediately flagged via the relevant ERR= and IOSTAT= mechanism, instead of such errors being flagged later as subsequent writes occur, forcing the previously written data to disk, or when the file is closed.

Essentially, the difference can be viewed as synchronous error reporting (immediate flagging of errors during writes) versus asynchronous, or, more precisely, buffered error reporting (detection of errors might be delayed).

libg2c supports flagging write errors immediately when it is built with the ALWAYS_FLUSH macro defined. This results in a libg2c that runs slower, sometimes quite a bit slower, under certain circumstances---for example, accessing files via the networked file system NFS---but the effect can be more reliable, robust file I/O.

If you know that Fortran programs requiring this level of precision of error reporting are to be compiled using the version of g77 you are building, you might wish to modify the g77 source tree so that the version of libg2c is built with the ALWAYS_FLUSH macro defined, enabling this behavior.

To do this, find this line in path-libf2c/f2c.h in your g77 source tree:

     /* #define ALWAYS_FLUSH */

Remove the leading /* , so the line begins with #define, and the trailing  */.

Then build or rebuild g77 as appropriate.

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 path-g77/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 version 0.6 of g77 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 path-g77/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 noticeably slower than linear performance would suggest.

Alpha Problems Fixed
--------------------

g77 used to warn when it was 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). That was because g77 was known to not work properly on such configurations.

As of version 0.5.20, g77 is believed to work well enough on such systems. So, the warning is no longer needed or provided.

However, support for 64-bit systems, especially in areas such as cross-compilation and handling of intrinsics, is still incomplete. The symptoms are believed to be compile-time diagnostics rather than the generation of bad code. It is hoped that version 0.6 will completely support 64-bit systems.

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-version-gcc.tar.gz
     /usr/FSF/g77-version-g77.tar.gz

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-version-gcc.tar.gz | tar xf -
     [Might say "Broken pipe"...that is normal on some systems.]
     sh[ 3]# gunzip -c < /usr/FSF/g77-version-g77.tar.gz | tar xf -
     ["Broken pipe" again possible.]
     sh[ 4]# ln -s gcc-version-gcc gcc
     sh[ 5]# ln -s g77-version-g77 g77
     sh[ 6]# mv -i g77/* gcc
     [No questions should be asked by mv here; or, you made a mistake.]
     sh[ 7]# cd gcc
     sh[ 8]# ./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[ 9]# make bootstrap
     [This takes a long time, and is where most problems occur.]
     sh[10]# make compare
     [This verifies that the compiler is `sane'.
     If any files are printed, you have likely found a g77 bug.]
     sh[11]# rm -fr stage1
     sh[12]# make -k install
     [The actual installation.]
     sh[13]# g77 -v
     [Verify that g77 is installed, obtain version info.]
     sh[14]#

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 3: gunzip -d < /usr/FSF/g77-version-g77.tar.gz | tar xf -
     It is not always necessary to obtain the latest version of g77 as a complete .tar.gz file if you have a complete, earlier distribution of g77. If appropriate, you can unpack that earlier version of g77, and then apply the appropriate patches to achieve the same result---a source tree containing version version-g77 of g77.

Step 4: ln -s gcc-version-gcc gcc

Step 5: ln -s g77-version-g77 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-version-g77 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 8: ./configure --prefix=/usr
     This is where you specify that the g77 and gcc executables are to be installed in /usr/bin/, the g77 and gcc documentation is to be installed in /usr/info/ and /usr/man/, and so on.

     You should ensure that any existing installation of the gcc executable is in /usr/bin/.

     However, if that existing version of gcc is not version-gcc, or if you simply wish to avoid risking overwriting it with a newly built copy of the same version, you can specify --prefix=/usr/local (which is the default) or some other path, and invoke the newly installed version directly from that path's bin directory.

     See Where in the World Does Fortran (and GNU CC) 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 9: 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 10: make compare
     See Where to Port Bugs, for information on where to report that you observed files having different contents during this phase.

     See How to Report Bugs, for information on how to report bugs like this.

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

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

          make -k install install-libf77

     Or, make sure you're using GNU make.

     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.

Step 13: g77 -v
     If this command prints approximately 25 lines of output, including the GNU Fortran Front End version number (which should be the same as the version number for the version of g77 you just built and installed) and the version numbers for the three parts of the libf2c library (libF77, libI77, libU77), and those version numbers are all in agreement, then there is a high likelihood that the installation has been successfully completed.

     You might consider doing further testing. For example, log in as a non-privileged user, then create a small Fortran program, such as:

                PROGRAM SMTEST
                DO 10 I=1, 10
                   PRINT *, 'Hello World #', I
          10    CONTINUE
                END

     Compile, link, and run the above program, and, assuming you named the source file smtest.f, the session should look like this:

          sh# g77 -o smtest smtest.f
          sh# ./smtest
           Hello World # 1
           Hello World # 2
           Hello World # 3
           Hello World # 4
           Hello World # 5
           Hello World # 6
           Hello World # 7
           Hello World # 8
           Hello World # 9
           Hello World # 10
          sh#

     If invoking g77 doesn't seem to work, the problem might be that you've installed it in a location that is not in your shell's search path. For example, if you specified --prefix=/gnu, and /gnu/bin is not in your PATH environment variable, you must explicitly specify the location of the compiler via /gnu/bin/g77 -o smtest smtest.f.

     After proper installation, you don't need to keep your gcc and g77 source and build directories around anymore. Removing them can free up a lot of disk space.

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 -c /usr/FSF/gcc-version-gcc.tar.gz | tar xf -
     sh# gunzip -c /usr/FSF/g77-version-g77.tar.gz | tar xf -
     sh# ln -s gcc-version-gcc gcc
     sh# ln -s g77-version-g77 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-version-gcc).

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 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, you have put together a complete g77 source tree.

As of version 0.5.23, g77 no longer modifies the version number of gcc, nor does it patch gcc itself.

g77 still depends on being merged with an appropriate version of gcc. For version version-g77 of g77, the specific version of gcc supported is version-gcc.

However, other versions of gcc might be suitable ``hosts'' for this version of g77.

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 path-g77/INSTALL/, which contains these installation instructions in plain-text format), 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 that version of gcc. Since it has the same MAJOR and MINOR fields, the resulting combination is likely to work.

So, for example, if a particular version of g77 has support for gcc versions 2.8.0 and 2.8.1, it is likely that gcc-2.8.2 would work well with g77.

However, gcc-2.9.0 would almost certainly not work with that version of g77 without appropriate modifications, so a new version of g77 would be needed.

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

Where in the World Does Fortran (and GNU CC) 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 normally includes installation of a Fortran-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 gcc being unable to compile Fortran source files, because when the older version of gcc is invoked, it 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 /usr/bin/gcc, and the entire /usr/lib directory, before you perform the actual installation (as described in this manual).

Existing gcc installations typically are found in /usr or /usr/local. (This means the commands are installed in /usr/bin or /usr/local/bin, the libraries in /usr/lib or /usr/local/lib, and so on.)

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. (The output also is likely to include a diagnostic from the linker, since there's no main_() function.) 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, although, in this case, g77 is an augmentation of the gcc 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 libg2c, which uses a variation of the GNU autoconf configuration system.

Generally, you shouldn't have to be concerned with either g77 or libg2c configuration, unless you're configuring g77 as a cross-compiler. In this case, the libg2c 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 plain-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, or by starting in an empty directory and typing a command such as ../gcc/configure to build with separate build and source directories, is known to work with GNU make, but it is known to not 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 used to issue a warning message about this when configuring for building binaries outside the source directory, but no longer does this as of version 0.5.23.

Instead, g77 simply rejects most common attempts to build it using a non-GNU make when the build directory is not the same as the source directory, issuing an explanatory diagnostic.

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

Note: You must have run the configure script in gcc 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.

Also, 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 compilers along with the necessary run-time libraries, issue the following command:

     make -k CC=gcc

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. Consider treating them as gcc bugs instead.

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 -B./ -v
     g77 version version-g77
     Driving: ./g77 -B./ -v -c -xf77-version /dev/null -xnone
     Reading specs from ./specs
     gcc version version-gcc
      cpp -lang-c -v -isystem ./include -undef -D__GNUC__=2 ...
     GNU CPP version version-gcc (Alpha GNU/Linux with ELF)
     #include "..." search starts here:
     #include <...> search starts here:
      include
      /usr/alpha-linux/include
      /usr/lib/gcc-lib/alpha-linux/version-gcc/include
      /usr/include
     End of search list.
      ./f771 -fnull-version -quiet -dumpbase g77-version.f -version ...
     GNU F77 version version-gcc (alpha-linux) compiled ...
     GNU Fortran Front End version version-g77
      as -nocpp -o /tmp/cca14485.o /tmp/cca14485.s
      ld -m elf64alpha -G 8 -O1 -dynamic-linker /lib/ld-linux.so.2 ...
      /tmp/cca14485
     __G77_LIBF77_VERSION__: version-g77
     @(#)LIBF77 VERSION 19970919
     __G77_LIBI77_VERSION__: version-g77
     @(#) LIBI77 VERSION pjw,dmg-mods 19980405
     __G77_LIBU77_VERSION__: version-g77
     @(#) LIBU77 VERSION 19970919
     sh# ./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone
     Reading specs from ./specs
     gcc version version-gcc
      ./cpp -lang-c -v -isystem ./include -undef ...
     GNU CPP version version-gcc (Alpha GNU/Linux with ELF)
     #include "..." search starts here:
     #include <...> search starts here:
      include
      /usr/alpha-linux/include
      /usr/lib/gcc-lib/alpha-linux/version-gcc/include
      /usr/include
     End of search list.
      ./cc1 /tmp/cca18063.i -quiet -dumpbase null.c -version ...
     GNU C version version-gcc (alpha-linux) compiled ...
      as -nocpp -o /tmp/cca180631.o /tmp/cca18063.s
      ld -m elf64alpha -G 8 -O1 -dynamic-linker /lib/ld-linux.so.2 ...
     /usr/lib/crt1.o: In function `_start':
     ../sysdeps/alpha/elf/start.S:77: undefined reference to `main'
     ../sysdeps/alpha/elf/start.S:77: 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, and so on.

If the output you get from either of the above two commands is noticeably 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 -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 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 libg2c.a as expected, try this:

     make -k ... install install-libf77

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

Note: g77 no longer installs files not directly part of g77, such as /usr/bin/f77, /usr/lib/libf2c.a, and /usr/include/f2c.h, or their /usr/local equivalents.

See Distributing Binaries, for information on how to accommodate systems with no existing non-g77 f77 compiler and systems with f2c installed.

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

As part of installing g77, you should make sure users of info can easily access this manual on-line.

g77 does this automatically by invoking the install-info command when you use make install to install g77.

If that fails, or if the info directory it updates is not the one normally accessed by users, consider invoking it yourself. For example:

     install-info --info-dir=/usr/info /usr/info/g77.info

The above example assumes the g77 documentation already is installed in /usr/info and that /usr/info/dir is the file you wish to update. Adjust the command accordingly, if those assumptions are wrong.

Missing tools?
--------------

A build of gcc might fail due to one or more tools being called upon by make (during the build or install process), when those tools are not installed on your system.

This situation can result from any of the following actions (performed by you or someone else):

  * Changing the source code or documentation yourself (as a developer or technical writer).

  * Applying a patch that changes the source code or documentation (including, sometimes, the official patches distributed by the FSF).

  * Deleting the files that are created by the (missing) tools.

     The make maintainer-clean command is supposed to delete these files, so invoking this command without having all the appropriate tools installed is not recommended.

  * Creating the source directory using a method that does not preserve the date-time-modified information in the original distribution.

     For example, the UNIX cp -r command copies a directory tree without preserving the date-time-modified information. Use cp -pr instead.

The reason these activities cause make to try and invoke tools that it probably wouldn't when building from a perfectly ``clean'' source directory containing gcc and g77 is that some files in the source directory (and the corresponding distribution) aren't really source files, but derived files that are produced by running tools with the corresponding source files as input. These derived files depend, in make terminology, on the corresponding source files.

make determines that a file that depends on another needs to be updated if the date-time-modified information for the source file shows that it is newer than the corresponding information for the derived file.

If it makes that determination, make runs the appropriate commands (specified in the ``Makefile'') to update the derived file, and this process typically calls upon one or more installed tools to do the work.

The ``safest'' approach to dealing with this situation is to recreate the gcc and g77 source directories from complete gcc and g77 distributions known to be provided by the FSF.

Another fairly ``safe'' approach is to simply install the tools you need to complete the build process. This is especially appropriate if you've changed the source code or applied a patch to do so.

However, if you're certain that the problem is limited entirely to incorrect date-time-modified information, that there are no discrepancies between the contents of source files and files derived from them in the source directory, you can often update the date-time-modified information for the derived files to work around the problem of not having the appropriate tools installed.

On UNIX systems, the simplest way to update the date-time-modified information of a file is to use the use the touch command.

How to use touch to update the derived files updated by each of the tools is described below. Note: New versions of g77 might change the set of files it generates by invoking each of these tools. If you cannot figure out for yourself how to handle such a situation, try an older version of g77 until you find someone who can (or until you obtain and install the relevant tools).

Missing autoconf?
.................

If you cannot install autoconf, make sure you have started with a fresh distribution of gcc and g77, do not do make maintainer-clean, and, to ensure that autoconf is not invoked by make during the build, type these commands:

     sh# cd path-libf2c
     sh# touch configure libU77/configure
     sh# cd ../../..
     sh#

Missing bison?
..............

If you cannot install bison, make sure you have started with a fresh distribution of gcc, do not do make maintainer-clean, 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# cd ..
     sh#

Missing gperf?
..............

If you cannot install gperf, make sure you have started with a fresh distribution of gcc, do not do make maintainer-clean, and, to ensure that gperf is not invoked by make during the build, type these commands:

     sh# cd gcc
     sh# touch c-gperf.h
     sh# cd ..
     sh#

Missing makeinfo?
.................

If makeinfo is needed but unavailable when installing (via make install), some files, like libg2c.a, might not be installed, because once make determines that it cannot invoke makeinfo, it cancels any further processing.

If you cannot install makeinfo, an easy work-around is to specify MAKEINFO=true on the make command line, or to specify the -k option (make -k install).

Another approach is to force the relevant files to be up-to-date by typing these commands and then re-trying the installation step:

     sh# cd gcc
     sh# touch f/g77.info f/BUGS f/INSTALL f/NEWS
     sh# cd ..
     sh#

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, although a script that accepts ``classic'' UNIX f77 options and translates the command-line to the appropriate g77 command line would be more appropriate. If you do this, please also provide a ``man page'' in man/man1/f77.1 describing the command. (A link to man/man1/g77.1 is appropriate if bin/f77 is a link to bin/g77.)

For a system that might already have f2c installed, consider whether inter-operation with g77 will be important to users of f2c on that system. 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 that, whenever they intend to combine f2c-produced code with g77-produced code in an executable, they:

  * Use the lib/gcc-lib/.../include/g2c.h file generated by the g77 build in place of the f2c.h file that normally comes with f2c (or versions of g77 prior to 0.5.23) when compiling all of the f2c-produced C code

  * Link to the lib/gcc-lib/.../libg2c.a library built by the g77 build instead of the libf2c.a library that normally comes with f2c (or versions of g77 prior to 0.5.23)

How you choose to effect the above depends on whether the existing installation of f2c must be maintained.

In any case, it is important to try and ensure that the installation keeps working properly even after subsequent re-installation of f2c, which probably involves overwriting /usr/local/lib/libf2c.a and /usr/local/include/f2c.h, or similar.

At least, copying libg2c.a and g2c.h into the appropriate ``public'' directories allows users to more easily select the version of libf2c they wish to use for a particular build. The names are changed by g77 to make this coexistence easier to maintain; even if f2c is installed later, the g77 files normally installed by its installation process aren't disturbed. Use of symbolic links from one set of files to another might result in problems after a subsequent reinstallation of either f2c or g77, so be sure to alert users of your distribution accordingly.

(Make sure you clearly document, in the description of 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 will be 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 new version of /usr/bin/f77 or /usr/local/bin/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 some users use to compile Fortran, typically when compiling programs written in other languages at the same time. 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.

info/g77.info*
     This is the documentation for g77. If it is not included, users will have trouble understanding diagnostics messages and other such things, and will send you a lot of email asking questions.

     Please edit this documentation (by editing path-g77/*.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. It is not always kept up-to-date, but you might as well include it for people who really like ``man'' pages.

lib/gcc-lib
     This is the directory containing the ``private'' files installed by and for gcc, g77, g++, and other GNU compilers.

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

lib/gcc-lib/.../libg2c.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, because they involve doing things like adding to the list of acceptable compiler options (so, for example, cc1plus accepts, and ignores, options that only f771 actually processes).

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 invoking 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.org has received a fair number 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.