C.3.1. Common Linker Error Messages

C.3.1. Common Linker Error Messages
	C.3. Understanding the Linker

[ fromfile: linker.xml id: commonlinkererrors ]

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.

`Error: Unable to find libxxx.so.x`

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.

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:
1. The directories specified in LD_LIBRARY_PATH
2. Installed libraries referenced from a cache file called /etc/ld.so.cache

`Error: undefined reference to identifier`

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.
The useful bits of information in the error message are:
- The symbol it can't find is DataObject::s_Cm.
- The function that tried to use it is DataObject::getConstraintGroup.
The first step is to see if you can find the missing definition.
If you find it in a .cpp file, you must make sure that
- Both the .cpp and the .h file are mentioned in the project.
- The file is included in a library with which you are linking.
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
- The .cpp file that contains the definition is not listed in qmake's SOURCES in the project file.
- The code is located in another library but the linker can't find the library. This can be solved by adding a missing LIBS argument in the project file.
  - -lmyLib adds a library to be linked.
  - -LmyLibDir adds a directory to the linker's lib search path list.

Error: Unresolved External Symbol

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.

Error: Undefined reference to vtable for ClassName

It generally means that a virtual function definition is missing.

Double check HEADERS and SOURCES in .pro 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.

^[92]A class with at least one virtual method is polymorphic.