COMPILING

LINKING

A common link-time error is forgetting to link library code into your program that uses it. If the compiler fails at link time with a list of undefined symbols in your program, it is due to your not linking in one or more .o files or library .a or .so files into your program (if you get an undefined reference error when a file is being compiled from .C to .o, then this means you forgot to include a header file). For example, if you are calling the sqrt function from the math library, you need to include the math.h header file in your .C file and you need to explicitly link the math library into your executable:

	g++ -g -Wall -o myprog myprog.o -lm
					^^^

# add the path to my library code; -L tells the linker where to find it
LFLAGS += -L /home/newhall/mylibs

# list of libraries to link into executable; -l tells the linker which 
# library to link into the executable 
LIBS = -lmymath -lsimple -lm
OBJS = myprog.o

# path to any header files not in /usr/include or the current directory 
INCLUDES += -I/home/newhall/include -I../include

default: myprog

myprog:
        $(CC) $(CFLAGS) $(LFLAGS) -o myprog $(OBJS) $(LIBS)

${OBJS}: %.o :  %.c
        ${CC} -c ${CFLAGS} ${LFLAGS} ${INCLUDES} ${@:.o=.c}

Because C++ compilers mangle names, often times one cannot easily decipher linker errors. For example, by looking at the following output from the linker:

	Undefined                       first referenced
 	symbol                             in file
	foo__FifP12BufHashTable             buf.o
	ld: fatal: Symbol referencing errors. No output written to buftest
	make: *** [buftest] Error 1

	% c++filt foo__FifP12BufHashTable
	foo(int, float, BufHashTable *)		# the symbol's demangled form

To list symbols in .so .a .o or an executable files, you can use nm or objdump -t to list the contents of the symbol table. The output will include all symbols (e.g. functions, global variables), and will list information about them including if they are defined or not (defined in a .o means the code for this function or the declaration of this global variable is in this file, undefined means it is in some other .o, .a, or .so file).

Executable files that are built using static linking contain all the library code needed to run. Executable files that are built using dynamic linking do not contain library code from .so files. Instead, library code from .so files is dynamically loaded into the address space of the process at runtime. To list the shared object dependencies of an executable file (or of a .so file) use ldd. ldd will list the name of each shared object file and the full path to its location. If a program fails at runtime with a linking error, it is due to the runtime linker not being able to find one or more of the .so files needed to run the executable.

	% ldd a.out 
	linux-gate.so.1 =>  (0xffffe000) 
	libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0xb7e53000) 
	libm.so.6 => /lib/tls/libm.so.6 (0xb7e1c000) 
	libgcc_s.so.1 => /lib/libgcc_s.so.1 (0xb7e11000) 
	libc.so.6 => /lib/tls/libc.so.6 (0xb7cdf000) 
	/lib/ld-linux.so.2 (0xb7f3b000)

If you get runtime errors like the following:

$ ./a.out
a.out: error while loading shared libraries: libmylib.so: cannot open shared object file: No such file or directory

  # if running bash:
  export LD_LIBRARY_PATH=/home/newhall/lib:$LD_LIBRARY_PATH

  # if running tcsh:
  setenv LD_LIBRARY_PATH /home/newhall/lib:$LD_LIBRARY_PATH

DEBUGGING: gdb, ddd, valgrind

gdb and ddd