diff options
Diffstat (limited to 'gcc/f/INSTALL')
| -rw-r--r-- | gcc/f/INSTALL | 1517 |
1 files changed, 1517 insertions, 0 deletions
diff --git a/gcc/f/INSTALL b/gcc/f/INSTALL new file mode 100644 index 0000000..97423be --- /dev/null +++ b/gcc/f/INSTALL @@ -0,0 +1,1517 @@ +This file contains installation information for the GNU Fortran +compiler. Copyright (C) 1995, 1996 Free Software Foundation, Inc. You +may copy, distribute, and modify it freely as long as you preserve this +copyright notice and permission notice. + +Installing GNU Fortran +********************** + + The following information describes how to install `g77'. + + The information in this file generally pertains to dealing with +*source* distributions of `g77' and `gcc'. It is possible that some of +this information will be applicable to some *binary* distributions of +these products--however, since these distributions are not made by the +maintainers of `g77', responsibility for binary distributions rests with +whoever built and first distributed them. + + Nevertheless, efforts to make `g77' easier to both build and install +from source and package up as a binary distribution are ongoing. + +Prerequisites +============= + + The procedures described to unpack, configure, build, and install +`g77' assume your system has certain programs already installed. + + The following prerequisites should be met by your system before you +follow the `g77' installation instructions: + +`gzip' + To unpack the `gcc' and `g77' distributions, you'll need the + `gunzip' utility in the `gzip' distribution. Most UNIX systems + already have `gzip' installed. If yours doesn't, you can get it + from the FSF. + + Note that you'll need `tar' and other utilities as well, but all + UNIX systems have these. There are GNU versions of all these + available--in fact, a complete GNU UNIX system can be put together + on most systems, if desired. + +`gcc-2.7.2.2.tar.gz' + You need to have this, or some other applicable, version of `gcc' + on your system. The version should be an exact copy of a + distribution from the FSF. It is approximately 7MB large. + + If you've already unpacked `gcc-2.7.2.2.tar.gz' into a directory + (named `gcc-2.7.2.2') called the "source tree" for `gcc', you can + delete the distribution itself, but you'll need to remember to + skip any instructions to unpack this distribution. + + Without an applicable `gcc' source tree, you cannot build `g77'. + You can obtain an FSF distribution of `gcc' from the FSF. + +`g77-0.5.21.tar.gz' + You probably have already unpacked this distribution, or you are + reading an advanced copy of this manual, which is contained in + this distribution. This distribution approximately 1MB large. + + You can obtain an FSF distribution of `g77' from the FSF, the same + way you obtained `gcc'. + +100MB disk space + For a complete "bootstrap" build, about 100MB of disk space is + required for `g77' by the author's current GNU/Linux system. + + Some juggling can reduce the amount of space needed; during the + bootstrap process, once Stage 3 starts, during which the version + of `gcc' that has been copied into the `stage2/' directory is used + to rebuild the system, you can delete the `stage1/' directory to + free up some space. + + It is likely that many systems don't require the complete + bootstrap build, as they already have a recent version of `gcc' + installed. Such systems might be able to build `g77' with only + about 75MB of free space. + +`patch' + Although you can do everything `patch' does yourself, by hand, + without much trouble, having `patch' installed makes installation + of new versions of GNU utilities such as `g77' so much easier that + it is worth getting. You can obtain `patch' the same way you + obtained `gcc' and `g77'. + + In any case, you can apply patches by hand--patch files are + designed for humans to read them. + +`make' + Your system must have `make', and you will probably save yourself + a lot of trouble if it is GNU `make' (sometimes referred to as + `gmake'). + +`cc' + Your system must have a working C compiler. + + *Note Installing GNU CC: (gcc)Installation, for more information + on prerequisites for installing `gcc'. + +`bison' + If you do not have `bison' installed, you can usually work around + any need for it, since `g77' itself does not use it, and `gcc' + normally includes all files generated by running it in its + distribution. You can obtain `bison' the same way you obtained + `gcc' and `g77'. + + *Note Missing bison?::, for information on how to work around not + having `bison'. + +`makeinfo' + If you are missing `makeinfo', you can usually work around any + need for it. You can obtain `makeinfo' the same way you obtained + `gcc' and `g77'. + + *Note Missing makeinfo?::, for information on getting around the + lack of `makeinfo'. + +`root' access + To perform the complete installation procedures on a system, you + need to have `root' access to that system, or equivalent access. + + Portions of the procedure (such as configuring and building `g77') + can be performed by any user with enough disk space and virtual + memory. + + However, these instructions are oriented towards less-experienced + users who want to install `g77' on their own personal systems. + + System administrators with more experience will want to determine + for themselves how they want to modify the procedures described + below to suit the needs of their installation. + +Problems Installing +=================== + + This is a list of problems (and some apparent problems which don't +really mean anything is wrong) that show up when configuring, building, +installing, or porting GNU Fortran. + + *Note Installation Problems: (gcc)Installation Problems, for more +information on installation problems that can afflict either `gcc' or +`g77'. + +General Problems +---------------- + + These problems can occur on most or all systems. + +GNU C Required +.............. + + Compiling `g77' requires GNU C, not just ANSI C. Fixing this +wouldn't be very hard (just tedious), but the code using GNU extensions +to the C language is expected to be rewritten for 0.6 anyway, so there +are no plans for an interim fix. + + This requirement does not mean you must already have `gcc' installed +to build `g77'. As long as you have a working C compiler, you can use a +bootstrap build to automate the process of first building `gcc' using +the working C compiler you have, then building `g77' and rebuilding +`gcc' using that just-built `gcc', and so on. + +Patching GNU CC Necessary +......................... + + `g77' currently requires application of a patch file to the gcc +compiler tree. The necessary patches should be folded in to the +mainline gcc distribution. + + Some combinations of versions of `g77' and `gcc' might actually +*require* no patches, but the patch files will be provided anyway as +long as there are more changes expected in subsequent releases. These +patch files might contain unnecessary, but possibly helpful, patches. +As a result, it is possible this issue might never be resolved, except +by eliminating the need for the person configuring `g77' to apply a +patch by hand, by going to a more automated approach (such as +configure-time patching). + +Building GNU CC Necessary +......................... + + It should be possible to build the runtime without building `cc1' +and other non-Fortran items, but, for now, an easy way to do that is +not yet established. + +Missing strtoul +............... + + On SunOS4 systems, linking the `f771' program produces an error +message concerning an undefined symbol named `_strtoul'. + + This is not a `g77' bug. *Note Patching GNU Fortran::, for +information on a workaround provided by `g77'. + + The proper fix is either to upgrade your system to one that provides +a complete ANSI C environment, or improve `gcc' so that it provides one +for all the languages and configurations it supports. + + *Note:* In earlier versions of `g77', an automated workaround for +this problem was attempted. It worked for systems without `_strtoul', +substituting the incomplete-yet-sufficient version supplied with `g77' +for those systems. However, the automated workaround failed +mysteriously for systems that appeared to have conforming ANSI C +environments, and it was decided that, lacking resources to more fully +investigate the problem, it was better to not punish users of those +systems either by requiring them to work around the problem by hand or +by always substituting an incomplete `strtoul()' implementation when +their systems had a complete, working one. Unfortunately, this meant +inconveniencing users of systems not having `strtoul()', but they're +using obsolete (and generally unsupported) systems anyway. + +Object File Differences +....................... + + A comparison of object files after building Stage 3 during a +bootstrap build will result in `gcc/f/zzz.o' being flagged as different +from the Stage 2 version. That is because it contains a string with an +expansion of the `__TIME__' macro, which expands to the current time of +day. It is nothing to worry about, since `gcc/f/zzz.c' doesn't contain +any actual code. It does allow you to override its use of `__DATE__' +and `__TIME__' by defining macros for the compilation--see the source +code for details. + +Cleanup Kills Stage Directories +............................... + + It'd be helpful if `g77''s `Makefile.in' or `Make-lang.in' would +create the various `stageN' directories and their subdirectories, so +developers and expert installers wouldn't have to reconfigure after +cleaning up. + +Missing `gperf'? +................ + + If a build aborts trying to invoke `gperf', that strongly suggests +an improper method was used to create the `gcc' source directory, such +as the UNIX `cp -r' command instead of `cp -pr', since this problem +very likely indicates that the date-time-modified information on the +`gcc' source files is incorrect. + + The proper solution is to recreate the `gcc' source directory from a +`gcc' distribution known to be provided by the FSF. + + It is possible you might be able to temporarily work around the +problem, however, by trying these commands: + + sh# cd gcc + sh# touch c-gperf.h + sh# + + These commands update the date-time-modified information for the +file produced by the invocation of `gperf' in the current versions of +`gcc', so that `make' no longer believes it needs to update it. This +file should already exist in a `gcc' distribution, but mistakes made +when copying the `gcc' directory can leave the modification information +set such that the `gperf' input files look more "recent" than the +corresponding output files. + + If the above does not work, definitely start from scratch and avoid +copying the `gcc' using any method that does not reliably preserve +date-time-modified information, such as the UNIX `cp -r' command. + +Cross-compiler Problems +----------------------- + + `g77' has been in alpha testing since September of 1992, and in +public beta testing since February of 1995. Alpha testing was done by +a small number of people worldwide on a fairly wide variety of +machines, involving self-compilation in most or all cases. Beta +testing has been done primarily via self-compilation, but in more and +more cases, cross-compilation (and "criss-cross compilation", where a +version of a compiler is built on one machine to run on a second and +generate code that runs on a third) has been tried and has succeeded, +to varying extents. + + Generally, `g77' can be ported to any configuration to which `gcc', +`f2c', and `libf2c' can be ported and made to work together, aside from +the known problems described in this manual. If you want to port `g77' +to a particular configuration, you should first make sure `gcc' and +`libf2c' can be ported to that configuration before focusing on `g77', +because `g77' is so dependent on them. + + Even for cases where `gcc' and `libf2c' work, you might run into +problems with cross-compilation on certain machines, for several +reasons. + + * There is one known bug (a design bug to be fixed in 0.6) that + prevents configuration of `g77' as a cross-compiler in some cases, + though there are assumptions made during configuration that + probably make doing non-self-hosting builds a hassle, requiring + manual intervention. + + * `gcc' might still have some trouble being configured for certain + combinations of machines. For example, it might not know how to + handle floating-point constants. + + * Improvements to the way `libf2c' is built could make building + `g77' as a cross-compiler easier--for example, passing and using + `LD' and `AR' in the appropriate ways. + + * There are still some challenges putting together the right + run-time libraries (needed by `libf2c') for a target system, + depending on the systems involved in the configuration. (This is + a general problem with cross-compilation, and with `gcc' in + particular.) + +Changing Settings Before Building +================================= + + Here are some internal `g77' settings that can be changed by editing +source files in `gcc/f/' before building. + + This information, and perhaps even these settings, represent +stop-gap solutions to problems people doing various ports of `g77' have +encountered. As such, none of the following information is expected to +be pertinent in future versions of `g77'. + +Larger File Unit Numbers +------------------------ + + As distributed, whether as part of `f2c' or `g77', `libf2c' accepts +file unit numbers only in the range 0 through 99. For example, a +statement such as `WRITE (UNIT=100)' causes a run-time crash in +`libf2c', because the unit number, 100, is out of range. + + If you know that Fortran programs at your installation require the +use of unit numbers higher than 99, you can change the value of the +`MXUNIT' macro, which represents the maximum unit number, to an +appropriately higher value. + + To do this, edit the file `f/runtime/libI77/fio.h' in your `g77' +source tree, changing the following line: + + #define MXUNIT 100 + + Change the line so that the value of `MXUNIT' is defined to be at +least one *greater* than the maximum unit number used by the Fortran +programs on your system. + + (For example, a program that does `WRITE (UNIT=255)' would require +`MXUNIT' set to at least 256 to avoid crashing.) + + Then build or rebuild `g77' as appropriate. + + *Note:* Changing this macro has *no* effect on other limits your +system might place on the number of files open at the same time. That +is, the macro might allow a program to do `WRITE (UNIT=100)', but the +library and operating system underlying `libf2c' might disallow it if +many other files have already been opened (via `OPEN' or implicitly via +`READ', `WRITE', and so on). Information on how to increase these +other limits should be found in your system's documentation. + +Always Flush Output +------------------- + + Some Fortran programs require output (writes) to be flushed to the +operating system (under UNIX, via the `fflush()' library call) so that +errors, such as disk full, are immediately flagged via the relevant +`ERR=' and `IOSTAT=' mechanism, instead of such errors being flagged +later as subsequent writes occur, forcing the previously written data +to disk, or when the file is closed. + + Essentially, the difference can be viewed as synchronous error +reporting (immediate flagging of errors during writes) versus +asynchronous, or, more precisely, buffered error reporting (detection +of errors might be delayed). + + `libf2c' supports flagging write errors immediately when it is built +with the `ALWAYS_FLUSH' macro defined. This results in a `libf2c' that +runs slower, sometimes quite a bit slower, under certain +circumstances--for example, accessing files via the networked file +system NFS--but the effect can be more reliable, robust file I/O. + + If you know that Fortran programs requiring this level of precision +of error reporting are to be compiled using the version of `g77' you +are building, you might wish to modify the `g77' source tree so that +the version of `libf2c' is built with the `ALWAYS_FLUSH' macro defined, +enabling this behavior. + + To do this, find this line in `f/runtime/configure.in' in your `g77' +source tree: + + dnl AC_DEFINE(ALWAYS_FLUSH) + + Remove the leading `dnl ', so the line begins with `AC_DEFINE(', and +run `autoconf' in that file's directory. (Or, if you don't have +`autoconf', you can modify `f2c.h.in' in the same directory to include +the line `#define ALWAYS_FLUSH' after `#define F2C_INCLUDE'.) + + Then build or rebuild `g77' as appropriate. + +Maximum Stackable Size +---------------------- + + `g77', on most machines, puts many variables and arrays on the stack +where possible, and can be configured (by changing +`FFECOM_sizeMAXSTACKITEM' in `gcc/f/com.c') to force smaller-sized +entities into static storage (saving on stack space) or permit +larger-sized entities to be put on the stack (which can improve +run-time performance, as it presents more opportunities for the GBE to +optimize the generated code). + + *Note:* Putting more variables and arrays on the stack might cause +problems due to system-dependent limits on stack size. Also, the value +of `FFECOM_sizeMAXSTACKITEM' has no effect on automatic variables and +arrays. *Note But-bugs::, for more information. + +Floating-point Bit Patterns +--------------------------- + + The `g77' build will crash if an attempt is made to build it as a +cross-compiler for a target when `g77' cannot reliably determine the +bit pattern of floating-point constants for the target. Planned +improvements for g77-0.6 will give it the capabilities it needs to not +have to crash the build but rather generate correct code for the target. +(Currently, `g77' would generate bad code under such circumstances if +it didn't crash during the build, e.g. when compiling a source file +that does something like `EQUIVALENCE (I,R)' and `DATA R/9.43578/'.) + +Initialization of Large Aggregate Areas +--------------------------------------- + + A warning message is issued when `g77' sees code that provides +initial values (e.g. via `DATA') to an aggregate area (`COMMON' or +`EQUIVALENCE', or even a large enough array or `CHARACTER' variable) +that is large enough to increase `g77''s compile time by roughly a +factor of 10. + + This size currently is quite small, since `g77' currently has a +known bug requiring too much memory and time to handle such cases. In +`gcc/f/data.c', the macro `FFEDATA_sizeTOO_BIG_INIT_' is defined to the +minimum size for the warning to appear. The size is specified in +storage units, which can be bytes, words, or whatever, on a +case-by-case basis. + + After changing this macro definition, you must (of course) rebuild +and reinstall `g77' for the change to take effect. + + Note that, as of version 0.5.18, improvements have reduced the scope +of the problem for *sparse* initialization of large arrays, especially +those with large, contiguous uninitialized areas. However, the warning +is issued at a point prior to when `g77' knows whether the +initialization is sparse, and delaying the warning could mean it is +produced too late to be helpful. + + Therefore, the macro definition should not be adjusted to reflect +sparse cases. Instead, adjust it to generate the warning when densely +initialized arrays begin to cause responses noticeably slower than +linear performance would suggest. + +Alpha Problems Fixed +-------------------- + + `g77' used to warn when it was used to compile Fortran code for a +target configuration that is not basically a 32-bit machine (such as an +Alpha, which is a 64-bit machine, especially if it has a 64-bit +operating system running on it). That was because `g77' was known to +not work properly on such configurations. + + As of version 0.5.20, `g77' is believed to work well enough on such +systems. So, the warning is no longer needed or provided. + + However, support for 64-bit systems, especially in areas such as +cross-compilation and handling of intrinsics, is still incomplete. The +symptoms are believed to be compile-time diagnostics rather than the +generation of bad code. It is hoped that version 0.6 will completely +support 64-bit systems. + +Quick Start +=========== + + This procedure configures, builds, and installs `g77' "out of the +box" and works on most UNIX systems. Each command is identified by a +unique number, used in the explanatory text that follows. For the most +part, the output of each command is not shown, though indications of +the types of responses are given in a few cases. + + To perform this procedure, the installer must be logged in as user +`root'. Much of it can be done while not logged in as `root', and +users experienced with UNIX administration should be able to modify the +procedure properly to do so. + + Following traditional UNIX conventions, it is assumed that the +source trees for `g77' and `gcc' will be placed in `/usr/src'. It also +is assumed that the source distributions themselves already reside in +`/usr/FSF', a naming convention used by the author of `g77' on his own +system: + + /usr/FSF/gcc-2.7.2.2.tar.gz + /usr/FSF/g77-0.5.21.tar.gz + + Users of the following systems should not blindly follow these +quick-start instructions, because of problems their systems have coping +with straightforward installation of `g77': + + * SunOS4 + + Instead, see *Note Complete Installation::, for detailed information +on how to configure, build, and install `g77' for your particular +system. Also, see *Note Known Causes of Trouble with GNU Fortran: +Trouble, for information on bugs and other problems known to afflict the +installation process, and how to report newly discovered ones. + + If your system is *not* on the above list, and *is* a UNIX system or +one of its variants, you should be able to follow the instructions +below. If you vary *any* of the steps below, you might run into +trouble, including possibly breaking existing programs for other users +of your system. Before doing so, it is wise to review the explanations +of some of the steps. These explanations follow this list of steps. + + sh[ 1]# cd /usr/src + + sh[ 2]# gunzip -c < /usr/FSF/gcc-2.7.2.2.tar.gz | tar xf - + [Might say "Broken pipe"...that is normal on some systems.] + + sh[ 3]# gunzip -c < /usr/FSF/g77-0.5.21.tar.gz | tar xf - + ["Broken pipe" again possible.] + + sh[ 4]# ln -s gcc-2.7.2.2 gcc + + sh[ 5]# ln -s g77-0.5.21 g77 + + sh[ 6]# mv -i g77/* gcc + [No questions should be asked by mv here; or, you made a mistake.] + + sh[ 7]# patch -p1 -V t -d gcc < gcc/f/gbe/2.7.2.2.diff + [Unless patch complains about rejected patches, this step worked.] + + sh[ 8]# cd gcc + sh[ 9]# touch f77-install-ok + [Do not do the above if your system already has an f77 + command, unless you've checked that overwriting it + is okay.] + + sh[10]# touch f2c-install-ok + [Do not do the above if your system already has an f2c + command, unless you've checked that overwriting it + is okay. Else, touch f2c-exists-ok.] + + sh[11]# ./configure --prefix=/usr + [Do not do the above if gcc is not installed in /usr/bin. + You might need a different --prefix=..., as + described below.] + + sh[12]# make bootstrap + [This takes a long time, and is where most problems occur.] + + sh[13]# rm -fr stage1 + + sh[14]# make -k install + [The actual installation.] + + sh[15]# g77 -v + [Verify that g77 is installed, obtain version info.] + + sh[16]# + + *Note Updating Your Info Directory: Updating Documentation, for +information on how to update your system's top-level `info' directory +to contain a reference to this manual, so that users of `g77' can +easily find documentation instead of having to ask you for it. + + Elaborations of many of the above steps follows: + +Step 1: `cd /usr/src' + You can build `g77' pretty much anyplace. By convention, this + manual assumes `/usr/src'. It might be helpful if other users on + your system knew where to look for the source code for the + installed version of `g77' and `gcc' in any case. + +Step 3: `gunzip -d < /usr/FSF/g77-0.5.21.tar.gz | tar xf -' + It is not always necessary to obtain the latest version of `g77' + as a complete `.tar.gz' file if you have a complete, earlier + distribution of `g77'. If appropriate, you can unpack that earlier + version of `g77', and then apply the appropriate patches to + achieve the same result--a source tree containing version 0.5.21 + of `g77'. + +Step 4: `ln -s gcc-2.7.2.2 gcc' + +Step 5: `ln -s g77-0.5.21 g77' + These commands mainly help reduce typing, and help reduce visual + clutter in examples in this manual showing what to type to install + `g77'. + + *Note Unpacking::, for information on using distributions of `g77' + made by organizations other than the FSF. + +Step 6: `mv -i g77/* gcc' + After doing this, you can, if you like, type `rm g77' and `rmdir + g77-0.5.21' to remove the empty directory and the symbol link to + it. But, it might be helpful to leave them around as quick + reminders of which version(s) of `g77' are installed on your + system. + + *Note Unpacking::, for information on the contents of the `g77' + directory (as merged into the `gcc' directory). + +Step 7: `patch -p1 ...' + This can produce a wide variety of printed output, from `Hmm, I + can't seem to find a patch in there anywhere...' to long lists of + messages indicated that patches are being found, applied + successfully, and so on. + + If messages about "fuzz", "offset", or especially "reject files" + are printed, it might mean you applied the wrong patch file. If + you believe this is the case, it is best to restart the sequence + after deleting (or at least renaming to unused names) the + top-level directories for `g77' and `gcc' and their symbolic links. + + After this command finishes, the `gcc' directory might have old + versions of several files as saved by `patch'. To remove these, + after `cd gcc', type `rm -i *.~*~'. + + *Note Merging Distributions::, for more information. + +Step 9: `touch f77-install-ok' + Don't do this if you don't want to overwrite an existing version + of `f77' (such as a native compiler, or a script that invokes + `f2c'). Otherwise, installation will overwrite the `f77' command + and the `f77' man pages with copies of the corresponding `g77' + material. + + *Note Installing `f77': Installing f77, for more information. + +Step 10: `touch f2c-install-ok' + Don't do this if you don't want to overwrite an existing + installation of `libf2c' (though, chances are, you do). Instead, + `touch f2c-exists-ok' to allow the installation to continue + without any error messages about `/usr/lib/libf2c.a' already + existing. + + *Note Installing `f2c': Installing f2c, for more information. + +Step 11: `./configure --prefix=/usr' + This is where you specify that the `g77' executable is to be + installed in `/usr/bin/', the `libf2c.a' library is to be + installed in `/usr/lib/', and so on. + + You should ensure that any existing installation of the `gcc' + executable is in `/usr/bin/'. Otherwise, installing `g77' so that + it does not fully replace the existing installation of `gcc' is + likely to result in the inability to compile Fortran programs. + + *Note Where in the World Does Fortran (and GNU CC) Go?: Where to + Install, for more information on determining where to install + `g77'. *Note Configuring gcc::, for more information on the + configuration process triggered by invoking the `./configure' + script. + +Step 12: `make bootstrap' + *Note Installing GNU CC: (gcc)Installation, for information on the + kinds of diagnostics you should expect during this procedure. + + *Note Building gcc::, for complete `g77'-specific information on + this step. + +Step 13: `rm -fr stage1' + You don't need to do this, but it frees up disk space. + +Step 14: `make -k install' + If this doesn't seem to work, try: + + make -k install install-libf77 install-f2c-all + + *Note Installation of Binaries::, for more information. + + *Note Updating Your Info Directory: Updating Documentation, for + information on entering this manual into your system's list of + texinfo manuals. + +Step 15: `g77 -v' + If this command prints approximately 25 lines of output, including + the GNU Fortran Front End version number (which should be the same + as the version number for the version of `g77' you just built and + installed) and the version numbers for the three parts of the + `libf2c' library (`libF77', `libI77', `libU77'), and those version + numbers are all in agreement, then there is a high likelihood that + the installation has been successfully completed. + + You might consider doing further testing. For example, log in as + a non-privileged user, then create a small Fortran program, such + as: + + PROGRAM SMTEST + DO 10 I=1, 10 + PRINT *, 'Hello World #', I + 10 CONTINUE + END + + Compile, link, and run the above program, and, assuming you named + the source file `smtest.f', the session should look like this: + + sh# g77 -o smtest smtest.f + sh# ./smtest + Hello World # 1 + Hello World # 2 + Hello World # 3 + Hello World # 4 + Hello World # 5 + Hello World # 6 + Hello World # 7 + Hello World # 8 + Hello World # 9 + Hello World # 10 + sh# + + 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. + +Complete Installation +===================== + + Here is the complete `g77'-specific information on how to configure, +build, and install `g77'. + +Unpacking +--------- + + The `gcc' source distribution is a stand-alone distribution. It is +designed to be unpacked (producing the `gcc' source tree) and built as +is, assuming certain prerequisites are met (including the availability +of compatible UNIX programs such as `make', `cc', and so on). + + However, before building `gcc', you will want to unpack and merge +the `g77' distribution in with it, so that you build a Fortran-capable +version of `gcc', which includes the `g77' command, the necessary +run-time libraries, and this manual. + + Unlike `gcc', the `g77' source distribution is *not* a stand-alone +distribution. It is designed to be unpacked and, afterwards, +immediately merged into an applicable `gcc' source tree. That is, the +`g77' distribution *augments* a `gcc' distribution--without `gcc', +generally only the documentation is immediately usable. + + A sequence of commands typically used to unpack `gcc' and `g77' is: + + sh# cd /usr/src + sh# gunzip -d < /usr/FSF/gcc-2.7.2.2.tar.gz | tar xf - + sh# gunzip -d < /usr/FSF/g77-0.5.21.tar.gz | tar xf - + sh# ln -s gcc-2.7.2.2 gcc + sh# ln -s g77-0.5.21 g77 + sh# mv -i g77/* gcc + + *Notes:* The commands beginning with `gunzip...' might print `Broken +pipe...' as they complete. That is nothing to worry about, unless you +actually *hear* a pipe breaking. The `ln' commands are helpful in +reducing typing and clutter in installation examples in this manual. +Hereafter, the top level of `gcc' source tree is referred to as `gcc', +and the top level of just the `g77' source tree (prior to issuing the +`mv' command, above) is referred to as `g77'. + + There are three top-level names in a `g77' distribution: + + g77/COPYING.g77 + g77/README.g77 + g77/f + + All three entries should be moved (or copied) into a `gcc' source +tree (typically named after its version number and as it appears in the +FSF distributions--e.g. `gcc-2.7.2.2'). + + `g77/f' is the subdirectory containing all of the code, +documentation, and other information that is specific to `g77'. The +other two files exist to provide information on `g77' to someone +encountering a `gcc' source tree with `g77' already present, who has +not yet read these installation instructions and thus needs help +understanding that the source tree they are looking at does not come +from a single FSF distribution. They also help people encountering an +unmerged `g77' source tree for the first time. + + *Note:* Please use *only* `gcc' and `g77' source trees as +distributed by the FSF. Use of modified versions, such as the +Pentium-specific-optimization port of `gcc', is likely to result in +problems that appear to be in the `g77' code but, in fact, are not. Do +not use such modified versions unless you understand all the +differences between them and the versions the FSF distributes--in which +case you should be able to modify the `g77' (or `gcc') source trees +appropriately so `g77' and `gcc' can coexist as they do in the stock +FSF distributions. + +Merging Distributions +--------------------- + + After merging the `g77' source tree into the `gcc' source tree, the +final merge step is done by applying the pertinent patches the `g77' +distribution provides for the `gcc' source tree. + + Read the file `gcc/f/gbe/README', and apply the appropriate patch +file for the version of the GNU CC compiler you have, if that exists. +If the directory exists but the appropriate file does not exist, you +are using either an old, unsupported version, or a release one that is +newer than the newest `gcc' version supported by the version of `g77' +you have. + + As of version 0.5.18, `g77' modifies the version number of `gcc' via +the pertinent patches. This is done because the resulting version of +`gcc' is deemed sufficiently different from the vanilla distribution to +make it worthwhile to present, to the user, information signaling the +fact that there are some differences. + + GNU version numbers make it easy to figure out whether a particular +version of a distribution is newer or older than some other version of +that distribution. The format is, generally, MAJOR.MINOR.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 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 `.0' fields often are omitted in +announcements and in names for distributions and the directories they +create.) + + If your version of `gcc' is older than the oldest version supported +by `g77' (as casually determined by listing the contents of +`gcc/f/gbe/'), you should obtain a newer, supported version of `gcc'. +(You could instead obtain an older version of `g77', or try and get +your `g77' to work with the old `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 `gcc' is newer than the newest version supported +by `g77', it is possible that your `g77' will work with it anyway. If +the version number for `gcc' differs only in the PATCH field, you might +as well try applying the `g77' patch that is for the newest version of +`gcc' having the same MAJOR and MINOR fields, as this is likely to work. + + So, for example, if a particular version of `g77' has support for +`gcc' versions 2.7.0 and 2.7.1, it is likely that `gcc-2.7.2' would +work well with `g77' by using the `2.7.1.diff' patch file provided with +`g77' (aside from some offsets reported by `patch', which usually are +harmless). + + However, `gcc-2.8.0' would almost certainly not work with that +version of `g77' no matter which patch file was used, so a new version +of `g77' would be needed (and you should wait for it rather than +bothering the maintainers--*note User-Visible Changes: Changes.). + + This complexity is the result of `gcc' and `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, `g77' often requires changes to contemporary versions of +`gcc'. Also, the GBE interface defined by `gcc' typically undergoes +some incompatible changes at least every time the MINOR field of the +version number is incremented, and such changes require corresponding +changes to the `g77' front end (FFE). + + It is hoped that the GBE interface, and the `gcc' and `g77' products +in general, will stabilize sufficiently for the need for hand-patching +to disappear. + + Invoking `patch' as described in `gcc/f/gbe/README' can produce a +wide variety of printed output, from `Hmm, I can't seem to find a patch +in there anywhere...' to long lists of messages indicated that patches +are being found, applied successfully, and so on. + + If messages about "fuzz", "offset", or especially "reject files" are +printed, it might mean you applied the wrong patch file. If you +believe this is the case, it is best to restart the sequence after +deleting (or at least renaming to unused names) the top-level +directories for `g77' and `gcc' and their symbolic links. That is +because `patch' might have partially patched some `gcc' source files, +so reapplying the correct patch file might result in the correct +patches being applied incorrectly (due to the way `patch' necessarily +works). + + After `patch' finishes, the `gcc' directory might have old versions +of several files as saved by `patch'. To remove these, after `cd gcc', +type `rm -i *.~*~'. + + *Note:* `g77''s configuration file `gcc/f/config-lang.in' ensures +that the source code for the version of `gcc' being configured has at +least one indication of being patched as required specifically by `g77'. +This configuration-time checking should catch failure to apply the +correct patch and, if so caught, should abort the configuration with an +explanation. *Please* do not try to disable the check, otherwise `g77' +might well appear to build and install correctly, and even appear to +compile correctly, but could easily produce broken code. + + `diff -rcp2N' is used to create the patch files in `gcc/f/gbe/'. + +Installing `f77' +---------------- + + You should decide whether you want installation of `g77' to also +install an `f77' command. On systems with a native `f77', this is not +normally desired, so `g77' does not do this by default. + + If you want `f77' installed, create the file `f77-install-ok' (e.g. +via the UNIX command `touch f77-install-ok') in the source or build +top-level directory (the same directory in which the `g77' `f' +directory resides, not the `f' directory itself), or edit +`gcc/f/Make-lang.in' and change the definition of the +`F77_INSTALL_FLAG' macro appropriately. + + Usually, this means that, after typing `cd gcc', you would type +`touch f77-install-ok'. + + When you enable installation of `f77', either a link to or a direct +copy of the `g77' command is made. Similarly, `f77.1' is installed as +a man page. + + (The `uninstall' target in the `gcc/Makefile' also tests this macro +and file, when invoked, to determine whether to delete the installed +copies of `f77' and `f77.1'.) + + *Note:* No attempt is yet made to install a program (like a shell +script) that provides compatibility with any other `f77' programs. +Only the most rudimentary invocations of `f77' will work the same way +with `g77'. + +Installing `f2c' +---------------- + + Currently, `g77' does not include `f2c' itself in its distribution. +However, it does include a modified version of the `libf2c'. This +version is normally compatible with `f2c', but has been modified to +meet the needs of `g77' in ways that might possibly be incompatible +with some versions or configurations of `f2c'. + + Decide how installation of `g77' should affect any existing +installation of `f2c' on your system. + + If you do not have `f2c' on your system (e.g. no `/usr/bin/f2c', no +`/usr/include/f2c.h', and no `/usr/lib/libf2c.a', `/usr/lib/libF77.a', +or `/usr/lib/libI77.a'), you don't need to be concerned with this item. + + If you do have `f2c' on your system, you need to decide how users of +`f2c' will be affected by your installing `g77'. Since `g77' is +currently designed to be object-code-compatible with `f2c' (with very +few, clear exceptions), users of `f2c' might want to combine +`f2c'-compiled object files with `g77'-compiled object files in a +single executable. + + To do this, users of `f2c' should use the same copies of `f2c.h' and +`libf2c.a' that `g77' uses (and that get built as part of `g77'). + + If you do nothing here, the `g77' installation process will not +overwrite the `include/f2c.h' and `lib/libf2c.a' files with its own +versions, and in fact will not even install `libf2c.a' for use with the +newly installed versions of `gcc' and `g77' if it sees that +`lib/libf2c.a' exists--instead, it will print an explanatory message +and skip this part of the installation. + + To install `g77''s versions of `f2c.h' and `libf2c.a' in the +appropriate places, create the file `f2c-install-ok' (e.g. via the UNIX +command `touch f2c-install-ok') in the source or build top-level +directory (the same directory in which the `g77' `f' directory resides, +not the `f' directory itself), or edit `gcc/f/Make-lang.in' and change +the definition of the `F2C_INSTALL_FLAG' macro appropriately. + + Usually, this means that, after typing `cd gcc', you would type +`touch f2c-install-ok'. + + Make sure that when you enable the overwriting of `f2c.h' and +`libf2c.a' as used by `f2c', you have a recent and properly configured +version of `bin/f2c' so that it generates code that is compatible with +`g77'. + + If you don't want installation of `g77' to overwrite `f2c''s existing +installation, but you do want `g77' installation to proceed with +installation of its own versions of `f2c.h' and `libf2c.a' in places +where `g77' will pick them up (even when linking `f2c'-compiled object +files--which might lead to incompatibilities), create the file +`f2c-exists-ok' (e.g. via the UNIX command `touch f2c-exists-ok') in +the source or build top-level directory, or edit `gcc/f/Make-lang.in' +and change the definition of the `F2CLIBOK' macro appropriately. + +Patching GNU Fortran +-------------------- + + If you're using a SunOS4 system, you'll need to make the following +change to `gcc/f/proj.h': edit the line reading + + #define FFEPROJ_STRTOUL 1 ... + +by replacing the `1' with `0'. Or, you can avoid editing the source by +adding + CFLAGS='-DFFEPROJ_STRTOUL=0 -g -O' + to the command line for `make' when you invoke it. (`-g' is the +default for `CFLAGS'.) + + This causes a minimal version of `strtoul()' provided as part of the +`g77' distribution to be compiled and linked into whatever `g77' +programs need it, since some systems (like SunOS4 with only the bundled +compiler and its runtime) do not provide this function in their system +libraries. + + Similarly, a minimal version of `bsearch()' is available and can be +enabled by editing a line similar to the one for `strtoul()' above in +`gcc/f/proj.h', if your system libraries lack `bsearch()'. The method +of overriding `X_CFLAGS' may also be used. + + These are not problems with `g77', which requires an ANSI C +environment. You should upgrade your system to one that provides a +full ANSI C environment, or encourage the maintainers of `gcc' to +provide one to all `gcc'-based compilers in future `gcc' distributions. + + *Note Problems Installing::, for more information on why `strtoul()' +comes up missing and on approaches to dealing with this problem that +have already been tried. + +Where in the World Does Fortran (and GNU CC) Go? +------------------------------------------------ + + Before configuring, you should make sure you know where you want the +`g77' and `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 `g77' installation necessarily requires installation of a +`g77'-aware version of `gcc', so that the `gcc' command recognizes +Fortran source files and knows how to compile them. + + For this to work, the version of `gcc' that you will be building as +part of `g77' *must* be installed as the "active" version of `gcc' on +the system. + + Sometimes people make the mistake of installing `gcc' as +`/usr/local/bin/gcc', leaving an older, non-Fortran-aware version in +`/usr/bin/gcc'. (Or, the opposite happens.) This can result in `g77' +being unable to compile Fortran source files, because when it calls on +`gcc' to do the actual compilation, `gcc' complains that it does not +recognize the language, or the file name suffix. + + So, determine whether `gcc' already is installed on your system, +and, if so, *where* it is installed, and prepare to configure the new +version of `gcc' you'll be building so that it installs over the +existing version of `gcc'. + + You might want to back up your existing copy of `bin/gcc', and the +entire `lib/' directory, before you perform the actual installation (as +described in this manual). + + Existing `gcc' installations typically are found in `/usr' or +`/usr/local'. If you aren't certain where the currently installed +version of `gcc' and its related programs reside, look at the output of +this command: + + gcc -v -o /tmp/delete-me -xc /dev/null -xnone + + All sorts of interesting information on the locations of various +`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 `main_()' function.) +However, you do have to sift through it yourself; `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 *building* `g77' should not overwrite any installed +programs--but, usually, after you build `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 `g77', though in this case it is +intentional that `g77' overwrites `gcc' if it is already installed--it +is unusual that the installation process for one distribution +intentionally overwrites a program or file installed by another +distribution.) + + Another reason to back up the existing version first, or make sure +you can restore it easily, is that it might be an older version on +which other users have come to depend for certain behaviors. However, +even the new version of `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 `g77' components. +*Note Specifying Target Machine and Compiler Version: (gcc)Target +Options, for information on the `-V' option of `gcc'. + +Configuring GNU CC +------------------ + + `g77' is configured automatically when you configure `gcc'. There +are two parts of `g77' that are configured in two different +ways--`g77', which "camps on" to the `gcc' configuration mechanism, and +`libf2c', which uses a variation of the GNU `autoconf' configuration +system. + + Generally, you shouldn't have to be concerned with either `g77' or +`libf2c' configuration, unless you're configuring `g77' as a +cross-compiler. In this case, the `libf2c' configuration, and possibly +the `g77' and `gcc' configurations as well, might need special +attention. (This also might be the case if you're porting `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 *Note Installing GNU CC: +(gcc)Installation, following the instructions for running `./configure'. +Pay special attention to the `--prefix=' option, which you almost +certainly will need to specify. + + (Note that `gcc' installation information is provided as a straight +text file in `gcc/INSTALL'.) + + The information printed by the invocation of `./configure' should +show that the `f' directory (the Fortran language) has been configured. +If it does not, there is a problem. + + *Note:* Configuring with the `--srcdir' argument is known to work +with GNU `make', but it is not known to work with other variants of +`make'. Irix5.2 and SunOS4.1 versions of `make' definitely won't work +outside the source directory at present. `g77''s portion of the +`configure' script issues a warning message about this when you +configure for building binaries outside the source directory. + +Building GNU CC +--------------- + + Building `g77' requires building enough of `gcc' that these +instructions assume you're going to build all of `gcc', including +`g++', `protoize', and so on. You can save a little time and disk +space by changes the `LANGUAGES' macro definition in `gcc/Makefile.in' +or `gcc/Makefile', but if you do that, you're on your own. One change +is almost *certainly* going to cause failures: removing `c' or `f77' +from the definition of the `LANGUAGES' macro. + + After configuring `gcc', which configures `g77' and `libf2c' +automatically, you're ready to start the actual build by invoking +`make'. + + *Note:* You *must* have run `./configure' before you run `make', +even if you're using an already existing `gcc' development directory, +because `./configure' does the work to recognize that you've added +`g77' to the configuration. + + There are two general approaches to building GNU CC from scratch: + +"bootstrap" + This method uses minimal native system facilities to build a + barebones, unoptimized `gcc', that is then used to compile + ("bootstrap") the entire system. + +"straight" + This method assumes a more complete native system exists, and uses + that just once to build the entire system. + + On all systems without a recent version of `gcc' already installed, +the bootstrap method must be used. In particular, `g77' uses +extensions to the C language offered, apparently, only by `gcc'. + + On most systems with a recent version of `gcc' already installed, +the 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. + +Bootstrap Build +............... + + A complete bootstrap build is done by issuing a command beginning +with `make bootstrap ...', as described in *Note Installing GNU CC: +(gcc)Installation. 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 `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 `make' commands to build each stage one at a time, +as described in the `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 `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 `rm -fr stage1' to remove the binaries built during Stage +1. + + *Note:* *Note Object File Differences::, for information on expected +differences in object files produced during Stage 2 and Stage 3 of a +bootstrap build. These differences will be encountered as a result of +using the `make compare' or similar command sequence recommended by the +GNU CC installation documentation. + + Also, *Note Installing GNU CC: (gcc)Installation, for important +information on building `gcc' that is not described in this `g77' +manual. For example, explanations of diagnostic messages and whether +they're expected, or indicate trouble, are found there. + +Straight Build +.............. + + If you have a recent version of `gcc' already installed on your +system, and if you're reasonably certain it produces code that is +object-compatible with the version of `gcc' you want to build as part +of building `g77', you can save time and disk space by doing a straight +build. + + To build just the C and Fortran compilers and the necessary run-time +libraries, issue the following command: + + make -k CC=gcc LANGUAGES=f77 all g77 + + (The `g77' target is necessary because the `gcc' build procedures +apparently do not automatically build command drivers for languages in +subdirectories. It's the `all' target that triggers building +everything except, apparently, the `g77' command itself.) + + If you run into problems using this method, you have two options: + + * Abandon this approach and do a bootstrap build. + + * Try to make this approach work by diagnosing the problems you're + running into and retrying. + + Especially if you do the latter, you might consider submitting any +solutions as bug/fix reports. *Note Known Causes of Trouble with GNU +Fortran: Trouble. + + However, understand that many problems preventing a straight build +from working are not `g77' problems, and, in such cases, are not likely +to be addressed in future versions of `g77'. + +Pre-installation Checks +----------------------- + + Before installing the system, which includes installing `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: + + sh# cd /usr/src/gcc + sh# ./g77 --driver=./xgcc -B./ -v + g77 version 0.5.21 + ./xgcc -B./ -v -fnull-version -o /tmp/gfa18047 ... + Reading specs from ./specs + gcc version 2.7.2.2.f.3 + ./cpp -lang-c -v -isystem ./include -undef ... + GNU CPP version 2.7.2.2.f.3 (Linux/Alpha) + #include "..." search starts here: + #include <...> search starts here: + ./include + /usr/local/include + /usr/alpha-unknown-linux/include + /usr/lib/gcc-lib/alpha-unknown-linux/2.7.2.2.f.3/include + /usr/include + End of search list. + ./f771 /tmp/cca18048.i -fset-g77-defaults -quiet -dumpbase ... + GNU F77 version 2.7.2.2.f.3 (Linux/Alpha) compiled ... + GNU Fortran Front End version 0.5.21 compiled: ... + as -nocpp -o /tmp/cca180481.o /tmp/cca18048.s + ld -G 8 -O1 -o /tmp/gfa18047 /usr/lib/crt0.o -L. ... + __G77_LIBF77_VERSION__: 0.5.21 + @(#)LIBF77 VERSION 19970404 + __G77_LIBI77_VERSION__: 0.5.21 + @(#) LIBI77 VERSION pjw,dmg-mods 19970527 + __G77_LIBU77_VERSION__: 0.5.21 + @(#) LIBU77 VERSION 19970609 + sh# ./xgcc -B./ -v -o /tmp/delete-me -xc /dev/null -xnone + Reading specs from ./specs + gcc version 2.7.2.2.f.3 + ./cpp -lang-c -v -isystem ./include -undef ... + GNU CPP version 2.7.2.2.f.3 (Linux/Alpha) + #include "..." search starts here: + #include <...> search starts here: + ./include + /usr/local/include + /usr/alpha-unknown-linux/include + /usr/lib/gcc-lib/alpha-unknown-linux/2.7.2.2.f.3/include + /usr/include + End of search list. + ./cc1 /tmp/cca18063.i -quiet -dumpbase null.c -version ... + GNU C version 2.7.2.2.f.3 (Linux/Alpha) compiled ... + as -nocpp -o /tmp/cca180631.o /tmp/cca18063.s + ld -G 8 -O1 -o /tmp/delete-me /usr/lib/crt0.o -L. ... + /usr/lib/crt0.o: In function `__start': + crt0.S:110: undefined reference to `main' + /usr/lib/crt0.o(.lita+0x28): undefined reference to `main' + sh# + + (Note that long lines have been truncated, and `...' used to +indicate such truncations.) + + The above two commands test whether `g77' and `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 `gcc' and `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 `gcc' and `g77', +use the following commands to invoke them. + + To invoke `g77', type: + + /usr/src/gcc/g77 --driver=/usr/src/gcc/xgcc -B/usr/src/gcc/ ... + + To invoke `gcc', type: + + /usr/src/gcc/xgcc -B/usr/src/gcc/ ... + +Installation of Binaries +------------------------ + + After configuring, building, and testing `g77' and `gcc', when you +are ready to install them on your system, type: + + make -k CC=gcc LANGUAGES=f77 install + + As described in *Note Installing GNU CC: (gcc)Installation, the +values for the `CC' and `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 `libf2c.a' as expected, try +this: + + make -k ... install install-libf77 install-f2c-all + + We don't know why some non-GNU versions of `make' sometimes require +this alternate command, but they do. (Remember to supply the +appropriate definitions for `CC' and `LANGUAGES' where you see `...' in +the above command.) + + Note that using the `-k' option tells `make' to continue after some +installation problems, like not having `makeinfo' installed on your +system. It might not be necessary for your system. + +Updating Your Info Directory +---------------------------- + + As part of installing `g77', you should make sure users of `info' +can easily access this manual on-line. Do this by making sure a line +such as the following exists in `/usr/info/dir', or in whatever file is +the top-level file in the `info' directory on your system (perhaps +`/usr/local/info/dir': + + * g77: (g77). The GNU Fortran programming language. + + If the menu in `dir' is organized into sections, `g77' probably +belongs in a section with a name such as one of the following: + + * Fortran Programming + + * Writing Programs + + * Programming Languages + + * Languages Other Than C + + * Scientific/Engineering Tools + + * GNU Compilers + +Missing `bison'? +---------------- + + If you cannot install `bison', make sure you have started with a +*fresh* distribution of `gcc', do *not* do `make maintainer-clean' (in +other versions of `gcc', this was called `make realclean'), and, to +ensure that `bison' is not invoked by `make' during the build, type +these commands: + + sh# cd gcc + sh# touch bi-parser.c bi-parser.h c-parse.c c-parse.h cexp.c + sh# touch cp/parse.c cp/parse.h objc-parse.c + sh# + + These commands update the date-time-modified information for all the +files produced by the various invocations of `bison' in the current +versions of `gcc', so that `make' no longer believes it needs to update +them. All of these files should already exist in a `gcc' distribution, +but the application of patches to upgrade to a newer version can leave +the modification information set such that the `bison' input files look +more "recent" than the corresponding output files. + + *Note:* New versions of `gcc' might change the set of files it +generates by invoking `bison'--if you cannot figure out for yourself +how to handle such a situation, try an older version of `gcc' until you +find someone who can (or until you obtain and install `bison'). + +Missing `makeinfo'? +------------------- + + If you cannot install `makeinfo', either use the `-k' option when +invoking make to specify any of the `install' or related targets, or +specify `MAKEINFO=echo' on the `make' command line. + + If you fail to do one of these things, some files, like `libf2c.a', +might not be installed, because the failed attempt by `make' to invoke +`makeinfo' causes it to cancel any further processing. + +Distributing Binaries +===================== + + If you are building `g77' for distribution to others in binary form, +first make sure you are aware of your legal responsibilities (read the +file `gcc/COPYING' thoroughly). + + Then, consider your target audience and decide where `g77' should be +installed. + + For systems like GNU/Linux that have no native Fortran compiler (or +where `g77' could be considered the native compiler for Fortran and +`gcc' for C, etc.), you should definitely configure `g77' for +installation in `/usr/bin' instead of `/usr/local/bin'. Specify the +`--prefix=/usr' option when running `./configure'. You might also want +to set up the distribution so the `f77' command is a link to +`g77'--just make an empty file named `f77-install-ok' in the source or +build directory (the one in which the `f' directory resides, not the +`f' directory itself) when you specify one of the `install' or +`uninstall' targets in a `make' command. + + For a system that might already have `f2c' installed, you definitely +will want to make another empty file (in the same directory) named +either `f2c-exists-ok' or `f2c-install-ok'. Use the former if you +don't want your distribution to overwrite `f2c'-related files in +existing systems; use the latter if you want to improve the likelihood +that users will be able to use both `f2c' and `g77' to compile code for +a single program without encountering link-time or run-time +incompatibilities. + + (Make sure you clearly document, in the "advertising" for your +distribution, how installation of your distribution will affect +existing installations of `gcc', `f2c', `f77', `libf2c.a', and so on. +Similarly, you should clearly document any requirements you assume are +met by users of your distribution.) + + For other systems with native `f77' (and `cc') compilers, configure +`g77' as you (or most of your audience) would configure `gcc' for their +installations. Typically this is for installation in `/usr/local', and +would not include a copy of `g77' named `f77', so users could still use +the native `f77'. + + In any case, for `g77' to work properly, you *must* ensure that the +binaries you distribute include: + +`bin/g77' + This is the command most users use to compile Fortran. + +`bin/gcc' + This is the command all users use to compile Fortran, either + directly or indirectly via the `g77' command. The `bin/gcc' + executable file must have been built from a `gcc' source tree into + which a `g77' source tree was merged and configured, or it will + not know how to compile Fortran programs. + +`bin/f77' + In installations with no non-GNU native Fortran compiler, this is + the same as `bin/g77'. Otherwise, it should be omitted from the + distribution, so the one on already on a particular system does + not get overwritten. + +`info/g77.info*' + This is the documentation for `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 `gcc/f/*.texi' and + doing `make doc' from the `/usr/src/gcc' directory) to reflect any + changes you've made to `g77', or at least to encourage users of + your binary distribution to report bugs to you first. + + Also, whether you distribute binaries or install `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 `info' node in + `/usr/info/dir'. That way, users can find `g77' documentation more + easily. *Note Updating Your Info Directory: Updating + Documentation. + +`man/man1/g77.1' + This is the short man page for `g77'. It is out of date, but you + might as well include it for people who really like man pages. + +`man/man1/f77.1' + In installations where `f77' is the same as `g77', this is the + same as `man/man1/g77.1'. Otherwise, it should be omitted from + the distribution, so the one already on a particular system does + not get overwritten. + +`lib/gcc-lib/.../f771' + This is the actual Fortran compiler. + +`lib/gcc-lib/.../libf2c.a' + This is the run-time library for `g77'-compiled programs. + + Whether you want to include the slightly updated (and possibly +improved) versions of `cc1', `cc1plus', and whatever other binaries get +rebuilt with the changes the GNU Fortran distribution makes to the GNU +back end, is up to you. These changes are highly unlikely to break any +compilers, and it is possible they'll fix back-end bugs that can be +demonstrated using front ends other than GNU Fortran's. + + Please assure users that unless they have a specific need for their +existing, older versions of `gcc' command, they are unlikely to +experience any problems by overwriting it with your version--though +they could certainly protect themselves by making backup copies first! +Otherwise, users might try and install your binaries in a "safe" place, +find they cannot compile Fortran programs with your distribution +(because, perhaps, they're picking up their old version of the `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, *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 `g77' sources to port `g77', e.g. to OS/2. +<fortran@gnu.ai.mit.edu> has received a fair number of bug reports that +turned out to be problems with other peoples' ports and distributions, +about which nothing could be done for the user. Once you are quite +certain a bug report does not involve your efforts, you can forward it +to us. + |