Best practices for debugging linking errors

Question

When building projects in C++, I've found debugging linking errors to be tricky, especially when picking up other people's code. What strategies do people use for debugging and fixing linking errors?

Stoneblind

Answer 1

Not sure what your level of expertise is, but here are the basics.

Below is a linker error from VS 2005 - yes, it's a giant mess if you're not familiar with it.

ByteComparator.obj : error LNK2019: unresolved external symbol "int __cdecl does_not_exist(void)" (?does_not_exist@@YAHXZ) referenced in function "void __cdecl TextScan(struct FileTextStats &,char const *,char const *,bool,bool,__int64)" (?TextScan@@YAXAAUFileTextStats@@PBD1_N2_J@Z)

There are a couple of points to focus on:

• "ByteComparator.obj" - Look for a ByteComparator.cpp file, this is the source of the linker problem
• "int __cdecl does_not_exist(void)" - This is the symbol it couldn't find, in this case a function named does_not_exist()

At this point, in many cases the fastest way to resolution is to search the code base for this function and find where the implementation is. Once you know where the function is implemented you just have to make sure the two places get linked together.

If you're using VS2005, you would use the "Project Dependencies..." right-click menu. If you're using gcc, you would look in your makefiles for the executable generation step (gcc called with a bunch of .o files) and add the missing .o file.

---

In a second scenario, you may be missing an "external" dependency, which you don't have code for. The Win32 libraries are often times implemented in static libraries that you have to link to. In this case, go to MSDN or "Microsoft Google" and search for the API. At the bottom of the API description the library name is given. Add this to your project properties "Configuration Properties->Linker->Input->Additional Dependencies" list. For example, the function timeGetTime()'s page on MSDN tells you to use Winmm.lib at the bottom of the page.

Campanile

Well, and if I find the place where the method is implemented and I see nothing wrong with it, what do I do next? Is there a way to get a list of files being linked? Your answer is sure good for beginners, but this is top 1 result for linker debugging and there are other possible causes than typo in function name. – Burck

Answer 2

One of the common linking errors I've run into is when a function is used differently from how it's defined. If you see such an error you should make sure that every function you use is properly declared in some .h file.
You should also make sure that all the relevant source files are compiled into the same lib file. An error I've run into is when I have two sets of files compiled into two separate libraries, and I cross-call between libraries.

Is there a failure you have in mind?

Cusk

Answer 3

The C-runtime libraries are often the biggest culprit. Making sure all your projects have the same settings wrt single vs multi-threading and static vs dll.

The MSDN documentation is good for pointing out which lib a particular Win32 API call requires if it comes up as missing.

Other than that it usually comes down to turning on the verbose flag and wading through the output looking for clues.

Marylnmarylou

Answer 4

If:

• your IDE isn't complaining about missing symbols
• you're sure you've got the headers you need
• your functions/methods are spelled consistently
• you're using the correct types for the parameters

...you might want to confirm that the required intermediate (.obj) file is available.

I'd been using a crude shell script to generate my builds, and after being stumped by this linker error, I realized I was missing a translation unit in my compilation! Including the missing source file in my compilation made all the difference.

My case was embarrassingly silly, but there are other ways this can happen. Maybe someone forgot to check in a file (classic "it works on my machine"), maybe it somehow got deleted but your build system is expecting it to already be there, etc.

Timpani