platform specific notes

[Ralf Wildenhues]

I think we need a better place to put platform specific notes.
branch-1-5 README has some, but README is not generally accessible
- for users of libtoolized packages
- before `configure'ing _that_ package

The online manual is accessible before issuing configure, so a pointer
from
  configure --help
to (yet non-existent, but see below)
  http://www.gnu.org/software/libtool/manual.html#Configure-notes
would be great.  Does anybody have an idea how to achieve that or do you
think it's not necessary?  By `configure' I mean a configure in any
libtoolized package.

But still, I would like to enable users to cope without going online,
at least for the Libtool package itself.  So, let's generate a new
Notes section, include it in libtool.texi plus also generate a text-only
version which we distribute and point to from README.

What do you think?  How about the patch below (against HEAD) for a first
simple cut that does half of it?  I'm pretty sure I violated that golden
distribution/creation rule again, so please show me how to create
notes.txt properly.  I've ordered the notes roughly in reverse age, so
that newer entries should come first (knowing how people read such
files..).  Dunno where to sensibly put the autoconf-mode entry at the
top.  The pgCC note needs my pgi patches as prerequisite, they are
moving in soon.

Yes, I am aware that the installation doc part is still in need of
other updates.  Patches are still very welcome.

Regards,
Ralf

--- /dev/null   2005-03-01 16:18:00.538006072 +0100
+++ doc/notes.texi      2005-03-18 11:38:48.426124864 +0100
@@ -0,0 +1,48 @@
address@hidden
+
address@hidden
address@hidden, @file{ltdl.m4} and the @file{configure.ac} files are marked
+to use autoconf-mode, which is distributed with GNU Emacs 21, Autoconf itself,
+and all recent releases of XEmacs.
+
address@hidden
+On AIX there are two different styles of shared linking, one in which symbols
+are bound at link-time and one in which symbols are bound at runtime only,
+similar to ELF.  In case of doubt use @code{LDFLAGS=-Wl,-brtl} for the latter 
style.
+
address@hidden
+For C++ code with templates, it may be necessary to specify the way the 
compiler
+will generate the instantiations.  For Portland pgCC version5, use
address@hidden'pgCC --one_instantiation_per_object}.
+
address@hidden
+FreeBSD @command{make} does not conform to @sc{posix} in its handling
+of file modification times, which causes it to loop while building libtool.
+Consider using a different @command{such} as GNU make instead.
+
address@hidden
+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.
+
address@hidden
+Some HP-UX @command{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 @command{sed} (such as GNU sed)
+on these systems.
+
address@hidden
+The vendor-distributed NCR MP-RAS @command{cc} programs emits copyright
+on standard error that confuse tests on size of conftest.err.  The
+workaround is to specify @env{CC} when run configure with
address@hidden'cc -Hnocopyr'}.
+
address@hidden
+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.
+
address@hidden
+On Reliant Unix libtool has only been tested with the Siemens C-compiler
+and an old version of @command{gcc} provided by Marco Walther.
+
address@hidden itemize
Index: doc/Makefile.am
===================================================================
RCS file: /cvsroot/libtool/libtool/doc/Makefile.am,v
retrieving revision 1.4
diff -u -r1.4 Makefile.am
--- doc/Makefile.am     25 Nov 2003 15:48:22 -0000      1.4
+++ doc/Makefile.am     18 Mar 2005 11:32:34 -0000
@@ -1,4 +1,12 @@
 ## Process this file with automake to produce Makefile.in
 
 info_TEXINFOS = libtool.texi
-libtool_TEXINFOS = PLATFORMS fdl.texi
+libtool_TEXINFOS = PLATFORMS fdl.texi notes.texi
+EXTRA_DIST = notes.txt
+
+all-local: $(srcdir)/notes.txt
+
+SUFFIXES = .texi .txt
+
+.texi.txt:
+       $(MAKEINFO) --plaintext $(MAKEINFOFLAGS) -o $@ $<
Index: doc/libtool.texi
===================================================================
RCS file: /cvsroot/libtool/libtool/doc/libtool.texi,v
retrieving revision 1.189
diff -u -r1.189 libtool.texi
--- doc/libtool.texi    12 Mar 2005 08:14:44 -0000      1.189
+++ doc/libtool.texi    18 Mar 2005 11:32:35 -0000
@@ -140,6 +140,7 @@
 Configuring libtool
 
 * LT_INIT::                     Configuring @code{libtool} in 
@file{configure.ac}.
+* Configure notes::             Platform-specific notes for configuration.
 
 Including libtool in your package
 
@@ -1825,6 +1826,7 @@
 
 @menu
 * LT_INIT::                     Configuring @code{libtool} in 
@file{configure.ac}.
+* Configure notes::             Platform-specific notes for configuration.
 @end menu
 
 @node LT_INIT
@@ -2122,6 +2124,18 @@
 @end example
 
 
+
address@hidden Configure notes
address@hidden Platform-specific configuration notes
+
+While Libtool tries to hide as many platform-specific features as possible,
+some have to be taken into account when configuring either the Libtool package
+or a libtoolized package.
+
address@hidden notes.texi
+
+
+
 @node Distributing
 @section Including libtool in your package