Next Previous Contents

## 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.

Next Previous Contents