Small additions on error.txt

alex at 22-music.de alex at 22-music.de
Wed Oct 8 02:01:52 PDT 2003


I'm sorry I pressed "reply" w/o thinking, so the stuff went to Tushar's
work address instead of this mailing list:

Tushar wrote me:
> A suggestion: Include something about distinguishing between a
> warning and an error and the use of CPPFLAGS="-w" to stop warnings 
> from being outputed (this confuses a lot of people, especially in 
> builds such as j2sdk and openoffice which have a tendency to spit 
> out lot of warnings without merit and which look like errors).    
> 
I aswered:    
> You're right, especially if the developer tried to show-off with 
> -Werror! Find it included in the attached version!

He told me afterwards:
> Can you send the hint to the hints mailing list. This is my yahoo 
> idfor use at work.
>       
> Another suggestion, ask the lfs folks to include it, I will include 
> it in BLFS.
> 
My answer:
> I think it's a bit long to be included into the LFS book (maybe as
> appendix?), a link to the hint would be sufficient anyway; Inclusion 
> in BLFS is a good idea. Maybe you could use a table for the cruel 
> abuse of ascii art in the hint ;-)

He replied:
> By inclusion I meant a link :-)

So that's the story.

And here's the updated hint.

Alex
-------------- next part --------------
AUTHOR:	Alex Kloss <alex at 22-music.com>

DATE: 2003-10-07

LICENSE: GNU Free Documentation License Version 1.2

SYNOPSIS: What to do on errors

DESCRIPTION:
The LFS Book has a short, but nice chapter about errors. A longer essay about 
how to spot where the error is, how to describe it (on IRC or the mailing 
list), and possibly get around it is the goal of this hint.

PREREQUISITES:
Common sense, LFS, patience.

HINT:
Almost every LFS adept has seen lines like:

- make[1]: Error
- Segmentation Fault
- ld returned signal 2: ...

The first urge is to write to the mailing list or on IRC something like:

I have an error in program <fill in whatever is appropriate>!

First of all, is it really an error? If you find the option "-Werror" in the 
lines that calls gcc, the "error" you're facing could as well be a warning
(-Werror makes gcc handle all warnings as errors). You will often find warning 
and error messages mixed before the classical "make[1]: Error". A warning is 
something gcc complains about, but continues without error, while an error is 
something that stops you from compiling the package you are about to build.
To disable distracting warning messages, use "export CFLAGS="-w".

Mostly further informations about the errors are missing, which is a nuisance
for both the one who asks and the one who tries to answer, because of the
annoying dialogue that is often following. I have to admid that the LFS mailing
list and IRC never failed to solve my problems (and that in a rather cheerful
way), but I reached a point at where I wanted to solve as much of my problems
myself. So I had to learn a much, which was undoubtedly fun.

WHAT KIND OF ERROR?

You have to distinguish between the different kinds of errors. The more you 
can tell about the error, the easier it is to solve.

This should be a normal hint, but I guess it is easier to draw a chart:

Question: When did it happen?   What happened?      Where did it happen?

                                                  , Compiling (gcc) ...
                              , ... not found ---<
          Compile-time Error <                    ` Linking (ld)
       ,'                     `.
Error <                          Segfault
       `.                     ,'
          Run-time Error ----<          , full
                              ` Hangup <
                                        ` Prog 
        				  only

That looks pretty simple, eh? But that's only the beginning. We will have a 
look at each of these error types closely!

1. Compile-time Errors

First of all, check the package you are about to compile for files like README
and/or INSTALL. You can ship around most errors by strictly following those 
instructions. 

When you are about to build your package, you sometimes get the error that 
something is missing or malformed or simply uncompileable.

1.1 ... not found

1.1.1 Compiling (gcc)

There is a lot gcc may be unable to find. If there is something to include, it 
may be the file that should be included, that is missing. The questions here 
are: 1. what's missing? and 2. what to do against?

1.1.1.1 Missing header file

If only a header file is missing, you will experience an error message like:

foo.c:3:31: /usr/include/bar.h: No such file or directory

If there's a file missing, you may want to search your system for it:

find / -name <filename> or
locate <filename> (run updatedb, if locate demands it)

If you don't find the file, the next question would be: where should this file
come from? Is there a prerequisite you forgot? Are all tools available in the 
required versions?

If the file is anywhere else than in the common include path (/usr/include,
/usr/local/include), you may add -I<uncommon include path> to the CFLAGS,
e.g. "export CFLAGS=-I/usr/X11R6/include". If the #include statement
contains a subdirectory, while the file to be included is in the common
directory, you'll have to edit the #include statement.

In most cases the file will be in another directory than the developer thinks 
it is. The easiest way around that would be a symlink, but that is not a clean
way. So we search the sources for occurrences of the "missing" file first:

grep -R "<missing file's path and name>" *.*

Now edit every file that uses the wrong path in it's #include statements. The
lazy user can utilize sed:

for i in *.*; do 
 mv $i $i.bak
 sed s|'<"missing" file>'|'<found file'>|g $i.bak > $i
done

This should solve the problem; you can continue building the package.

1.1.1.2 Missing declaration

Another fine errormessage goes about a missing declaration:

foo:124:4: bla undefined

if "bla" is a function from generic libraries (like glibc), it will probably be
documented with a manpage which holds informations about which header file(s)
it needs to be included:

man bla

Look at /usr/share/man/man3 for documented function calls: The manpage will
look something like that:

--snip
FUNC(3)				Linux Programmer's Manual		FUNC(3)

NAME
	func, ffunc, vfunc - Example function without any use

SYNOPSIS
	#include <stdfunc.h>
	int func(char *format, ...);
	int ffunc(FILE *stream, const char *format, ...);

	#include <vstdfunc.h>
	int vfunc(const char *format, va list ap);

DESCRIPTION
...
--snap

In most of the cases the header file is not included where it's neccessary, so
you just write it into the file where it is missing: "#include <stdfunc.h>".

If the definition is nowhere any standard library, you will have to search the
codebase of the program you are about to compile for the function it's missing:

grep "<function name>" *.* | less

Now search for something like "#define bla ( const char * ...". If you don't
find anything, the function is likely to be included in other sources, so you
better check the requirements of the package you are about to compile, in case
something is missing.

If the file where the definition is included is a header file (*.h), simply
include it, otherwise copy and paste the definition into the file gcc is
complaining about.

1.1.2 Linking (ld)

Linking mostly fails because of missing libraries. Make sure your
/etc/ld.so.conf contains all directories with libraries in it. In case, another
directory is needed, use LDFLAGS: "export LDFLAGS=-L/usr/X11R6/lib" to include
XFree86's libraries for sure.

Another (rather seldom) error can occur if libs are not linked right. I only
saw it happen once when some program linked to libpng, but forgot about libz,
which is used by libpng, but needs to be linked to, too. So in the Makefile,
where I found "LIBS=-lpng", I completed it to "LIBS=-lpng -lz". Mostly the
function that is missing is given; you can try to grep it in the library
(binary matches).

1.2 Segmentation Fault

This is most annoying. It means an application had an error that is so bad it
rather drops core and stop immediately.

1.2.1 Segfault during compilation

Segmentation faults during compilation are very seldom. You only get SIG11 if
the memory is full while building a package and will happen only on systems
with few memory. You can add a loop device to swap to expand your memory; this
will make compilation much slower, but at least it will work on such devices
that contains too few memory:

dd if=/dev/zero of=/tmp/swapspace bs=1M count=128
losetup /dev/loop0 /tmp/swapspace
mkswap /dev/loop0
swapon /dev/loop0

will set up 128MB of swap space (or virtual memory). If it still fails,
increase the amount of disk space used (count=256; count=512; count=XXX).

1.2.2 Segfault during execution

If a program segfaults, there isn't much you can easily do to hunt the error
down if you don't have some programming skills. Contact the developer and give
him a detailed view of your system; maybe in /var/log is something about the
error?

1.3 Hangup

Hangups are the most annoying errors there are. Fortunately, they are as seldom
as annoying with Linux (unless you use bleeding edge sources only). Hangups are
mostly caused by endless loops, driver problems that leads to bus lockups, and
hardware issues (like defect capacitors in the CPU power supply, check for 
bursted ones). Infinite loops are easily spotted by the warnings of most 
compilers, the latter is harder to find. Try to downgrade the driver you think 
is responsible for the hangup and send a report to the relative mailing list.

1.3.1 Full Hangup

You recognize a full hangup by pressing the [CAPS LOCK] key. If the led is
flashing, the keyboard is still hooked to the console, so that's no full
hangup. Try pressing different keys then. If nothing else works, use a hard 
reboot (that is always the last means of getting back to work). If the
keyboard is still available, but the screen is blank, try to reboot with
[ALT][CTRL][DEL]. If even that doesn't work, you may be lucky to have the sysrq
key feature compiled into your kernel. For further informations, read
[/usr/src/linux/Documentation/sysrq.txt].

1.3.2 Program-only Hangup

If the program hangs up leaving the rest of the system intact, you can use the
appropriate of the kill/killall/xkill commands to get rid of it.

1.4 Other errors

If you get an errormessage not covered by this hint, check the relative 
mailinglists, enter the error message into google and look 1. if there is a 
newer version or 2. if a cvs version, if available, has the same error. If 
nothing else helps, ask in IRC or mail to the developers mailinglist or submit
a bug report. Remember to describe the error precisely and give enough 
informations about the system you are trying to build the package on.

May the source be with you!

CHANGELOG:
  [2002-01-04]
    * Started to write this hint.

  [2003-10-07]
    * Initial Version, small additions.

  [2003-10-08]
    * Almost forgot to give Tushar some credits, little changes and additions.

CREDITS:
Thanks to teemu for reminding me on "-I" and "-l" as much as Tushar for the 
warning about warnings and ringing the bell of the "-w" option :-)


More information about the hints mailing list