[ fromfile: linker.xml id: commonlinkererrors ]

C++ programmers sometimes spend lots of time trying to understand and repair compiler and linker errors. If you can't understand the message, you're stuck. With a compiler error, the problem is easier to diagnose because it is related to the compilation of one source code module and the header files it includes. The compiler generally tells you the exact location of any error that it detects. With a linker error, the problem is related to how your source code modules link together. When the linker stage is reached, all the individual modules have compiled without errors. Linker errors can be caused by bugs in C++ code, but they can also be a result of mistakes in the project file.

Installing a library means making it available for more than a single user on a system. It is also possible to reuse a library without installing it. All libraries that you reuse must either be installed or placed in a directory listed in your LD_LIBRARY_PATH.

When you reuse a library for the first time, you will probably see this error message. It means that the linker can not find the library. When the gnu linker looks for a shared object, it checks at least two places:

/lib
/usr/lib
/usr/X11R6/lib
/usr/i486-linuxlibc1/lib
/usr/local/lib
/usr/lib/mozilla

This is the most common and, probably, the most annoying linker error of all. It means that the linker cannot find the definition of some named entity in your code. Following is some output from make:

.obj/ca_address.o(.gnu.linkonce.t._ZN10DataObject16getConstraintGroupEv+0x4):
In function `DataObject::getConstraintGroup()':
/usr/local/qt-x11-free-3.2.3/include/qshared.h:50:
undefined reference to `DataObject::s_Cm'
collect2: ld returned 1 exit status
make: *** [hw7] Error 1

The compiler found the declaration, but the linker can't find the corresponding definition. In some part of your code, you have a reference a symbol, but no definition can be found. The useful bits of information in the error message are:

The first step is to see if you can find the missing definition. If you can't find it, how can the linker? If you find it in a .cpp file, you must make sure that

Because you use good naming conventions (Section 3.1) you can immediately tell that s_Cm is a static data member of class DataObject. The compiler found the declaration, but the linker can't find the definition.

Because it is static (Section 2.9), the definition for s_Cm belongs in dataobject.cpp. The compiler expects to find a definition statement of the form:

ConstraintGroup DataObject::s_Cm;

If it's there, and the linker still can't find it, the most likely causes for this error are

When linking against your own library, from a Microsoft compiler, you might find a linker error like this:

customer.obj : error LNK2001: unresolved external symbol
"public: virtual bool __thiscall DataObject::readFrom(class QObject const &)"
(?readFrom@DataObject@@UAE_NABVQObject@@@Z)

This often means that the symbol was not exported when the DLL was built. Be sure that there is a Q_DECL_EXPORT macro for the library before the class or function declaration, and rebuild the DLL. See Section 7.1.2.

This is one of the most confusing errors. It generally means that a virtual function definition is missing. Literally, the vtable for that class (which has addresses of each the virtual functions) cannot be fully constructed.

This error can arise from missing function definitions in your code, but it can also be caused by a missing HEADERS or SOURCES entry in your make/project file. If you recently added a Q_OBJECT macro to one of your existing headers, then re-run qmake, because the Makefile needs to be rebuilt! See Section 8.4 for more details on this.

	Tip
	After this kind of linker error, check first that all files are listed properly in the project file, all QObjects have a proper Q_OBJECT macro, do a "qmake && make clean", and see if you can reproduce the error.