Re: README/NEWS

[Peter O'Gorman]

Is this README okay for branch-1-5?

Note, in this case, I thought it better to attach the whole thing, rather 
than a diff.

Peter
--
Peter O'Gorman - http://www.pogma.com

GNU Libtool
***********

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

This is GNU Libtool, a generic library support script.  Libtool hides
the complexity of using shared libraries behind a consistent, portable
interface.

To use libtool, add the new generic library building commands to your
Makefile, Makefile.in, or Makefile.am.  See the documentation for
details.

See the info node (libtool)Tested Platforms. (or the file
doc/PLATFORMS) for a list of platforms that libtool supports.

Libtool's home page is:

  http://www.gnu.org/software/libtool/libtool.html

See the file NEWS for a description of recent changes to libtool.

See the file INSTALL for instructions on how to build and install
libtool.

Version Numbering
=================

Note the version numbers in the libtool-1.5.x series are a little strange,
the micro version (x) jumps by two on each release. The version in cvs always
has an odd micro version, while only released versions have even micro versions.
This will change again in the future. For more information about version
numbers see:

    http://www.gnu.org/software/libtool/contribute.html
    

Reporting Bugs
==============

If you have any suggestions or bug reports, or you wish to port
libtool to a new platform, please send electronic mail to the libtool
mailing list <address@hidden> or bug reports to <address@hidden>.
Be sure to include the version of libtool that you are using - you can find
out with `./libtool --version'. Also give as much information as necessary on
your OS, compiler and other build tools.


The Test Suite
==============

Libtool comes with an integrated set of tests to check that your build
is sane.  You can run the entire suite like this:

  make check

The tests run in groups in the various demo subdirectories, so if one
of the tests early in a group FAILs, the rest of the tests in that
group will be SKIPPED.  If you see a FAIL further into a group, even
if a test with the same name PASSes in another test group, you need to
take note of the name of the first test in the group if you want to
rerun the group with FAILures to get verbose output.

To run a test group in isolation (say, you think you have fixed a bug,
but don't want to rerun the entire suite), you can do it like this:

  make check TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test'

Providing that you have a FAIL from the most recent group from a
particular demo directory (like the cdemo-static.test group above), you
can explore the state of the directory to help with debugging.

If you wish to report a test group failure to the libtool list, you
need to send the verbose output of the FAILing group, along with
information such as the host OS, compiler tools, shell etc. to the
bug report mailing list, <address@hidden>.  From a bourne
compatible shell, you can generate verbose test output like this:

  VERBOSE=yes make check \
  TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
  | tee cdemo-static-group.log

In order to enable debug shell tracing, use VERBOSE=debug
instead of VERBOSE=yes.

Notes
=====

1)  Some HP-UX sed programs are horribly broken, and cannot handle
libtool's requirements, so users may report unusual problems.  There
is no workaround except to install a working sed (such as GNU sed) on
these systems.

2)  The vendor-distributed NCR MP-RAS cc programs emits copyright
on standard error that confuse tests on size of conftest.err.  The
workaround is to specify CC when run configure with CC='cc -Hnocopyr'.

3)  Due to a bug in autoconf cc isn't supported on Motorola System V 4.
You can only use gcc. This bug will hopefully be fixed in autoconf 2.14.

4)  Any earlier DG/UX system with ELF executables, such as R3.10 or
R4.10, is also likely to work, but hasn't been explicitly tested.

5)  Libtool has only been tested with the Siemens C-compiler and
an old version of gcc provided by Marco Walther you can find on
ftp://ftp.mch.sni.de/sni/mr/pd/gnu/gcc/gcc.2.7.2.3 on Reliant Unix.  

6)  libtool.m4, ltdl.m4 and the configure.ac files are marked to use
autoconf-mode, which is distributed with GNU Emacs 21, and all recent
releases of XEmacs.

7)  The default shell on UNICOS 9, a ksh 88e variant, is too buggy to
correctly execute the libtool script.  Users are advised to install a
modern shell such as GNU bash.