From: Peter O'Gorman <peter@pogma.com>
Date: Thu, 24 Jan 2008 07:27:41 +0000 (+0000)
Subject: * doc/libtool/texi: Backport notes.texi from HEAD.
X-Git-Tag: release-1-5-26~5
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a81dcb86a45ff397b976226043394fa5d7a2cda7;p=thirdparty%2Flibtool.git

* doc/libtool/texi: Backport notes.texi from HEAD.
---

diff --git a/ChangeLog b/ChangeLog
index 9e4561f04..e2d36e0c8 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,7 @@
 2008-01-24  Peter O'Gorman  <peter@pogma.com>
 
+	* doc/libtool/texi: Backport notes.texi from HEAD.
+
 	* libtool.m4 (sys_lib_search_path_spec, sys_lib_dlsearch_path_spec):
 	Allow for a cache variable lt_cv_sys_lib... to set these at configure
 	time.
diff --git a/doc/libtool.texi b/doc/libtool.texi
index aabeca99e..24be2c6e8 100644
--- a/doc/libtool.texi
+++ b/doc/libtool.texi
@@ -137,6 +137,7 @@ Integrating libtool with your package
 Configuring libtool
 
 * AC_PROG_LIBTOOL::             Configuring @code{libtool} in @file{configure.in}.
+* Configure notes::             Platform-specific notes for configuration.
 
 Including libtool in your package
 
@@ -1632,6 +1633,7 @@ generate a libtool script for the installer's host machine.
 
 @menu
 * AC_PROG_LIBTOOL::             Configuring @code{libtool} in @file{configure.in}.
+* Configure notes::             Platform-specific notes for configuration.
 @end menu
 
 @node AC_PROG_LIBTOOL
@@ -1840,6 +1842,91 @@ compatible version of @file{libtool.m4} installed and accessible for
 @code{aclocal}.  This may lead to weird errors when versions don't
 match.
 
+
+@node Configure notes
+@subsection 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.
+
+@itemize
+
+@item
+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.
+
+@item
+On AIX, native tools are to be preferred over binutils; especially for C++ code,
+if using the AIX Toolbox GCC 4.0 and binutils, configure with
+@code{AR=/usr/bin/ar LD=/usr/bin/ld NM='/usr/bin/nm -B'}.
+
+@item
+On AIX, the @command{/bin/sh} is very slow due to its inefficient handling
+of here-documents.  A modern shell is preferable:
+@example
+CONFIG_SHELL=/bin/bash; export $CONFIG_SHELL
+$CONFIG_SHELL ./configure [...]
+@end example
+
+@item
+For C++ code with templates, it may be necessary to specify the way the compiler
+will generate the instantiations.  For Portland pgCC version5, use
+@code{CXX='pgCC --one_instantiation_per_object'} and avoid parallel @command{make}.
+
+@item
+On Darwin, for C++ code with templates you need two level shared libraries.
+Libtool builds these by default if @env{MACOSX_DEPLOYMENT_TARGET} is set to
+10.3 or later at @command{configure} time.  See @url{rdar://problem/4135857}
+for more information on this issue.
+
+@c @item
+@c FreeBSD @command{make} does not conform to @sc{posix} in its handling
+@c of file modification times, which causes it to loop while building libtool.
+@c Consider using a different @command{such} as GNU make instead.
+
+@item
+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.
+
+@item
+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.
+
+@item
+The vendor-distributed NCR MP-RAS @command{cc} programs emits copyright
+on standard error that confuse tests on size of @file{conftest.err}.  The
+workaround is to specify @env{CC} when run configure with
+@code{CC='cc -Hnocopyr'}.
+
+@item
+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.
+
+@item
+On Reliant Unix libtool has only been tested with the Siemens C-compiler
+and an old version of @command{gcc} provided by Marco Walther.
+
+@item
+@file{libtool.m4}, @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.
+
+@item
+When building on some linux systems for multilib targets
+@command{libtool} sometimes guesses the wrong paths that the linker
+and dynamic linker search by default. If this occurs, you may override
+libtool's guesses at @command{configure} time by setting the
+@command{autoconf} cache variables
+@code{lt_cv_sys_lib_search_path_spec} and
+@code{lt_sys_lib_dlsearch_path_spec} respectively to the correct search
+paths.
+
+@end itemize
 @node Distributing
 @section Including libtool in your package