1998-08-11 This directory contains the egcs variant of version 0.5.24 of the GNU Fortran compiler (g77). The GNU Fortran compiler is free software. See the file COPYING.g77 for copying permission. Currently, two variants of g77 exist. One is the Free Software Foundation (FSF) variant. The other is the egcs variant. As of egcs version 1.1, these variants are kept fairly similar in most respects. Pertinent differences, such as the layout of the source code, are specified below. Below, `[FSF]' denotes information applicable to only the FSF variant of g77, while `[egcs]' denotes egcs-only information. * IMPORTANT: Things you *must* do (or avoid) are marked with a * at the beginning of the line in this file!!! The email address to which bugs are to be reported is either [FSF] or [egcs] . * *DO NOT* send any email (reporting bugs, asking questions, etc.) to either of these addresses without *first* reading the g77 documentation. Use `info', Info mode in GNU Emacs, or a text viewer such as `more' to do this. The g77 documentation is in the source files named `g77.info', `g77.info-1', `g77.info-2', and so on in the `f' subdirectory. If these files are not present or you can't find them, contact the person or organization that put together the g77 distribution you are using (probably not the FSF or egcs), or ask your system administrator for help. This README applies to only the g77-specific portions of the source-code tree that contains it. These portions include: - The README.g77 and [FSF] COPYING.g77 files, in this directory, "this directory" being [FSF] the top-level directory containing a g77 distribution or [egcs] the gcc/ subdirectory of an egcs distribution. - The g77 front end, in the f/ subdirectory of this directory. - The libg2c library, in [FSF] the f/runtime/ subdirectory of this directory or [egcs] the libf2c/ directory under the top-level directory of the egcs distribution. * To build g77, you must have a source distribution of [FSF] gcc version 2.8 or [egcs] egcs version 1.1. Do not attempt to use any other version of gcc or egcs, because this version of g77 is designed to work with only those versions. Note that you must have *source* copies of the gcc or egcs distribution! You cannot build g77 just using binaries of gcc or egcs. Also, unless you are an expert, avoid using any distribution of gcc or egcs not identical to the ones distributed by the FSF and Cygnus Support, respectively. The primary FSF distribution site is: The primary egcs distribution site is: Both of these sites have approved mirror sites from which valid distributions also may be obtained. * Do not attempt to combine the egcs version of g77 with the FSF gcc distribution, or the FSF version of g77 with the egcs gcc distribution. Although the differences are minor, they might be sufficient to prevent g77 from building properly, or from working properly if the build appears to succeed. [FSF] g77 is distributed as g77-/f/ so that unpacking the g77 distribution is done in the normal GNU way, resulting in a directory having the version number in the name. However, to build g77, the g77 distribution must be merged with an appropriate gcc distribution, normally in a gcc source directory, before configuring, building, and installing g77. [FSF] If you have just unpacked the g77 distribution, before proceeding, you must merge the contents of the g77 distribution with the appropriate gcc distribution on your system. * [FSF] Read and follow the instructions in f/INSTALL that explain how to merge a g77 source directory into a gcc source directory. You can use Info to read the same installation instructions via: info -f f/g77.info -n Unpacking [FSF] The resulting directory layout includes the following, where gcc/ might be a link to, for example, gcc-2.8.1/: gcc/ Non-g77 files in gcc gcc/COPYING.g77 A copy of the GPL, under which g77 is licensed gcc/README.g77 This file gcc/f/ GNU Fortran front end gcc/f/runtime/ libg2c configuration and g2c.h file generation gcc/f/runtime/libF77/ Non-I/O portion of libg2c gcc/f/runtime/libI77/ I/O portion of libg2c gcc/f/runtime/libU77/ Additional interfaces to libc for libg2c [FSF] Applying g77 patches in the form of .diff files is done by typing `patch -p1 -d gcc' (where gcc/ contains the f/ subdirectory). That is, g77 patches are distributed in the same form, and at the same directory level, as patches to the gcc distribution. (Note: make sure you're using GNU patch, version 2.5 or later! Other versions of patch have trouble with g77-related patches.) [egcs] The egcs version of g77 is distributed already merged with the rest of egcs (such as the gcc back end). [egcs] The resulting directory layout includes the following, where egcs/ might be a link to, for example, egcs-1.1/: egcs/gcc/ Non-g77 files in gcc egcs/gcc/README.g77 This file egcs/gcc/f/ GNU Fortran front end egcs/libf2c/ libg2c configuration and g2c.h file generation egcs/libf2c/libF77/ Non-I/O portion of libg2c egcs/libf2c/libI77/ I/O portion of libg2c egcs/libf2c/libU77/ Additional interfaces to libc for libg2c [egcs] Applying g77-specific patches to egcs is done the same way as applying other egcs patches. Below, `libf2c/' shall denote [FSF] gcc/f/runtime/ or [egcs] egcs/libf2c/, while `f/' shall denote [FSF] the rest of gcc/f/ or [egcs] egcs/gcc/f/. Components of note in g77 are described below. f/ as a whole contains the program GNU Fortran (g77), while libf2c/ contains a portion of the separate program f2c. Note: The libf2c code is not part of the program g77, just distributed with it. f/ contains text files that document the Fortran compiler, source files for the GNU Fortran Front End (FFE), and some other stuff. The g77 compiler code is placed in f/ because it, along with its contents, is designed to be a subdirectory of a GNU CC (gcc) source directory, gcc/, which is structured so that language-specific front ends can be "dropped in" as subdirectories. The C++ front end (g++), is an example of this -- it resides in the cp/ subdirectory. Note that the C front end (also referred to as gcc) is an exception to this, as its source files reside in the gcc/ directory itself. libf2c/ contains the run-time libraries for the f2c program, also used by g77. These libraries normally referred to collectively as libf2c. When built as part of g77, libf2c is installed under the name libg2c to avoid conflict with any existing version of libf2c, and thus is often referred to as libg2c when the g77 version is specifically being referred to. The netlib version of libf2c/ contains two distinct libraries, libF77 and libI77, each in their own subdirectories. In g77, this distinction is not made, beyond maintaining the subdirectory structure in the source-code tree. libf2c/ is not part of the program g77, just distributed with it. It contains files not present in the official (netlib) version of libf2c, and also contains some minor changes made from libf2c, to fix some bugs, and to facilitate automatic configuration, building, and installation of libf2c (as libg2c) for use by g77 users. * See libf2c/README for more information, including licensing conditions governing distribution of programs containing code from libg2c. libg2c, g77's version of libf2c, adds Dave Love's implementation of libU77, in the libf2c/libU77/ directory. This library is distributed under the GNU Library General Public License (LGPL) -- see the file libf2c/libU77/COPYING.LIB for more information, as this license governs distribution conditions for programs containing code from this portion of the library. Files of note in g77 are described below. f/BUGS lists some important bugs known to be in g77. Or: info -f f/g77.info -n "Actual Bugs" f/ChangeLog lists recent changes to g77 internals. libf2c/ChangeLog lists recent changes to libg2c internals. [FSF] f/INSTALL describes how to build and install GNU Fortran. Or: info -f f/g77.info -n Installation f/NEWS contains the per-release changes. These include the user-visible changes described under "Changes" in the g77 documentation, plus internal changes of import. Or: info -f f/g77.info -n News * All users of g77 (not just installers) should read f/g77.info* as well, using the `more' command if neither the `info' command, nor GNU Emacs (with its Info mode), are available, or if they aren't yet accustomed to using these tools. Read f/BUGS and f/NEWS plus, if you are planning on building or installing the FSF version of g77, f/INSTALL, at the very least! All of these files are readable as "plain text" files. * Also see for up-to-date information regarding g77 bug reports, known bugs, bug-fixes, and new versions. The rest of this file is of note to only those who wish to debug, modify, or test the FFE (in conjunction with the gcc back end). If you want to explore the FFE code, which lives entirely in f/, here are a few clues. The file g77spec.c contains the g77-specific source code for the `g77' command only -- this just forms a variant of the `gcc' command, so, just as the `gcc' command itself does not contain the C front end, the `g77' command does not contain the Fortran front end (FFE). The FFE code ends up in an executable named `f771', which does the actual compiling, so it contains the FFE plus the gcc back end (the latter to do most of the optimization, and the code generation). The file parse.c is the source file for main() for a stand-alone FFE and yyparse() for f771. (Stand-alone building of the FFE doesn't work these days.) The file top.c contains the top-level FFE function ffe_file and it (along with top.h) define all ffe_[a-z].*, ffe[A-Z].*, and FFE_[A-Za-z].* symbols. The file fini.c is a main() program that is used when building the FFE to generate C header and source files for recognizing keywords. The files malloc.c and malloc.h comprise a memory manager that defines all malloc_[a-z].*, malloc[A-Z].*, and MALLOC_[A-Za-z].* symbols. All other modules named are comprised of all files named *. and define all ffe_[a-z].*, ffe[A-Z].*, and FFE_[A-Za-z].* symbols. If you understand all this, congratulations -- it's easier for me to remember how it works than to type in these grep patterns (such as they are). But it does make it easy to find where a symbol is defined -- for example, the symbol "ffexyz_set_something" would be defined in xyz.h and implemented there (if it's a macro) or in xyz.c. The "porting" files of note currently are: proj.h, which defines the "language" used by all the other source files (the language being Standard C plus some useful things like ARRAY_SIZE and such) -- change this file when you find your system doesn't properly define a Standard C macro or function, for example; target.h and target.c, which describe the target machine in terms of what data types are supported, how they are denoted (what C type does an INTEGER*8 map to, for example), how to convert between them, and so on (though as of 0.5.3, more and more of this information is being dynamically configured by ffecom_init_0); com.h and com.c, which interface to the target back end (currently only FFE stand-alone and the GBE); ste.c, which contains code for implementing recognized executable statements in the target back end (again currently either FFE or GBE); src.h and src.c, which describe information on the format(s) of source files (such as whether they are never to be processed as case-insensitive with regard to Fortran keywords); and proj.c, which contains whatever code is needed to support the language defined by proj.h. If you want to debug the f771 executable, for example if it crashes, note that the global variables "lineno" and "input_filename" are set to reflect the current line being read by the lexer during the first-pass analysis of a program unit and to reflect the current line being processed during the second-pass compilation of a program unit. If an invocation of the function ffestd_exec_end() is on the stack, the compiler is in the second pass, otherwise it is in the first. (This information might help you reduce a test case and/or work around a bug in g77 until a fix is available.) Any questions or comments on these topics? Read the g77 documentation!