gcc/README.g77

   1 1998-03-08
   2
   3 This directory contains the version 0.5.22 release of the GNU Fortran
   4 compiler.  The GNU Fortran compiler is free software.  See the file
   5 COPYING.g77 for copying permission.
   6
   7 * IMPORTANT: Things you *must* do are marked with a * at the beginning of
   8   the line in this file!!!
   9
  10 * DO NOT send any email (reporting bugs, asking questions, etc.) to
  11   <fortran@gnu.org> without *first* reading the g77 documentation,
  12   using `info', Info mode in GNU Emacs, or a text viewer such as `more'.
  13   The g77 documentation is in the files named `g77.info', `g77.info-1',
  14   `g77.info-2', and so on in g77 `f' directory.  If these files are
  15   not present or you can't find them, contact the person or organization
  16   that put together the g77 distribution you are using (probably not the
  17   FSF), or ask your system administrator for help.
  18
  19 This README is for GNU Fortran, and describes the files in the f/
  20 directory.  The f/ directory is intended to be a subdirectory of a
  21 gcc source tree.  These directories are referred to below as gcc/,
  22 which is the top-level directory containing the gcc back end, the
  23 gcc C front end, and other non-Fortran files, and gcc/f/, which
  24 contains all of the Fortran files.
  25
  26 * To build GNU Fortran, you must have a source distribution of gcc
  27   version 2.7.2.3.  Do not attempt to use any other version
  28   of gcc, because this version of g77 is designed to work only with
  29   gcc version 2.7.2.3.
  30
  31 * Note that you must have source copies of these gcc distributions!!
  32   You cannot build g77 just using binaries of gcc.  Also, unless you
  33   are an expert, avoid using any distribution of gcc not identical to
  34   the one distributed by the FSF.
  35
  36 If you have just unpacked the g77 distribution, before proceeding,
  37 you must merge the contents of the g77 distribution with the appropriate
  38 gcc distribution on your system before proceeding.
  39
  40 * Read and follow the instructions in g77-0.5.22/f/INSTALL that
  41   explain how to merge a g77 source directory into a gcc source
  42   directory.  You can use Info to read the same installation
  43   instructions via:
  44
  45     info -f g77-0.5.22/f/g77.info -n Unpacking
  46
  47 The resulting directory layout includes the following, where gcc/ might be
  48 a link to, for example, gcc-2.7.2.3/:
  49
  50     gcc/                    Non-Fortran files in gcc (not part of g77*.tar)
  51     gcc/README.g77          This file
  52     gcc/f/                  GNU Fortran front end
  53     gcc/f/gbe/              Patches required for gcc back end versions
  54     gcc/f/runtime/          libf2c configuration and f2c.h file generation
  55     gcc/f/runtime/libF77/   Non-I/O portion of libf2c
  56     gcc/f/runtime/libI77/   I/O portion of libf2c
  57     gcc/f/runtime/libU77/   Additional interfaces to libc for libf2c
  58
  59 gcc/f/ as a whole contains the program GNU Fortran (g77), plus a portion
  60 of the separate program f2c, which is in gcc/f/runtime.  NOTE: The libf2c
  61 code is not part of the program g77, just distributed with it.
  62
  63 This directory is named gcc/f/ because it, along with its contents, is
  64 designed to be a subdirectory of a GNU CC (gcc) development directory.  I.e.
  65 when a gcc distribution is unpacked into a directory (named gcc/ for
  66 example), it typically contains subdirectories like gcc/config/ and
  67 gcc/cp/.  The latter is the subdirectory for the GNU C++ (g++) program.
  68
  69 Similarly, the g77 directory f/ is designed to be placed in gcc/ so that
  70 it becomes the subdirectory gcc/f/.  g77 is distributed as g77-someversion/f/
  71 so that unpacking the g77 distribution is done in the normal GNU way,
  72 resulting in a directory having the version number in the name.  However,
  73 to build g77, the g77 distribution must be merged with an appropriate gcc
  74 distribution, normally in a gcc directory, before configuring, building,
  75 and installing g77.
  76
  77 Applying g77 patches in the form of .diff files is done by typing
  78 `patch -p1 -d gcc' (where gcc/f/ is the active version).  That is,
  79 g77 patches are distributed in the same form, and at the same directory
  80 level, as patches to the gcc distribution.  (Note: make sure you're
  81 using GNU patch, version 2.5 or later!  Other versions of patch
  82 have trouble with g77-related patches.)
  83
  84 gcc/f/ has text files that document the Fortran compiler, source
  85 files for the GNU Fortran Front End (FFE), and some other stuff.
  86
  87 gcc/f/gbe/ has patch files for various versions of gcc, primarily
  88 needed to patch the GNU compiler Back End (GBE) to fix and improve it
  89 for use with g77.  If a patch file exists for the version of gcc you
  90 want to build along with g77, you MUST apply the patch before building
  91 g77 with that version or g77 will not build or work properly.*
  92
  93 * Read gcc/f/gbe/README for more information.
  94
  95 gcc/f/runtime/ contains the run-time libraries for the f2c program, also used
  96 by g77, and referred to as libf2c (though libf2c is really a combination of
  97 two distinct libraries, libF77 and libI77 -- in g77, this distinction is
  98 not made, and, further, Dave Love's implementation of libU77 is added
  99 to the mix).  This separate subdirectory is not part of the program g77, just
 100 distributed with it.  Some new files have been added to this subdirectory
 101 and some minor changes made to the files contained therein, to fix some
 102 bugs and facilitate automatic configuration, building, and installation of
 103 libf2c for use by g77 users.  See gcc/f/runtime/README for more information.
 104
 105 gcc/f/BUGS lists some important bugs known to be in g77.  Or:
 106
 107   info -f gcc/f/g77.info -n "Actual Bugs"
 108
 109 gcc/f/ChangeLog lists recent changes to g77 internals.
 110
 111 gcc/f/INSTALL describes how to build and install GNU Fortran.  Or:
 112
 113   info -f gcc/f/g77.info -n Installation
 114
 115 gcc/f/NEWS contains the per-release changes (not just user-visible ones
 116 seen in gcc/f/DOC) listed in the ~fortran/.plan file.  Or:
 117
 118   info -f gcc/f/g77.info -n News
 119
 120 * Read gcc/f/BUGS, gcc/f/INSTALL, and gcc/f/NEWS at the very least!
 121   All users of g77 (not just installers) should read gcc/f/g77.info*
 122   as well, using the `more' command if neither the `info' command,
 123   nor GNU Emacs (with its Info mode), are available, or if they
 124   aren't yet accustomed to using these tools.
 125
 126 If you want to get into the FFE code, which lives entirely in gcc/f/, here
 127 are a few clues.  The file g77.c is the stand-alone source file for the
 128 `g77' command driver only -- this just invokes the `gcc' command, so it has
 129 nothing to do with the rest of the code in g77.  Most of the code
 130 ends up in an executable named `f771', which does the actual compiling,
 131 so it has the FFE merged with the gcc back end.
 132
 133 The file parse.c is the source file for main() for a stand-alone FFE and
 134 yyparse() for f771.  (Stand-alone building of the FFE doesn't work these days.)
 135 The file top.c contains the top-level FFE function ffe_file and it (along
 136 with top.h) define all ffe_[a-z].*, ffe[A-Z].*, and FFE_[A-Za-z].* symbols.
 137 The file fini.c is a main() program that is used when building the FFE to
 138 generate C header and source files for recognizing keywords.  The files
 139 malloc.c and malloc.h comprise a memory manager that defines all
 140 malloc_[a-z].*, malloc[A-Z].*, and MALLOC_[A-Za-z].* symbols.  All other
 141 modules named <xyz> are comprised of all files named <xyz>*.<ext> and
 142 define all ffe<xyz>_[a-z].*, ffe<xyz>[A-Z].*, and FFE<XYZ>_[A-Za-z].* symbols.
 143 If you understand all this, congratulations -- it's easier for me to remember
 144 how it works than to type in these grep patterns (such as they are).  But it
 145 does make it easy to find where a symbol is defined -- for example,
 146 the symbol "ffexyz_set_something" would be defined in xyz.h and implemented
 147 there (if it's a macro) or in xyz.c.
 148
 149 The "porting" files of note currently are: proj.h, which defines the
 150 "language" used by all the other source files (the language being
 151 Standard C plus some useful things like ARRAY_SIZE and such) -- change
 152 this file when you find your system doesn't properly define a Standard C
 153 macro or function, for example; target.h and target.c, which describe
 154 the target machine in terms of what data types are supported, how they are
 155 denoted (what C type does an INTEGER*8 map to, for example), how to convert
 156 between them, and so on (though as of 0.5.3, more and more of this information
 157 is being dynamically configured by ffecom_init_0); com.h and com.c, which
 158 interface to the target back end (currently only FFE stand-alone and the GBE);
 159 ste.c, which contains code for implementing recognized executable statements
 160 in the target back end (again currently either FFE or GBE); src.h and src.c,
 161 which describe information on the format(s) of source files (like whether
 162 they are never to be processed as case-insensitive with regard to Fortran
 163 keywords); and proj.c, which contains whatever code is needed to support
 164 the language defined by proj.h.
 165
 166 If you want to debug the f771 executable, for example if it crashes,
 167 note that the global variables "lineno" and "input_filename" are set
 168 to reflect the current line being read by the lexer during the first-pass
 169 analysis of a program unit and to reflect the current line being
 170 processed during the second-pass compilation of a program unit.  If
 171 an invocation of the function ffestd_exec_end() is on the stack,
 172 the compiler is in the second pass, otherwise it is in the first.
 173 (This information might help you reduce a test case and/or work around
 174 a bug in g77 until a fix is available.)
 175
 176 Any questions or comments on these topics, email <fortran@gnu.org>.