                      Software Distribution for

   Algorithm xxx: QUADLOG --- A Package of Routines for Generating
 High-Accuracy Quadrature for Two Classes of Logarithmic Weight Functions

                                 and

     Algorithm xxx: Quadruple-Precision $\Gamma(x)$ and $\psi(x)$
                     Functions for Real Arguments

                                  by

                          Nelson H. F. Beebe
                                 and
                            James S. Ball

                          University of Utah
                            [14-Dec-2000]

			       updated
			    [17-Jun-2004]

=================
Table of Contents
=================

	Filesystem space requirements
	Recommended prerequisite
        Unpacking the software distribution
        Quick and (usually) clean installation
        Introduction
        Building, validation, and installation
	Tested platforms
        IBM RS/6000 and SGI systems
        Portland Group, Inc. Fortran compilers
        Non-IEEE 754 systems
        Non-POSIX-conformant operating systems
        Arithmetic-system-dependent constants
        Bug and problem reports
        Copyright issues
        Manual builds, or, doing it the hard way


=============================
Filesystem space requirements
=============================

This package is normally distributed as gzip-compressed Unix tar
files.  There may be two separate distributions, the normal one:

	quadlog-gampsi.tar.gz		[28 MB]

containing the full test suite, and a smaller distribution with much
of the test suite data for the gamma and psi functions removed:

	quadlog-gampsi-slim.tar.gz	[5 MB]

Software MUST be tested; use the full distribution unless you have a
very cramped environment.

After a successful build, the full distribution requires about 120MB
of filesystem space; the slim distribution requires about 25MB.

After installation, the run-time library occupies about 0.5MB, and the
manual pages, about 4MB, so once the temporary build directory has
been removed, the net addition to your filesystem is under 5MB.  That
corresponds to about 14K lines of installed software, 9K lines of
manual-page documentation, and about 9K lines of noninstalled test
software.


========================
Recommended prerequisite
========================

Before you begin, we STRONGLY recommend that you fetch and install the
ndiff package noted in the companion INSTALL file.  It will make the
validation suite test output very much easier to read.  ndiff has been
successfully installed on all of the systems that we tested (listed
below).


===================================
Unpacking the software distribution
===================================

With GNU tar, you can unpack a distribution like this:

	tar xfz quadlog-gampsi.tar.gz

With Unix tar, use a pipeline, like this:

	gunzip < quadlog-gampsi.tar.gz | tar xf -

In either case, the distribution is unbundled into a subdirectory
named by the basename of the distribution, here quadlog-gampsi.
You can now do

	cd quadlog-gampsi

in preparation for the build.

Should you lose or corrupt the distribution, you can retrieve a
digitally-signed copy at either of these locations:

	ftp://ftp.math.utah.edu/pub/quadlog
	http://www.math.utah.edu/pub/quadlog


======================================
Quick and (usually) clean installation
======================================

At many sites, this simple command

        ./configure && make all check install

will build, validate, and install these packages.  Unless this fails,
or you want to control choice of compilers, compilation options, and
installation directories, you can stop reading this file now :^).


============
Introduction
============

This README file is provided in the top-level directory of a directory
tree for the two ACM Transactions on Mathematics Software Algorithms
in the title above.  The software subdirectories are

        common
        gampsi
        jacobi
        laguerre

and the UNIX manual page subdirectory is

        man

For portability, ALL file names in this directory tree conform to the
draconian IBM PC-DOS 8+3 limit, and the old UNIX System III and V
14-character limit, which can be checked like this:

        find . -type f | sort | doschk

The doschk utility is available at

        ftp://ftp.gnu.org/pub/gnu/non-gnu/doschk/doschk-1.1.tar.gz

File names are generally spelled entirely in lowercase, with a few
exceptions:

        INSTALL
        MKDIRS
        Makefile
        Makefile.in
        README

Their initial uppercase letters place them at the beginning of a
directory contents listing (by, e.g., the UNIX "ls" command, assuming
the traditional C locale: set the environment variable LC_ALL to C to
ensure this) for better visibility, and conformance to widespread
conventions.  However, no harm, or collisions, will arise from all
file names being mapped to a single lettercase.

As its name implies, subdirectory ./common contains code shared by
software in the other three software directories.

The ./jacobi and ./laguerre directories belong to package QUADLOG, and
the ./gampsi directory to the second article in the title above.

Although they share a considerable amount of code, the two packages
are INDEPENDENT, and can be built separately if desired.  However, in
this document, we assume that both are to be built sequentially.

This software tree uses the Free Software Foundation's GNU Project
autoconfigure system to significantly facilitate the compilation,
linking, testing, and installation of complex software packages.

The autoconfigure software should be usable on ANY POSIX-conformant
system, which includes all stock UNIX variants, including GNU/Linux,
and also on most other operating systems, PROVIDED that the additional
POSIX support has been installed on them.

More information on POSIX issues can be found in ./common/README.

The autoconfigure system is now described in a book:

	@String{pub-NEW-RIDERS          = "New Riders Publishing"}
	@String{pub-NEW-RIDERS:adr      = "Carmel, IN, USA"}

	@Book{Vaughan:2000:GAA,
	  author =       "Gary V. Vaughan and Ben Elliston and Tom Tromey and
			 Ian Lance Taylor",
	  title =        "{GNU} Autoconf, Automake and Libtool",
	  publisher =    pub-NEW-RIDERS,
	  address =      pub-NEW-RIDERS:adr,
	  pages =        "xx + 390",
	  year =         "2000",
	  ISBN =         "1-57870-190-2",
	  LCCN =         "QA76.76.O63 G598 2000",
	  bibdate =      "Sat Feb 24 11:27:09 2001",
	  price =        "US\$40.00",
	  URL =          "http://www.newriders.com/books/title.cfm?isbn=1578701902;
			 http://sources.redhat.com/autobook/;
			 http://sources.redhat.com/autobook/autobook/autobook_toc.html;
			 http://sources.redhat.com/autobook/download.html",
	  acknowledgement = ack-nhfb,
	}

Nevertheless, installation of an autoconfigured package does NOT require
prior installation of the GNU autoconf package: that is only needed if
you wish to modify the short configure.in files, and then regenerate
the big configure scripts, which are 6 to 130 times bigger in the
subdirectories here.  Should you wish to do so (for example, for a
port to a new system where the standard configure scripts fail), you
can find autoconf at

        ftp://ftp.gnu.org/gnu/autoconf/

Make sure to get the latest version if you do this; 2.13 has been
stable since 15-Jan-1999, and 2.54 was released on 20-Feb-2004.  The
authors shall, of course, be pleased to receive any resulting updates
to the configure.in and Makefile.in files; the shortest, and best, way
to communicate such updates is to send NHFB the output of "diff -c"
between the original and changed files.


======================================
Building, validation, and installation
======================================

To build, validate, and install both packages:

        ./configure && make all check install

If your compilation environment supports quadruple precision
(Fortran's REAL*16, C/C++'s long double), then you can optionally
follow that command with

	make all-qp check-qp install

to get the quadruple-precision code and its Unix manual page
documentation installed as well.

The top-level configure script, after doing its job here, will then
step into each of the four subdirectories in turn and run configure
there with the same environment.  The subsequent "make" step will also
operate first here, then in each of the four software subdirectories,
and the manual page directory.

This is roughly equivalent to

        ( cd common ; ./configure && make all check install )
        ( cd man ; ./configure && make all check install )
        ( cd gampsi ; ./configure && make all check install )
        ( cd jacobi ; ./configure && make all check install )
        ( cd laguerre ; ./configure && make all check install )

in case you want to do the job partly by hand, or restart a failed
build.

To specify compilers, set environment variables for CC (C or C++
compiler name, optionally with special flags (e.g., CC='c89 -posix')),
and F77 (Fortran 77, 90, 95 or HPF compiler name, optionally with
special flags (e.g., F77='f77 -fpe3')):

        env CC=CC F77=f90 ./configure && make all check install

The env command works in all known UNIX shells, eliminating the
nuisance of syntax variations in the setting of environment variables
in different shells.

NB: The test programs intentionally generate at least one overflow, in
subroutine getnan() (./common/getnan.f): on machines with IEEE 754
arithmetic, this should be transparent.  Unfortunately, some compilers
do not by default provide the full IEEE 754 environment, and terminate
on overflow or zero divide.  Also, some Fortran 90 and 95 compilers
need notification of fixed source format.

Here are additional Fortran compiler switches that may be needed at
your site:

    ---------------------------------------------------------------------
    Compiler(s)     Operating System                     Options
    ---------------------------------------------------------------------
    nagf90, nagf95  all UNIX                      -ieee=full -w=obs
    f90, f95        Sun Solaris 2.x               -ftrap=%none
    xlf90, xlf95    IBM RS/6000 AIX 4.x           -qfixed
    f77, f90, f95   Compaq/DEC OSF/1 4.x (Tru64)  -fpe2 or -fpe3 or -fpe4
    g77             GNU/Linux and OSF/1 on Alpha  -mieee
    ---------------------------------------------------------------------

Please note that due to an irregularity in GNU autoconf, the Fortran
compiler name variable is F77 at "configure" time, but FC at "make"
time.  While I could repair this locally to remove the inconsistency,
the correction would be lost if autoconf were run again at an end-user
site.  It is unknown when, or if, this flaw in autoconf may be
repaired.

You can set compiler optimization levels through the COPT
and FOPT variables on the make command line, for C/C++ and
Fortran respectively:

        make COPT=-xO3 FOPT='-xO5 -g3' targets...

Unless overridden by the F77 environment variable, ./configure will
search for the first Fortran compiler found in this list:

        f77 g77 f90 f95

The code has been written very carefully to work under any Fortran
compiler conforming to ANSI/ISO Fortran 77, 90, 95, or
High-Performance Fortran.  Fortran 66 is NOT supported.

Some Fortran 90 and 95 compilers assume free-form source format by
default, in which case they need an extra flag to revert to fixed-form
source format.  ./configure will supply this flag automatically where
necessary for compilers on the test systems at the development sites.
Most such compilers more sensibly automatically assume fixed-form
source format for source file extension .f, and free-form format for
extensions .f90 and .f95.

If you are a system manager, and the GNU-standard /usr/local is an
acceptable location, that single command line should suffice.

Otherwise, if you use non-standard installation trees, or are a user
without privileges to write into a shared system-wide directory tree,
you can change the installation location like this:

        ./configure --prefix=/some/other/path && make all check install

or

        ./configure && make all check install prefix=/some/other/path

For a single unprivileged user, $HOME/local is a recommended choice for
/some/other/path.

Under NO CIRCUMSTANCES should you ever do local software installations
with the prefix set to /usr; doing so will make it impossible to
distinguish locally-installed software from vendor software, and all
of your locally-added material will be lost when you next upgrade your
operating system!

At most large POSIX sites, /usr/local is a file tree shared among
machines of compatible architectures; thus, in a multi-platform
environment, you will need to repeat the installation only once per
architecture, rather than once per individual machine.

Assuming that $PREFIX stands for the value of the --prefix option, or
the Makefile "prefix" variable when "make install" is run, the
installation will place files in these standard directories, which
must already exist:

        $PREFIX/lib
        $PREFIX/man/man3

In addition, files will be installed here too,

        $PREFIX/man/html/man3
        $PREFIX/man/pdf/man3
        $PREFIX/man/ps/man3

but ONLY if these directories already exist.

To encourage software installations to be put in standard places, some
software package authors, including at least one of us, consider it
bad form for a package installation to create new installation
directories, unless they are intended to be used solely for that
package, so "make install" for this package will NOT create any new
directories.

For convenience, a command like

        ./MKDIRS --prefix=/some/other/path

tries to create the required installation directory tree, assuming
/some/other/path is changed to something sensible :^)!

Although UNIX manual pages for library routines conventionally go into
a directory tree .../man/man3 (raw nroff/troff files) and .../man/cat3
(formatted ASCII text files), no widely-adopted convention exists
for where HTML, PostScript, and PDF forms of the formatted manual
pages should be installed.  The settings above reflect reasonable
choices made at the authors' sites.

The default UNIX manual page installation locations can always be
overridden at install time, like this:

        cd man; make install \
                        htmldir=/some/directory \
                        mandir=/some/other/directory \
                        pdfdir=/yet/another/directory \
                        psdir=/yet/one/more/directory


================
Tested platforms
================

Table 1 in the QUADLOG article contains a list of 13 hardware
platforms and 44 Fortran compilers on which the package was
successfully built and tested in 1999--2000.

Since then, some of those systems have been retired, and new systems
have been added.  They include at least these 19 hardware platforms
and 56 compilers, covering all of the major commercial Unix platforms,
plus GNU/Linux, FreeBSD, MacOS X, NetBSD, and OpenBSD on various CPU
architectures:

	Apple PowerPC G3 267MHz	GNU/Linux 2.4.19-4a (Yellow Dog Linux release 2.3 (Dayton))
				/usr/local/bin/f77
				/usr/local/bin/g77

	Apple PowerPC G4 1.4GHz	Darwin 7.3.0 (MacOS 10.3.2 (7D26))
				/usr/local/bin/f77
				/usr/local/bin/g77

	Compaq Alpha Sierra	OSF/1 5.1
				/usr/bin/f77
				/usr/bin/f90
				/usr/bin/f95
				$HOME/alpha/local/bin/g77

	Compaq/DEC Alpha	OSF/1 4.0F
				/usr/local/bin/g77
				/usr/ucb/f77
				/usr/ucb/f90
				/usr/ucb/f95

	DEC Alpha		GNU/Linux 2.2.19-6.2.1 (Red Hat 6.2)
				/usr/bin/fort
				/usr/local/bin/f77
				/usr/local/bin/g77

	HP rx2600 Itanium-2	HP-UX 11i 11.23
				/opt/fortran90/bin/f90

	HP rp2470 PA-RISC 8700	HP HP-UX 11i 11.11
				/opt/fortran90/bin/f90

	HP/Intel IA-64		GNU/Linux 2.2.17-14smp (Red Hat 6.2) [via HP NUE emulator on IA-32]
				/usr/local/bin/f77

	IBM PowerPC		AIX 4.2
				/bin/f77
				/bin/xlf90
				/usr/local/bin/g77

	Intel Itanium-2		GNU/Linux Red Hat Linux Advanced Server release 2.1AS (Derry)
				/opt/intel_fc_80/bin/ifort
				/usr/bin/g77
				/usr/local/bin/f77

	Intel Pentium II	FreeBSD 4.4-RELEASE #0
				/usr/bin/f77
				/usr/local/bin/g77

	Intel Pentium III	FreeBSD 5.0
				/usr/bin/f77
				/usr/local/bin/g77

	Intel Pentium III	GNU/Linux 2.4.18-26.8.0smp (Red Hat 8.0 (Psyche))
				/opt/intel_fc_80/bin/ifort
				/usr/local/bin/f77
				/usr/local/bin/g77
				/usr/local/bin/lf95
				/usr/local/sys/pgi/pgi/linux86/5.1/bin/pgf77
				/usr/local/sys/pgi/pgi/linux86/5.1/bin/pgf90

	Intel Pentium III	NetBSD 1.6
				/usr/bin/f77
				/usr/local/bin/g77

	Intel Pentium III	OpenBSD 3.2
				/usr/bin/f77
				/usr/local/bin/g77

	Intel Pentium III	Solaris 9 x86
				/usr/local/bin/g77

	SGI Origin 200		IRIX 6.5
				/bin/f77
				/bin/f90
				/usr/local/bin/g77

	Sun SPARC		GNU/Linux 2.2.19-6.2.1 (Red Hat 6.2)
				/usr/local/bin/f77
				/usr/local/bin/g77

	Sun SPARC		Solaris 2.7, 2.8, 2.9
				/opt/SUNWspro/bin/f77
				/opt/SUNWspro/bin/f90
				/opt/SUNWspro/bin/f95
				/usr/local/bin/g77


===========================
IBM RS/6000 and SGI systems
===========================

See the section with this name in ./common/README.


======================================
Portland Group, Inc. Fortran compilers
======================================

See the section with this name in ./common/README.


====================
Non-IEEE 754 systems
====================

See the section with this name in ./common/README.


======================================
Non-POSIX-conformant operating systems
======================================

See the section with this name in ./common/README.


=====================================
Arithmetic-system-dependent constants
=====================================

See the section with this name in ./common/README.


=======================
Bug and problem reports
=======================

See the section with this name in ./common/README.


================
Copyright issues
================

This code is distributed under the usual copyright arrangement for the
ACM Algorithms, as described from time to time in the journal ACM
Transactions on Mathematical Software.  In general, the copyright
provides for unrestricted use of the software, in both commercial and
noncommercial software.


========================================
Manual builds, or, doing it the hard way
========================================

For manual builds, without using "configure" and "make", see the
sections with this name in each individual subdirectory.

---------------------------------The End--------------------------------
