contrib/gcc/f/INSTALL

   1 *Note:* This file is automatically generated from the files
   2 `install0.texi' and `g77install.texi'.  `INSTALL' is *not* a source
   3 file, although it is normally included within source distributions.
   4
   5    This file contains installation information for the GNU Fortran
   6 compiler.  Copyright (C) {No Value For "copyrights-install"} Free
   7 Software Foundation, Inc.  You may copy, distribute, and modify it
   8 freely as long as you preserve this copyright notice and permission
   9 notice.
  10
  11 Installing GNU Fortran
  12 **********************
  13
  14    The following information describes how to install `g77'.
  15
  16    Note that, for users of the GCC-2.95 version of `g77', much of the
  17 information is obsolete, and is superceded by the GCC installation
  18 procedures.  Such information is accordingly omitted and flagged as
  19 such.
  20
  21    *Warning:* The information below is still under development, and
  22 might not accurately reflect the `g77' code base of which it is a part.
  23 Efforts are made to keep it somewhat up-to-date, but they are
  24 particularly concentrated on any version of this information that is
  25 distributed as part of a *released* `g77'.
  26
  27    In particular, while this information is intended to apply to the
  28 GCC-2.95 version of `g77', only an official *release* of that version
  29 is expected to contain documentation that is most consistent with the
  30 `g77' product in that version.
  31
  32    The following information was last updated on 1999-07-17:
  33
  34 Prerequisites
  35 =============
  36
  37    For users of the GCC-2.95 version of `g77', this information is
  38 superceded by the GCC installation instructions.
  39
  40 Problems Installing
  41 ===================
  42
  43    This is a list of problems (and some apparent problems which don't
  44 really mean anything is wrong) that show up when configuring, building,
  45 installing, or porting GNU Fortran.
  46
  47    *Note Installation Problems: (gcc)Installation Problems, for more
  48 information on installation problems that can afflict either `gcc' or
  49 `g77'.
  50
  51 General Problems
  52 ----------------
  53
  54    These problems can occur on most or all systems.
  55
  56 GNU C Required
  57 ..............
  58
  59    Compiling `g77' requires GNU C, not just ANSI C.  Fixing this
  60 wouldn't be very hard (just tedious), but the code using GNU extensions
  61 to the C language is expected to be rewritten for 0.6 anyway, so there
  62 are no plans for an interim fix.
  63
  64    This requirement does not mean you must already have `gcc' installed
  65 to build `g77'.  As long as you have a working C compiler, you can use a
  66 "bootstrap" build to automate the process of first building `gcc' using
  67 the working C compiler you have, then building `g77' and rebuilding
  68 `gcc' using that just-built `gcc', and so on.
  69
  70 Patching GNU CC
  71 ...............
  72
  73    `g77' no longer requires application of a patch file to the `gcc'
  74 compiler tree.  In fact, no such patch file is distributed with `g77'.
  75 This is as of version 0.5.23 and `egcs' version 1.0.
  76
  77 Building GNU CC Necessary
  78 .........................
  79
  80    It should be possible to build the runtime without building `cc1'
  81 and other non-Fortran items, but, for now, an easy way to do that is
  82 not yet established.
  83
  84 Missing strtoul or bsearch
  85 ..........................
  86
  87    This information does not apply to the GCC-2.95 version of `g77',
  88
  89 Cleanup Kills Stage Directories
  90 ...............................
  91
  92    It'd be helpful if `g77''s `Makefile.in' or `Make-lang.in' would
  93 create the various `stageN' directories and their subdirectories, so
  94 developers and expert installers wouldn't have to reconfigure after
  95 cleaning up.
  96
  97    That help has arrived as of version 0.5.23 of `g77' and version 1.1
  98 of `egcs'.  Configuration itself no longer creates any particular
  99 directories that are unique to `g77'.  The build procedures in
 100 `Make-lang.in' take care of that, on demand.
 101
 102 LANGUAGES Macro Ignored
 103 .......................
 104
 105    Prior to version 0.5.23 of `g77' and version 1.1 of `egcs', `g77'
 106 would sometimes ignore the absence of `f77' and `F77' in the
 107 `LANGUAGES' macro definition used for the `make' command being
 108 processed.
 109
 110    As of `g77' version 0.5.23 and `egcs' version 1.1, `g77' now obeys
 111 this macro in all relevant situations.
 112
 113    However, in versions of `gcc' through 2.8.1, non-`g77' portions of
 114 `gcc', such as `g++', are known to go ahead and perform various
 115 language-specific activities when their respective language strings do
 116 not appear in the `LANGUAGES' macro in effect during that invocation of
 117 `make'.
 118
 119    It is expected that these remaining problems will be fixed in a
 120 future version of `gcc'.
 121
 122 System-specific Problems
 123 ------------------------
 124
 125    A linker bug on some versions of AIX 4.1 might prevent building when
 126 `g77' is built within `gcc'.  It might also occur when building within
 127 `egcs'.
 128
 129 Cross-compiler Problems
 130 -----------------------
 131
 132    `g77' has been in alpha testing since September of 1992, and in
 133 public beta testing since February of 1995.  Alpha testing was done by
 134 a small number of people worldwide on a fairly wide variety of
 135 machines, involving self-compilation in most or all cases.  Beta
 136 testing has been done primarily via self-compilation, but in more and
 137 more cases, cross-compilation (and "criss-cross compilation", where a
 138 version of a compiler is built on one machine to run on a second and
 139 generate code that runs on a third) has been tried and has succeeded,
 140 to varying extents.
 141
 142    Generally, `g77' can be ported to any configuration to which `gcc',
 143 `f2c', and `libf2c' can be ported and made to work together, aside from
 144 the known problems described in this manual.  If you want to port `g77'
 145 to a particular configuration, you should first make sure `gcc' and
 146 `libf2c' can be ported to that configuration before focusing on `g77',
 147 because `g77' is so dependent on them.
 148
 149    Even for cases where `gcc' and `libf2c' work, you might run into
 150 problems with cross-compilation on certain machines, for several
 151 reasons.
 152
 153    * There is one known bug (a design bug to be fixed in 0.6) that
 154      prevents configuration of `g77' as a cross-compiler in some cases,
 155      though there are assumptions made during configuration that
 156      probably make doing non-self-hosting builds a hassle, requiring
 157      manual intervention.
 158
 159    * `gcc' might still have some trouble being configured for certain
 160      combinations of machines.  For example, it might not know how to
 161      handle floating-point constants.
 162
 163    * Improvements to the way `libg2c' is built could make building
 164      `g77' as a cross-compiler easier--for example, passing and using
 165      `$(LD)' and `$(AR)' in the appropriate ways.  (This is improved in
 166      the `egcs' version of `g77', especially as of version 1.1.)
 167
 168    * There are still some challenges putting together the right
 169      run-time libraries (needed by `libg2c') for a target system,
 170      depending on the systems involved in the configuration.  (This is
 171      a general problem with cross-compilation, and with `gcc' in
 172      particular.)
 173
 174 Changing Settings Before Building
 175 =================================
 176
 177    Here are some internal `g77' settings that can be changed by editing
 178 source files in `egcs/gcc/f/' before building.
 179
 180    This information, and perhaps even these settings, represent
 181 stop-gap solutions to problems people doing various ports of `g77' have
 182 encountered.  As such, none of the following information is expected to
 183 be pertinent in future versions of `g77'.
 184
 185 Larger File Unit Numbers
 186 ------------------------
 187
 188    As distributed, whether as part of `f2c' or `g77', `libf2c' accepts
 189 file unit numbers only in the range 0 through 99.  For example, a
 190 statement such as `WRITE (UNIT=100)' causes a run-time crash in
 191 `libf2c', because the unit number, 100, is out of range.
 192
 193    If you know that Fortran programs at your installation require the
 194 use of unit numbers higher than 99, you can change the value of the
 195 `MXUNIT' macro, which represents the maximum unit number, to an
 196 appropriately higher value.
 197
 198    To do this, edit the file `egcs/libf2c/libI77/fio.h' in your `g77'
 199 source tree, changing the following line:
 200
 201      #define MXUNIT 100
 202
 203    Change the line so that the value of `MXUNIT' is defined to be at
 204 least one *greater* than the maximum unit number used by the Fortran
 205 programs on your system.
 206
 207    (For example, a program that does `WRITE (UNIT=255)' would require
 208 `MXUNIT' set to at least 256 to avoid crashing.)
 209
 210    Then build or rebuild `g77' as appropriate.
 211
 212    *Note:* Changing this macro has *no* effect on other limits your
 213 system might place on the number of files open at the same time.  That
 214 is, the macro might allow a program to do `WRITE (UNIT=100)', but the
 215 library and operating system underlying `libf2c' might disallow it if
 216 many other files have already been opened (via `OPEN' or implicitly via
 217 `READ', `WRITE', and so on).  Information on how to increase these
 218 other limits should be found in your system's documentation.
 219
 220 Always Flush Output
 221 -------------------
 222
 223    Some Fortran programs require output (writes) to be flushed to the
 224 operating system (under UNIX, via the `fflush()' library call) so that
 225 errors, such as disk full, are immediately flagged via the relevant
 226 `ERR=' and `IOSTAT=' mechanism, instead of such errors being flagged
 227 later as subsequent writes occur, forcing the previously written data
 228 to disk, or when the file is closed.
 229
 230    Essentially, the difference can be viewed as synchronous error
 231 reporting (immediate flagging of errors during writes) versus
 232 asynchronous, or, more precisely, buffered error reporting (detection
 233 of errors might be delayed).
 234
 235    `libg2c' supports flagging write errors immediately when it is built
 236 with the `ALWAYS_FLUSH' macro defined.  This results in a `libg2c' that
 237 runs slower, sometimes quite a bit slower, under certain
 238 circumstances--for example, accessing files via the networked file
 239 system NFS--but the effect can be more reliable, robust file I/O.
 240
 241    If you know that Fortran programs requiring this level of precision
 242 of error reporting are to be compiled using the version of `g77' you
 243 are building, you might wish to modify the `g77' source tree so that
 244 the version of `libg2c' is built with the `ALWAYS_FLUSH' macro defined,
 245 enabling this behavior.
 246
 247    To do this, find this line in `egcs/libf2c/f2c.h' in your `g77'
 248 source tree:
 249
 250      /* #define ALWAYS_FLUSH */
 251
 252    Remove the leading `/* ', so the line begins with `#define', and the
 253 trailing ` */'.
 254
 255    Then build or rebuild `g77' as appropriate.
 256
 257 Maximum Stackable Size
 258 ----------------------
 259
 260    `g77', on most machines, puts many variables and arrays on the stack
 261 where possible, and can be configured (by changing
 262 `FFECOM_sizeMAXSTACKITEM' in `egcs/gcc/f/com.c') to force smaller-sized
 263 entities into static storage (saving on stack space) or permit
 264 larger-sized entities to be put on the stack (which can improve
 265 run-time performance, as it presents more opportunities for the GBE to
 266 optimize the generated code).
 267
 268    *Note:* Putting more variables and arrays on the stack might cause
 269 problems due to system-dependent limits on stack size.  Also, the value
 270 of `FFECOM_sizeMAXSTACKITEM' has no effect on automatic variables and
 271 arrays.  *Note But-bugs::, for more information.
 272
 273 Floating-point Bit Patterns
 274 ---------------------------
 275
 276    The `g77' build will crash if an attempt is made to build it as a
 277 cross-compiler for a target when `g77' cannot reliably determine the
 278 bit pattern of floating-point constants for the target.  Planned
 279 improvements for version 0.6 of `g77' will give it the capabilities it
 280 needs to not have to crash the build but rather generate correct code
 281 for the target.  (Currently, `g77' would generate bad code under such
 282 circumstances if it didn't crash during the build, e.g. when compiling
 283 a source file that does something like `EQUIVALENCE (I,R)' and `DATA
 284 R/9.43578/'.)
 285
 286 Initialization of Large Aggregate Areas
 287 ---------------------------------------
 288
 289    A warning message is issued when `g77' sees code that provides
 290 initial values (e.g. via `DATA') to an aggregate area (`COMMON' or
 291 `EQUIVALENCE', or even a large enough array or `CHARACTER' variable)
 292 that is large enough to increase `g77''s compile time by roughly a
 293 factor of 10.
 294
 295    This size currently is quite small, since `g77' currently has a
 296 known bug requiring too much memory and time to handle such cases.  In
 297 `egcs/gcc/f/data.c', the macro `FFEDATA_sizeTOO_BIG_INIT_' is defined
 298 to the minimum size for the warning to appear.  The size is specified
 299 in storage units, which can be bytes, words, or whatever, on a
 300 case-by-case basis.
 301
 302    After changing this macro definition, you must (of course) rebuild
 303 and reinstall `g77' for the change to take effect.
 304
 305    Note that, as of version 0.5.18, improvements have reduced the scope
 306 of the problem for *sparse* initialization of large arrays, especially
 307 those with large, contiguous uninitialized areas.  However, the warning
 308 is issued at a point prior to when `g77' knows whether the
 309 initialization is sparse, and delaying the warning could mean it is
 310 produced too late to be helpful.
 311
 312    Therefore, the macro definition should not be adjusted to reflect
 313 sparse cases.  Instead, adjust it to generate the warning when densely
 314 initialized arrays begin to cause responses noticeably slower than
 315 linear performance would suggest.
 316
 317 Alpha Problems Fixed
 318 --------------------
 319
 320    `g77' used to warn when it was used to compile Fortran code for a
 321 target configuration that is not basically a 32-bit machine (such as an
 322 Alpha, which is a 64-bit machine, especially if it has a 64-bit
 323 operating system running on it).  That was because `g77' was known to
 324 not work properly on such configurations.
 325
 326    As of version 0.5.20, `g77' is believed to work well enough on such
 327 systems.  So, the warning is no longer needed or provided.
 328
 329    However, support for 64-bit systems, especially in areas such as
 330 cross-compilation and handling of intrinsics, is still incomplete.  The
 331 symptoms are believed to be compile-time diagnostics rather than the
 332 generation of bad code.  It is hoped that version 0.6 will completely
 333 support 64-bit systems.
 334
 335 Quick Start
 336 ===========
 337
 338    For users of the GCC-2.95 version of `g77', this information is
 339 superceded by the GCC installation instructions.
 340
 341 Complete Installation
 342 =====================
 343
 344    For users of the GCC-2.95 version of `g77', this information is
 345 superceded by the GCC installation instructions.
 346
 347 Distributing Binaries
 348 =====================
 349
 350    For users of the GCC-2.95 version of `g77', this information is
 351 superceded by the GCC installation instructions.
 352