                                                  -*-indented-text-*-


`libU77' library for G77 -- preliminary release
-----------------------------------------------

Dave Love <d.love@dl.ac.uk>  1996-12-16

Distribution: <URL:ftp//ftp.dl.ac.uk/pub/fx/libu77/>


* Abstract

This is a preliminary release of an implementation of the
oft-requested traditional `libU77' routines for GNU Fortran (G77).
The routines involved are mostly Fortran77 interfaces to typical Unix
C and maths library routines plus additional ones for timing etc.

* Overview

** Scope

The contents of libU77 and its interfaces aren't consistent across
implementations.  This one is mostly taken from documentation for (an
old version of) the Convex implementation and the v2 SunPro one.
Where there are differences with or between other implementations,
this will eventually be taken care of when they are made G77
intrinsics.  In the mean time some routines have a version with a name
prefixed by `vxt', corresponding to the VMS Fortran versions, and
others come with a health warning.

** Features c.f. other work

Various people have worked on and propagated implementations of at
least some of the functionality provided here.  Some of these have
been incorrect in various ways, and most haven't considered wide
portability; some work I might have built on only came to light after
I'd written done this work, which has been hanging around for a long
time now.

This release is intended to be highly portable by using the autoconf
system for configuration (even for cross-building).  Remaining
non-portabilities should be easy to take care of, given information
about the target systems.  It will also become part of G77 at a later
date and has documentation.

The standard for many of the sort of system interfaces provided here
is POSIX.9.  Someone is working on an implementation of that, but it
will probably demand a POSIX.1 compliant system as a base.

** Status

This is a preliminary release, in need of testing, particularly for
portability.  Please send feedback per `Bug reports' below.  It will
be included with a future version of G77, when the routines are
expected to have INTRINSIC support.  This will probably involve their
calling sequences changing so that non-referentially-transparent
routines aren't called as FUNCTIONs, which is Evil.

A few routines are currently missing; in the case of `fork', for
instance, because they're probably not useful and in the case of
`qsort' and some for stream-based i/o handling, because they need more
effort/research.  The configuration should weed out those few which
correspond to facilities which may not be present on some Unix
systems, such as symbolic links.  I'm undecided whether the interfaces
to the native library random number routines should be retained, since
their implementation is likely to be something one should avoid
assiduously.

** f2c compatibility

These routines could also be used with f2c-compiled code *if* the
object code is produced with the same version of GCC and the f2c.h
header file used to compile libf2c.a.  The configuration stuff
currently assumes GCC is in use, and all the declarations may not be
compatible with K&R C compilers, but this could be fixed so that it
will work with f2c independently of G77.

* Installation

The distribution comprises patches to some configuration/build files
in the G77 0.5.19 distribution and an extra sub-directory (`libU77')
of `runtime'.  It may or may not either work with or be relevant to
earlier or later versions of G77, but I'll update it to future
versions as appropriate.

Un-tar the distribution from a directory containing the g77-0.5.19
directory with the original sources; extra files will be created in
g77-0.5.19.  Then `cd' into g77-0.5.19 and apply the patch using the
command
  patch -p1 < g77-0.5.19-u77.diff
or equivalent.

If you have moved the g77-0.5.19 into the gcc directory to build G77
already, just copy the files from this distribution into the same
place, cd to the gcc directory and apply the patch in the same way as
above.

The facility for building the libU77 routines is then available.  The
resulting top-level and f/runtime `configure's have an additional
option `--enable-libu77' which will set things up to add the libU77
routines to libf2c.a when it's built.  Thus follow the normal
instructions for G77, but add `--enable-libu77' to the command line
when you run `./configure'.  Then use `make' to build everything as
normal.  If you do this in a directory which has already been used to
build G77 less will need to be compiled.

It should also work just to do a configure and make in the libU77
sub-directory to add to an existing libf2c.a in the build tree,
*providing the GCC which gets found by `configure' is consistent with
the one built from the current tree*.  In this case only the code in
the libU77 directory will be compiled.  Install the resulting libf2c.a
by hand if necessary.

* Documentation

Please see the supplied TeXinfo documentation, `g77-rtl.texi' and the
info-formatted version, `g77-rtl.info'.  This also documents
user-callable routines in the `libf2c' library currently distributed
with G77.

* Copyright

This is distributed under the GNU Library General Public Licence.  I
might be prepared to change that to be a la libI77/libF77 given a good
reason.

* Bug reports

Please send reports of bugs, incompatibilities, non-portabilities,
suggestions for extension, etc. to me, <d.love@dl.ac.uk> directly
until this is incorporated into the G77 distribution proper.
