@c Copyright (C) 1995, 1996, 1997, 1998, 1999 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 Keep this the same as the dates above, since it's used @c in the standalone derivations of this file (e.g. INSTALL). @set copyrights 1995, 1996, 1997, 1998, 1999 @set last-update-install 1999-07-17 @include root.texi @ifset DOC-INSTALL @c The immediately following lines apply to the INSTALL file @c which is generated using this file. @emph{Note:} This file is automatically generated from the files @file{install0.texi} and @file{g77install.texi}. @file{INSTALL} is @emph{not} a source file, although it is normally included within source distributions. This file contains installation information for the GNU Fortran compiler. Copyright (C) @value{copyrights-install} Free Software Foundation, Inc. You may copy, distribute, and modify it freely as long as you preserve this copyright notice and permission notice. @node Top,,, (dir) @chapter Installing GNU Fortran @end ifset @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 @ifset DOC-G77 @node Installation @chapter Installing GNU Fortran @cindex installing, GNU Fortran @end ifset The following information describes how to install @code{g77}. @clear OMIT-FSF-G77 @ifset EGCS-G77 @set OMIT-FSF-G77 @end ifset @ifset GCC-G77 @set OMIT-FSF-G77 @end ifset @ifset OMIT-FSF-G77 Note that, for users of the @value{which-g77} version of @code{g77}, much of the information is obsolete, and is superceded by the @value{which-gcc} installation procedures. Such information is accordingly omitted and flagged as such. @end ifset @ifclear OMIT-FSF-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. @end ifclear @ifset DEVELOPMENT @emph{Warning:} The information below is still under development, and might not accurately reflect the @code{g77} code base of which it is a part. Efforts are made to keep it somewhat up-to-date, but they are particularly concentrated on any version of this information that is distributed as part of a @emph{released} @code{g77}. In particular, while this information is intended to apply to the @value{which-g77} version of @code{g77}, only an official @emph{release} of that version is expected to contain documentation that is most consistent with the @code{g77} product in that version. @end ifset The following information was last updated on @value{last-update-install}: @menu * Prerequisites:: Make sure your system is ready for @code{g77}. * Problems Installing:: Known trouble areas. * Settings:: Changing @code{g77} internals before building. * Quick Start:: The easier procedure for non-experts. * Complete Installation:: For experts, or those who want to be: the details. * Distributing Binaries:: If you plan on distributing your @code{g77}. @end menu @node Prerequisites @section Prerequisites @cindex prerequisites @ifset OMIT-FSF-G77 For users of the @value{which-g77} version of @code{g77}, this information is superceded by the @value{which-gcc} installation instructions. @end ifset @ifclear OMIT-FSF-G77 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 @end ifclear @node Problems Installing @section Problems Installing @cindex problems installing @cindex installation problems This is a list of problems (and some apparent problems which don't really mean anything is wrong) that show up when configuring, building, installing, or porting GNU Fortran. @xref{Installation Problems,,,gcc,Using and Porting GNU CC}, for more information on installation problems that can afflict either @code{gcc} or @code{g77}. @menu * General Problems:: Problems afflicting most or all systems. * System-specific Problems:: Problems afflicting particular systems. * Cross-compiler Problems:: Problems afflicting cross-compilation setups. @end menu @node General Problems @subsection General Problems These problems can occur on most or all systems. @menu * GNU C Required:: Why even ANSI C is not enough. * Patching GNU CC:: Why @code{gcc} needn't be patched. * Building GNU CC Necessary:: Why you can't build @emph{just} Fortran. * Missing strtoul or bsearch:: When linking @code{f771} fails. * Cleanup Kills Stage Directories:: For @code{g77} developers. * LANGUAGES Macro Ignored:: Sometimes @code{LANGUAGES} is ignored. @end menu @node GNU C Required @subsubsection GNU C Required @cindex GNU C required @cindex requirements, GNU C Compiling @code{g77} requires GNU C, not just ANSI C. Fixing this wouldn't be very hard (just tedious), but the code using GNU extensions to the C language is expected to be rewritten for 0.6 anyway, so there are no plans for an interim fix. This requirement does not mean you must already have @code{gcc} installed to build @code{g77}. As long as you have a working C compiler, you can use a ``bootstrap'' build to automate the process of first building @code{gcc} using the working C compiler you have, then building @code{g77} and rebuilding @code{gcc} using that just-built @code{gcc}, and so on. @node Patching GNU CC @subsubsection Patching GNU CC @cindex patch files @cindex GBE @code{g77} no longer requires application of a patch file to the @code{gcc} compiler tree. In fact, no such patch file is distributed with @code{g77}. This is as of version 0.5.23 and @code{egcs} version 1.0. @node Building GNU CC Necessary @subsubsection Building GNU CC Necessary @cindex @code{gcc}, building @cindex building gcc It should be possible to build the runtime without building @code{cc1} and other non-Fortran items, but, for now, an easy way to do that is not yet established. @node Missing strtoul or bsearch @subsubsection Missing strtoul or bsearch @cindex bsearch @cindex _bsearch @cindex strtoul @cindex _strtoul @cindex undefined reference (_bsearch) @cindex undefined reference (_strtoul) @cindex f771, linking error for @cindex linking error for f771 @cindex @code{ld}, error linking f771 @cindex @code{ld}, can't find _bsearch @cindex @code{ld}, can't find _strtoul @cindex SunOS4 @ifset OMIT-FSF-G77 This information does not apply to the @value{which-g77} version of @code{g77}, @end ifset @ifclear OMIT-FSF-G77 On SunOS4 systems, linking the @code{f771} program used to produce an error message concerning an undefined symbol named @samp{_strtoul}, because the @code{strtoul} library function is not provided on that system. Other systems have, in the past, been reported to not provide their own @code{strtoul} or @code{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{@value{path-g77}/proj.c}, if the appropriate macros are defined. These are @code{NEED_BSEARCH} for @code{bsearch} and @code{NEED_STRTOUL} for @code{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{@value{path-g77}/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{@value{path-g77}/proj.c}, it might be due to a discrepancy between how @code{bsearch} or @code{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{@value{path-g77}/proj.c} somewhat. @end ifclear @node Cleanup Kills Stage Directories @subsubsection Cleanup Kills Stage Directories @cindex stage directories @cindex make clean It'd be helpful if @code{g77}'s @file{Makefile.in} or @file{Make-lang.in} would create the various @file{stage@var{n}} directories and their subdirectories, so developers and expert installers wouldn't have to reconfigure after cleaning up. That help has arrived as of version 0.5.23 of @code{g77} and version 1.1 of @code{egcs}. Configuration itself no longer creates any particular directories that are unique to @code{g77}. The build procedures in @file{Make-lang.in} take care of that, on demand. @node LANGUAGES Macro Ignored @subsubsection LANGUAGES Macro Ignored @cindex @code{LANGUAGES} macro ignored @cindex ignoring @code{LANGUAGES} macro Prior to version 0.5.23 of @code{g77} and version 1.1 of @code{egcs}, @code{g77} would sometimes ignore the absence of @code{f77} and @code{F77} in the @code{LANGUAGES} macro definition used for the @code{make} command being processed. As of @code{g77} version 0.5.23 and @code{egcs} version 1.1, @code{g77} now obeys this macro in all relevant situations. However, in versions of @code{gcc} through 2.8.1, non-@code{g77} portions of @code{gcc}, such as @code{g++}, are known to go ahead and perform various language-specific activities when their respective language strings do not appear in the @code{LANGUAGES} macro in effect during that invocation of @code{make}. It is expected that these remaining problems will be fixed in a future version of @code{gcc}. @node System-specific Problems @subsection System-specific Problems @cindex AIX A linker bug on some versions of AIX 4.1 might prevent building when @code{g77} is built within @code{gcc}. It might also occur when building within @code{egcs}. @ifset DOC-G77 @xref{LINKFAIL}. @end ifset @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{@value{path-g77}/} before building. This information, and perhaps even these settings, represent stop-gap solutions to problems people doing various ports of @code{g77} have encountered. As such, none of the following information is expected to be pertinent in future versions of @code{g77}. @menu * Larger File Unit Numbers:: Raising @code{MXUNIT}. * Always Flush Output:: Synchronizing write errors. * Maximum Stackable Size:: Large arrays forced off the stack. * Floating-point Bit Patterns:: Possible programs building @code{g77} as a cross-compiler. * Large Initialization:: Large arrays with @code{DATA} initialization. * Alpha Problems Fixed:: Problems with 64-bit systems like Alphas now fixed? @end menu @node Larger File Unit Numbers @subsection Larger File Unit Numbers @cindex MXUNIT @cindex unit numbers @cindex maximum unit number @cindex illegal unit number @cindex increasing maximum unit number As distributed, whether as part of @code{f2c} or @code{g77}, @code{libf2c} accepts file unit numbers only in the range 0 through 99. For example, a statement such as @samp{WRITE (UNIT=100)} causes a run-time crash in @code{libf2c}, because the unit number, 100, is out of range. If you know that Fortran programs at your installation require the use of unit numbers higher than 99, you can change the value of the @code{MXUNIT} macro, which represents the maximum unit number, to an appropriately higher value. To do this, edit the file @file{@value{path-libf2c}/libI77/fio.h} in your @code{g77} source tree, changing the following line: @example #define MXUNIT 100 @end example Change the line so that the value of @code{MXUNIT} is defined to be at least one @emph{greater} than the maximum unit number used by the Fortran programs on your system. (For example, a program that does @samp{WRITE (UNIT=255)} would require @code{MXUNIT} set to at least 256 to avoid crashing.) Then build or rebuild @code{g77} as appropriate. @emph{Note:} Changing this macro has @emph{no} effect on other limits your system might place on the number of files open at the same time. That is, the macro might allow a program to do @samp{WRITE (UNIT=100)}, but the library and operating system underlying @code{libf2c} might disallow it if many other files have already been opened (via @code{OPEN} or implicitly via @code{READ}, @code{WRITE}, and so on). Information on how to increase these other limits should be found in your system's documentation. @node Always Flush Output @subsection Always Flush Output @cindex ALWAYS_FLUSH @cindex synchronous write errors @cindex disk full @cindex flushing output @cindex fflush() @cindex I/O, flushing @cindex output, flushing @cindex writes, flushing @cindex NFS @cindex network file system Some Fortran programs require output (writes) to be flushed to the operating system (under UNIX, via the @code{fflush()} library call) so that errors, such as disk full, are immediately flagged via the relevant @code{ERR=} and @code{IOSTAT=} mechanism, instead of such errors being flagged later as subsequent writes occur, forcing the previously written data to disk, or when the file is closed. Essentially, the difference can be viewed as synchronous error reporting (immediate flagging of errors during writes) versus asynchronous, or, more precisely, buffered error reporting (detection of errors might be delayed). @code{libg2c} supports flagging write errors immediately when it is built with the @code{ALWAYS_FLUSH} macro defined. This results in a @code{libg2c} that runs slower, sometimes quite a bit slower, under certain circumstances---for example, accessing files via the networked file system NFS---but the effect can be more reliable, robust file I/O. If you know that Fortran programs requiring this level of precision of error reporting are to be compiled using the version of @code{g77} you are building, you might wish to modify the @code{g77} source tree so that the version of @code{libg2c} is built with the @code{ALWAYS_FLUSH} macro defined, enabling this behavior. To do this, find this line in @file{@value{path-libf2c}/f2c.h} in your @code{g77} source tree: @example /* #define ALWAYS_FLUSH */ @end example Remove the leading @samp{/*@w{ }}, so the line begins with @samp{#define}, and the trailing @samp{@w{ }*/}. Then build or rebuild @code{g77} as appropriate. @node Maximum Stackable Size @subsection Maximum Stackable Size @vindex FFECOM_sizeMAXSTACKITEM @cindex code, stack variables @cindex maximum stackable size @cindex stack, allocation @cindex segmentation violation @code{g77}, on most machines, puts many variables and arrays on the stack where possible, and can be configured (by changing @code{FFECOM_sizeMAXSTACKITEM} in @file{@value{path-g77}/com.c}) to force smaller-sized entities into static storage (saving on stack space) or permit larger-sized entities to be put on the stack (which can improve run-time performance, as it presents more opportunities for the GBE to optimize the generated code). @emph{Note:} Putting more variables and arrays on the stack might cause problems due to system-dependent limits on stack size. Also, the value of @code{FFECOM_sizeMAXSTACKITEM} has no effect on automatic variables and arrays. @xref{But-bugs}, for more information. @node Floating-point Bit Patterns @subsection Floating-point Bit Patterns @cindex cross-compiler, building @cindex floating-point bit patterns @cindex bit patterns The @code{g77} build will crash if an attempt is made to build it as a cross-compiler for a target when @code{g77} cannot reliably determine the bit pattern of floating-point constants for the target. Planned improvements for version 0.6 of @code{g77} will give it the capabilities it needs to not have to crash the build but rather generate correct code for the target. (Currently, @code{g77} would generate bad code under such circumstances if it didn't crash during the build, e.g. when compiling a source file that does something like @samp{EQUIVALENCE (I,R)} and @samp{DATA R/9.43578/}.) @node Large Initialization @subsection Initialization of Large Aggregate Areas @cindex speed, of compiler @cindex slow compiler @cindex memory utilization @cindex large initialization @cindex aggregate initialization A warning message is issued when @code{g77} sees code that provides initial values (e.g. via @code{DATA}) to an aggregate area (@code{COMMON} or @code{EQUIVALENCE}, or even a large enough array or @code{CHARACTER} variable) that is large enough to increase @code{g77}'s compile time by roughly a factor of 10. This size currently is quite small, since @code{g77} currently has a known bug requiring too much memory and time to handle such cases. In @file{@value{path-g77}/data.c}, the macro @code{FFEDATA_sizeTOO_BIG_INIT_} is defined to the minimum size for the warning to appear. The size is specified in storage units, which can be bytes, words, or whatever, on a case-by-case basis. After changing this macro definition, you must (of course) rebuild and reinstall @code{g77} for the change to take effect. Note that, as of version 0.5.18, improvements have reduced the scope of the problem for @emph{sparse} initialization of large arrays, especially those with large, contiguous uninitialized areas. However, the warning is issued at a point prior to when @code{g77} knows whether the initialization is sparse, and delaying the warning could mean it is produced too late to be helpful. Therefore, the macro definition should not be adjusted to reflect sparse cases. Instead, adjust it to generate the warning when densely initialized arrays begin to cause responses noticeably slower than linear performance would suggest. @node Alpha Problems Fixed @subsection Alpha Problems Fixed @cindex Alpha, support @cindex 64-bit systems @code{g77} used to warn when it was used to compile Fortran code for a target configuration that is not basically a 32-bit machine (such as an Alpha, which is a 64-bit machine, especially if it has a 64-bit operating system running on it). That was because @code{g77} was known to not work properly on such configurations. As of version 0.5.20, @code{g77} is believed to work well enough on such systems. So, the warning is no longer needed or provided. However, support for 64-bit systems, especially in areas such as cross-compilation and handling of intrinsics, is still incomplete. The symptoms are believed to be compile-time diagnostics rather than the generation of bad code. It is hoped that version 0.6 will completely support 64-bit systems. @node Quick Start @section Quick Start @cindex quick start @ifset OMIT-FSF-G77 For users of the @value{which-g77} version of @code{g77}, this information is superceded by the @value{which-gcc} installation instructions. @end ifset @ifclear OMIT-FSF-G77 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 @end ifclear @node Complete Installation @section Complete Installation @ifset OMIT-FSF-G77 For users of the @value{which-g77} version of @code{g77}, this information is superceded by the @value{which-gcc} installation instructions. @end ifset @ifclear OMIT-FSF-G77 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 optimization, for 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, @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 @code{gcc}, version number @cindex version number @cindex @code{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{@value{path-g77}/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. @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{@value{path-g77}/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 @code{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} @cindex @code{LANGUAGES} macro 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 @code{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 @code{c} or @code{f77} from the definition of the @code{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, see @ref{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 @code{CC} and @code{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 @code{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 @code{touch} command. How to use @code{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 @value{path-libf2c}} 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} 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 @end ifclear @node Distributing Binaries @section Distributing Binaries @cindex binaries, distributing @cindex code, distributing @ifset OMIT-FSF-G77 For users of the @value{which-g77} version of @code{g77}, this information is superceded by the @value{which-gcc} installation instructions. @end ifset @ifclear OMIT-FSF-G77 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{@value{path-g77}/*.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. @end ifclear