diff options
author | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2014-12-26 16:56:33 +0000 |
---|---|---|
committer | giraffedata <giraffedata@9d0c8265-081b-0410-96cb-a4ca84ce46f8> | 2014-12-26 16:56:33 +0000 |
commit | 4ab437f0e6e36af08c2267a5b8914190ad785857 (patch) | |
tree | 2cd7ea207b343e8e043eaef426dc3c9b1c9fb754 /doc | |
parent | 6ce28348628081c359aca5f33d9599efb6453b1f (diff) | |
download | netpbm-mirror-4ab437f0e6e36af08c2267a5b8914190ad785857.tar.gz netpbm-mirror-4ab437f0e6e36af08c2267a5b8914190ad785857.tar.xz netpbm-mirror-4ab437f0e6e36af08c2267a5b8914190ad785857.zip |
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
Diffstat (limited to 'doc')
-rw-r--r-- | doc/INSTALL | 58 |
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. + + |