7. Troubleshooting

If xmkmf and/or make succeeded without errors, you may proceed to the next section. However, in "real life", few things work right the first time. This is when your resourcefulness is put to the test.

7.1 Link Errors

• Suppose make fails with a Link error: -lX11: No such file or directory, even after xmkmf has been invoked. This may mean that the Imake file was not set up properly. Check the first part of the Makefile for lines such as:

  LIB=            -L/usr/X11/lib
  INCLUDE=        -I/usr/X11/include/X11
  LIBS=           -lX11 -lc -lm
  

  The -L and -I switches tell the compiler and linker where to look for the library and include files, respectively. In this example, the X11 libraries should be in the /usr/X11/lib directory, and the X11 include files should be in the /usr/X11/include/X11 directory. If this is incorrect for your machine, make the necessary changes to the Makefile and try the make again.

• Undefined references to math library functions, such as the following:

           /tmp/cca011551.o(.text+0x11): undefined reference to `cos'
  

  The fix for this is to explicitly link in the math library, by adding an -lm to the LIB or LIBS flags in the Makefile (see previous example).

• Yet another thing to try if xmkmf fails is the following script:

           make -DUseInstalled -I/usr/X386/lib/X11/config
  

  This is a sort of bare bones equivalent of xmkmf.

• In a very few cases, running ldconfig as root may be the solution:
  # ldconfig updates the shared library symbolic links. This may not be necessary .

• Some Makefiles use unrecognized aliases for libraries present in your system. For example, the build may require libX11.so.6, but there exists no such file or link in /usr/X11R6/lib. Yet, there is a libX11.so.6.1. The solution is to do a ln -s /usr/X11R6/lib/libX11.so.6.1 /usr/X11R6/lib/libX11.so.6, as root. This may need to be followed by a ldconfig.

• Sometimes the source needs the older release X11R5 libraries to build. If you have the R5 libs in /usr/X11R6/lib (you were given the option of having them when first installing Linux), then you need only ensure that you have the links that the software needs to build. The R5 libs are named libX11.so.3.1.0, libXaw.so.3.1.0, and libXt.so.3.1.0. You generally need links, such as libX11.so.3 -> libX11.so.3.1.0. Possibly the software will also need a link of the form libX11.so -> libX11.so.3.1.0. Of course, to create a "missing" link, use the command ln -s libX11.so.3.1.0 libX11.so, as root.

• Some packages will require you to install updated versions of one or more libraries. For example, the 4.x versions of the StarOffice suite from StarDivision GmbH were notorious for needing a libc version 5.4.4 or greater. Even the more recent StarOffice 5.0 will not run after installation with the new glibc 2.1 libs. Fortunately, the newer StarOffice 5.1 solves these problems. If running an older version of StarOffice you would, as root, need to copy one or more libraries to the appropriate directories, remove the old libraries, then reset the symbolic links (check the latest version of the StarOffice miniHOWTO for more information on this). Caution: Exercise extreme care in this, as you can render your system nonfunctional if you screw up. You can usually find the latest updated libraries at Sunsite.

7.2 Other Problems

• An installed Perl or shell script gives you a No such file or directory error message. In this case, check the file permissions to make sure the file is executable and check the file header to ascertain whether the shell or program invoked by the script is in the place specified. For example, the scrip may begin with:

  #!/usr/local/bin/perl
  

  If Perl is in fact installed in your /usr/bin directory instead of the /usr/local/bin one, then the script will not run. There are two methods of correcting this. The script file header may be changed to #!/usr/bin/perl, or a symbolic link to the correct directory may be added, ln -s /usr/bin/perl /usr/local/bin/perl.

• Some X11 software requires the Motif libraries to build. The standard Linux distributions do not have the Motif libraries installed, and at present Motif costs an extra $100-$200 (though the freeware Lesstif also works in many cases). If you need Motif to build a certain package, but lack the Motif libraries, it may be possible to obtain statically linked binaries. Static linking incorporates the library routines in the binaries themselves. This results in much larger binary files, but the code will run on systems lacking the libraries.
  When a package requires libraries not present on your system for the build, it will result in link errors (undefined reference errors). The libraries may be expensive proprietary ones or difficult to find for sone other reason. In that case, obtaining a statically linked binary either from the author of the package or from a Linux user group may be the easiest to implement fix.

• Running a configure script creates a strange Makefile, one seemingly unrelated to the package you are attempting to build. This means the wrong configure ran, one found somewhere else in your path. Always invoke configure as ./configure to prevent this.

• Most Linux distributions have changed over to the libc 6 / glibc 2 libraries from the older libc 5. Precompiled binaries that worked with the older library may bomb if you have upgraded your library. The solution is to either recompile the applications from the source or to obtain newer precompiled binaries. If you are in the process of upgrading your system to libc 6 and are experiencing problems, refer to Eric Green's Glibc 2 HOWTO.
  Note that there are some minor incompatibilities between glibc versions, so a binary built with glibc 2.1 may not work with glibc 2.0, and vice versa.

• Sometimes it is necessary to remove the -ansi option from the compile flags in the Makefile. This enables gcc's extra, non-ANSI features, and allows building packages that require these extensions. (Thanks to Sebastien Blondeel for pointing this out.)

• Some programs require having setuid root, in order to run with root privileges. The command to implement this is chmod u+s filename, as root (note that the program must already be owned by root). This has the effect of setting the setuid bit in the file permissions. This issue comes up when the program accesses the system hardware, such as a modem or CD ROM drive, or when the SVGA libs are invoked from console mode, as in one particularly notorious emulation package. If a program works when run by root, but gives access denied error messages to an ordinary user, suspect this as the cause.

  Warning: A program with setuid as root may pose a security risk to your system. The program runs with root privileges and thus has the potential for doing significant damage. Make certain that you know what the program does, by looking at the source if possible, before setting the setuid bit.

7.3 Tweaking and fine tuning

You may wish to examine the Makefile to make certain that the best compilation options for your system are invoked. For example, setting the -O2 flag chooses the highest level of optimization and the -fomit-frame-pointer flag results in a smaller binary (though debugging will then be disabled). Do not play around with this unless you know what you are doing, and in any case, not until after a trial build works.

7.4 Where to go for more help

In my experience, perhaps 25% of applications build "right out of the box". Another 50% or so can be "persuaded" to build with an effort ranging from trivial to herculean. That still means a significant number of packages will not build no matter what. Even then, the Intel ELF and/or a.out binaries for these might possibly be found at Sunsite or the TSX-11 archive. Red Hat and Debian have extensive archives of prepackaged binaries of most of the popular Linux software. Perhaps the author of the software can supply the binaries compiled for your particular flavor of machine.

Note that if you obtain precompiled binaries, you will need to check for compatibility with your system:

• The binaries must run on your hardware (i.e., Intel x86).
• The binaries must be compatible with your kernel (i.e., a.out or ELF).
• Your libraries must be up to date.
• Your system must have the appropriate installation utility (rpm or deb).

If all else fails, you may find help in the appropriate newsgroups, such as comp.os.linux.x or comp.os.linux.development.

If nothing at all works, at least you gave it your best effort, and you learned a lot.