diff options
author | obrien <obrien@FreeBSD.org> | 1999-11-14 08:31:18 +0000 |
---|---|---|
committer | obrien <obrien@FreeBSD.org> | 1999-11-14 08:31:18 +0000 |
commit | 163cbd8b5acfb8f5ad046644ca980d4f31507128 (patch) | |
tree | c02c8cd2edc715e3115bece44af8de4b297c8727 /contrib | |
parent | 077ec7b22cc6ba9c1f5d23eef88ff83789900257 (diff) | |
download | FreeBSD-src-163cbd8b5acfb8f5ad046644ca980d4f31507128.zip FreeBSD-src-163cbd8b5acfb8f5ad046644ca980d4f31507128.tar.gz |
Virgin import of gcc from EGCS 1.1.2
Diffstat (limited to 'contrib')
-rw-r--r-- | contrib/gcc/f/g77install.texi | 2170 |
1 files changed, 2170 insertions, 0 deletions
diff --git a/contrib/gcc/f/g77install.texi b/contrib/gcc/f/g77install.texi new file mode 100644 index 0000000..7041107 --- /dev/null +++ b/contrib/gcc/f/g77install.texi @@ -0,0 +1,2170 @@ +@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 1998-07-13 + +@set version-g77 0.5.24 +@set version-gcc 2.8.1 +@set version-autoconf 2.12 +@set version-bison 1.25 +@set version-gperf 2.5 +@set version-gzip 1.2.4 +@set version-make 3.76.1 +@set version-makeinfo 1.68 +@set version-patch 2.5 +@set version-sed 2.05 +@set version-tar 1.12 +@set version-texinfo 3.12 + +@ifclear INSTALLONLY +@node Installation +@chapter Installing GNU Fortran +@end ifclear +@cindex installing GNU Fortran + +The following information describes how to install @code{g77}. + +Note that, for @code{egcs} users, +much of this information is obsolete, +and is superceded by the +@code{egcs} installation procedures. +Such information is explicitly flagged as such. + +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 + +@emph{Version info:} +For @code{egcs} users, the following information is +superceded by the @code{egcs} installation instructions. + +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} and @code{tar} +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 @value{version-gzip}. +(The version of GNU @code{tar} used to package this release +is @value{version-tar}.) + +@item @file{gcc-@value{version-gcc}.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 8.4MB. + +If you've already unpacked @file{gcc-@value{version-gcc}.tar.gz} into a +directory (named @file{gcc-@value{version-gcc}}) 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-@value{version-g77}.tar.gz} +You probably have already unpacked this package, +or you are reading an advance copy of these installation instructions, +which are contained in this distribution. +The size of this package is approximately 1.4MB. + +You can obtain an FSF distribution of @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 +@c As of `Version 2.249', texinfo.tex loses on a construction like +@c @code{...@value{...-...}...} since the hyphen is expanded as +@c -@discretionary{}{}{}, even though @value resets its catcode. +@c Fortunately this is currently the only instance. Kluge, kluge. +@iftex +@begingroup @let@codedash=@realdash +@end iftex +@code{gcc-@value{version-gcc}}, +@iftex +@endgroup +@end iftex +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 10MB +packed, 40MB 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 91MB +for a total of 132MB on an ix86, and an additional +136MB for a total of 177MB on an Alpha. + +@item +Removing @file{gcc/stage1} after the build recovers +13MB for a total of 119MB on an ix86, and recovers +21MB for a total of 155MB on an Alpha. + +After doing this, the integrity of the build can +still be verified via @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 39MB for a total of 80MB, and recovers +57MB for a total of 98MB on an Alpha. + +After doing this, the compiler can still be installed, +especially if GNU @code{make} is used to avoid +gratuitous rebuilds (or, the installation can be done +by hand). + +@item +Installing @code{gcc} and @code{g77} copies +23MB onto the @samp{--prefix} disk for a total of 103MB +on an ix86, and copies 31MB onto the @samp{--prefix} +disk for a total of 130MB 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{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}). +In particular, you probably need GNU @code{make} +to build outside the source directory +(with @code{configure}'s @samp{--srcdir} option.) + +The version of GNU @code{make} used to develop this release +is @value{version-make}. + +@item @code{cc} +Your system must have a working C compiler. +If it doesn't, you might be able to obtain +a prebuilt binary of some version of @code{gcc} +from the network or on CD-ROM, +perhaps from the FSF@. +The best source of information about binaries +is probably a system-specific Usenet news group, +initially via its FAQ. + +@xref{Installation,,Installing GNU CC,gcc,Using and Porting GNU CC}, +for more information on prerequisites for installing @code{gcc}. + +@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 @value{version-sed}. +(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 @value{version-sed} 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. + +@item @code{autoconf} +The version of GNU @code{autoconf} used to develop this release +is @value{version-autoconf}. + +@code{autoconf} is not needed in the typical case of +installing @code{gcc} and @code{g77}. +@xref{Missing tools?}, for information on when it +might be needed and how to work around not having it. + +@item @code{bison} +The version of GNU @code{bison} used to develop this release +is @value{version-bison}. + +@code{bison} is not needed in the typical case of +installing @code{gcc} and @code{g77}. +@xref{Missing tools?}, for information on when it +might be needed and how to work around not having it. + +@item @code{gperf} +The version of GNU @code{gperf} used to develop this release +is @value{version-gperf}. + +@code{gperf} is not needed in the typical case of +installing @code{gcc} and @code{g77}. +@xref{Missing tools?}, for information on when it +might be needed and how to work around not having it. + +@item @code{makeinfo} +The version of GNU @code{makeinfo} used to develop this release +is @value{version-makeinfo}. + +@code{makeinfo} is part of the GNU @code{texinfo} package; +@code{makeinfo} version @value{version-makeinfo} +is distributed as part of +GNU @code{texinfo} version @value{version-texinfo}. + +@code{makeinfo} is not needed in the typical case of +installing @code{gcc} and @code{g77}. +@xref{Missing tools?}, for information on when it +might be needed and how to work around not having it. + +An up-to-date version of GNU @code{makeinfo} is still convenient +when obtaining a new version of a GNU distribution such as +@code{gcc} or @code{g77}, +as it allows you to obtain the @file{.diff.gz} file +instead of the entire @file{.tar.gz} distribution +(assuming you have installed @code{patch}). + +@item @code{patch} +The version of GNU @code{patch} used to develop this release +is @value{version-patch}. + +Beginning with @code{g77} version 0.5.23, it is no longer +necessary to patch the @code{gcc} back end to build @code{g77}. + +An up-to-date version of GNU @code{patch} is still convenient +when obtaining a new version of a GNU distribution such as +@code{gcc} or @code{g77}, +as it allows you to obtain the @file{.diff.gz} file +instead of the entire @file{.tar.gz} distribution +(assuming you have installed the tools needed +to rebuild derived files, such as @code{makeinfo}). +@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. +* System-specific Problems:: Problems afflicting particular systems. +* Cross-compiler Problems:: Problems afflicting cross-compilation setups. +@end menu + +@node General Problems +@subsection General Problems + +These problems can occur on most or all systems. + +@menu +* GNU C Required:: Why even ANSI C is not enough. +* Patching GNU CC:: Why @code{gcc} needn't be patched. +* Building GNU CC Necessary:: Why you can't build @emph{just} Fortran. +* Missing strtoul or bsearch:: When linking @samp{f771} fails. +* Cleanup Kills Stage Directories:: For @code{g77} developers. +* LANGUAGES Macro Ignored:: Sometimes @samp{LANGUAGES} is ignored. +@end menu + +@node GNU C Required +@subsubsection GNU C Required +@cindex GNU C required +@cindex requirements, GNU C + +Compiling @code{g77} requires GNU C, not just ANSI C. +Fixing this wouldn't +be very hard (just tedious), but the code using GNU extensions to +the C language is expected to be rewritten for 0.6 anyway, +so there are no plans for an interim fix. + +This requirement does not mean you must already have @code{gcc} +installed to build @code{g77}. +As long as you have a working C compiler, you can use a +bootstrap build to automate the process of first building +@code{gcc} using the working C compiler you have, then building +@code{g77} and rebuilding @code{gcc} using that just-built @code{gcc}, +and so on. + +@node Patching GNU CC +@subsubsection Patching GNU CC +@cindex patch files +@cindex GBE + +@code{g77} no longer requires application of a patch file +to the @code{gcc} compiler tree. +In fact, no such patch file is distributed with @code{g77}. +This is as of version 0.5.23 +and @code{egcs} version 1.0. + +@node Building GNU CC Necessary +@subsubsection Building GNU CC Necessary +@cindex gcc, building +@cindex building gcc + +It should be possible to build the runtime without building @code{cc1} +and other non-Fortran items, but, for now, an easy way to do that +is not yet established. + +@node Missing strtoul or bsearch +@subsubsection Missing strtoul or bsearch +@cindex bsearch +@cindex _bsearch +@cindex strtoul +@cindex _strtoul +@cindex undefined reference (_bsearch) +@cindex undefined reference (_strtoul) +@cindex f771, linking error for +@cindex linking error for f771 +@cindex ld error for f771 +@cindex ld can't find _bsearch +@cindex ld can't find _strtoul +@cindex SunOS4 + +@emph{Version info:} +The following information does not apply to the +@code{egcs} version of @code{g77}. + +On SunOS4 systems, linking the @code{f771} program used to +produce an error message concerning an undefined symbol named +@samp{_strtoul}, because the @samp{strtoul} library function +is not provided on that system. + +Other systems have, in the past, been reported to not provide +their own @samp{strtoul} or @samp{bsearch} function. + +Some versions @code{g77} tried to default to providing bare-bones +versions of @code{bsearch} and @code{strtoul} automatically, +but every attempt at this has failed for at least one kind of system. + +To limit the failures to those few systems actually missing the +required routines, the bare-bones versions are still provided, +in @file{gcc/f/proj.c}, +if the appropriate macros are defined. +These are @code{NEED_BSEARCH} for @samp{bsearch} and +@code{NEED_STRTOUL} for @samp{NEED_STRTOUL}. + +Therefore, if you are sure your system is missing +@code{bsearch} or @code{strtoul} in its library, +define the relevant macro(s) before building @code{g77}. +This can be done by editing @file{gcc/f/proj.c} and inserting +either or both of the following @samp{#define} statements +before the comment shown: + +@smallexample +/* Insert #define statements here. */ + +#define NEED_BSEARCH +#define NEED_STRTOUL +@end smallexample + +Then, continue configuring and building @code{g77} as usual. + +Or, you can define these on the @code{make} command line. +To build with the bundled @code{cc} on SunOS4, for example, try: +@smallexample +make bootstrap BOOT_CFLAGS='-O2 -g -DNEED_STRTOUL' +@end smallexample + +If you then encounter problems compiling @file{gcc/f/proj.c}, +it might be due to a discrepancy between how @samp{bsearch} +or @samp{strtoul} are defined by that file and how they're +declared by your system's header files. + +In that case, you'll have to use some basic knowledge of C +to work around the problem, perhaps by editing @file{gcc/f/proj.c} +somewhat. + +@node Cleanup Kills Stage Directories +@subsubsection Cleanup Kills Stage Directories +@cindex stage directories +@cindex make clean + +It'd be helpful if @code{g77}'s @file{Makefile.in} or @file{Make-lang.in} +would create the various @file{stage@var{n}} directories and their +subdirectories, so developers and expert installers wouldn't have to +reconfigure after cleaning up. + +That help has arrived as of version 0.5.23 of @code{g77} +and version 1.1 of @code{egcs}. +Configuration itself no longer creates any particular directories +that are unique to @code{g77}. +The build procedures in @file{Make-lang.in} take care of +that, on demand. + +@node LANGUAGES Macro Ignored +@subsubsection LANGUAGES Macro Ignored +@cindex @samp{LANGUAGES} macro ignored +@cindex ignoring @samp{LANGUAGES} macro + +Prior to version 0.5.23 of @code{g77} +and version 1.1 of @code{egcs}, +@code{g77} would sometimes ignore +the absence of @samp{f77} and @samp{F77} in the +@samp{LANGUAGES} macro definition used for the +@code{make} command being processed. + +As of @code{g77} version 0.5.23 +and @code{egcs} version 1.1, +@code{g77} now obeys this macro +in all relevant situations. + +However, in versions of @code{gcc} through 2.8.1, +non-@code{g77} portions of @code{gcc}, +such as @code{g++}, +are known to go ahead and perform various +language-specific activities when their +respective language strings do not appear +in the @samp{LANGUAGES} macro in effect +during that invocation of @code{make}. + +It is expected that these remaining problems will +be fixed in a future version of @code{gcc}. + +@node System-specific Problems +@subsection System-specific Problems + +@cindex AIX +A linker bug on some versions of AIX 4.1 might prevent building +when @code{g77} is built within @code{gcc}. +It might also occur when building within @code{egcs}. +@xref{LINKFAIL}. + +@node Cross-compiler Problems +@subsection Cross-compiler Problems +@cindex cross-compiler, problems + +@code{g77} has been in alpha testing since September of +1992, and in public beta testing since February of 1995. +Alpha testing was done by a small number of people worldwide on a fairly +wide variety of machines, involving self-compilation in most or +all cases. +Beta testing has been done primarily via self-compilation, +but in more and more cases, cross-compilation (and ``criss-cross +compilation'', where a version of a compiler is built on one machine +to run on a second and generate code that runs on a third) has +been tried and has succeeded, to varying extents. + +Generally, @code{g77} can be ported to any configuration to which +@code{gcc}, @code{f2c}, and @code{libf2c} can be ported and made +to work together, aside from the known problems described in this +manual. +If you want to port @code{g77} to a particular configuration, +you should first make sure @code{gcc} and @code{libf2c} can be +ported to that configuration before focusing on @code{g77}, because +@code{g77} is so dependent on them. + +Even for cases where @code{gcc} and @code{libf2c} work, +you might run into problems with cross-compilation on certain machines, +for several reasons. + +@itemize @bullet +@item +There is one known bug +(a design bug to be fixed in 0.6) that prevents configuration of +@code{g77} as a cross-compiler in some cases, +though there are assumptions made during +configuration that probably make doing non-self-hosting builds +a hassle, requiring manual intervention. + +@item +@code{gcc} might still have some trouble being configured +for certain combinations of machines. +For example, it might not know how to handle floating-point +constants. + +@item +Improvements to the way @code{libg2c} is built could make +building @code{g77} as a cross-compiler easier---for example, +passing and using @samp{$(LD)} and @samp{$(AR)} in the appropriate +ways. +(This is improved in the @code{egcs} version of @code{g77}, +especially as of version 1.1.) + +@item +There are still some challenges putting together the right +run-time libraries (needed by @code{libg2c}) for a target +system, depending on the systems involved in the configuration. +(This is a general problem with cross-compilation, and with +@code{gcc} in particular.) +@end itemize + +@node Settings +@section Changing Settings Before Building + +Here are some internal @code{g77} settings that can be changed +by editing source files in @file{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{libg2c} supports flagging write errors immediately when +it is built with the @samp{ALWAYS_FLUSH} macro defined. +This results in a @code{libg2c} that runs slower, sometimes +quite a bit slower, under certain circumstances---for example, +accessing files via the networked file system NFS---but the +effect can be more reliable, robust file I/O. + +If you know that Fortran programs requiring this level of precision +of error reporting are to be compiled using the +version of @code{g77} you are building, you might wish to +modify the @code{g77} source tree so that the version of +@code{libg2c} is built with the @samp{ALWAYS_FLUSH} macro +defined, enabling this behavior. + +To do this, find this line in @file{f/runtime/f2c.h} in +your @code{g77} source tree: + +@example +/* #define ALWAYS_FLUSH */ +@end example + +Remove the leading @samp{/*@w{ }}, +so the line begins with @samp{#define}, +and the trailing @samp{@w{ }*/}. + +Then build or rebuild @code{g77} as appropriate. + +@node Maximum Stackable Size +@subsection Maximum Stackable Size +@vindex FFECOM_sizeMAXSTACKITEM +@cindex code, stack variables +@cindex maximum stackable size +@cindex stack allocation +@cindex segmentation violation +@code{g77}, on most machines, puts many variables and arrays on the stack +where possible, and can be configured (by changing +@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 version 0.6 of @code{g77} +will give it the capabilities it needs to not have to crash the build +but rather generate correct code for the target. +(Currently, @code{g77} +would generate bad code under such circumstances if it didn't crash +during the build, e.g. when compiling a source file that does +something like @samp{EQUIVALENCE (I,R)} and @samp{DATA R/9.43578/}.) + +@node Large Initialization +@subsection Initialization of Large Aggregate Areas + +@cindex speed, 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 + +@emph{Version info:} +For @code{egcs} users, the following information is +superceded by the @code{egcs} installation instructions. + +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-@value{version-gcc}.tar.gz +/usr/FSF/g77-@value{version-g77}.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.) + +@c @cindex SunOS4 +@c Users of the following systems should not blindly follow +@c these quick-start instructions, because of problems their +@c systems have coping with straightforward installation of +@c @code{g77}: +@c +@c @itemize @bullet +@c @item +@c SunOS4 +@c @end itemize +@c +@c Instead, see @ref{Complete Installation}, for detailed information +@c on how to configure, build, and install @code{g77} for your +@c particular system. +@c Also, see @ref{Trouble,,Known Causes of Trouble with GNU Fortran}, +@c for information on bugs and other problems known to afflict the +@c installation process, and how to report newly discovered ones. +@c +@c If your system is @emph{not} on the above list, and @emph{is} +@c a UNIX system or one of its variants, you should be able to +@c 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-@value{version-gcc}.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-@value{version-g77}.tar.gz | tar xf -} +["Broken pipe" again possible.] +@set unpack-g77 3 +sh[ 4]# @kbd{ln -s gcc-@value{version-gcc} gcc} +@set link-gcc 4 +sh[ 5]# @kbd{ln -s g77-@value{version-g77} 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{cd gcc} +sh[ 8]# @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 8 +sh[ 9]# @kbd{make bootstrap} +[This takes a long time, and is where most problems occur.] +@set build-gcc 9 +sh[10]# @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 10 +sh[11]# @kbd{rm -fr stage1} +@set rm-stage1 11 +sh[12]# @kbd{make -k install} +[The actual installation.] +@set install-g77 12 +sh[13]# @kbd{g77 -v} +[Verify that g77 is installed, obtain version info.] +@set show-version 13 +sh[14]# +@set end-procedure 14 +@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-@value{version-g77}.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 +@value{version-g77} of @code{g77}. + +@item Step @value{link-gcc}: @kbd{ln -s gcc-@value{version-gcc} gcc} +@item Step @value{link-g77}: @kbd{ln -s g77-@value{version-g77} g77} +These commands mainly help reduce typing, +and help reduce visual clutter in examples +in this manual showing what to type to install @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-@value{version-g77}} to remove +the empty directory and the symbol link to it. +But, it might be helpful to leave them around as +quick reminders of which version(s) of @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{configure-gcc}: @kbd{./configure --prefix=/usr} +This is where you specify that +the @file{g77} and @file{gcc} executables are to be +installed in @file{/usr/bin/}, +the @code{g77} and @code{gcc} documentation is +to be installed in @file{/usr/info/} and @file{/usr/man/}, +and so on. + +You should ensure that any existing installation of the @file{gcc} +executable is in @file{/usr/bin/}. + +However, if that existing version of @code{gcc} is not @value{version-gcc}, +or if you simply wish to avoid risking overwriting it with a +newly built copy of the same version, +you can specify @samp{--prefix=/usr/local} +(which is the default) +or some other path, +and invoke the newly installed version +directly from that path's @file{bin} directory. + +@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 +@end example + +Or, make sure you're using GNU @code{make}. + +@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 + +If invoking @code{g77} doesn't seem to work, +the problem might be that you've installed it in +a location that is not in your shell's search path. +For example, if you specified @samp{--prefix=/gnu}, +and @file{/gnu/bin} is not in your @code{PATH} +environment variable, +you must explicitly specify the location of the compiler +via @kbd{/gnu/bin/g77 -o smtest smtest.f}. + +After proper installation, you don't +need to keep your gcc and g77 source and build directories +around anymore. +Removing them can free up a lot of disk space. +@end table + +@node Complete Installation +@section Complete Installation + +@emph{Version info:} +For @code{egcs} users, the following information is +mostly superceded by the @code{egcs} installation instructions. + +Here is the complete @code{g77}-specific information on how +to configure, build, and install @code{g77}. + +@menu +* Unpacking:: +* Merging Distributions:: +* Where to Install:: +* Configuring gcc:: +* Building gcc:: +* Pre-installation Checks:: +* Installation of Binaries:: +* Updating Documentation:: +* Missing tools?:: +@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-@value{version-gcc}.tar.gz | tar xf -} +sh# @kbd{gunzip -c /usr/FSF/g77-@value{version-g77}.tar.gz | tar xf -} +sh# @kbd{ln -s gcc-@value{version-gcc} gcc} +sh# @kbd{ln -s g77-@value{version-g77} 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-@value{version-gcc}}). + +@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 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, +you have put together a complete @code{g77} source tree. + +@cindex gcc version numbering +@cindex version numbering +@cindex g77 version number +@cindex GNU version numbering +As of version 0.5.23, @code{g77} no longer modifies +the version number of @code{gcc}, +nor does it patch @code{gcc} itself. + +@code{g77} still depends on being merged with an +appropriate version of @code{gcc}. +For version @value{version-g77} of @code{g77}, +the specific version of @code{gcc} supported is @value{version-gcc}. + +However, other versions of @code{gcc} might be suitable +``hosts'' for this version of @code{g77}. + +GNU version numbers make it easy to figure out whether a +particular version of a distribution is newer or older than +some other version of that distribution. +The format is, +generally, @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/INSTALL/}, +which contains these installation instructions in plain-text format), +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 that version of @code{gcc}. +Since it has the same @var{major} and @var{minor} fields, +the resulting combination is likely to work. + +So, for example, if a particular version of @code{g77} has support for +@code{gcc} versions 2.8.0 and 2.8.1, +it is likely that @file{gcc-2.8.2} would work well with @code{g77}. + +However, @file{gcc-2.9.0} would almost certainly +not work with that version of @code{g77} +without appropriate modifications, +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, 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). + +@c @pindex config-lang.in +@c @emph{Note:} @code{g77}'s configuration file @file{gcc/f/config-lang.in} +@c sometimes ensures that the source code for the version of @code{gcc} +@c being configured has at least one indication of being an appropriate +@c version as required specifically by @code{g77}. +@c This configuration-time +@c checking should catch failures to use the proper version of @code{gcc} and, +@c if so caught, should abort the configuration with an explanation. +@c @emph{Please} do not try to disable this check, +@c otherwise @code{g77} might well appear to build +@c and install correctly, and even appear to compile correctly, +@c but could easily produce broken code. + +@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 normally includes installation of +a Fortran-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{gcc} being unable to compile Fortran +source files, +because when the older version of @code{gcc} is invoked, +it 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{/usr/bin/gcc}, and +the entire @file{/usr/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}. +(This means the commands are installed in @file{/usr/bin} or +@file{/usr/local/bin}, +the libraries in @file{/usr/lib} or @file{/usr/local/lib}, +and so on.) + +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, +although, in this case, @code{g77} is an augmentation of the +@code{gcc} distribution.) + +Another reason to back up the existing version first, +or make sure you can restore it easily, is that it might be +an older version on which other users have come to depend +for certain behaviors. +However, even the new version of @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{libg2c}, 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{libg2c} configuration, unless +you're configuring @code{g77} as a cross-compiler. +In this case, the @code{libg2c} 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 plain-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, +or by starting in an empty directory +and typing a command such as @kbd{../gcc/configure} to +build with separate build and source directories, +is known to work with GNU @code{make}, +but it is known to not 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 +used to issue a warning message about this +when configuring for building binaries outside the source directory, +but no longer does this as of version 0.5.23. + +Instead, @code{g77} simply rejects most common attempts +to build it using a non-GNU @code{make} when the +build directory is not the same as the source directory, +issuing an explanatory diagnostic. + +@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{libg2c} automatically, you're ready to start the actual +build by invoking @code{make}. + +@pindex configure +@emph{Note:} You @strong{must} have run the @file{configure} +script in @code{gcc} 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 compilers along with the +necessary run-time libraries, issue the following +command: + +@example +make -k CC=gcc +@end example + +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}. +Consider treating them as @code{gcc} bugs instead. + +@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 -B./ -v} +g77 version @value{version-g77} +Driving: ./g77 -B./ -v -c -xf77-version /dev/null -xnone +Reading specs from ./specs +gcc version @value{version-gcc} + cpp -lang-c -v -isystem ./include -undef -D__GNUC__=2 @dots{} +GNU CPP version @value{version-gcc} (Alpha GNU/Linux with ELF) +#include "..." search starts here: +#include <...> search starts here: + include + /usr/alpha-linux/include + /usr/lib/gcc-lib/alpha-linux/@value{version-gcc}/include + /usr/include +End of search list. + ./f771 -fnull-version -quiet -dumpbase g77-version.f -version @dots{} +GNU F77 version @value{version-gcc} (alpha-linux) compiled @dots{} +GNU Fortran Front End version @value{version-g77} + as -nocpp -o /tmp/cca14485.o /tmp/cca14485.s + ld -m elf64alpha -G 8 -O1 -dynamic-linker /lib/ld-linux.so.2 @dots{} + /tmp/cca14485 +__G77_LIBF77_VERSION__: @value{version-g77} +@@(#)LIBF77 VERSION 19970919 +__G77_LIBI77_VERSION__: @value{version-g77} +@@(#) LIBI77 VERSION pjw,dmg-mods 19980405 +__G77_LIBU77_VERSION__: @value{version-g77} +@@(#) LIBU77 VERSION 19970919 +sh# @kbd{./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone} +Reading specs from ./specs +gcc version @value{version-gcc} + ./cpp -lang-c -v -isystem ./include -undef @dots{} +GNU CPP version @value{version-gcc} (Alpha GNU/Linux with ELF) +#include "..." search starts here: +#include <...> search starts here: + include + /usr/alpha-linux/include + /usr/lib/gcc-lib/alpha-linux/@value{version-gcc}/include + /usr/include +End of search list. + ./cc1 /tmp/cca18063.i -quiet -dumpbase null.c -version @dots{} +GNU C version @value{version-gcc} (alpha-linux) compiled @dots{} + as -nocpp -o /tmp/cca180631.o /tmp/cca18063.s + ld -m elf64alpha -G 8 -O1 -dynamic-linker /lib/ld-linux.so.2 @dots{} +/usr/lib/crt1.o: In function `_start': +../sysdeps/alpha/elf/start.S:77: undefined reference to `main' +../sysdeps/alpha/elf/start.S:77: undefined reference to `main' +sh# +@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 -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 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{libg2c.a} +as expected, try this: + +@example +make -k @dots{} install install-libf77 +@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 definition for @samp{CC} +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. + +@emph{Note:} @code{g77} no longer installs +files not directly part of @code{g77}, +such as @file{/usr/bin/f77}, @file{/usr/lib/libf2c.a}, +and @file{/usr/include/f2c.h}, or their +@file{/usr/local} equivalents. + +@xref{Distributing Binaries}, for information on +how to accommodate systems with no existing non-@code{g77} +@code{f77} compiler and systems with @code{f2c} installed. + +@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. + +@code{g77} does this automatically by +invoking the @code{install-info} command +when you use @samp{make install} to install @code{g77}. + +If that fails, or if the @code{info} directory +it updates is not the one normally accessed by users, +consider invoking it yourself. +For example: + +@smallexample +install-info --info-dir=/usr/info /usr/info/g77.info +@end smallexample + +The above example assumes the @code{g77} documentation +already is installed in @file{/usr/info} +and that @file{/usr/info/dir} is the file +you wish to update. +Adjust the command accordingly, +if those assumptions are wrong. + +@node Missing tools? +@subsection Missing tools? +@cindex command missing +@cindex command not found +@cindex file not found +@cindex not found + +A build of @code{gcc} might fail due to one or more tools +being called upon by @code{make} +(during the build or install process), +when those tools are not installed on your system. + +This situation can result from any of the following actions +(performed by you or someone else): + +@itemize @bullet +@item +Changing the source code or documentation yourself +(as a developer or technical writer). + +@item +Applying a patch that changes the source code or documentation +(including, sometimes, the official patches distributed by +the FSF). + +@item +Deleting the files that are created by the (missing) tools. + +The @samp{make maintainer-clean} command is supposed +to delete these files, so invoking this command without +having all the appropriate tools installed is not recommended. + +@item +Creating the source directory using a method that +does not preserve the date-time-modified information +in the original distribution. + +For example, the UNIX @samp{cp -r} command copies a +directory tree without preserving the date-time-modified +information. +Use @samp{cp -pr} instead. +@end itemize + +The reason these activities cause @code{make} to try and +invoke tools that it probably wouldn't when building +from a perfectly ``clean'' source directory containing +@code{gcc} and @code{g77} is that some files in the +source directory (and the corresponding distribution) +aren't really source files, but @emph{derived} files +that are produced by running tools with the corresponding +source files as input. +These derived files @dfn{depend}, in @code{make} terminology, +on the corresponding source files. + +@code{make} determines that a file that depends on another +needs to be updated if the date-time-modified information for +the source file shows that it is newer than the corresponding +information for the derived file. + +If it makes that determination, @code{make} runs the appropriate +commands (specified in the ``Makefile'') to update the +derived file, and this process typically calls upon one or +more installed tools to do the work. + +The ``safest'' approach to dealing with this situation +is to recreate the @code{gcc} and @code{g77} source +directories from complete @code{gcc} and @code{g77} distributions +known to be provided by the FSF. + +Another fairly ``safe'' approach is to simply install +the tools you need to complete the build process. +This is especially appropriate if you've changed the +source code or applied a patch to do so. + +However, if you're certain that the problem is limited +entirely to incorrect date-time-modified information, +that there are no discrepancies between the contents of +source files and files derived from them in the source +directory, you can often update the date-time-modified +information for the derived files to work around the +problem of not having the appropriate tools installed. + +On UNIX systems, the simplest way to update the date-time-modified +information of a file is to use the use the @samp{touch} +command. + +How to use @samp{touch} to update the derived files +updated by each of the tools is described below. +@emph{Note:} New versions of @code{g77} might change the set of +files it generates by invoking each of these tools. +If you cannot figure +out for yourself how to handle such a situation, try an +older version of @code{g77} until you find someone who can +(or until you obtain and install the relevant tools). + +@menu +* autoconf: Missing autoconf?. +* bison: Missing bison?. +* gperf: Missing gperf?. +* makeinfo: Missing makeinfo?. +@end menu + +@node Missing autoconf? +@subsubsection Missing @code{autoconf}? +@cindex @code{autoconf} +@cindex missing @code{autoconf} + +If you cannot install @code{autoconf}, make sure you have started +with a @emph{fresh} distribution of @code{gcc} and @code{g77}, +do @emph{not} do @samp{make maintainer-clean}, and, to ensure that +@code{autoconf} is not invoked by @code{make} during the build, +type these commands: + +@example +sh# @kbd{cd gcc/f/runtime} +sh# @kbd{touch configure libU77/configure} +sh# @kbd{cd ../../..} +sh# +@end example + +@node Missing bison? +@subsubsection 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}, 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# @kbd{cd ..} +sh# +@end example + +@node Missing gperf? +@subsubsection Missing @code{gperf}? +@cindex @code{gperf} +@cindex missing @code{gperf} + +If you cannot install @code{gperf}, make sure you have started +with a @emph{fresh} distribution of @code{gcc}, do @emph{not} +do @samp{make maintainer-clean}, and, to ensure that +@code{gperf} is not invoked by @code{make} during the build, +type these commands: + +@example +sh# @kbd{cd gcc} +sh# @kbd{touch c-gperf.h} +sh# @kbd{cd ..} +sh# +@end example + +@node Missing makeinfo? +@subsubsection Missing @code{makeinfo}? +@cindex @code{makeinfo} +@cindex missing @code{makeinfo} +@cindex @code{libg2c.a} not found +@cindex missing @code{libg2c.a} + +If @code{makeinfo} is needed but unavailable +when installing (via @code{make install}), +some files, like @file{libg2c.a}, +might not be installed, +because once @code{make} determines that it cannot +invoke @code{makeinfo}, it cancels any further processing. + +If you cannot install @code{makeinfo}, an easy work-around is to +specify @samp{MAKEINFO=true} on the @code{make} command line, +or to specify the @samp{-k} option (@kbd{make -k install}). + +Another approach is to force the relevant files to be up-to-date +by typing these commands and then re-trying the installation step: + +@example +sh# @kbd{cd gcc} +sh# @kbd{touch f/g77.info f/BUGS f/INSTALL f/NEWS} +sh# @kbd{cd ..} +sh# +@end example + +@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 @file{f77} command is a link to @file{g77}, +although a script that accepts ``classic'' UNIX @code{f77} +options and translates the command-line to the +appropriate @code{g77} command line would be more appropriate. +If you do this, @emph{please} also provide a ``man page'' in +@file{man/man1/f77.1} describing the command. +(A link to @file{man/man1/g77.1} is appropriate +if @file{bin/f77} is a link to @file{bin/g77}.) + +For a system that might already have @code{f2c} installed, +consider whether inter-operation with @code{g77} will be +important to users of @code{f2c} on that system. +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 that, +whenever they intend to combine @code{f2c}-produced code +with @code{g77}-produced code in an executable, they: + +@itemize @bullet +@item +Use the @file{lib/gcc-lib/@dots{}/include/g2c.h} file +generated by the @code{g77} build +in place of the @file{f2c.h} file +that normally comes with @code{f2c} +(or versions of @code{g77} prior to 0.5.23) +when compiling @emph{all} of the @code{f2c}-produced C code + +@item +Link to the @code{lib/gcc-lib/@dots{}/libg2c.a} library +built by the @code{g77} build +instead of the @file{libf2c.a} library +that normally comes with @code{f2c} +(or versions of @code{g77} prior to 0.5.23) +@end itemize + +How you choose to effect the above depends on whether +the existing installation of @code{f2c} must be +maintained. + +In any case, it is important to try and ensure that +the installation keeps working properly even after +subsequent re-installation of @code{f2c}, +which probably involves overwriting +@file{/usr/local/lib/libf2c.a} and +@file{/usr/local/include/f2c.h}, +or similar. + +At least, copying @file{libg2c.a} and @file{g2c.h} into +the appropriate ``public'' directories +allows users to more easily select the version of +@code{libf2c} they wish to use for a particular +build. +The names are changed by @code{g77} to make this +coexistence easier to maintain; +even if @code{f2c} is installed later, +the @code{g77} files normally installed +by its installation process aren't disturbed. +Use of symbolic links from one set of files to +another might result in problems after a subsequent +reinstallation of either @code{f2c} or @code{g77}, +so be sure to alert users of your distribution +accordingly. + +(Make sure you clearly document, in the description of +your distribution, how installation of your distribution will +affect existing installations of @code{gcc}, @code{f2c}, +@code{f77}, @file{libf2c.a}, and so on. +Similarly, you should clearly document any requirements +you assume will be met by users of your distribution.) + +For other systems with native @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 new version of @file{/usr/bin/f77} +or @file{/usr/local/bin/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 some users use to compile Fortran, +typically when compiling programs written in other languages +at the same time. +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 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 not always kept up-to-date, +but you might as well include it +for people who really like ``man'' pages. + +@cindex gcc-lib directory +@cindex directories, gcc-lib +@item lib/gcc-lib +This is the directory containing the ``private'' files +installed by and for @code{gcc}, @code{g77}, @code{g++}, +and other GNU compilers. + +@item lib/gcc-lib/@dots{}/f771 +This is the actual Fortran compiler. + +@item lib/gcc-lib/@dots{}/libg2c.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 @file{cc1}, @file{cc1plus}, and whatever other +binaries get rebuilt with the changes the GNU Fortran distribution +makes to the GNU back end, is up to you. +These changes are highly unlikely to break any compilers, +because they involve doing things like adding to the +list of acceptable compiler options +(so, for example, @file{cc1plus} accepts, and ignores, +options that only @file{f771} actually processes). + +Please assure users that unless +they have a specific need for their existing, +older versions of @file{gcc} command, +they are unlikely to experience any problems by overwriting +it with your version---though they could certainly protect +themselves by making backup copies first! + +Otherwise, users might try and install your binaries +in a ``safe'' place, find they cannot compile Fortran +programs with your distribution (because, perhaps, they're +invoking their old version of the @file{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.org} has received a fair number of bug +reports that turned out to be problems with other peoples' ports +and distributions, about which nothing could be done for the +user. +Once you are quite certain a bug report does not involve +your efforts, you can forward it to us. |