* lex.c (ffelex_hash_): Avoid eating one whole line after

[pf3gnuchains/gcc-fork.git] / gcc / f / g77install.texi

@c Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000 Free Software Foundation, Inc.
@c This is part of the G77 manual.
@c For copying conditions, see the file g77.texi.

@set last-update-install 2000-12-21

@include root.texi

@node Installation
@chapter Installing GNU Fortran
@cindex installing, GNU Fortran

The following information describes how to install @code{g77}.

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

@ifset DEVELOPMENT
@emph{Warning:} The information below is still under development,
and might not accurately reflect the @code{g77} code base
of which it is a part.
Efforts are made to keep it somewhat up-to-date,
but they are particularly concentrated
on any version of this information
that is distributed as part of a @emph{released} @code{g77}.

In particular, while this information is intended to apply to
the @value{which-g77} version of @code{g77},
only an official @emph{release} of that version
is expected to contain documentation that is
most consistent with the @code{g77} product in that version.
@end ifset

The following information was last updated on @value{last-update-install}:

@menu
* Prerequisites::          Make sure your system is ready for @code{g77}.
* Problems Installing::    Known trouble areas.
* Settings::               Changing @code{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 @code{g77}.
@end menu

@node Prerequisites
@section Prerequisites
@cindex prerequisites

For users of the @value{which-g77} version of @code{g77},
this information is superseded by the
@value{which-gcc} installation instructions.

@node Problems Installing
@section Problems Installing
@cindex problems installing
@cindex installation problems

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.

@xref{Installation Problems,,,gcc,Using and Porting GNU CC},
for more information on installation problems that can afflict
either @code{gcc} or @code{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.
@end menu

@node General Problems
@subsection 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 @code{gcc} needn't be patched.
* Building GNU CC Necessary::  Why you can't build @emph{just} Fortran.
* Missing strtoul or bsearch:: When linking @code{f771} fails.
* Cleanup Kills Stage Directories::  For @code{g77} developers.
* LANGUAGES Macro Ignored::    Sometimes @code{LANGUAGES} is ignored.
@end menu

@node GNU C Required
@subsubsection GNU C Required
@cindex GNU C required
@cindex requirements, GNU C

Compiling @code{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 @code{gcc}
installed to build @code{g77}.
As long as you have a working C compiler, you can use a
``bootstrap'' build to automate the process of first building
@code{gcc} using the working C compiler you have, then building
@code{g77} and rebuilding @code{gcc} using that just-built @code{gcc},
and so on.

@node Patching GNU CC
@subsubsection Patching GNU CC
@cindex patch files
@cindex GBE

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

@node Building GNU CC Necessary
@subsubsection Building GNU CC Necessary
@cindex @code{gcc}, building
@cindex building gcc

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

@node Missing strtoul or bsearch
@subsubsection Missing strtoul or bsearch
@cindex bsearch
@cindex _bsearch
@cindex strtoul
@cindex _strtoul
@cindex undefined reference (_bsearch)
@cindex undefined reference (_strtoul)
@cindex f771, linking error for
@cindex linking error for f771
@cindex @code{ld}, error linking f771
@cindex @code{ld}, can't find _bsearch
@cindex @code{ld}, can't find _strtoul
@cindex SunOS4

This information does not apply to
the @value{which-g77} version of @code{g77},

@node Cleanup Kills Stage Directories
@subsubsection Cleanup Kills Stage Directories
@cindex stage directories
@cindex make clean

It'd be helpful if @code{g77}'s @file{Makefile.in} or @file{Make-lang.in}
would create the various @file{stage@var{n}} 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 @code{g77}
and version 1.1 of @code{egcs}.
Configuration itself no longer creates any particular directories
that are unique to @code{g77}.
The build procedures in @file{Make-lang.in} take care of
that, on demand.

@node LANGUAGES Macro Ignored
@subsubsection LANGUAGES Macro Ignored
@cindex @code{LANGUAGES} macro ignored
@cindex ignoring @code{LANGUAGES} macro

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

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

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

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

@node System-specific Problems
@subsection System-specific Problems

@cindex AIX
A linker bug on some versions of AIX 4.1 might prevent building
when @code{g77} is built within @code{gcc}.
@xref{LINKFAIL}.

@node Cross-compiler Problems
@subsection Cross-compiler Problems
@cindex cross-compiler, problems

@code{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, @code{g77} can be ported to any configuration to which
@code{gcc}, @code{f2c}, and @code{libf2c} can be ported and made
to work together, aside from the known problems described in this
manual.
If you want to port @code{g77} to a particular configuration,
you should first make sure @code{gcc} and @code{libf2c} can be
ported to that configuration before focusing on @code{g77}, because
@code{g77} is so dependent on them.

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

@itemize @bullet
@item
There is one known bug
(a design bug to be fixed in 0.6) that prevents configuration of
@code{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.

@item
@code{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.

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

@item
There are still some challenges putting together the right
run-time libraries (needed by @code{libg2c}) for a target
system, depending on the systems involved in the configuration.
(This is a general problem with cross-compilation, and with
@code{gcc} in particular.)
@end itemize

@node Settings
@section Changing Settings Before Building

Here are some internal @code{g77} settings that can be changed
by editing source files in @file{@value{path-g77}/} before building.

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

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

@node Larger File Unit Numbers
@subsection Larger File Unit Numbers
@cindex MXUNIT
@cindex unit numbers
@cindex maximum unit number
@cindex illegal unit number
@cindex increasing maximum unit number

As distributed, whether as part of @code{f2c} or @code{g77},
@code{libf2c} accepts file unit numbers only in the range
0 through 99.
For example, a statement such as @samp{WRITE (UNIT=100)} causes
a run-time crash in @code{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 @code{MXUNIT} macro, which represents the maximum unit
number, to an appropriately higher value.

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

@example
#define MXUNIT 100
@end example

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

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

Then build or rebuild @code{g77} as appropriate.

@emph{Note:} Changing this macro has @emph{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 @samp{WRITE (UNIT=100)},
but the library and operating system underlying @code{libf2c} might
disallow it if many other files have already been opened (via @code{OPEN} or
implicitly via @code{READ}, @code{WRITE}, and so on).
Information on how to increase these other limits should be found
in your system's documentation.

@node Always Flush Output
@subsection Always Flush Output
@cindex ALWAYS_FLUSH
@cindex synchronous write errors
@cindex disk full
@cindex flushing output
@cindex fflush()
@cindex I/O, flushing
@cindex output, flushing
@cindex writes, flushing
@cindex NFS
@cindex network file system

Some Fortran programs require output
(writes) to be flushed to the operating system (under UNIX,
via the @code{fflush()} library call) so that errors,
such as disk full, are immediately flagged via the relevant
@code{ERR=} and @code{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).

@code{libg2c} supports flagging write errors immediately when
it is built with the @code{ALWAYS_FLUSH} macro defined.
This results in a @code{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 @code{g77} you are building, you might wish to
modify the @code{g77} source tree so that the version of
@code{libg2c} is built with the @code{ALWAYS_FLUSH} macro
defined, enabling this behavior.

To do this, find this line in @file{@value{path-libf2c}/f2c.h} in
your @code{g77} source tree:

@example
/* #define ALWAYS_FLUSH */
@end example

Remove the leading @samp{/*@w{ }},
so the line begins with @samp{#define},
and the trailing @samp{@w{ }*/}.

Then build or rebuild @code{g77} as appropriate.

@node Maximum Stackable Size
@subsection Maximum Stackable Size
@vindex FFECOM_sizeMAXSTACKITEM
@cindex code, stack variables
@cindex maximum stackable size
@cindex stack, allocation
@cindex segmentation violation
@code{g77}, on most machines, puts many variables and arrays on the stack
where possible, and can be configured (by changing
@code{FFECOM_sizeMAXSTACKITEM} in @file{@value{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).

@emph{Note:} Putting more variables and arrays on the stack
might cause problems due to system-dependent limits on stack size.
Also, the value of @code{FFECOM_sizeMAXSTACKITEM} has no
effect on automatic variables and arrays.
@xref{But-bugs}, for more information.

@node Floating-point Bit Patterns
@subsection Floating-point Bit Patterns

@cindex cross-compiler, building
@cindex floating-point bit patterns
@cindex bit patterns
The @code{g77} build will crash if an attempt is made to build
it as a cross-compiler
for a target when @code{g77} cannot reliably determine the bit pattern of
floating-point constants for the target.
Planned improvements for version 0.6 of @code{g77}
will give it the capabilities it needs to not have to crash the build
but rather generate correct code for the target.
(Currently, @code{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 @samp{EQUIVALENCE (I,R)} and @samp{DATA R/9.43578/}.)

@node Large Initialization
@subsection Initialization of Large Aggregate Areas

@cindex speed, of compiler
@cindex slow compiler
@cindex memory utilization
@cindex large initialization
@cindex aggregate initialization
A warning message is issued when @code{g77} sees code that provides
initial values (e.g. via @code{DATA}) to an aggregate area (@code{COMMON}
or @code{EQUIVALENCE}, or even a large enough array or @code{CHARACTER}
variable)
that is large enough to increase @code{g77}'s compile time by roughly
a factor of 10.

This size currently is quite small, since @code{g77}
currently has a known bug requiring too much memory
and time to handle such cases.
In @file{@value{path-g77}/data.c}, the macro
@code{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 @code{g77} for
the change to take effect.

Note that, as of version 0.5.18, improvements have
reduced the scope of the problem for @emph{sparse}
initialization of large arrays, especially those
with large, contiguous uninitialized areas.
However, the warning is issued at a point prior to
when @code{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.

@node Alpha Problems Fixed
@subsection Alpha Problems Fixed

@cindex Alpha, support
@cindex 64-bit systems
@code{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 @code{g77} was known to not work
properly on such configurations.

As of version 0.5.20, @code{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.

@node Quick Start
@section Quick Start
@cindex quick start

For users of the @value{which-g77} version of @code{g77},
this information is superseded by the
@value{which-gcc} installation instructions.

@node Complete Installation
@section Complete Installation

For users of the @value{which-g77} version of @code{g77},
this information is superseded by the
@value{which-gcc} installation instructions.

@node Distributing Binaries
@section Distributing Binaries
@cindex binaries, distributing
@cindex code, distributing

For users of the @value{which-g77} version of @code{g77},
this information is superseded by the
@value{which-gcc} installation instructions.