contrib/libf2c/README

   1 1998-08-11
   2
   3 This directory contains the libf2c library packaged for use with g77
   4 to configure and build automatically (in principle!) as part of the
   5 top-level configure and make steps.  g77 names this library `libg2c'
   6 to avoid conflicts with existing copies of `libf2c' on a system.
   7
   8 Some small changes have been made vis-a-vis the netlib distribution of
   9 libf2c, which comes from <ftp:bell-labs.com/netlib/f2c/> and is maintained
  10 (excellently) by David M. Gay <dmg@bell-labs.com>.  See the Notice files
  11 for copyright information.  We usually try to get g77-specific changes
  12 rolled back into the libf2c distribution.
  13
  14 Files that come directly from netlib are either maintained in the
  15 libf2c directory under their original names or, if they are not pertinent
  16 for g77's version of libf2c, under their original names with `.netlib'
  17 appended.  For example, permissions.netlib is a copy of f2c's top-level
  18 `permissions' file in the netlib distribution.  In this case, it applies
  19 only to the relevant portions of the libF77/ and libI77/ directories; it
  20 does not apply to the libU77/ directory, which is distributed under
  21 different licensing arrangements.  Similarly, the `makefile.netlib' files
  22 in the libF77/ and libI77/ subdirectories are copies of the respective
  23 `makefile' files in the netlib distribution, but are not used when
  24 building g77's version of libf2c.
  25
  26 The README.netlib files in libF77/ and libI77/ thus might be
  27 interesting, but should not be taken as guidelines for how to
  28 configure and build libf2c in g77's distribution.
  29
  30 * Read permissions.netlib for licensing conditions that apply to
  31   distributing programs containing portions of code in the libF77/ and
  32   libI77/ subdirectories.  Also read disclaimer.netlib.
  33
  34 * Read libU77/COPYING.LIB for licensing conditions that apply to
  35   distributing programs containing portions of code in the libU77/
  36   subdirectory.
  37
  38 Among the user-visible changes (choices) g77 makes in its version of libf2c:
  39
  40 -  f2c.h configured to default to padding unformatted direct reads
  41    (#define Pad_UDread), because that's the behavior most users
  42    expect.
  43
  44 -  f2c.h configured to default to outputting leading zeros before
  45    decimal points in formatted and list-directed output, to be compatible
  46    with many other compilers (#define WANT_LEAD_0).  Either way is
  47    standard-conforming, however, and you should try to avoid writing
  48    code that assumes one format or another.
  49
  50 -  dtime_() and etime_() are from Dave Love's libU77, not from
  51    netlib's libF77.
  52
  53 -  Routines that are intended to be called directly via user code
  54    (as in `CALL EXIT', but not the support routines for `OPEN')
  55    have been renamed from `<name>' to `G77_<name>_0'.  This, in
  56    combination with g77 recognizing these names as intrinsics and
  57    calling them directly by those names, reduces the likelihood of
  58    interface mismatches occurring due to use of compiler options
  59    that change code generation, and permits use of these names as
  60    both intrinsics and user-supplied routines in applications (as
  61    required by the Fortran standards).  f2cext.c contains "jacket"
  62    routines named `<name>' that call `G77_<name>_0', to support
  63    code that relies on calling the relevant routines as `EXTERNAL'
  64    routines.
  65
  66    Note that the `_0' in the name denotes version 0 of the *interface*,
  67    not the *implementation*, of a routine.  The interface of a
  68    given routine *must not change* -- instead, introduce a new copy
  69    of the code, with an increment (e.g. `_1') suffix, having the
  70    new interface.  Whether the previous interface is maintained is
  71    not as important as ensuring the routine implementing the new
  72    interface is never successfully linked to a call in existing,
  73    e.g. previously compiled, code that expects the old interface.
  74
  75 -  Version.c in the subdirectories contains g77-specific version
  76    information and a routine (per subdirectory) to print both the
  77    netlib and g77 version information when called.  The `g77 -v'
  78    command is designed to trigger this, by compiling, linking, and
  79    running a small program that calls the routines in sequence.
  80
  81 -  libF77/main.c no longer contains the actual code to copy the
  82    argc and argv values into globals or to set up the signal-handling
  83    environment.  These have been removed to libF77/setarg.c and
  84    libF77/setsig.c, respectively.  libF77/main.c contains procedure
  85    calls to the new code in place of the code itself.  This should
  86    simplify linking executables with a main() function other than
  87    that in libF77/main.c (such as one written by the user in C or
  88    C++).  See the g77 documentation for more information.
  89
  90 -  Complex-arithmetic support routines in libF77/ take a different approach
  91    to avoiding problems resulting from aliased input and output arguments,
  92    which should avoid particularly unusual alias problems that netlib
  93    libf2c might suffer from.
  94
  95 -  libF77/signal_.c supports systems with 64-bit pointers and 32-bit
  96    integers.
  97
  98 -  I/O routines in libI77/ have code to detect attempts to do recursive
  99    I/O more "directly", mainly to lead to a clearer diagnostic than
 100    typically occurs under such conditions.
 101
 102 -  Formatted-I/O routines in libI77/ have code to pretty-print a FORMAT
 103    string when printing a fatal diagnostic involving formatted I/O.
 104
 105 -  libI77/open.c supports a more robust, perhaps more secure, method
 106    of naming temporary files on some systems.
 107
 108 -  Some g77-specific handling of building under Microsoft operating
 109    systems exists, mainly in libI77/.