This is Info file f/g77.info, produced by Makeinfo version 1.68 from
the input file ../../gcc/f/g77.texi.

   This file explains how to use the GNU Fortran system.

   Published by the Free Software Foundation 59 Temple Place - Suite 330
Boston, MA 02111-1307 USA

   Copyright (C) 1995-1997 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", and this permission notice, may be included in
translations approved by the Free Software Foundation instead of in the
original English.

   Contributed by James Craig Burley (<craig@jcb-sc.com>).  Inspired by
a first pass at translating `g77-0.5.16/f/DOC' that was contributed to
Craig by David Ronis (<ronis@onsager.chem.mcgill.ca>).

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* g77: (g77).                  The GNU Fortran compiler.
END-INFO-DIR-ENTRY


File: g77.info,  Node: C Interfacing Tools,  Next: C Access to Type Information,  Up: Interoperating with C and C++

C Interfacing Tools
-------------------

   Even if you don't actually use it as a compiler, `f2c' from
`ftp://ftp.netlib.org/f2c/src', can be a useful tool when you're
interfacing (linking) Fortran and C.  *Note Generating Skeletons and
Prototypes with `f2c': f2c Skeletons and Prototypes.

   To use `f2c' for this purpose you only need retrieve and build the
`src' directory from the distribution, consult the `README'
instructions there for machine-specifics, and install the `f2c' program
on your path.

   Something else that might be useful is `cfortran.h' from
`ftp://zebra/desy.de/cfortran'.  This is a fairly general tool which
can be used to generate interfaces for calling in both directions
between Fortran and C.  It can be used in `f2c' mode with
`g77'--consult its documentation for details.


File: g77.info,  Node: C Access to Type Information,  Next: f2c Skeletons and Prototypes,  Prev: C Interfacing Tools,  Up: Interoperating with C and C++

Accessing Type Information in C
-------------------------------

   Generally, C code written to link with `g77' code--calling and/or
being called from Fortran--should `#include <g2c.h>' to define the C
versions of the Fortran types.  Don't assume Fortran `INTEGER' types
correspond to C `int's, for instance; instead, declare them as
`integer', a type defined by `g2c.h'.  `g2c.h' is installed where `gcc'
will find it by default, assuming you use a copy of `gcc' compatible
with `g77', probably built at the same time as `g77'.


File: g77.info,  Node: f2c Skeletons and Prototypes,  Next: C++ Considerations,  Prev: C Access to Type Information,  Up: Interoperating with C and C++

Generating Skeletons and Prototypes with `f2c'
----------------------------------------------

   A simple and foolproof way to write `g77'-callable C routines--e.g.
to interface with an existing library--is to write a file (named, for
example, `fred.f') of dummy Fortran skeletons comprising just the
declaration of the routine(s) and dummy arguments plus `END' statements.
Then run `f2c' on file `fred.f' to produce `fred.c' into which you can
edit useful code, confident the calling sequence is correct, at least.
(There are some errors otherwise commonly made in generating C
interfaces with `f2c' conventions, such as not using `doublereal' as
the return type of a `REAL' `FUNCTION'.)

   `f2c' also can help with calling Fortran from C, using its `-P'
option to generate C prototypes appropriate for calling the Fortran.(1)
If the Fortran code containing any routines to be called from C is in
file `joe.f', use the command `f2c -P joe.f' to generate the file
`joe.P' containing prototype information.  `#include' this in the C
which has to call the Fortran routines to make sure you get it right.

   *Note Arrays (DIMENSION): Arrays, for information on the differences
between the way Fortran (including compilers like `g77') and C handle
arrays.

   ---------- Footnotes ----------

   (1) The files generated like this can also be used for inter-unit
consistency checking of dummy and actual arguments, although the
`ftnchek' tool from `ftp://ftp.netlib.org/fortran' or
`ftp://ftp.dsm.fordham.edu' is probably better for this purpose.


File: g77.info,  Node: C++ Considerations,  Next: Startup Code,  Prev: f2c Skeletons and Prototypes,  Up: Interoperating with C and C++

C++ Considerations
------------------

   `f2c' can be used to generate suitable code for compilation with a
C++ system using the `-C++' option.  The important thing about linking
`g77'-compiled code with C++ is that the prototypes for the `g77'
routines must specify C linkage to avoid name mangling.  So, use an
`extern "C"' declaration.  `f2c''s `-C++' option will take care of this
when generating skeletons or prototype files as above, and also avoid
clashes with C++ reserved words in addition to those in C.


File: g77.info,  Node: Startup Code,  Prev: C++ Considerations,  Up: Interoperating with C and C++

Startup Code
------------

   Unlike with some runtime systems, it shouldn't be necessary (unless
there are bugs) to use a Fortran main program unit to ensure the
runtime--specifically the I/O system--is initialized.

   However, to use the `g77' intrinsics `GETARG' and `IARGC', either
the `main' routine from the `libg2c' library must be used, or the
`f_setarg' routine (new as of `egcs' version 1.1 and `g77' version
0.5.23) must be called with the appropriate `argc' and `argv' arguments
prior to the program calling `GETARG' or `IARGC'.

   To provide more flexibility for mixed-language programming involving
`g77' while allowing for shared libraries, as of `egcs' version 1.1 and
`g77' version 0.5.23, `g77''s `main' routine in `libg2c' does the
following, in order:

  1. Calls `f_setarg' with the incoming `argc' and `argv' arguments, in
     the same order as for `main' itself.

     This sets up the command-line environment for `GETARG' and `IARGC'.

  2. Calls `f_setsig' (with no arguments).

     This sets up the signaling and exception environment.

  3. Calls `f_init' (with no arguments).

     This initializes the I/O environment, though that should not be
     necessary, as all I/O functions in `libf2c' are believed to call
     `f_init' automatically, if necessary.

     (A future version of `g77' might skip this explicit step, to speed
     up normal exit of a program.)

  4. Arranges for `f_exit' to be called (with no arguments) when the
     program exits.

     This ensures that the I/O environment is properly shut down before
     the program exits normally.  Otherwise, output buffers might not
     be fully flushed, scratch files might not be deleted, and so on.

     The simple way `main' does this is to call `f_exit' itself after
     calling `MAIN__' (in the next step).

     However, this does not catch the cases where the program might
     call `exit' directly, instead of using the `EXIT' intrinsic
     (implemented as `exit_' in `libf2c').

     So, `main' attempts to use the operating environment's `onexit' or
     `atexit' facility, if available, to cause `f_exit' to be called
     automatically upon any invocation of `exit'.

  5. Calls `MAIN__' (with no arguments).

     This starts executing the Fortran main program unit for the
     application.  (Both `g77' and `f2c' currently compile a main
     program unit so that its global name is `MAIN__'.)

  6. If no `onexit' or `atexit' is provided by the system, calls
     `f_exit'.

  7. Calls `exit' with a zero argument, to signal a successful program
     termination.

  8. Returns a zero value to the caller, to signal a successful program
     termination, in case `exit' doesn't exit on the system.

   All of the above names are C `extern' names, i.e. not mangled.

   When using the `main' procedure provided by `g77' without a Fortran
main program unit, you need to provide `MAIN__' as the entry point for
your C code.  (Make sure you link the object file that defines that
entry point with the rest of your program.)

   To provide your own `main' procedure in place of `g77''s, make sure
you specify the object file defining that procedure *before* `-lg2c' on
the `g77' command line.  Since the `-lg2c' option is implicitly
provided, this is usually straightforward.  (Use the `--verbose' option
to see how and where `g77' implicitly adds `-lg2c' in a command line
that will link the program.  Feel free to specify `-lg2c' explicitly,
as appropriate.)

   However, when providing your own `main', make sure you perform the
appropriate tasks in the appropriate order.  For example, if your
`main' does not call `f_setarg', make sure the rest of your application
does not call `GETARG' or `IARGC'.

   And, if your `main' fails to ensure that `f_exit' is called upon
program exit, some files might end up incompletely written, some
scratch files might be left lying around, and some existing files being
written might be left with old data not properly truncated at the end.

   Note that, generally, the `g77' operating environment does not
depend on a procedure named `MAIN__' actually being called prior to any
other `g77'-compiled code.  That is, `MAIN__' does not, itself, set up
any important operating-environment characteristics upon which other
code might depend.  This might change in future versions of `g77', with
appropriate notification in the release notes.

   For more information, consult the source code for the above routines.
These are in `egcs/libf2c/libF77/', named `main.c', `setarg.c',
`setsig.c', `getarg_.c', and `iargc_.c'.

   Also, the file `egcs/gcc/f/com.c' contains the code `g77' uses to
open-code (inline) references to `IARGC'.


File: g77.info,  Node: Installation,  Next: Debugging and Interfacing,  Prev: Other Languages,  Up: Top

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

   The following information describes how to install `g77'.

   Note that, for `egcs' users, much of this information is obsolete,
and is superceded by the `egcs' installation procedures.  Such
information is explicitly flagged as such.

   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.

* Menu:

* Prerequisites::          Make sure your system is ready for `g77'.
* Problems Installing::    Known trouble areas.
* Settings::               Changing `g77' internals before building.
* Quick Start::            The easier procedure for non-experts.
* Complete Installation::  For experts, or those who want to be: the details.
* Distributing Binaries::  If you plan on distributing your `g77'.


File: g77.info,  Node: Prerequisites,  Next: Problems Installing,  Up: Installation

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

   *Version info:* For `egcs' users, the following information is
superceded by the `egcs' installation instructions.

   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-2.8.1.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-2.8.1.tar.gz' into a directory
     (named `gcc-2.8.1') 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.24.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-2.8.1', 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.

     *Note Installing GNU CC: (gcc)Installation, 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'.  *Note 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'.  *Note 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'.  *Note 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'.  *Note 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').


File: g77.info,  Node: Problems Installing,  Next: Settings,  Prev: Prerequisites,  Up: Installation

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

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

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

* Menu:

* General Problems::         Problems afflicting most or all systems.
* System-specific Problems:: Problems afflicting particular systems.
* Cross-compiler Problems::  Problems afflicting cross-compilation setups.


File: g77.info,  Node: General Problems,  Next: System-specific Problems,  Up: Problems Installing

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

   These problems can occur on most or all systems.

* Menu:

* GNU C Required::             Why even ANSI C is not enough.
* Patching GNU CC::            Why `gcc' needn't be patched.
* Building GNU CC Necessary::  Why you can't build *just* Fortran.
* Missing strtoul or bsearch:: When linking `f771' fails.
* Cleanup Kills Stage Directories::  For `g77' developers.
* LANGUAGES Macro Ignored::    Sometimes `LANGUAGES' is ignored.


File: g77.info,  Node: GNU C Required,  Next: Patching GNU CC,  Up: General Problems

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.


File: g77.info,  Node: Patching GNU CC,  Next: Building GNU CC Necessary,  Prev: GNU C Required,  Up: General Problems

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.


File: g77.info,  Node: Building GNU CC Necessary,  Next: Missing strtoul or bsearch,  Prev: Patching GNU CC,  Up: General Problems

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.


File: g77.info,  Node: Missing strtoul or bsearch,  Next: Cleanup Kills Stage Directories,  Prev: Building GNU CC Necessary,  Up: General Problems

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

   *Version info:* The following information does not apply to the
`egcs' version of `g77'.

   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
`gcc/f/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 `gcc/f/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 `gcc/f/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 `gcc/f/proj.c' somewhat.


File: g77.info,  Node: Cleanup Kills Stage Directories,  Next: LANGUAGES Macro Ignored,  Prev: Missing strtoul or bsearch,  Up: General Problems

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.


File: g77.info,  Node: LANGUAGES Macro Ignored,  Prev: Cleanup Kills Stage Directories,  Up: General Problems

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


File: g77.info,  Node: System-specific Problems,  Next: Cross-compiler Problems,  Prev: General Problems,  Up: Problems Installing

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'.  *Note LINKFAIL::.


File: g77.info,  Node: Cross-compiler Problems,  Prev: System-specific Problems,  Up: Problems Installing

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


File: g77.info,  Node: Settings,  Next: Quick Start,  Prev: Problems Installing,  Up: Installation

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

* Menu:

* Larger File Unit Numbers::     Raising `MXUNIT'.
* Always Flush Output::          Synchronizing write errors.
* Maximum Stackable Size::       Large arrays forced off the stack.
* Floating-point Bit Patterns::  Possible programs building `g77'
                                   as a cross-compiler.
* Large Initialization::         Large arrays with `DATA'
                                   initialization.
* Alpha Problems Fixed::         Problems with 64-bit systems like
                                   Alphas now fixed?


File: g77.info,  Node: Larger File Unit Numbers,  Next: Always Flush Output,  Up: Settings

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 `f/runtime/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.


File: g77.info,  Node: Always Flush Output,  Next: Maximum Stackable Size,  Prev: Larger File Unit Numbers,  Up: Settings

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 `f/runtime/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.


File: g77.info,  Node: Maximum Stackable Size,  Next: Floating-point Bit Patterns,  Prev: Always Flush Output,  Up: Settings

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

   `g77', on most machines, puts many variables and arrays on the stack
where possible, and can be configured (by changing
`FFECOM_sizeMAXSTACKITEM' in `gcc/f/com.c') to force smaller-sized
entities into static storage (saving on stack space) or permit
larger-sized entities to be put on the stack (which can improve
run-time performance, as it presents more opportunities for the GBE to
optimize the generated code).

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


File: g77.info,  Node: Floating-point Bit Patterns,  Next: Large Initialization,  Prev: Maximum Stackable Size,  Up: Settings

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


File: g77.info,  Node: Large Initialization,  Next: Alpha Problems Fixed,  Prev: Floating-point Bit Patterns,  Up: Settings

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 noticeably slower than
linear performance would suggest.


File: g77.info,  Node: Alpha Problems Fixed,  Prev: Large Initialization,  Up: Settings

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.


File: g77.info,  Node: Quick Start,  Next: Complete Installation,  Prev: Settings,  Up: Installation

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

   *Version info:* For `egcs' users, the following information is
superceded by the `egcs' installation instructions.

   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.8.1.tar.gz
     /usr/FSF/g77-0.5.24.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-2.8.1.tar.gz | tar xf -
     [Might say "Broken pipe"...that is normal on some systems.]
     
     sh[ 3]# gunzip -c < /usr/FSF/g77-0.5.24.tar.gz | tar xf -
     ["Broken pipe" again possible.]
     
     sh[ 4]# ln -s gcc-2.8.1 gcc
     
     sh[ 5]# ln -s g77-0.5.24 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]#

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

   Elaborations of many of the above steps follows:

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

Step 3: `gunzip -d < /usr/FSF/g77-0.5.24.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
     0.5.24 of `g77'.

Step 4: `ln -s gcc-2.8.1 gcc'

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

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

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

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

Step 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 2.8.1, 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.

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

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

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

Step 10: `make compare'
     *Note Where to Port Bugs: Bug Lists, for information on where to
     report that you observed files having different contents during
     this phase.

     *Note How to Report Bugs: Bug Reporting, 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'.

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

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

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.


File: g77.info,  Node: Complete Installation,  Next: Distributing Binaries,  Prev: Quick Start,  Up: Installation

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

   *Version info:* For `egcs' users, the following information is
mostly superceded by the `egcs' installation instructions.

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

* Menu:

* Unpacking::
* Merging Distributions::
* Where to Install::
* Configuring gcc::
* Building gcc::
* Pre-installation Checks::
* Installation of Binaries::
* Updating Documentation::
* Missing tools?::


File: g77.info,  Node: Unpacking,  Next: Merging Distributions,  Up: Complete Installation

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

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

