From 4ac480d6052ec2c98b6cff0c4f3f959cfc68b1dc Mon Sep 17 00:00:00 2001 From: Jeffrey A Law Date: Fri, 19 Sep 1997 01:28:39 +0000 Subject: g77install.texi: Renamed from install.texi * g77install.texi: Renamed from install.texi * g77.texi: Corresponding changes. Fixes problem with g77.texi getting gcc/install.texi instead of gcc/f/install.texi when building in the source tree. From-SVN: r15556 --- gcc/f/ChangeLog.egcs | 3 + gcc/f/g77.texi | 2 +- gcc/f/g77install.texi | 2114 +++++++++++++++++++++++++++++++++++++++++++++++++ gcc/f/install.texi | 2114 ------------------------------------------------- 4 files changed, 2118 insertions(+), 2115 deletions(-) create mode 100644 gcc/f/g77install.texi delete mode 100644 gcc/f/install.texi (limited to 'gcc') diff --git a/gcc/f/ChangeLog.egcs b/gcc/f/ChangeLog.egcs index 5b6fe83..7c1e265 100644 --- a/gcc/f/ChangeLog.egcs +++ b/gcc/f/ChangeLog.egcs @@ -1,5 +1,8 @@ Thu Sep 18 17:31:38 1997 Jeffrey A Law (law@cygnus.com) + * g77install.texi: Renamed from install.texi + * g77.texi: Corresponding changes. + * fini.c (main): Return type is int. * com.c (lang_printable_name): Use verbosity argument. diff --git a/gcc/f/g77.texi b/gcc/f/g77.texi index 59ba3b8..c5b5bb6 100644 --- a/gcc/f/g77.texi +++ b/gcc/f/g77.texi @@ -7973,7 +7973,7 @@ provide a dummy version of this to avoid linkers complaining about failure to resolve @code{MAIN__()} if linking against @file{libf2c} and not using @code{main()} from it. -@include install.texi +@include g77install.texi @node Debugging and Interfacing @chapter Debugging and Interfacing diff --git a/gcc/f/g77install.texi b/gcc/f/g77install.texi new file mode 100644 index 0000000..acee44a --- /dev/null +++ b/gcc/f/g77install.texi @@ -0,0 +1,2114 @@ +@c Copyright (C) 1995-1997 Free Software Foundation, Inc. +@c This is part of the G77 manual. +@c For copying conditions, see the file g77.texi. + +@c The text of this file appears in the file INSTALL +@c in the G77 distribution, as well as in the G77 manual. + +@c 1997-09-09 + +@ifclear INSTALLONLY +@node Installation +@chapter Installing GNU Fortran +@end ifclear +@cindex installing GNU Fortran + +The following information describes how to install @code{g77}. + +The information in this file generally pertains to dealing +with @emph{source} distributions of @code{g77} and @code{gcc}. +It is possible that some of this information will be applicable +to some @emph{binary} distributions of these products---however, +since these distributions are not made by the maintainers of +@code{g77}, responsibility for binary distributions rests with +whoever built and first distributed them. + +Nevertheless, efforts to make @code{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 @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 + +The procedures described to unpack, configure, build, and +install @code{g77} assume your system has certain programs +already installed. + +The following prerequisites should be met by your +system before you follow the @code{g77} installation instructions: + +@table @asis +@item @code{gzip} +To unpack the @code{gcc} and @code{g77} distributions, +you'll need the @code{gunzip} utility in the @code{gzip} +distribution. +Most UNIX systems already have @code{gzip} installed. +If yours doesn't, you can get it from the FSF. + +Note that you'll need @code{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 @code{gzip} used to package this release +is 1.24. +(The version of GNU @code{tar} used to package this release +is 1.11.2.) + +@item @file{gcc-2.7.2.3.tar.gz} +You need to have this, or some other applicable, version +of @code{gcc} on your system. +The version should be an exact copy of a distribution +from the FSF. +Its size is approximately 7.1MB. + +If you've already unpacked @file{gcc-2.7.2.3.tar.gz} into a +directory (named @file{gcc-2.7.2.3}) called the @dfn{source tree} +for @code{gcc}, you can delete the distribution +itself, but you'll need to remember to skip any instructions to unpack +this distribution. + +Without an applicable @code{gcc} source tree, you cannot +build @code{g77}. +You can obtain an FSF distribution of @code{gcc} from the FSF. + +@item @file{g77-0.5.21.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.5MB. + +You can obtain an FSF distribution of @code{g77} from the FSF, +the same way you obtained @code{gcc}. + +@item Enough disk space +The amount of disk space needed to unpack, build, install, +and use @code{g77} depends on the type of system you're +using, how you build @code{g77}, and how much of it you +install (primarily, which languages you install). + +The sizes shown below assume all languages distributed +in @code{gcc-2.7.2.3}, plus @code{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. + +@itemize --- +@item +@code{gcc} and @code{g77} distributions occupy 8.6MB +packed, 35MB unpacked. +These consist of the source code and documentation, +plus some derived files (mostly documentation), for +@code{gcc} and @code{g77}. +Any deviations from these numbers for different +kinds of systems are likely to be very minor. + +@item +A ``bootstrap'' build requires an additional 67.3MB +for a total of 102MB on an ix86, and an additional +98MB for a total of 165MB on an Alpha. + +@item +Removing @file{gcc/stage1} after the build recovers +10.7MB for a total of 91MB on an ix86, and recovers +??MB for a total of ??MB on an Alpha. + +After doing this, the integrity of the build can +still be verified via @samp{make compare}, and the +@code{gcc} compiler modified and used to build itself for +testing fairly quickly, using the copy of the compiler +kept in @code{gcc/stage2}. + +@item +Removing @file{gcc/stage2} after the build further +recovers 27.3MB for a total of 64.3MB, and recovers +??MB for a total of ??MB on an Alpha. + +After doing this, the compiler can still be installed, +especially if GNU @code{make} is used to avoid +gratuitous rebuilds (or, the installation can be done +by hand). + +@item +Installing @code{gcc} and @code{g77} copies +14.9MB onto the @samp{--prefix} disk for a total of 79.2MB +on an ix86, and copies ??MB onto the @samp{--prefix} +disk for a total of ??MB on an Alpha. +@end itemize + +After installation, if no further modifications and +builds of @code{gcc} or @code{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 @code{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 @file{gcc/stage1} and @file{gcc/stage2} +directories. + +Installing @code{gcc} and @code{g77} over existing +versions might require less @emph{new} disk space, +but note that, unlike many products, @code{gcc} +installs itself in a way that avoids overwriting other +installed versions of itself, so that other versions may +easily be invoked (via @samp{gcc -V @var{version}}). + +So, the amount of space saved as a result of having +an existing version of @code{gcc} and @code{g77} +already installed is not much---typically only the +command drivers (@code{gcc}, @code{g77}, @code{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). + +@item @code{patch} +Although you can do everything @code{patch} does yourself, +by hand, without much trouble, having @code{patch} installed +makes installation of new versions of GNU utilities such as +@code{g77} so much easier that it is worth getting. +You can obtain @code{patch} the same way you obtained +@code{gcc} and @code{g77}. + +In any case, you can apply patches by hand---patch files +are designed for humans to read them. + +The version of GNU @code{patch} used to develop this release +is 2.4. + +@item @code{make} +Your system must have @code{make}, and you will probably save +yourself a lot of trouble if it is GNU @code{make} (sometimes +referred to as @code{gmake}). + +The version of GNU @code{make} used to develop this release +is 3.73. + +@item @code{cc} +Your system must have a working C compiler. + +@xref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, +for more information on prerequisites for installing @code{gcc}. + +@item @code{bison} +If you do not have @code{bison} installed, you can usually +work around any need for it, since @code{g77} itself does +not use it, and @code{gcc} normally includes all files +generated by running it in its distribution. +You can obtain @code{bison} the same way you obtained +@code{gcc} and @code{g77}. + +The version of GNU @code{bison} used to develop this release +is 1.25. + +@xref{Missing bison?}, +for information on how to work around not having @code{bison}. + +@item @code{makeinfo} +If you are missing @code{makeinfo}, you can usually work +around any need for it. +You can obtain @code{makeinfo} the same way you obtained +@code{gcc} and @code{g77}. + +The version of GNU @code{makeinfo} used to develop this release +is 1.68, from GNU @code{texinfo} version 3.11. + +@xref{Missing makeinfo?}, +for information on getting around the lack of @code{makeinfo}. + +@item @code{sed} +All UNIX systems have @code{sed}, but some have a broken +version that cannot handle configuring, building, or +installing @code{gcc} or @code{g77}. + +The version of GNU @code{sed} used to develop this release +is 2.05. +(Note that GNU @code{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.) + +@item @code{root} access or equivalent +To perform the complete installation procedures on a system, +you need to have @code{root} access to that system, or +equivalent access to the @samp{--prefix} directory tree +specified on the @code{configure} command line. + +Portions of the procedure (such as configuring and building +@code{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 @code{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. +@end table + +@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. +* 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 Necessary:: Why @code{gcc} must be patched first. +* Building GNU CC Necessary:: Why you can't build @emph{just} Fortran. +* Missing strtoul:: If linking @code{f771} fails due to an + unresolved reference to @code{strtoul}. +* Cleanup Kills Stage Directories:: A minor nit for @code{g77} developers. +* Missing gperf?:: When building requires @code{gperf}. +@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 Necessary +@subsubsection Patching GNU CC Necessary +@cindex patch files +@cindex GBE + +@code{g77} currently requires application of a patch file to the gcc compiler +tree. +The necessary patches should be folded in to the mainline gcc distribution. + +Some combinations +of versions of @code{g77} and @code{gcc} might actually @emph{require} no +patches, but the patch files will be provided anyway as long as +there are more changes expected in subsequent releases. +These patch files might contain +unnecessary, but possibly helpful, patches. +As a result, it is possible this issue might never be +resolved, except by eliminating the need for the person +configuring @code{g77} to apply a patch by hand, by going +to a more automated approach (such as configure-time patching). + +@node Building GNU CC Necessary +@subsubsection Building GNU CC Necessary +@cindex 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 +@subsubsection Missing strtoul +@cindex strtoul +@cindex _strtoul +@cindex undefined reference (_strtoul) +@cindex f771, linking error for +@cindex linking error for f771 +@cindex ld error for f771 +@cindex ld can't find _strtoul +@cindex SunOS4 + +On SunOS4 systems, linking the @code{f771} program produces +an error message concerning an undefined symbol named +@samp{_strtoul}. + +This is not a @code{g77} bug. +@xref{Patching GNU Fortran}, for information on +a workaround provided by @code{g77}. + +The proper fix is either to upgrade your system to one that +provides a complete ANSI C environment, or improve @code{gcc} so +that it provides one for all the languages and configurations it supports. + +@emph{Note:} In earlier versions of @code{g77}, an automated +workaround for this problem was attempted. +It worked for systems without @samp{_strtoul}, substituting +the incomplete-yet-sufficient version supplied with @code{g77} +for those systems. +However, the automated workaround failed mysteriously for systems +that appeared to have conforming ANSI C environments, and it +was decided that, lacking resources to more fully investigate +the problem, it was better to not punish users of those systems +either by requiring them to work around the problem by hand or +by always substituting an incomplete @code{strtoul()} implementation +when their systems had a complete, working one. +Unfortunately, this meant inconveniencing users of systems not +having @code{strtoul()}, but they're using obsolete (and generally +unsupported) systems anyway. + +@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. + +@node Missing gperf? +@subsubsection Missing @code{gperf}? +@cindex @code{gperf} +@cindex missing @code{gperf} + +If a build aborts trying to invoke @code{gperf}, that +strongly suggests an improper method was used to +create the @code{gcc} source directory, +such as the UNIX @samp{cp -r} command instead +of @samp{cp -pr}, since this problem very likely +indicates that the date-time-modified information on +the @code{gcc} source files is incorrect. + +The proper solution is to recreate the @code{gcc} source +directory from a @code{gcc} distribution known to be +provided by the FSF. + +It is possible you might be able to temporarily +work around the problem, however, by trying these +commands: + +@example +sh# @kbd{cd gcc} +sh# @kbd{touch c-gperf.h} +sh# +@end example + +These commands update the date-time-modified information for +the file produced by the invocation of @code{gperf} +in the current versions of @code{gcc}, so that @code{make} no +longer believes it needs to update it. +This file should already exist in a @code{gcc} +distribution, but mistakes made when copying the @code{gcc} +directory can leave the modification information +set such that the @code{gperf} input files look more ``recent'' +than the corresponding output files. + +If the above does not work, definitely start from scratch +and avoid copying the @code{gcc} using any method that does +not reliably preserve date-time-modified information, such +as the UNIX @samp{cp -r} command. + +@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{libf2c} 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. + +@item +There are still some challenges putting together the right +run-time libraries (needed by @code{libf2c}) 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{gcc/f/} 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 @samp{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 @samp{MXUNIT} macro, which represents the maximum unit +number, to an appropriately higher value. + +To do this, edit the file @file{f/runtime/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 @samp{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 +@samp{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{libf2c} supports flagging write errors immediately when +it is built with the @samp{ALWAYS_FLUSH} macro defined. +This results in a @code{libf2c} 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{libf2c} is built with the @samp{ALWAYS_FLUSH} macro +defined, enabling this behavior. + +To do this, find this line in @file{f/runtime/configure.in} in +your @code{g77} source tree: + +@example +dnl AC_DEFINE(ALWAYS_FLUSH) +@end example + +Remove the leading @samp{dnl@w{ }}, so the line begins with +@samp{AC_DEFINE(}, and run @code{autoconf} in that file's directory. +(Or, if you don't have @code{autoconf}, you can modify @file{f2c.h.in} +in the same directory to include the line @samp{#define ALWAYS_FLUSH} +after @samp{#define F2C_INCLUDE}.) + +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 +@samp{FFECOM_sizeMAXSTACKITEM} in @file{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). + +@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 @samp{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 g77-0.6 +will give it the capabilities it needs to not have to crash the build +but rather generate correct code for the target. +(Currently, @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, 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{gcc/f/data.c}, the macro +@samp{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 + +This procedure configures, builds, and installs @code{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 @code{root}. +Much of it can be done while not logged in as @code{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 @code{g77} and @code{gcc} will be +placed in @file{/usr/src}. +It also is assumed that the source distributions themselves +already reside in @file{/usr/FSF}, a naming convention +used by the author of @code{g77} on his own system: + +@example +/usr/FSF/gcc-2.7.2.3.tar.gz +/usr/FSF/g77-0.5.21.tar.gz +@end example + +@c (You can use @file{gcc-2.7.2.1.tar.gz} instead, or +@c the equivalent of it obtained by applying the +@c patch distributed as @file{gcc-2.7.2-2.7.2.1.diff.gz} +@c to version 2.7.2 of @code{gcc}, +@c if you remember to make the appropriate adjustments in the +@c instructions below.) + +@cindex SunOS4 +Users of the following systems should not blindly follow +these quick-start instructions, because of problems their +systems have coping with straightforward installation of +@code{g77}: + +@itemize @bullet +@item +SunOS4 +@end itemize + +Instead, see @ref{Complete Installation}, for detailed information +on how to configure, build, and install @code{g77} for your +particular system. +Also, see @ref{Trouble,,Known Causes of Trouble with GNU Fortran}, +for information on bugs and other problems known to afflict the +installation process, and how to report newly discovered ones. + +If your system is @emph{not} on the above list, and @emph{is} +a UNIX system or one of its variants, you should be able to +follow the instructions below. +If you vary @emph{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. + +@example +sh[ 1]# @kbd{cd /usr/src} +@set source-dir 1 +sh[ 2]# @kbd{gunzip -c < /usr/FSF/gcc-2.7.2.3.tar.gz | tar xf -} +[Might say "Broken pipe"...that is normal on some systems.] +@set unpack-gcc 2 +sh[ 3]# @kbd{gunzip -c < /usr/FSF/g77-0.5.21.tar.gz | tar xf -} +["Broken pipe" again possible.] +@set unpack-g77 3 +sh[ 4]# @kbd{ln -s gcc-2.7.2.3 gcc} +@set link-gcc 4 +sh[ 5]# @kbd{ln -s g77-0.5.21 g77} +@set link-g77 5 +sh[ 6]# @kbd{mv -i g77/* gcc} +[No questions should be asked by mv here; or, you made a mistake.] +@set merge-g77 6 +sh[ 7]# @kbd{patch -p1 -V t -d gcc < gcc/f/gbe/2.7.2.3.diff} +[Unless patch complains about rejected patches, this step worked.] +@set apply-patch 7 +sh[ 8]# @kbd{cd gcc} +sh[ 9]# @kbd{touch f77-install-ok} +[Do not do the above if your system already has an f77 +command, unless you've checked that overwriting it +is okay.] +@set f77-install-ok 9 +sh[10]# @kbd{touch f2c-install-ok} +[Do not do the above if your system already has an f2c +command, unless you've checked that overwriting it +is okay. Else, @kbd{touch f2c-exists-ok}.] +@set f2c-install-ok 10 +sh[11]# @kbd{./configure --prefix=/usr} +[Do not do the above if gcc is not installed in /usr/bin. +You might need a different @kbd{--prefix=@dots{}}, as +described below.] +@set configure-gcc 11 +sh[12]# @kbd{make bootstrap} +[This takes a long time, and is where most problems occur.] +@set build-gcc 12 +sh[13]# @kbd{make compare} +[This verifies that the compiler is `sane'. +If any files are printed, you have likely found a g77 bug.] +@set compare-gcc 13 +sh[14]# @kbd{rm -fr stage1} +@set rm-stage1 14 +sh[15]# @kbd{make -k install} +[The actual installation.] +@set install-g77 15 +sh[16]# @kbd{g77 -v} +[Verify that g77 is installed, obtain version info.] +@set show-version 16 +sh[17]# +@set end-procedure 17 +@end example + +@xref{Updating Documentation,,Updating Your Info Directory}, for +information on how to update your system's top-level @code{info} +directory to contain a reference to this manual, so that +users of @code{g77} can easily find documentation instead +of having to ask you for it. + +Elaborations of many of the above steps follows: + +@table @asis +@item Step @value{source-dir}: @kbd{cd /usr/src} +You can build @code{g77} pretty much anyplace. +By convention, this manual assumes @file{/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 @code{g77} and @code{gcc} in any case. + +@c @item Step @value{unpack-gcc}: @kbd{gunzip -d @dots{}} +@c Here, you might wish to use @file{gcc-2.7.2.1.tar.gz} +@c instead, or apply @file{gcc-2.7.2-2.7.2.1.diff.gz} to achieve +@c similar results. + +@item Step @value{unpack-g77}: @kbd{gunzip -d < /usr/FSF/g77-0.5.21.tar.gz | tar xf -} +It is not always necessary to obtain the latest version of +@code{g77} as a complete @file{.tar.gz} file if you have +a complete, earlier distribution of @code{g77}. +If appropriate, you can unpack that earlier +version of @code{g77}, and then apply the appropriate patches +to achieve the same result---a source tree containing version +0.5.21 of @code{g77}. + +@item Step @value{link-gcc}: @kbd{ln -s gcc-2.7.2.3 gcc} +@item Step @value{link-g77}: @kbd{ln -s g77-0.5.21 g77} +These commands mainly help reduce typing, +and help reduce visual clutter in examples +in this manual showing what to type to install @code{g77}. + +@c Of course, if appropriate, @kbd{ln -s gcc-2.7.2.1 gcc} or +@c similar. + +@xref{Unpacking}, for information on +using distributions of @code{g77} made by organizations +other than the FSF. + +@item Step @value{merge-g77}: @kbd{mv -i g77/* gcc} +After doing this, you can, if you like, type +@samp{rm g77} and @samp{rmdir g77-0.5.21} 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 @code{g77} are +installed on your system. + +@xref{Unpacking}, for information +on the contents of the @file{g77} directory (as merged +into the @file{gcc} directory). + +@item Step @value{apply-patch}: @kbd{patch -p1 @dots{}} +@c (Or `@kbd{@dots{} < gcc/f/gbe/2.7.2.1.diff}', if appropriate.) +@c +This can produce a wide variety of printed output, +from @samp{Hmm, I can't seem to find a patch in there anywhere...} +to long lists of messages indicated that patches are +being found, applied successfully, and so on. + +If messages about ``fuzz'', ``offset'', or +especially ``reject files'' are printed, it might +mean you applied the wrong patch file. +If you believe this is the case, it is best to restart +the sequence after deleting (or at least renaming to unused +names) the top-level directories for @code{g77} and @code{gcc} +and their symbolic links. + +After this command finishes, the @code{gcc} directory might +have old versions of several files as saved by @code{patch}. +To remove these, after @kbd{cd gcc}, type @kbd{rm -i *.~*~}. + +@xref{Merging Distributions}, for more information. + +@item Step @value{f77-install-ok}: @kbd{touch f77-install-ok} +Don't do this if you don't want to overwrite an existing +version of @code{f77} (such as a native compiler, or a +script that invokes @code{f2c}). +Otherwise, installation will overwrite the @code{f77} command +and the @code{f77} man pages with copies of the corresponding +@code{g77} material. + +@xref{Installing f77,,Installing @code{f77}}, for more +information. + +@item Step @value{f2c-install-ok}: @kbd{touch f2c-install-ok} +Don't do this if you don't want to overwrite an existing +installation of @code{libf2c} (though, chances are, you do). +Instead, @kbd{touch f2c-exists-ok} to allow the installation +to continue without any error messages about @file{/usr/lib/libf2c.a} +already existing. + +@xref{Installing f2c,,Installing @code{f2c}}, for more +information. + +@item Step @value{configure-gcc}: @kbd{./configure --prefix=/usr} +This is where you specify that the @file{g77} executable is to be +installed in @file{/usr/bin/}, the @file{libf2c.a} library is +to be installed in @file{/usr/lib/}, and so on. + +You should ensure that any existing installation of the @file{gcc} +executable is in @file{/usr/bin/}. +Otherwise, installing @code{g77} so that it does not fully +replace the existing installation of @code{gcc} is likely +to result in the inability to compile Fortran programs. + +@xref{Where to Install,,Where in the World Does Fortran (and GNU CC) Go?}, +for more information on determining where to install @code{g77}. +@xref{Configuring gcc}, for more information on the +configuration process triggered by invoking the @file{./configure} +script. + +@item Step @value{build-gcc}: @kbd{make bootstrap} +@xref{Installation,,Installing GNU CC, +gcc,Using and Porting GNU CC}, for information +on the kinds of diagnostics you should expect during +this procedure. + +@xref{Building gcc}, for complete @code{g77}-specific +information on this step. + +@item Step @value{compare-gcc}: @kbd{make compare} +@xref{Bug Lists,,Where to Port Bugs}, for information +on where to report that you observed files +having different contents during this +phase. + +@xref{Bug Reporting,,How to Report Bugs}, for +information on @emph{how} to report bugs like this. + +@item Step @value{rm-stage1}: @kbd{rm -fr stage1} +You don't need to do this, but it frees up disk space. + +@item Step @value{install-g77}: @kbd{make -k install} +If this doesn't seem to work, try: + +@example +make -k install install-libf77 install-f2c-all +@end example + +@xref{Installation of Binaries}, for more information. + +@xref{Updating Documentation,,Updating Your Info Directory}, +for information on entering this manual into your +system's list of texinfo manuals. + +@item Step @value{show-version}: @kbd{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 @code{g77} you just built and installed) and the +version numbers for the three parts of the @code{libf2c} +library (@code{libF77}, @code{libI77}, @code{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: + +@example + PROGRAM SMTEST + DO 10 I=1, 10 + PRINT *, 'Hello World #', I +10 CONTINUE + END +@end example + +Compile, link, and run the above program, and, assuming you named +the source file @file{smtest.f}, the session should look like this: + +@example +sh# @kbd{g77 -o smtest smtest.f} +sh# @kbd{./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# +@end example + +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. +@end table + +@node Complete Installation +@section Complete Installation + +Here is the complete @code{g77}-specific information on how +to configure, build, and install @code{g77}. + +@menu +* Unpacking:: +* Merging Distributions:: +* f77: Installing f77. +* f2c: Installing f2c. +* Patching GNU Fortran:: +* Where to Install:: +* Configuring gcc:: +* Building gcc:: +* Pre-installation Checks:: +* Installation of Binaries:: +* Updating Documentation:: +* bison: Missing bison?. +* makeinfo: Missing makeinfo?. +@end menu + +@node Unpacking +@subsection Unpacking +@cindex unpacking distributions +@cindex distributions, unpacking +@cindex code, source +@cindex source code +@cindex source tree +@cindex packages + +The @code{gcc} source distribution is a stand-alone distribution. +It is designed to be unpacked (producing the @code{gcc} +source tree) and built as is, assuming certain +prerequisites are met (including the availability of compatible +UNIX programs such as @code{make}, @code{cc}, and so on). + +However, before building @code{gcc}, you will want to unpack +and merge the @code{g77} distribution in with it, so that you +build a Fortran-capable version of @code{gcc}, which includes +the @code{g77} command, the necessary run-time libraries, +and this manual. + +Unlike @code{gcc}, the @code{g77} source distribution +is @emph{not} a stand-alone distribution. +It is designed to be unpacked and, afterwards, immediately merged +into an applicable @code{gcc} source tree. +That is, the @code{g77} distribution @emph{augments} a +@code{gcc} distribution---without @code{gcc}, generally +only the documentation is immediately usable. + +A sequence of commands typically used to unpack @code{gcc} +and @code{g77} is: + +@example +sh# @kbd{cd /usr/src} +sh# @kbd{gunzip -c /usr/FSF/gcc-2.7.2.3.tar.gz | tar xf -} +sh# @kbd{gunzip -c /usr/FSF/g77-0.5.21.tar.gz | tar xf -} +sh# @kbd{ln -s gcc-2.7.2.3 gcc} +sh# @kbd{ln -s g77-0.5.21 g77} +sh# @kbd{mv -i g77/* gcc} +@end example + +@emph{Notes:} The commands beginning with @samp{gunzip@dots{}} might +print @samp{Broken pipe@dots{}} as they complete. +That is nothing to worry about, unless you actually +@emph{hear} a pipe breaking. +The @code{ln} commands are helpful in reducing typing +and clutter in installation examples in this manual. +Hereafter, the top level of @code{gcc} source tree is referred to +as @file{gcc}, and the top level of just the @code{g77} +source tree (prior to issuing the @code{mv} command, above) +is referred to as @file{g77}. + +There are three top-level names in a @code{g77} distribution: + +@example +g77/COPYING.g77 +g77/README.g77 +g77/f +@end example + +All three entries should be moved (or copied) into a @code{gcc} +source tree (typically named after its version number and +as it appears in the FSF distributions---e.g. @file{gcc-2.7.2.3}). + +@file{g77/f} is the subdirectory containing all of the +code, documentation, and other information that is specific +to @code{g77}. +The other two files exist to provide information on @code{g77} +to someone encountering a @code{gcc} source tree with @code{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 @code{g77} source +tree for the first time. + +@cindex modifying @code{g77} +@cindex code, modifying +@cindex Pentium optimizations +@cindex optimizations, Pentium +@emph{Note:} Please use @strong{only} @code{gcc} and @code{g77} +source trees as distributed by the FSF. +Use of modified versions, such as the Pentium-specific-optimization +port of @code{gcc}, is likely to result in problems that appear to be +in the @code{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 +@code{g77} (or @code{gcc}) source trees appropriately so @code{g77} +and @code{gcc} can coexist as they do in the stock FSF distributions. + +@node Merging Distributions +@subsection Merging Distributions +@cindex merging distributions +@cindex @code{gcc} versions supported by @code{g77} +@cindex versions of @code{gcc} +@cindex support for @code{gcc} versions + +After merging the @code{g77} source tree into the @code{gcc} +source tree, the final merge step is done by applying the +pertinent patches the @code{g77} distribution provides for +the @code{gcc} source tree. + +Read the file @file{gcc/f/gbe/README}, and apply the appropriate +patch file for the version of the GNU CC compiler you have, if +that exists. +If the directory exists but the appropriate file +does not exist, you are using either an old, unsupported version, +or a release one that is newer than the newest @code{gcc} version +supported by the version of @code{g77} you have. + +@cindex gcc version numbering +@cindex version numbering +@cindex g77 version number +@cindex GNU version numbering +As of version 0.5.18, @code{g77} modifies the version number +of @code{gcc} via the pertinent patches. +This is done because the resulting version of @code{gcc} is +deemed sufficiently different from the vanilla distribution +to make it worthwhile to present, to the user, information +signaling the fact that there are some differences. + +GNU version numbers make it easy to figure out whether a +particular version of a distribution is newer or older than +some other version of that distribution. +The format is, +generally, @var{major}.@var{minor}.@var{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 @var{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 @samp{.0} fields often are omitted in +announcements and in names for distributions and +the directories they create.) + +If your version of @code{gcc} is older than the oldest version +supported by @code{g77} (as casually determined by listing +the contents of @file{gcc/f/gbe/}), you should obtain a newer, +supported version of @code{gcc}. +(You could instead obtain an older version of @code{g77}, +or try and get your @code{g77} to work with the old +@code{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 @code{gcc} is newer than the newest version +supported by @code{g77}, it is possible that your @code{g77} +will work with it anyway. +If the version number for @code{gcc} differs only in the +@var{patch} field, you might as well try applying the @code{g77} patch +that is for the newest version of @code{gcc} having the same +@var{major} and @var{minor} fields, as this is likely to work. + +So, for example, if a particular version of @code{g77} has support for +@code{gcc} versions 2.7.0 and 2.7.1, +it is likely that @file{gcc-2.7.2} would work well with @code{g77} +by using the @file{2.7.1.diff} patch file provided +with @code{g77} (aside from some offsets reported by @code{patch}, +which usually are harmless). + +However, @file{gcc-2.8.0} would almost certainly +not work with that version of @code{g77} no matter which patch file was +used, so a new version of @code{g77} would be needed (and you should +wait for it rather than bothering the maintainers---@pxref{Changes,, +User-Visible Changes}). + +@cindex distributions, why separate +@cindex separate distributions +@cindex why separate distributions +This complexity is the result of @code{gcc} and @code{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, @code{g77} often requires changes to contemporary +versions of @code{gcc}. +Also, the GBE interface defined by @code{gcc} typically +undergoes some incompatible changes at least every time the +@var{minor} field of the version number is incremented, +and such changes require corresponding changes to +the @code{g77} front end (FFE). + +It is hoped that the GBE interface, and the @code{gcc} and +@code{g77} products in general, will stabilize sufficiently +for the need for hand-patching to disappear. + +Invoking @code{patch} as described in @file{gcc/f/gbe/README} +can produce a wide variety of printed output, +from @samp{Hmm, I can't seem to find a patch in there anywhere...} +to long lists of messages indicated that patches are +being found, applied successfully, and so on. + +If messages about ``fuzz'', ``offset'', or +especially ``reject files'' are printed, it might +mean you applied the wrong patch file. +If you believe this is the case, it is best to restart +the sequence after deleting (or at least renaming to unused +names) the top-level directories for @code{g77} and @code{gcc} +and their symbolic links. +That is because @code{patch} might have partially patched +some @code{gcc} source files, so reapplying the correct +patch file might result in the correct patches being +applied incorrectly (due to the way @code{patch} necessarily +works). + +After @code{patch} finishes, the @code{gcc} directory might +have old versions of several files as saved by @code{patch}. +To remove these, after @kbd{cd gcc}, type @kbd{rm -i *.~*~}. + +@pindex config-lang.in +@emph{Note:} @code{g77}'s configuration file @file{gcc/f/config-lang.in} +ensures that the source code for the version of @code{gcc} +being configured has at least one indication of being patched +as required specifically by @code{g77}. +This configuration-time +checking should catch failure to apply the correct patch and, +if so caught, should abort the configuration with an explanation. +@emph{Please} do not try to disable the check, +otherwise @code{g77} might well appear to build +and install correctly, and even appear to compile correctly, +but could easily produce broken code. + +@cindex creating patch files +@cindex patch files, creating +@pindex gcc/f/gbe/ +@samp{diff -rcp2N} is used to create the patch files +in @file{gcc/f/gbe/}. + +@node Installing f77 +@subsection Installing @code{f77} +@cindex f77 command +@cindex commands, f77 +@cindex native compiler + +You should decide whether you want installation of @code{g77} +to also install an @code{f77} command. +On systems with a native @code{f77}, this is not +normally desired, so @code{g77} does not do this by +default. + +@pindex f77-install-ok +@vindex F77_INSTALL_FLAG +If you want @code{f77} installed, create the file @file{f77-install-ok} +(e.g. via the UNIX command @samp{touch f77-install-ok}) in the +source or build top-level directory (the same directory in +which the @code{g77} @file{f} directory resides, not the @file{f} directory +itself), or edit @file{gcc/f/Make-lang.in} and change the definition +of the @samp{F77_INSTALL_FLAG} macro appropriately. + +Usually, this means that, after typing @samp{cd gcc}, you +would type @samp{touch f77-install-ok}. + +When you enable installation of @code{f77}, either a link to or a +direct copy of the @code{g77} command is made. +Similarly, @file{f77.1} is installed as a man page. + +(The @code{uninstall} target in the @file{gcc/Makefile} also tests +this macro and file, when invoked, to determine whether to delete the +installed copies of @code{f77} and @file{f77.1}.) + +@emph{Note:} No attempt is yet made +to install a program (like a shell script) that provides +compatibility with any other @code{f77} programs. +Only the most rudimentary invocations of @code{f77} will +work the same way with @code{g77}. + +@node Installing f2c +@subsection Installing @code{f2c} + +Currently, @code{g77} does not include @code{f2c} itself in its +distribution. +However, it does include a modified version of the @code{libf2c}. +This version is normally compatible with @code{f2c}, but has been +modified to meet the needs of @code{g77} in ways that might possibly +be incompatible with some versions or configurations of @code{f2c}. + +Decide how installation of @code{g77} should affect any existing installation +of @code{f2c} on your system. + +@pindex f2c +@pindex f2c.h +@pindex libf2c.a +@pindex libF77.a +@pindex libI77.a +If you do not have @code{f2c} on your system (e.g. no @file{/usr/bin/f2c}, +no @file{/usr/include/f2c.h}, and no @file{/usr/lib/libf2c.a}, +@file{/usr/lib/libF77.a}, or @file{/usr/lib/libI77.a}), you don't need to +be concerned with this item. + +If you do have @code{f2c} on your system, you need to decide how users +of @code{f2c} will be affected by your installing @code{g77}. +Since @code{g77} is +currently designed to be object-code-compatible with @code{f2c} (with +very few, clear exceptions), users of @code{f2c} might want to combine +@code{f2c}-compiled object files with @code{g77}-compiled object files in a +single executable. + +To do this, users of @code{f2c} should use the same copies of @file{f2c.h} and +@file{libf2c.a} that @code{g77} uses (and that get built as part of +@code{g77}). + +If you do nothing here, the @code{g77} installation process will not +overwrite the @file{include/f2c.h} and @file{lib/libf2c.a} files with its +own versions, and in fact will not even install @file{libf2c.a} for use +with the newly installed versions of @code{gcc} and @code{g77} if it sees +that @file{lib/libf2c.a} exists---instead, it will print an explanatory +message and skip this part of the installation. + +@pindex f2c-install-ok +@vindex F2C_INSTALL_FLAG +To install @code{g77}'s versions of @file{f2c.h} and @file{libf2c.a} +in the appropriate +places, create the file @file{f2c-install-ok} (e.g. via the UNIX +command @samp{touch f2c-install-ok}) in the source or build top-level +directory (the same directory in which the @code{g77} @file{f} directory +resides, not the @file{f} directory itself), or edit @file{gcc/f/Make-lang.in} +and change the definition of the @samp{F2C_INSTALL_FLAG} macro appropriately. + +Usually, this means that, after typing @samp{cd gcc}, you +would type @samp{touch f2c-install-ok}. + +Make sure that when you enable the overwriting of @file{f2c.h} +and @file{libf2c.a} +as used by @code{f2c}, you have a recent and properly configured version of +@file{bin/f2c} so that it generates code that is compatible with @code{g77}. + +@pindex f2c-exists-ok +@vindex F2CLIBOK +If you don't want installation of @code{g77} to overwrite @code{f2c}'s existing +installation, but you do want @code{g77} installation to proceed with +installation of its own versions of @file{f2c.h} and @file{libf2c.a} in places +where @code{g77} will pick them up (even when linking @code{f2c}-compiled +object files---which might lead to incompatibilities), create +the file @file{f2c-exists-ok} (e.g. via the UNIX command +@samp{touch f2c-exists-ok}) in the source or build top-level directory, +or edit @file{gcc/f/Make-lang.in} and change the definition of the +@samp{F2CLIBOK} macro appropriately. + +@node Patching GNU Fortran +@subsection Patching GNU Fortran + +If you're using a SunOS4 system, you'll need to make the following +change to @file{gcc/f/proj.h}: edit the line reading + +@example +#define FFEPROJ_STRTOUL 1 @dots{} +@end example + +@noindent +by replacing the @samp{1} with @samp{0}. +Or, you can avoid editing the source by adding +@example +CFLAGS='-DFFEPROJ_STRTOUL=0 -g -O' +@end example +to the command line for @code{make} when you invoke it. +(@samp{-g} is the default for @samp{CFLAGS}.) + +This causes a minimal version of @code{strtoul()} provided +as part of the @code{g77} distribution to be compiled and +linked into whatever @code{g77} programs need it, since +some systems (like SunOS4 with only the bundled compiler and its +runtime) do not provide this function in their system libraries. + +Similarly, a minimal version of @code{bsearch()} is available +and can be enabled by editing a line similar to the one +for @code{strtoul()} above in @file{gcc/f/proj.h}, if +your system libraries lack @code{bsearch()}. +The method of overriding @samp{X_CFLAGS} may also be used. + +These are not problems with @code{g77}, which requires an +ANSI C environment. +You should upgrade your system to one that provides +a full ANSI C environment, or encourage the maintainers +of @code{gcc} to provide one to all @code{gcc}-based +compilers in future @code{gcc} distributions. + +@xref{Problems Installing}, for more information on +why @code{strtoul()} comes up missing and on approaches +to dealing with this problem that have already been tried. + +@node Where to Install +@subsection Where in the World Does Fortran (and GNU CC) Go? +@cindex language f77 not recognized +@cindex gcc will not compile Fortran programs + +Before configuring, you should make sure you know +where you want the @code{g77} and @code{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 @code{g77} installation necessarily requires installation of +a @code{g77}-aware version of @code{gcc}, so that the @code{gcc} +command recognizes Fortran source files and knows how to compile +them. + +For this to work, the version of @code{gcc} that you will be building +as part of @code{g77} @strong{must} be installed as the ``active'' +version of @code{gcc} on the system. + +Sometimes people make the mistake of installing @code{gcc} as +@file{/usr/local/bin/gcc}, +leaving an older, non-Fortran-aware version in @file{/usr/bin/gcc}. +(Or, the opposite happens.)@ +This can result in @code{g77} being unable to compile Fortran +source files, because when it calls on @code{gcc} to do the +actual compilation, @code{gcc} complains that it does not +recognize the language, or the file name suffix. + +So, determine whether @code{gcc} already is installed on your system, +and, if so, @emph{where} it is installed, and prepare to configure the +new version of @code{gcc} you'll be building so that it installs +over the existing version of @code{gcc}. + +You might want to back up your existing copy of @file{bin/gcc}, and +the entire @file{lib/} directory, before +you perform the actual installation (as described in this manual). + +Existing @code{gcc} installations typically are +found in @file{/usr} or @file{/usr/local}. +If you aren't certain where the currently +installed version of @code{gcc} and its +related programs reside, look at the output +of this command: + +@example +gcc -v -o /tmp/delete-me -xc /dev/null -xnone +@end example + +All sorts of interesting information on the locations of various +@code{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 @samp{main_()} function.) +However, you do have to sift through it yourself; @code{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 @emph{building} @code{g77} should not overwrite any installed +programs---but, usually, after you build @code{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 @code{g77}, +though in this case it is intentional that @code{g77} overwrites +@code{gcc} if it is already installed---it is unusual that +the installation process for one distribution intentionally +overwrites a program or file installed by another distribution.) + +Another reason to back up the existing version first, +or make sure you can restore it easily, is that it might be +an older version on which other users have come to depend +for certain behaviors. +However, even the new version of @code{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 @code{g77} components. +@xref{Target Options,,Specifying Target Machine and Compiler Version, +gcc,Using and Porting GNU CC}, for information on the @samp{-V} +option of @code{gcc}. + +@node Configuring gcc +@subsection Configuring GNU CC + +@code{g77} is configured automatically when you configure +@code{gcc}. +There are two parts of @code{g77} that are configured in two +different ways---@code{g77}, which ``camps on'' to the +@code{gcc} configuration mechanism, and @code{libf2c}, which +uses a variation of the GNU @code{autoconf} configuration +system. + +Generally, you shouldn't have to be concerned with +either @code{g77} or @code{libf2c} configuration, unless +you're configuring @code{g77} as a cross-compiler. +In this case, the @code{libf2c} configuration, and possibly the +@code{g77} and @code{gcc} configurations as well, +might need special attention. +(This also might be the case if you're porting @code{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 +@ref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, +following the instructions for running @file{./configure}. +Pay special attention to the @samp{--prefix=} option, which +you almost certainly will need to specify. + +(Note that @code{gcc} installation information is provided +as a straight text file in @file{gcc/INSTALL}.) + +The information printed by the invocation of @file{./configure} +should show that the @file{f} directory (the Fortran language) +has been configured. +If it does not, there is a problem. + +@emph{Note:} Configuring with the @samp{--srcdir} argument is known +to work with GNU @code{make}, but it is not known to work with +other variants of @code{make}. +Irix5.2 and SunOS4.1 versions of @code{make} definitely +won't work outside the source directory at present. +@code{g77}'s +portion of the @file{configure} script issues a warning message +about this when you configure for building binaries outside +the source directory. + +@node Building gcc +@subsection Building GNU CC +@cindex building @code{gcc} +@cindex building @code{g77} + +@vindex LANGUAGES +Building @code{g77} requires building enough of @code{gcc} that +these instructions assume you're going to build all of +@code{gcc}, including @code{g++}, @code{protoize}, and so on. +You can save a little time and disk space by changes the +@samp{LANGUAGES} macro definition in @code{gcc/Makefile.in} +or @code{gcc/Makefile}, but if you do that, you're on your own. +One change is almost @emph{certainly} going to cause failures: +removing @samp{c} or @samp{f77} from the definition of the +@samp{LANGUAGES} macro. + +After configuring @code{gcc}, which configures @code{g77} and +@code{libf2c} automatically, you're ready to start the actual +build by invoking @code{make}. + +@pindex configure +@emph{Note:} You @strong{must} have run @file{./configure} +before you run @code{make}, even if you're +using an already existing @code{gcc} development directory, because +@file{./configure} does the work to recognize that you've added +@code{g77} to the configuration. + +There are two general approaches to building GNU CC from +scratch: + +@table @dfn +@item bootstrap +This method uses minimal native system facilities to +build a barebones, unoptimized @code{gcc}, that is then +used to compile (``bootstrap'') the entire system. + +@item straight +This method assumes a more complete native system +exists, and uses that just once to build the entire +system. +@end table + +On all systems without a recent version of @code{gcc} +already installed, the @i{bootstrap} method must be +used. +In particular, @code{g77} uses extensions to the C +language offered, apparently, only by @code{gcc}. + +On most systems with a recent version of @code{gcc} +already installed, the @i{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. + +@menu +* Bootstrap Build:: For all systems. +* Straight Build:: For systems with a recent version of @code{gcc}. +@end menu + +@node Bootstrap Build +@subsubsection Bootstrap Build +@cindex bootstrap build +@cindex build, bootstrap + +A complete bootstrap build is done by issuing a command +beginning with @samp{make bootstrap @dots{}}, as +described in @ref{Installation,,Installing GNU CC, +gcc,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 @code{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 @code{make} commands to build +each stage one at a time, as described in the @code{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 @code{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 @samp{rm -fr stage1} to remove the +binaries built during Stage 1. + +Also, @xref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, +for important information on building @code{gcc} that is +not described in this @code{g77} manual. +For example, explanations of diagnostic messages +and whether they're expected, or indicate trouble, +are found there. + +@node Straight Build +@subsubsection Straight Build +@cindex straight build +@cindex build, straight + +If you have a recent version of @code{gcc} +already installed on your system, and if you're +reasonably certain it produces code that is +object-compatible with the version of @code{gcc} +you want to build as part of building @code{g77}, +you can save time and disk space by doing a straight +build. + +To build just the C and Fortran compilers and the +necessary run-time libraries, issue the following +command: + +@example +make -k CC=gcc LANGUAGES=f77 all g77 +@end example + +(The @samp{g77} target is necessary because the @code{gcc} +build procedures apparently do not automatically build +command drivers for languages in subdirectories. +It's the @samp{all} target that triggers building +everything except, apparently, the @code{g77} command +itself.) + +If you run into problems using this method, you have +two options: + +@itemize @bullet +@item +Abandon this approach and do a bootstrap build. + +@item +Try to make this approach work by diagnosing the +problems you're running into and retrying. +@end itemize + +Especially if you do the latter, you might consider +submitting any solutions as bug/fix reports. +@xref{Trouble,,Known Causes of Trouble with GNU Fortran}. + +However, understand that many problems preventing a +straight build from working are not @code{g77} problems, +and, in such cases, are not likely to be addressed in +future versions of @code{g77}. + +@node Pre-installation Checks +@subsection Pre-installation Checks +@cindex pre-installation checks +@cindex installing, checking before + +Before installing the system, which includes installing +@code{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: + +@example +sh# @kbd{cd /usr/src/gcc} +sh# @kbd{./g77 --driver=./xgcc -B./ -v} +g77 version 0.5.21 + ./xgcc -B./ -v -fnull-version -o /tmp/gfa18047 @dots{} +Reading specs from ./specs +gcc version 2.7.2.3.f.1 + ./cpp -lang-c -v -isystem ./include -undef @dots{} +GNU CPP version 2.7.2.3.f.1 (Linux/Alpha) +#include "..." search starts here: +#include <...> search starts here: + ./include + /usr/local/include + /usr/alpha-unknown-linux/include + /usr/lib/gcc-lib/alpha-unknown-linux/2.7.2.3.f.1/include + /usr/include +End of search list. + ./f771 /tmp/cca18048.i -fset-g77-defaults -quiet -dumpbase @dots{} +GNU F77 version 2.7.2.3.f.1 (Linux/Alpha) compiled @dots{} +GNU Fortran Front End version 0.5.21 compiled: @dots{} + as -nocpp -o /tmp/cca180481.o /tmp/cca18048.s + ld -G 8 -O1 -o /tmp/gfa18047 /usr/lib/crt0.o -L. @dots{} +__G77_LIBF77_VERSION__: 0.5.21 +@@(#)LIBF77 VERSION 19970404 +__G77_LIBI77_VERSION__: 0.5.21 +@@(#) LIBI77 VERSION pjw,dmg-mods 19970816 +__G77_LIBU77_VERSION__: 0.5.21 +@@(#) LIBU77 VERSION 19970609 +sh# @kbd{./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone} +Reading specs from ./specs +gcc version 2.7.2.3.f.1 + ./cpp -lang-c -v -isystem ./include -undef @dots{} +GNU CPP version 2.7.2.3.f.1 (Linux/Alpha) +#include "..." search starts here: +#include <...> search starts here: + ./include + /usr/local/include + /usr/alpha-unknown-linux/include + /usr/lib/gcc-lib/alpha-unknown-linux/2.7.2.3.f.1/include + /usr/include +End of search list. + ./cc1 /tmp/cca18063.i -quiet -dumpbase null.c -version @dots{} +GNU C version 2.7.2.3.f.1 (Linux/Alpha) compiled @dots{} + as -nocpp -o /tmp/cca180631.o /tmp/cca18063.s + ld -G 8 -O1 -o /tmp/delete-me /usr/lib/crt0.o -L. @dots{} +/usr/lib/crt0.o: In function `__start': +crt0.S:110: undefined reference to `main' +/usr/lib/crt0.o(.lita+0x28): undefined reference to `main' +sh# +@end example + +(Note that long lines have been truncated, and @samp{@dots{}} +used to indicate such truncations.) + +The above two commands test whether @code{g77} and @code{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 @code{gcc} and @code{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 @code{gcc} +and @code{g77}, use the following commands to invoke them. + +To invoke @code{g77}, type: + +@example +/usr/src/gcc/g77 --driver=/usr/src/gcc/xgcc -B/usr/src/gcc/ @dots{} +@end example + +To invoke @code{gcc}, type: + +@example +/usr/src/gcc/xgcc -B/usr/src/gcc/ @dots{} +@end example + +@node Installation of Binaries +@subsection Installation of Binaries +@cindex installation of binaries +@cindex @code{g77}, installation of +@cindex @code{gcc}, installation of + +After configuring, building, and testing @code{g77} and @code{gcc}, +when you are ready to install them on your system, type: + +@example +make -k CC=gcc LANGUAGES=f77 install +@end example + +As described in @ref{Installation,,Installing GNU CC, +gcc,Using and Porting GNU CC}, the values for +the @samp{CC} and @samp{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 @file{libf2c.a} +as expected, try this: + +@example +make -k @dots{} install install-libf77 install-f2c-all +@end example + +We don't know why some non-GNU versions of @code{make} sometimes +require this alternate command, but they do. +(Remember to supply the appropriate definitions for @samp{CC} and +@samp{LANGUAGES} where you see @samp{@dots{}} in the above command.) + +Note that using the @samp{-k} option tells @code{make} to +continue after some installation problems, like not having +@code{makeinfo} installed on your system. +It might not be necessary for your system. + +@node Updating Documentation +@subsection Updating Your Info Directory +@cindex updating info directory +@cindex info, updating directory +@cindex directory, updating info +@pindex /usr/info/dir +@pindex g77.info +@cindex texinfo +@cindex documentation + +As part of installing @code{g77}, you should make sure users +of @code{info} can easily access this manual on-line. +Do this by making sure a line such as the following exists +in @file{/usr/info/dir}, or in whatever file is the top-level +file in the @code{info} directory on your system (perhaps +@file{/usr/local/info/dir}: + +@example +* g77: (g77). The GNU Fortran programming language. +@end example + +If the menu in @file{dir} is organized into sections, @code{g77} +probably belongs in a section with a name such as one of +the following: + +@itemize @bullet +@item +Fortran Programming + +@item +Writing Programs + +@item +Programming Languages + +@item +Languages Other Than C + +@item +Scientific/Engineering Tools + +@item +GNU Compilers +@end itemize + +@node Missing bison? +@subsection Missing @code{bison}? +@cindex @code{bison} +@cindex missing @code{bison} + +If you cannot install @code{bison}, make sure you have started +with a @emph{fresh} distribution of @code{gcc}, do @emph{not} +do @samp{make maintainer-clean} (in other versions of @code{gcc}, +this was called @samp{make realclean}), and, to ensure that +@code{bison} is not invoked by @code{make} during the build, +type these commands: + +@example +sh# @kbd{cd gcc} +sh# @kbd{touch bi-parser.c bi-parser.h c-parse.c c-parse.h cexp.c} +sh# @kbd{touch cp/parse.c cp/parse.h objc-parse.c} +sh# +@end example + +These commands update the date-time-modified information for +all the files produced by the various invocations of @code{bison} +in the current versions of @code{gcc}, so that @code{make} no +longer believes it needs to update them. +All of these files should already exist in a @code{gcc} +distribution, but the application of patches to upgrade +to a newer version can leave the modification information +set such that the @code{bison} input files look more ``recent'' +than the corresponding output files. + +@emph{Note:} New versions of @code{gcc} might change the set of +files it generates by invoking @code{bison}---if you cannot figure +out for yourself how to handle such a situation, try an +older version of @code{gcc} until you find someone who can +(or until you obtain and install @code{bison}). + +@node Missing makeinfo? +@subsection Missing @code{makeinfo}? +@cindex @code{makeinfo} +@cindex missing @code{makeinfo} + +If you cannot install @code{makeinfo}, either use the @code{-k} option when +invoking make to specify any of the @samp{install} or related targets, +or specify @samp{MAKEINFO=echo} on the @code{make} command line. + +If you fail to do one of these things, some files, like @file{libf2c.a}, +might not be installed, because the failed attempt by @code{make} to +invoke @code{makeinfo} causes it to cancel any further processing. + +@node Distributing Binaries +@section Distributing Binaries +@cindex binaries, distributing +@cindex code, distributing + +If you are building @code{g77} for distribution to others in binary form, +first make sure you are aware of your legal responsibilities (read +the file @file{gcc/COPYING} thoroughly). + +Then, consider your target audience and decide where @code{g77} should +be installed. + +For systems like GNU/Linux that have no native Fortran compiler (or +where @code{g77} could be considered the native compiler for Fortran and +@code{gcc} for C, etc.), you should definitely configure +@code{g77} for installation +in @file{/usr/bin} instead of @file{/usr/local/bin}. +Specify the +@samp{--prefix=/usr} option when running @file{./configure}. +You might +also want to set up the distribution so the @code{f77} command is a +link to @code{g77}---just make an empty file named @file{f77-install-ok} in +the source or build directory (the one in which the @file{f} directory +resides, not the @file{f} directory itself) when you specify one of the +@file{install} or @file{uninstall} targets in a @code{make} command. + +For a system that might already have @code{f2c} installed, you definitely +will want to make another empty file (in the same directory) named +either @file{f2c-exists-ok} or @file{f2c-install-ok}. +Use the former if you +don't want your distribution to overwrite @code{f2c}-related files in existing +systems; use the latter if you want to improve the likelihood that +users will be able to use both @code{f2c} and @code{g77} to compile code for a +single program without encountering link-time or run-time +incompatibilities. + +(Make sure you clearly document, in the ``advertising'' for +your distribution, how installation of your distribution will +affect existing installations of @code{gcc}, @code{f2c}, +@code{f77}, @file{libf2c.a}, and so on. +Similarly, you should clearly document any requirements +you assume are met by users of your distribution.) + +For other systems with native @code{f77} (and @code{cc}) compilers, +configure @code{g77} as you (or most of your audience) would +configure @code{gcc} for their installations. +Typically this is for installation in +@file{/usr/local}, and would not include a copy of +@code{g77} named @code{f77}, so +users could still use the native @code{f77}. + +In any case, for @code{g77} to work properly, you @strong{must} ensure +that the binaries you distribute include: + +@table @file +@item bin/g77 +This is the command most users use to compile Fortran. + +@item bin/gcc +This is the command all users use to compile Fortran, either +directly or indirectly via the @code{g77} command. +The @file{bin/gcc} executable file must have been built +from a @code{gcc} source tree into which a @code{g77} source +tree was merged and configured, or it will not know how +to compile Fortran programs. + +@item bin/f77 +In installations with no non-GNU native Fortran +compiler, this is the same as @file{bin/g77}. +Otherwise, it should be omitted from the distribution, +so the one on already on a particular system does +not get overwritten. + +@item info/g77.info* +This is the documentation for @code{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 @file{gcc/f/*.texi} +and doing @samp{make doc} from the @file{/usr/src/gcc} directory) +to reflect any changes you've made to @code{g77}, or at +least to encourage users of your binary distribution to +report bugs to you first. + +Also, whether you distribute binaries or install @code{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 @code{info} node in @file{/usr/info/dir}. +That way, users can find @code{g77} documentation more +easily. +@xref{Updating Documentation,,Updating Your Info Directory}. + +@item man/man1/g77.1 +This is the short man page for @code{g77}. +It is out of date, but you might as well include it +for people who really like man pages. + +@item man/man1/f77.1 +In installations where @code{f77} is the same as @code{g77}, +this is the same as @file{man/man1/g77.1}. +Otherwise, it should be omitted from the distribution, +so the one already on a particular system does not +get overwritten. + +@item lib/gcc-lib/@dots{}/f771 +This is the actual Fortran compiler. + +@item lib/gcc-lib/@dots{}/libf2c.a +This is the run-time library for @code{g77}-compiled programs. +@end table + +Whether you want to include the slightly updated (and possibly +improved) versions of @code{cc1}, @code{cc1plus}, and whatever other +binaries get rebuilt with the changes the GNU Fortran distribution +makes to the GNU back end, is up to you. +These changes are +highly unlikely to break any compilers, and it is possible +they'll fix back-end bugs that can be demonstrated using front +ends other than GNU Fortran's. + +Please assure users that unless +they have a specific need for their existing, +older versions of @code{gcc} command, +they are unlikely to experience any problems by overwriting +it with your version---though they could certainly protect +themselves by making backup copies first! +Otherwise, users might try and install your binaries +in a ``safe'' place, find they cannot compile Fortran +programs with your distribution (because, perhaps, they're +picking up their old version of the @code{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, @strong{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 @code{g77} sources to port @code{g77}, e.g. to OS/2. +@email{fortran@@gnu.ai.mit.edu} 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. diff --git a/gcc/f/install.texi b/gcc/f/install.texi deleted file mode 100644 index acee44a..0000000 --- a/gcc/f/install.texi +++ /dev/null @@ -1,2114 +0,0 @@ -@c Copyright (C) 1995-1997 Free Software Foundation, Inc. -@c This is part of the G77 manual. -@c For copying conditions, see the file g77.texi. - -@c The text of this file appears in the file INSTALL -@c in the G77 distribution, as well as in the G77 manual. - -@c 1997-09-09 - -@ifclear INSTALLONLY -@node Installation -@chapter Installing GNU Fortran -@end ifclear -@cindex installing GNU Fortran - -The following information describes how to install @code{g77}. - -The information in this file generally pertains to dealing -with @emph{source} distributions of @code{g77} and @code{gcc}. -It is possible that some of this information will be applicable -to some @emph{binary} distributions of these products---however, -since these distributions are not made by the maintainers of -@code{g77}, responsibility for binary distributions rests with -whoever built and first distributed them. - -Nevertheless, efforts to make @code{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 @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 - -The procedures described to unpack, configure, build, and -install @code{g77} assume your system has certain programs -already installed. - -The following prerequisites should be met by your -system before you follow the @code{g77} installation instructions: - -@table @asis -@item @code{gzip} -To unpack the @code{gcc} and @code{g77} distributions, -you'll need the @code{gunzip} utility in the @code{gzip} -distribution. -Most UNIX systems already have @code{gzip} installed. -If yours doesn't, you can get it from the FSF. - -Note that you'll need @code{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 @code{gzip} used to package this release -is 1.24. -(The version of GNU @code{tar} used to package this release -is 1.11.2.) - -@item @file{gcc-2.7.2.3.tar.gz} -You need to have this, or some other applicable, version -of @code{gcc} on your system. -The version should be an exact copy of a distribution -from the FSF. -Its size is approximately 7.1MB. - -If you've already unpacked @file{gcc-2.7.2.3.tar.gz} into a -directory (named @file{gcc-2.7.2.3}) called the @dfn{source tree} -for @code{gcc}, you can delete the distribution -itself, but you'll need to remember to skip any instructions to unpack -this distribution. - -Without an applicable @code{gcc} source tree, you cannot -build @code{g77}. -You can obtain an FSF distribution of @code{gcc} from the FSF. - -@item @file{g77-0.5.21.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.5MB. - -You can obtain an FSF distribution of @code{g77} from the FSF, -the same way you obtained @code{gcc}. - -@item Enough disk space -The amount of disk space needed to unpack, build, install, -and use @code{g77} depends on the type of system you're -using, how you build @code{g77}, and how much of it you -install (primarily, which languages you install). - -The sizes shown below assume all languages distributed -in @code{gcc-2.7.2.3}, plus @code{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. - -@itemize --- -@item -@code{gcc} and @code{g77} distributions occupy 8.6MB -packed, 35MB unpacked. -These consist of the source code and documentation, -plus some derived files (mostly documentation), for -@code{gcc} and @code{g77}. -Any deviations from these numbers for different -kinds of systems are likely to be very minor. - -@item -A ``bootstrap'' build requires an additional 67.3MB -for a total of 102MB on an ix86, and an additional -98MB for a total of 165MB on an Alpha. - -@item -Removing @file{gcc/stage1} after the build recovers -10.7MB for a total of 91MB on an ix86, and recovers -??MB for a total of ??MB on an Alpha. - -After doing this, the integrity of the build can -still be verified via @samp{make compare}, and the -@code{gcc} compiler modified and used to build itself for -testing fairly quickly, using the copy of the compiler -kept in @code{gcc/stage2}. - -@item -Removing @file{gcc/stage2} after the build further -recovers 27.3MB for a total of 64.3MB, and recovers -??MB for a total of ??MB on an Alpha. - -After doing this, the compiler can still be installed, -especially if GNU @code{make} is used to avoid -gratuitous rebuilds (or, the installation can be done -by hand). - -@item -Installing @code{gcc} and @code{g77} copies -14.9MB onto the @samp{--prefix} disk for a total of 79.2MB -on an ix86, and copies ??MB onto the @samp{--prefix} -disk for a total of ??MB on an Alpha. -@end itemize - -After installation, if no further modifications and -builds of @code{gcc} or @code{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 @code{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 @file{gcc/stage1} and @file{gcc/stage2} -directories. - -Installing @code{gcc} and @code{g77} over existing -versions might require less @emph{new} disk space, -but note that, unlike many products, @code{gcc} -installs itself in a way that avoids overwriting other -installed versions of itself, so that other versions may -easily be invoked (via @samp{gcc -V @var{version}}). - -So, the amount of space saved as a result of having -an existing version of @code{gcc} and @code{g77} -already installed is not much---typically only the -command drivers (@code{gcc}, @code{g77}, @code{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). - -@item @code{patch} -Although you can do everything @code{patch} does yourself, -by hand, without much trouble, having @code{patch} installed -makes installation of new versions of GNU utilities such as -@code{g77} so much easier that it is worth getting. -You can obtain @code{patch} the same way you obtained -@code{gcc} and @code{g77}. - -In any case, you can apply patches by hand---patch files -are designed for humans to read them. - -The version of GNU @code{patch} used to develop this release -is 2.4. - -@item @code{make} -Your system must have @code{make}, and you will probably save -yourself a lot of trouble if it is GNU @code{make} (sometimes -referred to as @code{gmake}). - -The version of GNU @code{make} used to develop this release -is 3.73. - -@item @code{cc} -Your system must have a working C compiler. - -@xref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, -for more information on prerequisites for installing @code{gcc}. - -@item @code{bison} -If you do not have @code{bison} installed, you can usually -work around any need for it, since @code{g77} itself does -not use it, and @code{gcc} normally includes all files -generated by running it in its distribution. -You can obtain @code{bison} the same way you obtained -@code{gcc} and @code{g77}. - -The version of GNU @code{bison} used to develop this release -is 1.25. - -@xref{Missing bison?}, -for information on how to work around not having @code{bison}. - -@item @code{makeinfo} -If you are missing @code{makeinfo}, you can usually work -around any need for it. -You can obtain @code{makeinfo} the same way you obtained -@code{gcc} and @code{g77}. - -The version of GNU @code{makeinfo} used to develop this release -is 1.68, from GNU @code{texinfo} version 3.11. - -@xref{Missing makeinfo?}, -for information on getting around the lack of @code{makeinfo}. - -@item @code{sed} -All UNIX systems have @code{sed}, but some have a broken -version that cannot handle configuring, building, or -installing @code{gcc} or @code{g77}. - -The version of GNU @code{sed} used to develop this release -is 2.05. -(Note that GNU @code{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.) - -@item @code{root} access or equivalent -To perform the complete installation procedures on a system, -you need to have @code{root} access to that system, or -equivalent access to the @samp{--prefix} directory tree -specified on the @code{configure} command line. - -Portions of the procedure (such as configuring and building -@code{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 @code{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. -@end table - -@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. -* 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 Necessary:: Why @code{gcc} must be patched first. -* Building GNU CC Necessary:: Why you can't build @emph{just} Fortran. -* Missing strtoul:: If linking @code{f771} fails due to an - unresolved reference to @code{strtoul}. -* Cleanup Kills Stage Directories:: A minor nit for @code{g77} developers. -* Missing gperf?:: When building requires @code{gperf}. -@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 Necessary -@subsubsection Patching GNU CC Necessary -@cindex patch files -@cindex GBE - -@code{g77} currently requires application of a patch file to the gcc compiler -tree. -The necessary patches should be folded in to the mainline gcc distribution. - -Some combinations -of versions of @code{g77} and @code{gcc} might actually @emph{require} no -patches, but the patch files will be provided anyway as long as -there are more changes expected in subsequent releases. -These patch files might contain -unnecessary, but possibly helpful, patches. -As a result, it is possible this issue might never be -resolved, except by eliminating the need for the person -configuring @code{g77} to apply a patch by hand, by going -to a more automated approach (such as configure-time patching). - -@node Building GNU CC Necessary -@subsubsection Building GNU CC Necessary -@cindex 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 -@subsubsection Missing strtoul -@cindex strtoul -@cindex _strtoul -@cindex undefined reference (_strtoul) -@cindex f771, linking error for -@cindex linking error for f771 -@cindex ld error for f771 -@cindex ld can't find _strtoul -@cindex SunOS4 - -On SunOS4 systems, linking the @code{f771} program produces -an error message concerning an undefined symbol named -@samp{_strtoul}. - -This is not a @code{g77} bug. -@xref{Patching GNU Fortran}, for information on -a workaround provided by @code{g77}. - -The proper fix is either to upgrade your system to one that -provides a complete ANSI C environment, or improve @code{gcc} so -that it provides one for all the languages and configurations it supports. - -@emph{Note:} In earlier versions of @code{g77}, an automated -workaround for this problem was attempted. -It worked for systems without @samp{_strtoul}, substituting -the incomplete-yet-sufficient version supplied with @code{g77} -for those systems. -However, the automated workaround failed mysteriously for systems -that appeared to have conforming ANSI C environments, and it -was decided that, lacking resources to more fully investigate -the problem, it was better to not punish users of those systems -either by requiring them to work around the problem by hand or -by always substituting an incomplete @code{strtoul()} implementation -when their systems had a complete, working one. -Unfortunately, this meant inconveniencing users of systems not -having @code{strtoul()}, but they're using obsolete (and generally -unsupported) systems anyway. - -@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. - -@node Missing gperf? -@subsubsection Missing @code{gperf}? -@cindex @code{gperf} -@cindex missing @code{gperf} - -If a build aborts trying to invoke @code{gperf}, that -strongly suggests an improper method was used to -create the @code{gcc} source directory, -such as the UNIX @samp{cp -r} command instead -of @samp{cp -pr}, since this problem very likely -indicates that the date-time-modified information on -the @code{gcc} source files is incorrect. - -The proper solution is to recreate the @code{gcc} source -directory from a @code{gcc} distribution known to be -provided by the FSF. - -It is possible you might be able to temporarily -work around the problem, however, by trying these -commands: - -@example -sh# @kbd{cd gcc} -sh# @kbd{touch c-gperf.h} -sh# -@end example - -These commands update the date-time-modified information for -the file produced by the invocation of @code{gperf} -in the current versions of @code{gcc}, so that @code{make} no -longer believes it needs to update it. -This file should already exist in a @code{gcc} -distribution, but mistakes made when copying the @code{gcc} -directory can leave the modification information -set such that the @code{gperf} input files look more ``recent'' -than the corresponding output files. - -If the above does not work, definitely start from scratch -and avoid copying the @code{gcc} using any method that does -not reliably preserve date-time-modified information, such -as the UNIX @samp{cp -r} command. - -@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{libf2c} 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. - -@item -There are still some challenges putting together the right -run-time libraries (needed by @code{libf2c}) 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{gcc/f/} 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 @samp{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 @samp{MXUNIT} macro, which represents the maximum unit -number, to an appropriately higher value. - -To do this, edit the file @file{f/runtime/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 @samp{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 -@samp{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{libf2c} supports flagging write errors immediately when -it is built with the @samp{ALWAYS_FLUSH} macro defined. -This results in a @code{libf2c} 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{libf2c} is built with the @samp{ALWAYS_FLUSH} macro -defined, enabling this behavior. - -To do this, find this line in @file{f/runtime/configure.in} in -your @code{g77} source tree: - -@example -dnl AC_DEFINE(ALWAYS_FLUSH) -@end example - -Remove the leading @samp{dnl@w{ }}, so the line begins with -@samp{AC_DEFINE(}, and run @code{autoconf} in that file's directory. -(Or, if you don't have @code{autoconf}, you can modify @file{f2c.h.in} -in the same directory to include the line @samp{#define ALWAYS_FLUSH} -after @samp{#define F2C_INCLUDE}.) - -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 -@samp{FFECOM_sizeMAXSTACKITEM} in @file{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). - -@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 @samp{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 g77-0.6 -will give it the capabilities it needs to not have to crash the build -but rather generate correct code for the target. -(Currently, @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, 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{gcc/f/data.c}, the macro -@samp{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 - -This procedure configures, builds, and installs @code{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 @code{root}. -Much of it can be done while not logged in as @code{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 @code{g77} and @code{gcc} will be -placed in @file{/usr/src}. -It also is assumed that the source distributions themselves -already reside in @file{/usr/FSF}, a naming convention -used by the author of @code{g77} on his own system: - -@example -/usr/FSF/gcc-2.7.2.3.tar.gz -/usr/FSF/g77-0.5.21.tar.gz -@end example - -@c (You can use @file{gcc-2.7.2.1.tar.gz} instead, or -@c the equivalent of it obtained by applying the -@c patch distributed as @file{gcc-2.7.2-2.7.2.1.diff.gz} -@c to version 2.7.2 of @code{gcc}, -@c if you remember to make the appropriate adjustments in the -@c instructions below.) - -@cindex SunOS4 -Users of the following systems should not blindly follow -these quick-start instructions, because of problems their -systems have coping with straightforward installation of -@code{g77}: - -@itemize @bullet -@item -SunOS4 -@end itemize - -Instead, see @ref{Complete Installation}, for detailed information -on how to configure, build, and install @code{g77} for your -particular system. -Also, see @ref{Trouble,,Known Causes of Trouble with GNU Fortran}, -for information on bugs and other problems known to afflict the -installation process, and how to report newly discovered ones. - -If your system is @emph{not} on the above list, and @emph{is} -a UNIX system or one of its variants, you should be able to -follow the instructions below. -If you vary @emph{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. - -@example -sh[ 1]# @kbd{cd /usr/src} -@set source-dir 1 -sh[ 2]# @kbd{gunzip -c < /usr/FSF/gcc-2.7.2.3.tar.gz | tar xf -} -[Might say "Broken pipe"...that is normal on some systems.] -@set unpack-gcc 2 -sh[ 3]# @kbd{gunzip -c < /usr/FSF/g77-0.5.21.tar.gz | tar xf -} -["Broken pipe" again possible.] -@set unpack-g77 3 -sh[ 4]# @kbd{ln -s gcc-2.7.2.3 gcc} -@set link-gcc 4 -sh[ 5]# @kbd{ln -s g77-0.5.21 g77} -@set link-g77 5 -sh[ 6]# @kbd{mv -i g77/* gcc} -[No questions should be asked by mv here; or, you made a mistake.] -@set merge-g77 6 -sh[ 7]# @kbd{patch -p1 -V t -d gcc < gcc/f/gbe/2.7.2.3.diff} -[Unless patch complains about rejected patches, this step worked.] -@set apply-patch 7 -sh[ 8]# @kbd{cd gcc} -sh[ 9]# @kbd{touch f77-install-ok} -[Do not do the above if your system already has an f77 -command, unless you've checked that overwriting it -is okay.] -@set f77-install-ok 9 -sh[10]# @kbd{touch f2c-install-ok} -[Do not do the above if your system already has an f2c -command, unless you've checked that overwriting it -is okay. Else, @kbd{touch f2c-exists-ok}.] -@set f2c-install-ok 10 -sh[11]# @kbd{./configure --prefix=/usr} -[Do not do the above if gcc is not installed in /usr/bin. -You might need a different @kbd{--prefix=@dots{}}, as -described below.] -@set configure-gcc 11 -sh[12]# @kbd{make bootstrap} -[This takes a long time, and is where most problems occur.] -@set build-gcc 12 -sh[13]# @kbd{make compare} -[This verifies that the compiler is `sane'. -If any files are printed, you have likely found a g77 bug.] -@set compare-gcc 13 -sh[14]# @kbd{rm -fr stage1} -@set rm-stage1 14 -sh[15]# @kbd{make -k install} -[The actual installation.] -@set install-g77 15 -sh[16]# @kbd{g77 -v} -[Verify that g77 is installed, obtain version info.] -@set show-version 16 -sh[17]# -@set end-procedure 17 -@end example - -@xref{Updating Documentation,,Updating Your Info Directory}, for -information on how to update your system's top-level @code{info} -directory to contain a reference to this manual, so that -users of @code{g77} can easily find documentation instead -of having to ask you for it. - -Elaborations of many of the above steps follows: - -@table @asis -@item Step @value{source-dir}: @kbd{cd /usr/src} -You can build @code{g77} pretty much anyplace. -By convention, this manual assumes @file{/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 @code{g77} and @code{gcc} in any case. - -@c @item Step @value{unpack-gcc}: @kbd{gunzip -d @dots{}} -@c Here, you might wish to use @file{gcc-2.7.2.1.tar.gz} -@c instead, or apply @file{gcc-2.7.2-2.7.2.1.diff.gz} to achieve -@c similar results. - -@item Step @value{unpack-g77}: @kbd{gunzip -d < /usr/FSF/g77-0.5.21.tar.gz | tar xf -} -It is not always necessary to obtain the latest version of -@code{g77} as a complete @file{.tar.gz} file if you have -a complete, earlier distribution of @code{g77}. -If appropriate, you can unpack that earlier -version of @code{g77}, and then apply the appropriate patches -to achieve the same result---a source tree containing version -0.5.21 of @code{g77}. - -@item Step @value{link-gcc}: @kbd{ln -s gcc-2.7.2.3 gcc} -@item Step @value{link-g77}: @kbd{ln -s g77-0.5.21 g77} -These commands mainly help reduce typing, -and help reduce visual clutter in examples -in this manual showing what to type to install @code{g77}. - -@c Of course, if appropriate, @kbd{ln -s gcc-2.7.2.1 gcc} or -@c similar. - -@xref{Unpacking}, for information on -using distributions of @code{g77} made by organizations -other than the FSF. - -@item Step @value{merge-g77}: @kbd{mv -i g77/* gcc} -After doing this, you can, if you like, type -@samp{rm g77} and @samp{rmdir g77-0.5.21} 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 @code{g77} are -installed on your system. - -@xref{Unpacking}, for information -on the contents of the @file{g77} directory (as merged -into the @file{gcc} directory). - -@item Step @value{apply-patch}: @kbd{patch -p1 @dots{}} -@c (Or `@kbd{@dots{} < gcc/f/gbe/2.7.2.1.diff}', if appropriate.) -@c -This can produce a wide variety of printed output, -from @samp{Hmm, I can't seem to find a patch in there anywhere...} -to long lists of messages indicated that patches are -being found, applied successfully, and so on. - -If messages about ``fuzz'', ``offset'', or -especially ``reject files'' are printed, it might -mean you applied the wrong patch file. -If you believe this is the case, it is best to restart -the sequence after deleting (or at least renaming to unused -names) the top-level directories for @code{g77} and @code{gcc} -and their symbolic links. - -After this command finishes, the @code{gcc} directory might -have old versions of several files as saved by @code{patch}. -To remove these, after @kbd{cd gcc}, type @kbd{rm -i *.~*~}. - -@xref{Merging Distributions}, for more information. - -@item Step @value{f77-install-ok}: @kbd{touch f77-install-ok} -Don't do this if you don't want to overwrite an existing -version of @code{f77} (such as a native compiler, or a -script that invokes @code{f2c}). -Otherwise, installation will overwrite the @code{f77} command -and the @code{f77} man pages with copies of the corresponding -@code{g77} material. - -@xref{Installing f77,,Installing @code{f77}}, for more -information. - -@item Step @value{f2c-install-ok}: @kbd{touch f2c-install-ok} -Don't do this if you don't want to overwrite an existing -installation of @code{libf2c} (though, chances are, you do). -Instead, @kbd{touch f2c-exists-ok} to allow the installation -to continue without any error messages about @file{/usr/lib/libf2c.a} -already existing. - -@xref{Installing f2c,,Installing @code{f2c}}, for more -information. - -@item Step @value{configure-gcc}: @kbd{./configure --prefix=/usr} -This is where you specify that the @file{g77} executable is to be -installed in @file{/usr/bin/}, the @file{libf2c.a} library is -to be installed in @file{/usr/lib/}, and so on. - -You should ensure that any existing installation of the @file{gcc} -executable is in @file{/usr/bin/}. -Otherwise, installing @code{g77} so that it does not fully -replace the existing installation of @code{gcc} is likely -to result in the inability to compile Fortran programs. - -@xref{Where to Install,,Where in the World Does Fortran (and GNU CC) Go?}, -for more information on determining where to install @code{g77}. -@xref{Configuring gcc}, for more information on the -configuration process triggered by invoking the @file{./configure} -script. - -@item Step @value{build-gcc}: @kbd{make bootstrap} -@xref{Installation,,Installing GNU CC, -gcc,Using and Porting GNU CC}, for information -on the kinds of diagnostics you should expect during -this procedure. - -@xref{Building gcc}, for complete @code{g77}-specific -information on this step. - -@item Step @value{compare-gcc}: @kbd{make compare} -@xref{Bug Lists,,Where to Port Bugs}, for information -on where to report that you observed files -having different contents during this -phase. - -@xref{Bug Reporting,,How to Report Bugs}, for -information on @emph{how} to report bugs like this. - -@item Step @value{rm-stage1}: @kbd{rm -fr stage1} -You don't need to do this, but it frees up disk space. - -@item Step @value{install-g77}: @kbd{make -k install} -If this doesn't seem to work, try: - -@example -make -k install install-libf77 install-f2c-all -@end example - -@xref{Installation of Binaries}, for more information. - -@xref{Updating Documentation,,Updating Your Info Directory}, -for information on entering this manual into your -system's list of texinfo manuals. - -@item Step @value{show-version}: @kbd{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 @code{g77} you just built and installed) and the -version numbers for the three parts of the @code{libf2c} -library (@code{libF77}, @code{libI77}, @code{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: - -@example - PROGRAM SMTEST - DO 10 I=1, 10 - PRINT *, 'Hello World #', I -10 CONTINUE - END -@end example - -Compile, link, and run the above program, and, assuming you named -the source file @file{smtest.f}, the session should look like this: - -@example -sh# @kbd{g77 -o smtest smtest.f} -sh# @kbd{./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# -@end example - -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. -@end table - -@node Complete Installation -@section Complete Installation - -Here is the complete @code{g77}-specific information on how -to configure, build, and install @code{g77}. - -@menu -* Unpacking:: -* Merging Distributions:: -* f77: Installing f77. -* f2c: Installing f2c. -* Patching GNU Fortran:: -* Where to Install:: -* Configuring gcc:: -* Building gcc:: -* Pre-installation Checks:: -* Installation of Binaries:: -* Updating Documentation:: -* bison: Missing bison?. -* makeinfo: Missing makeinfo?. -@end menu - -@node Unpacking -@subsection Unpacking -@cindex unpacking distributions -@cindex distributions, unpacking -@cindex code, source -@cindex source code -@cindex source tree -@cindex packages - -The @code{gcc} source distribution is a stand-alone distribution. -It is designed to be unpacked (producing the @code{gcc} -source tree) and built as is, assuming certain -prerequisites are met (including the availability of compatible -UNIX programs such as @code{make}, @code{cc}, and so on). - -However, before building @code{gcc}, you will want to unpack -and merge the @code{g77} distribution in with it, so that you -build a Fortran-capable version of @code{gcc}, which includes -the @code{g77} command, the necessary run-time libraries, -and this manual. - -Unlike @code{gcc}, the @code{g77} source distribution -is @emph{not} a stand-alone distribution. -It is designed to be unpacked and, afterwards, immediately merged -into an applicable @code{gcc} source tree. -That is, the @code{g77} distribution @emph{augments} a -@code{gcc} distribution---without @code{gcc}, generally -only the documentation is immediately usable. - -A sequence of commands typically used to unpack @code{gcc} -and @code{g77} is: - -@example -sh# @kbd{cd /usr/src} -sh# @kbd{gunzip -c /usr/FSF/gcc-2.7.2.3.tar.gz | tar xf -} -sh# @kbd{gunzip -c /usr/FSF/g77-0.5.21.tar.gz | tar xf -} -sh# @kbd{ln -s gcc-2.7.2.3 gcc} -sh# @kbd{ln -s g77-0.5.21 g77} -sh# @kbd{mv -i g77/* gcc} -@end example - -@emph{Notes:} The commands beginning with @samp{gunzip@dots{}} might -print @samp{Broken pipe@dots{}} as they complete. -That is nothing to worry about, unless you actually -@emph{hear} a pipe breaking. -The @code{ln} commands are helpful in reducing typing -and clutter in installation examples in this manual. -Hereafter, the top level of @code{gcc} source tree is referred to -as @file{gcc}, and the top level of just the @code{g77} -source tree (prior to issuing the @code{mv} command, above) -is referred to as @file{g77}. - -There are three top-level names in a @code{g77} distribution: - -@example -g77/COPYING.g77 -g77/README.g77 -g77/f -@end example - -All three entries should be moved (or copied) into a @code{gcc} -source tree (typically named after its version number and -as it appears in the FSF distributions---e.g. @file{gcc-2.7.2.3}). - -@file{g77/f} is the subdirectory containing all of the -code, documentation, and other information that is specific -to @code{g77}. -The other two files exist to provide information on @code{g77} -to someone encountering a @code{gcc} source tree with @code{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 @code{g77} source -tree for the first time. - -@cindex modifying @code{g77} -@cindex code, modifying -@cindex Pentium optimizations -@cindex optimizations, Pentium -@emph{Note:} Please use @strong{only} @code{gcc} and @code{g77} -source trees as distributed by the FSF. -Use of modified versions, such as the Pentium-specific-optimization -port of @code{gcc}, is likely to result in problems that appear to be -in the @code{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 -@code{g77} (or @code{gcc}) source trees appropriately so @code{g77} -and @code{gcc} can coexist as they do in the stock FSF distributions. - -@node Merging Distributions -@subsection Merging Distributions -@cindex merging distributions -@cindex @code{gcc} versions supported by @code{g77} -@cindex versions of @code{gcc} -@cindex support for @code{gcc} versions - -After merging the @code{g77} source tree into the @code{gcc} -source tree, the final merge step is done by applying the -pertinent patches the @code{g77} distribution provides for -the @code{gcc} source tree. - -Read the file @file{gcc/f/gbe/README}, and apply the appropriate -patch file for the version of the GNU CC compiler you have, if -that exists. -If the directory exists but the appropriate file -does not exist, you are using either an old, unsupported version, -or a release one that is newer than the newest @code{gcc} version -supported by the version of @code{g77} you have. - -@cindex gcc version numbering -@cindex version numbering -@cindex g77 version number -@cindex GNU version numbering -As of version 0.5.18, @code{g77} modifies the version number -of @code{gcc} via the pertinent patches. -This is done because the resulting version of @code{gcc} is -deemed sufficiently different from the vanilla distribution -to make it worthwhile to present, to the user, information -signaling the fact that there are some differences. - -GNU version numbers make it easy to figure out whether a -particular version of a distribution is newer or older than -some other version of that distribution. -The format is, -generally, @var{major}.@var{minor}.@var{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 @var{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 @samp{.0} fields often are omitted in -announcements and in names for distributions and -the directories they create.) - -If your version of @code{gcc} is older than the oldest version -supported by @code{g77} (as casually determined by listing -the contents of @file{gcc/f/gbe/}), you should obtain a newer, -supported version of @code{gcc}. -(You could instead obtain an older version of @code{g77}, -or try and get your @code{g77} to work with the old -@code{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 @code{gcc} is newer than the newest version -supported by @code{g77}, it is possible that your @code{g77} -will work with it anyway. -If the version number for @code{gcc} differs only in the -@var{patch} field, you might as well try applying the @code{g77} patch -that is for the newest version of @code{gcc} having the same -@var{major} and @var{minor} fields, as this is likely to work. - -So, for example, if a particular version of @code{g77} has support for -@code{gcc} versions 2.7.0 and 2.7.1, -it is likely that @file{gcc-2.7.2} would work well with @code{g77} -by using the @file{2.7.1.diff} patch file provided -with @code{g77} (aside from some offsets reported by @code{patch}, -which usually are harmless). - -However, @file{gcc-2.8.0} would almost certainly -not work with that version of @code{g77} no matter which patch file was -used, so a new version of @code{g77} would be needed (and you should -wait for it rather than bothering the maintainers---@pxref{Changes,, -User-Visible Changes}). - -@cindex distributions, why separate -@cindex separate distributions -@cindex why separate distributions -This complexity is the result of @code{gcc} and @code{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, @code{g77} often requires changes to contemporary -versions of @code{gcc}. -Also, the GBE interface defined by @code{gcc} typically -undergoes some incompatible changes at least every time the -@var{minor} field of the version number is incremented, -and such changes require corresponding changes to -the @code{g77} front end (FFE). - -It is hoped that the GBE interface, and the @code{gcc} and -@code{g77} products in general, will stabilize sufficiently -for the need for hand-patching to disappear. - -Invoking @code{patch} as described in @file{gcc/f/gbe/README} -can produce a wide variety of printed output, -from @samp{Hmm, I can't seem to find a patch in there anywhere...} -to long lists of messages indicated that patches are -being found, applied successfully, and so on. - -If messages about ``fuzz'', ``offset'', or -especially ``reject files'' are printed, it might -mean you applied the wrong patch file. -If you believe this is the case, it is best to restart -the sequence after deleting (or at least renaming to unused -names) the top-level directories for @code{g77} and @code{gcc} -and their symbolic links. -That is because @code{patch} might have partially patched -some @code{gcc} source files, so reapplying the correct -patch file might result in the correct patches being -applied incorrectly (due to the way @code{patch} necessarily -works). - -After @code{patch} finishes, the @code{gcc} directory might -have old versions of several files as saved by @code{patch}. -To remove these, after @kbd{cd gcc}, type @kbd{rm -i *.~*~}. - -@pindex config-lang.in -@emph{Note:} @code{g77}'s configuration file @file{gcc/f/config-lang.in} -ensures that the source code for the version of @code{gcc} -being configured has at least one indication of being patched -as required specifically by @code{g77}. -This configuration-time -checking should catch failure to apply the correct patch and, -if so caught, should abort the configuration with an explanation. -@emph{Please} do not try to disable the check, -otherwise @code{g77} might well appear to build -and install correctly, and even appear to compile correctly, -but could easily produce broken code. - -@cindex creating patch files -@cindex patch files, creating -@pindex gcc/f/gbe/ -@samp{diff -rcp2N} is used to create the patch files -in @file{gcc/f/gbe/}. - -@node Installing f77 -@subsection Installing @code{f77} -@cindex f77 command -@cindex commands, f77 -@cindex native compiler - -You should decide whether you want installation of @code{g77} -to also install an @code{f77} command. -On systems with a native @code{f77}, this is not -normally desired, so @code{g77} does not do this by -default. - -@pindex f77-install-ok -@vindex F77_INSTALL_FLAG -If you want @code{f77} installed, create the file @file{f77-install-ok} -(e.g. via the UNIX command @samp{touch f77-install-ok}) in the -source or build top-level directory (the same directory in -which the @code{g77} @file{f} directory resides, not the @file{f} directory -itself), or edit @file{gcc/f/Make-lang.in} and change the definition -of the @samp{F77_INSTALL_FLAG} macro appropriately. - -Usually, this means that, after typing @samp{cd gcc}, you -would type @samp{touch f77-install-ok}. - -When you enable installation of @code{f77}, either a link to or a -direct copy of the @code{g77} command is made. -Similarly, @file{f77.1} is installed as a man page. - -(The @code{uninstall} target in the @file{gcc/Makefile} also tests -this macro and file, when invoked, to determine whether to delete the -installed copies of @code{f77} and @file{f77.1}.) - -@emph{Note:} No attempt is yet made -to install a program (like a shell script) that provides -compatibility with any other @code{f77} programs. -Only the most rudimentary invocations of @code{f77} will -work the same way with @code{g77}. - -@node Installing f2c -@subsection Installing @code{f2c} - -Currently, @code{g77} does not include @code{f2c} itself in its -distribution. -However, it does include a modified version of the @code{libf2c}. -This version is normally compatible with @code{f2c}, but has been -modified to meet the needs of @code{g77} in ways that might possibly -be incompatible with some versions or configurations of @code{f2c}. - -Decide how installation of @code{g77} should affect any existing installation -of @code{f2c} on your system. - -@pindex f2c -@pindex f2c.h -@pindex libf2c.a -@pindex libF77.a -@pindex libI77.a -If you do not have @code{f2c} on your system (e.g. no @file{/usr/bin/f2c}, -no @file{/usr/include/f2c.h}, and no @file{/usr/lib/libf2c.a}, -@file{/usr/lib/libF77.a}, or @file{/usr/lib/libI77.a}), you don't need to -be concerned with this item. - -If you do have @code{f2c} on your system, you need to decide how users -of @code{f2c} will be affected by your installing @code{g77}. -Since @code{g77} is -currently designed to be object-code-compatible with @code{f2c} (with -very few, clear exceptions), users of @code{f2c} might want to combine -@code{f2c}-compiled object files with @code{g77}-compiled object files in a -single executable. - -To do this, users of @code{f2c} should use the same copies of @file{f2c.h} and -@file{libf2c.a} that @code{g77} uses (and that get built as part of -@code{g77}). - -If you do nothing here, the @code{g77} installation process will not -overwrite the @file{include/f2c.h} and @file{lib/libf2c.a} files with its -own versions, and in fact will not even install @file{libf2c.a} for use -with the newly installed versions of @code{gcc} and @code{g77} if it sees -that @file{lib/libf2c.a} exists---instead, it will print an explanatory -message and skip this part of the installation. - -@pindex f2c-install-ok -@vindex F2C_INSTALL_FLAG -To install @code{g77}'s versions of @file{f2c.h} and @file{libf2c.a} -in the appropriate -places, create the file @file{f2c-install-ok} (e.g. via the UNIX -command @samp{touch f2c-install-ok}) in the source or build top-level -directory (the same directory in which the @code{g77} @file{f} directory -resides, not the @file{f} directory itself), or edit @file{gcc/f/Make-lang.in} -and change the definition of the @samp{F2C_INSTALL_FLAG} macro appropriately. - -Usually, this means that, after typing @samp{cd gcc}, you -would type @samp{touch f2c-install-ok}. - -Make sure that when you enable the overwriting of @file{f2c.h} -and @file{libf2c.a} -as used by @code{f2c}, you have a recent and properly configured version of -@file{bin/f2c} so that it generates code that is compatible with @code{g77}. - -@pindex f2c-exists-ok -@vindex F2CLIBOK -If you don't want installation of @code{g77} to overwrite @code{f2c}'s existing -installation, but you do want @code{g77} installation to proceed with -installation of its own versions of @file{f2c.h} and @file{libf2c.a} in places -where @code{g77} will pick them up (even when linking @code{f2c}-compiled -object files---which might lead to incompatibilities), create -the file @file{f2c-exists-ok} (e.g. via the UNIX command -@samp{touch f2c-exists-ok}) in the source or build top-level directory, -or edit @file{gcc/f/Make-lang.in} and change the definition of the -@samp{F2CLIBOK} macro appropriately. - -@node Patching GNU Fortran -@subsection Patching GNU Fortran - -If you're using a SunOS4 system, you'll need to make the following -change to @file{gcc/f/proj.h}: edit the line reading - -@example -#define FFEPROJ_STRTOUL 1 @dots{} -@end example - -@noindent -by replacing the @samp{1} with @samp{0}. -Or, you can avoid editing the source by adding -@example -CFLAGS='-DFFEPROJ_STRTOUL=0 -g -O' -@end example -to the command line for @code{make} when you invoke it. -(@samp{-g} is the default for @samp{CFLAGS}.) - -This causes a minimal version of @code{strtoul()} provided -as part of the @code{g77} distribution to be compiled and -linked into whatever @code{g77} programs need it, since -some systems (like SunOS4 with only the bundled compiler and its -runtime) do not provide this function in their system libraries. - -Similarly, a minimal version of @code{bsearch()} is available -and can be enabled by editing a line similar to the one -for @code{strtoul()} above in @file{gcc/f/proj.h}, if -your system libraries lack @code{bsearch()}. -The method of overriding @samp{X_CFLAGS} may also be used. - -These are not problems with @code{g77}, which requires an -ANSI C environment. -You should upgrade your system to one that provides -a full ANSI C environment, or encourage the maintainers -of @code{gcc} to provide one to all @code{gcc}-based -compilers in future @code{gcc} distributions. - -@xref{Problems Installing}, for more information on -why @code{strtoul()} comes up missing and on approaches -to dealing with this problem that have already been tried. - -@node Where to Install -@subsection Where in the World Does Fortran (and GNU CC) Go? -@cindex language f77 not recognized -@cindex gcc will not compile Fortran programs - -Before configuring, you should make sure you know -where you want the @code{g77} and @code{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 @code{g77} installation necessarily requires installation of -a @code{g77}-aware version of @code{gcc}, so that the @code{gcc} -command recognizes Fortran source files and knows how to compile -them. - -For this to work, the version of @code{gcc} that you will be building -as part of @code{g77} @strong{must} be installed as the ``active'' -version of @code{gcc} on the system. - -Sometimes people make the mistake of installing @code{gcc} as -@file{/usr/local/bin/gcc}, -leaving an older, non-Fortran-aware version in @file{/usr/bin/gcc}. -(Or, the opposite happens.)@ -This can result in @code{g77} being unable to compile Fortran -source files, because when it calls on @code{gcc} to do the -actual compilation, @code{gcc} complains that it does not -recognize the language, or the file name suffix. - -So, determine whether @code{gcc} already is installed on your system, -and, if so, @emph{where} it is installed, and prepare to configure the -new version of @code{gcc} you'll be building so that it installs -over the existing version of @code{gcc}. - -You might want to back up your existing copy of @file{bin/gcc}, and -the entire @file{lib/} directory, before -you perform the actual installation (as described in this manual). - -Existing @code{gcc} installations typically are -found in @file{/usr} or @file{/usr/local}. -If you aren't certain where the currently -installed version of @code{gcc} and its -related programs reside, look at the output -of this command: - -@example -gcc -v -o /tmp/delete-me -xc /dev/null -xnone -@end example - -All sorts of interesting information on the locations of various -@code{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 @samp{main_()} function.) -However, you do have to sift through it yourself; @code{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 @emph{building} @code{g77} should not overwrite any installed -programs---but, usually, after you build @code{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 @code{g77}, -though in this case it is intentional that @code{g77} overwrites -@code{gcc} if it is already installed---it is unusual that -the installation process for one distribution intentionally -overwrites a program or file installed by another distribution.) - -Another reason to back up the existing version first, -or make sure you can restore it easily, is that it might be -an older version on which other users have come to depend -for certain behaviors. -However, even the new version of @code{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 @code{g77} components. -@xref{Target Options,,Specifying Target Machine and Compiler Version, -gcc,Using and Porting GNU CC}, for information on the @samp{-V} -option of @code{gcc}. - -@node Configuring gcc -@subsection Configuring GNU CC - -@code{g77} is configured automatically when you configure -@code{gcc}. -There are two parts of @code{g77} that are configured in two -different ways---@code{g77}, which ``camps on'' to the -@code{gcc} configuration mechanism, and @code{libf2c}, which -uses a variation of the GNU @code{autoconf} configuration -system. - -Generally, you shouldn't have to be concerned with -either @code{g77} or @code{libf2c} configuration, unless -you're configuring @code{g77} as a cross-compiler. -In this case, the @code{libf2c} configuration, and possibly the -@code{g77} and @code{gcc} configurations as well, -might need special attention. -(This also might be the case if you're porting @code{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 -@ref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, -following the instructions for running @file{./configure}. -Pay special attention to the @samp{--prefix=} option, which -you almost certainly will need to specify. - -(Note that @code{gcc} installation information is provided -as a straight text file in @file{gcc/INSTALL}.) - -The information printed by the invocation of @file{./configure} -should show that the @file{f} directory (the Fortran language) -has been configured. -If it does not, there is a problem. - -@emph{Note:} Configuring with the @samp{--srcdir} argument is known -to work with GNU @code{make}, but it is not known to work with -other variants of @code{make}. -Irix5.2 and SunOS4.1 versions of @code{make} definitely -won't work outside the source directory at present. -@code{g77}'s -portion of the @file{configure} script issues a warning message -about this when you configure for building binaries outside -the source directory. - -@node Building gcc -@subsection Building GNU CC -@cindex building @code{gcc} -@cindex building @code{g77} - -@vindex LANGUAGES -Building @code{g77} requires building enough of @code{gcc} that -these instructions assume you're going to build all of -@code{gcc}, including @code{g++}, @code{protoize}, and so on. -You can save a little time and disk space by changes the -@samp{LANGUAGES} macro definition in @code{gcc/Makefile.in} -or @code{gcc/Makefile}, but if you do that, you're on your own. -One change is almost @emph{certainly} going to cause failures: -removing @samp{c} or @samp{f77} from the definition of the -@samp{LANGUAGES} macro. - -After configuring @code{gcc}, which configures @code{g77} and -@code{libf2c} automatically, you're ready to start the actual -build by invoking @code{make}. - -@pindex configure -@emph{Note:} You @strong{must} have run @file{./configure} -before you run @code{make}, even if you're -using an already existing @code{gcc} development directory, because -@file{./configure} does the work to recognize that you've added -@code{g77} to the configuration. - -There are two general approaches to building GNU CC from -scratch: - -@table @dfn -@item bootstrap -This method uses minimal native system facilities to -build a barebones, unoptimized @code{gcc}, that is then -used to compile (``bootstrap'') the entire system. - -@item straight -This method assumes a more complete native system -exists, and uses that just once to build the entire -system. -@end table - -On all systems without a recent version of @code{gcc} -already installed, the @i{bootstrap} method must be -used. -In particular, @code{g77} uses extensions to the C -language offered, apparently, only by @code{gcc}. - -On most systems with a recent version of @code{gcc} -already installed, the @i{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. - -@menu -* Bootstrap Build:: For all systems. -* Straight Build:: For systems with a recent version of @code{gcc}. -@end menu - -@node Bootstrap Build -@subsubsection Bootstrap Build -@cindex bootstrap build -@cindex build, bootstrap - -A complete bootstrap build is done by issuing a command -beginning with @samp{make bootstrap @dots{}}, as -described in @ref{Installation,,Installing GNU CC, -gcc,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 @code{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 @code{make} commands to build -each stage one at a time, as described in the @code{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 @code{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 @samp{rm -fr stage1} to remove the -binaries built during Stage 1. - -Also, @xref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, -for important information on building @code{gcc} that is -not described in this @code{g77} manual. -For example, explanations of diagnostic messages -and whether they're expected, or indicate trouble, -are found there. - -@node Straight Build -@subsubsection Straight Build -@cindex straight build -@cindex build, straight - -If you have a recent version of @code{gcc} -already installed on your system, and if you're -reasonably certain it produces code that is -object-compatible with the version of @code{gcc} -you want to build as part of building @code{g77}, -you can save time and disk space by doing a straight -build. - -To build just the C and Fortran compilers and the -necessary run-time libraries, issue the following -command: - -@example -make -k CC=gcc LANGUAGES=f77 all g77 -@end example - -(The @samp{g77} target is necessary because the @code{gcc} -build procedures apparently do not automatically build -command drivers for languages in subdirectories. -It's the @samp{all} target that triggers building -everything except, apparently, the @code{g77} command -itself.) - -If you run into problems using this method, you have -two options: - -@itemize @bullet -@item -Abandon this approach and do a bootstrap build. - -@item -Try to make this approach work by diagnosing the -problems you're running into and retrying. -@end itemize - -Especially if you do the latter, you might consider -submitting any solutions as bug/fix reports. -@xref{Trouble,,Known Causes of Trouble with GNU Fortran}. - -However, understand that many problems preventing a -straight build from working are not @code{g77} problems, -and, in such cases, are not likely to be addressed in -future versions of @code{g77}. - -@node Pre-installation Checks -@subsection Pre-installation Checks -@cindex pre-installation checks -@cindex installing, checking before - -Before installing the system, which includes installing -@code{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: - -@example -sh# @kbd{cd /usr/src/gcc} -sh# @kbd{./g77 --driver=./xgcc -B./ -v} -g77 version 0.5.21 - ./xgcc -B./ -v -fnull-version -o /tmp/gfa18047 @dots{} -Reading specs from ./specs -gcc version 2.7.2.3.f.1 - ./cpp -lang-c -v -isystem ./include -undef @dots{} -GNU CPP version 2.7.2.3.f.1 (Linux/Alpha) -#include "..." search starts here: -#include <...> search starts here: - ./include - /usr/local/include - /usr/alpha-unknown-linux/include - /usr/lib/gcc-lib/alpha-unknown-linux/2.7.2.3.f.1/include - /usr/include -End of search list. - ./f771 /tmp/cca18048.i -fset-g77-defaults -quiet -dumpbase @dots{} -GNU F77 version 2.7.2.3.f.1 (Linux/Alpha) compiled @dots{} -GNU Fortran Front End version 0.5.21 compiled: @dots{} - as -nocpp -o /tmp/cca180481.o /tmp/cca18048.s - ld -G 8 -O1 -o /tmp/gfa18047 /usr/lib/crt0.o -L. @dots{} -__G77_LIBF77_VERSION__: 0.5.21 -@@(#)LIBF77 VERSION 19970404 -__G77_LIBI77_VERSION__: 0.5.21 -@@(#) LIBI77 VERSION pjw,dmg-mods 19970816 -__G77_LIBU77_VERSION__: 0.5.21 -@@(#) LIBU77 VERSION 19970609 -sh# @kbd{./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone} -Reading specs from ./specs -gcc version 2.7.2.3.f.1 - ./cpp -lang-c -v -isystem ./include -undef @dots{} -GNU CPP version 2.7.2.3.f.1 (Linux/Alpha) -#include "..." search starts here: -#include <...> search starts here: - ./include - /usr/local/include - /usr/alpha-unknown-linux/include - /usr/lib/gcc-lib/alpha-unknown-linux/2.7.2.3.f.1/include - /usr/include -End of search list. - ./cc1 /tmp/cca18063.i -quiet -dumpbase null.c -version @dots{} -GNU C version 2.7.2.3.f.1 (Linux/Alpha) compiled @dots{} - as -nocpp -o /tmp/cca180631.o /tmp/cca18063.s - ld -G 8 -O1 -o /tmp/delete-me /usr/lib/crt0.o -L. @dots{} -/usr/lib/crt0.o: In function `__start': -crt0.S:110: undefined reference to `main' -/usr/lib/crt0.o(.lita+0x28): undefined reference to `main' -sh# -@end example - -(Note that long lines have been truncated, and @samp{@dots{}} -used to indicate such truncations.) - -The above two commands test whether @code{g77} and @code{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 @code{gcc} and @code{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 @code{gcc} -and @code{g77}, use the following commands to invoke them. - -To invoke @code{g77}, type: - -@example -/usr/src/gcc/g77 --driver=/usr/src/gcc/xgcc -B/usr/src/gcc/ @dots{} -@end example - -To invoke @code{gcc}, type: - -@example -/usr/src/gcc/xgcc -B/usr/src/gcc/ @dots{} -@end example - -@node Installation of Binaries -@subsection Installation of Binaries -@cindex installation of binaries -@cindex @code{g77}, installation of -@cindex @code{gcc}, installation of - -After configuring, building, and testing @code{g77} and @code{gcc}, -when you are ready to install them on your system, type: - -@example -make -k CC=gcc LANGUAGES=f77 install -@end example - -As described in @ref{Installation,,Installing GNU CC, -gcc,Using and Porting GNU CC}, the values for -the @samp{CC} and @samp{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 @file{libf2c.a} -as expected, try this: - -@example -make -k @dots{} install install-libf77 install-f2c-all -@end example - -We don't know why some non-GNU versions of @code{make} sometimes -require this alternate command, but they do. -(Remember to supply the appropriate definitions for @samp{CC} and -@samp{LANGUAGES} where you see @samp{@dots{}} in the above command.) - -Note that using the @samp{-k} option tells @code{make} to -continue after some installation problems, like not having -@code{makeinfo} installed on your system. -It might not be necessary for your system. - -@node Updating Documentation -@subsection Updating Your Info Directory -@cindex updating info directory -@cindex info, updating directory -@cindex directory, updating info -@pindex /usr/info/dir -@pindex g77.info -@cindex texinfo -@cindex documentation - -As part of installing @code{g77}, you should make sure users -of @code{info} can easily access this manual on-line. -Do this by making sure a line such as the following exists -in @file{/usr/info/dir}, or in whatever file is the top-level -file in the @code{info} directory on your system (perhaps -@file{/usr/local/info/dir}: - -@example -* g77: (g77). The GNU Fortran programming language. -@end example - -If the menu in @file{dir} is organized into sections, @code{g77} -probably belongs in a section with a name such as one of -the following: - -@itemize @bullet -@item -Fortran Programming - -@item -Writing Programs - -@item -Programming Languages - -@item -Languages Other Than C - -@item -Scientific/Engineering Tools - -@item -GNU Compilers -@end itemize - -@node Missing bison? -@subsection Missing @code{bison}? -@cindex @code{bison} -@cindex missing @code{bison} - -If you cannot install @code{bison}, make sure you have started -with a @emph{fresh} distribution of @code{gcc}, do @emph{not} -do @samp{make maintainer-clean} (in other versions of @code{gcc}, -this was called @samp{make realclean}), and, to ensure that -@code{bison} is not invoked by @code{make} during the build, -type these commands: - -@example -sh# @kbd{cd gcc} -sh# @kbd{touch bi-parser.c bi-parser.h c-parse.c c-parse.h cexp.c} -sh# @kbd{touch cp/parse.c cp/parse.h objc-parse.c} -sh# -@end example - -These commands update the date-time-modified information for -all the files produced by the various invocations of @code{bison} -in the current versions of @code{gcc}, so that @code{make} no -longer believes it needs to update them. -All of these files should already exist in a @code{gcc} -distribution, but the application of patches to upgrade -to a newer version can leave the modification information -set such that the @code{bison} input files look more ``recent'' -than the corresponding output files. - -@emph{Note:} New versions of @code{gcc} might change the set of -files it generates by invoking @code{bison}---if you cannot figure -out for yourself how to handle such a situation, try an -older version of @code{gcc} until you find someone who can -(or until you obtain and install @code{bison}). - -@node Missing makeinfo? -@subsection Missing @code{makeinfo}? -@cindex @code{makeinfo} -@cindex missing @code{makeinfo} - -If you cannot install @code{makeinfo}, either use the @code{-k} option when -invoking make to specify any of the @samp{install} or related targets, -or specify @samp{MAKEINFO=echo} on the @code{make} command line. - -If you fail to do one of these things, some files, like @file{libf2c.a}, -might not be installed, because the failed attempt by @code{make} to -invoke @code{makeinfo} causes it to cancel any further processing. - -@node Distributing Binaries -@section Distributing Binaries -@cindex binaries, distributing -@cindex code, distributing - -If you are building @code{g77} for distribution to others in binary form, -first make sure you are aware of your legal responsibilities (read -the file @file{gcc/COPYING} thoroughly). - -Then, consider your target audience and decide where @code{g77} should -be installed. - -For systems like GNU/Linux that have no native Fortran compiler (or -where @code{g77} could be considered the native compiler for Fortran and -@code{gcc} for C, etc.), you should definitely configure -@code{g77} for installation -in @file{/usr/bin} instead of @file{/usr/local/bin}. -Specify the -@samp{--prefix=/usr} option when running @file{./configure}. -You might -also want to set up the distribution so the @code{f77} command is a -link to @code{g77}---just make an empty file named @file{f77-install-ok} in -the source or build directory (the one in which the @file{f} directory -resides, not the @file{f} directory itself) when you specify one of the -@file{install} or @file{uninstall} targets in a @code{make} command. - -For a system that might already have @code{f2c} installed, you definitely -will want to make another empty file (in the same directory) named -either @file{f2c-exists-ok} or @file{f2c-install-ok}. -Use the former if you -don't want your distribution to overwrite @code{f2c}-related files in existing -systems; use the latter if you want to improve the likelihood that -users will be able to use both @code{f2c} and @code{g77} to compile code for a -single program without encountering link-time or run-time -incompatibilities. - -(Make sure you clearly document, in the ``advertising'' for -your distribution, how installation of your distribution will -affect existing installations of @code{gcc}, @code{f2c}, -@code{f77}, @file{libf2c.a}, and so on. -Similarly, you should clearly document any requirements -you assume are met by users of your distribution.) - -For other systems with native @code{f77} (and @code{cc}) compilers, -configure @code{g77} as you (or most of your audience) would -configure @code{gcc} for their installations. -Typically this is for installation in -@file{/usr/local}, and would not include a copy of -@code{g77} named @code{f77}, so -users could still use the native @code{f77}. - -In any case, for @code{g77} to work properly, you @strong{must} ensure -that the binaries you distribute include: - -@table @file -@item bin/g77 -This is the command most users use to compile Fortran. - -@item bin/gcc -This is the command all users use to compile Fortran, either -directly or indirectly via the @code{g77} command. -The @file{bin/gcc} executable file must have been built -from a @code{gcc} source tree into which a @code{g77} source -tree was merged and configured, or it will not know how -to compile Fortran programs. - -@item bin/f77 -In installations with no non-GNU native Fortran -compiler, this is the same as @file{bin/g77}. -Otherwise, it should be omitted from the distribution, -so the one on already on a particular system does -not get overwritten. - -@item info/g77.info* -This is the documentation for @code{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 @file{gcc/f/*.texi} -and doing @samp{make doc} from the @file{/usr/src/gcc} directory) -to reflect any changes you've made to @code{g77}, or at -least to encourage users of your binary distribution to -report bugs to you first. - -Also, whether you distribute binaries or install @code{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 @code{info} node in @file{/usr/info/dir}. -That way, users can find @code{g77} documentation more -easily. -@xref{Updating Documentation,,Updating Your Info Directory}. - -@item man/man1/g77.1 -This is the short man page for @code{g77}. -It is out of date, but you might as well include it -for people who really like man pages. - -@item man/man1/f77.1 -In installations where @code{f77} is the same as @code{g77}, -this is the same as @file{man/man1/g77.1}. -Otherwise, it should be omitted from the distribution, -so the one already on a particular system does not -get overwritten. - -@item lib/gcc-lib/@dots{}/f771 -This is the actual Fortran compiler. - -@item lib/gcc-lib/@dots{}/libf2c.a -This is the run-time library for @code{g77}-compiled programs. -@end table - -Whether you want to include the slightly updated (and possibly -improved) versions of @code{cc1}, @code{cc1plus}, and whatever other -binaries get rebuilt with the changes the GNU Fortran distribution -makes to the GNU back end, is up to you. -These changes are -highly unlikely to break any compilers, and it is possible -they'll fix back-end bugs that can be demonstrated using front -ends other than GNU Fortran's. - -Please assure users that unless -they have a specific need for their existing, -older versions of @code{gcc} command, -they are unlikely to experience any problems by overwriting -it with your version---though they could certainly protect -themselves by making backup copies first! -Otherwise, users might try and install your binaries -in a ``safe'' place, find they cannot compile Fortran -programs with your distribution (because, perhaps, they're -picking up their old version of the @code{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, @strong{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 @code{g77} sources to port @code{g77}, e.g. to OS/2. -@email{fortran@@gnu.ai.mit.edu} 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. -- cgit v1.1