     [file root.texi not included]

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

The following information describes how to install g77.

Note that, for users of the which-g77 version of g77, much of the information is obsolete, and is superseded by the which-gcc installation procedures. Such information is accordingly omitted and flagged as such.

The following information was last updated on 2000-12-21:

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

For users of the which-g77 version of g77, this information is superseded by the which-gcc installation instructions.

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

This information does not apply to the which-g77 version of g77,

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

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

For users of the which-g77 version of g77, this information is superseded by the which-gcc installation instructions.

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

For users of the which-g77 version of g77, this information is superseded by the which-gcc installation instructions.

Distributing Binaries
=====================

For users of the which-g77 version of g77, this information is superseded by the which-gcc installation instructions.