Add description of link failures due to bad -config program

git-svn-id: http://svn.code.sf.net/p/netpbm/code/trunk@2354 9d0c8265-081b-0410-96cb-a4ca84ce46f8

1 files changed, 58 insertions, 0 deletions

diff --git a/doc/INSTALL b/doc/INSTALL
index f933722d..f0b3e87b 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -372,3 +372,61 @@ DOCUMENTATION
 
 Documentation is not packaged with the program source code.  See the
 file doc/USERDOC for information on installing documentation.
+
+
+COMMON PROBLEMS
+---------------
+
+Improper -config files
+----------------------
+
+The most common problem building Netpbm is one of improperly installed
+prerequisite libraries, such as Libpng.  Such a library is designed to be
+installed along with a -config program (e.g. libpng-config) that tells
+builders of dependent packages (such as Netpbm) how to use it.  When the
+-config program is wrong, you get Netpbm build failures with messages about
+undefined references.
+
+The exact nature of the problems with -config programs can be quite
+involved, especially since there is no guarantee that a -config
+program can do what's required of it in every situation.  But I'll
+explain the basic problem.  For simplicity, I'll talk specifically
+about Libpng, but the principles apply to any library that has a -config
+program.
+
+The point of libpng-config is to describe how Libpng is installed on your
+particular system.  You have choices of where to install the various parts
+and what prerequisites to build into them, and libpng-config is how you
+communicate those choices to the Netpbm make files.
+
+Libpng's builder automatically creates a libpng-config program for you,
+but you should not think of it as part of Libpng.  It's really a
+configuration file -- something that tells how your particular system
+is put together.  The Libpng builder is not smart enough to know exactly
+what to put in libpng-config; it just builds one that works for most
+people.  The local system administrator is actually responsible for
+the contents of libpng-config.
+
+One rather complex way in which the libpng-config that the Libpng builder
+builds can be wrong is that it often indicates that to link to the
+Libpng library, you need a "-L /usr/lib" option (or something like that
+-- an option that adds to the linker's search path a directory that is
+already in it).  This is usually unnecessary because the directory is
+already in the search path, and often breaks things because it puts
+the directory too early in the search path.  If your libpng-config says to
+link with -L /usr/lib, you should normally edit it to remove that.
+
+As an example of how -L /usr/lib breaks things, here is a problem that is
+often reported: The user has Netpbm installed on his system, but wants to
+build a new one to replace it, or to use for a particular project instead of
+the system version.  But the build of the new version fails with undefined
+references to symbol "pm_foo".  pm_foo is a new symbol - it was added to
+Netpbm in a recent release.  The version of Netpbm installed on the system is
+too old to have it.  The make file obviously specifies the path to the current
+libraries that the user just built in the link library search order, but the
+link is picking up the old system version instead.  Why?  Because the link
+options say to search /usr/lib _before_ the local build directory.  And they
+do that because libpng-config erroneously says that you need a -L /usr/lib
+link option to find the Libpng library.
+
+