J.3 Linking

1. Why do I get undefined symbols when linking with the mpatrol library?

   This is most likely caused by the mpatrol library requiring additional symbols defined in an object file access library. If mpatrol was built with FORMAT=FORMAT_COFF or FORMAT=FORMAT_XCOFF then you'll need to add -lld (or equivalent) to the compiler command line straight after -lmpatrol. If mpatrol was built with FORMAT=FORMAT_ELF32 or FORMAT=FORMAT_ELF64 then you'll need to add -lelf (or equivalent) to the compiler command line straight after -lmpatrol. If mpatrol was built with FORMAT=FORMAT_BFD then you'll need to add -lbfd -liberty -lintl (or equivalent) instead. If you are using the thread-safe version of mpatrol then you may also need to link with the system threads library.

2. Why do I still get undefined symbols on HP/UX, IRIX, Tru64 or Windows platforms, despite following the above instructions?

   If the symbol is called U_get_previous_frame on HP/UX then you still need to link with the system stack traceback library, libcl.sl. If the symbols are called exc_setjmp and unwind on IRIX or Tru64 and you defined the MP_LIBRARYSTACK_SUPPORT preprocessor macro when building the mpatrol library then you still need to link with the system exception library, libexc.so. If the symbols all begin with Sym on Windows platforms then you still need to link with the system symbol access library, imagehlp.lib.

3. I tried all of the above, but why is the SymGetLineFromAddr symbol still undefined on Windows platforms?

   This is due to the imagehlp.lib or imagehlp.dll libraries on your system being out of date. The SymGetLineFromAddr() function was added to this library at a much later date from the original release so if you want the USEDEBUG option to work you should try to get an updated library from Microsoft. Alternatively, you can disable the call to it in __mp_findsource() but the USEDEBUG option will no longer work.

4. Why is the mpatrol library unable to read any symbols from DLLs despite the fact that my program uses them?

   Windows executable files and DLLs only contain a list of symbol names which are imported and exported but do not contain details of such symbols at the same level as object files. To do this requires the symbolic information to be retained by the linker, but this has not been done for the system DLLs. The mpatrol library uses the imagehlp system library to read symbols from DLLs but this will only work if the required system debugging symbols are installed on your machine. In Visual C++, this can be done by selecting the `Windows NT Symbols Setup' start menu item.

5. Why do I get duplicate definitions of symbols when linking with the mpatrol library?

   This is most likely caused by your code, or a library, providing definitions of malloc() and free() which conflict with those defined in the mpatrol library. You'll need to disable these in order to perform a successful link and use the replacements in mpatrol instead.

6. Why do I get xmalloc() as a multiply-defined symbol when I link with the archive version of the mpatrol library?

   If the mpatrol library was built with FORMAT=FORMAT_BFD then it is because the libiberty library contains definitions of the xmalloc() family of functions as well. You should rebuild the mpatrol library without the definitions of the relevant xmalloc() functions in malloc.c. You're also likely to get this error if you link with the archive version of the mpatrol library and one or more of the xmalloc() family of functions is defined in another archive library that you are linking with.

7. I linked my program to a shared library version of mpatrol. Now, when I try to run my program, the system complains that it cannot find the mpatrol library. How do I get this to work?

   You need to tell the system where to find the shared library version of the mpatrol library, either by setting your LD_LIBRARY_PATH environment variable (or just PATH on Windows platforms), or by embedding the full path to the library into the executable when you link your program by setting the LD_RUN_PATH environment variable.

8. I linked my program to a shared library version of mpatrol. Will future releases of mpatrol remain compatible with this version or will I have to relink my program?

   Backwards compatibility is not generally guaranteed, but should be preserved if only the bug fix part of the mpatrol version number has changed, with the major and minor versions staying the same. For example, versions 1.0.3 and 1.0.8 should be compatible, but upgrading to version 1.1.0 may require a relink.

9. I have linked my program with the DLL version of the mpatrol library on Windows but it crashes when I run it. I suspect that the crash is occurring when the mpatrol library is being initialised, so what is going wrong?

   There appears to be a problem when using the mpatrol DLL and the static version of the Microsoft C run-time library, and also a problem when using the static version of mpatrol and the Microsoft C run-time library DLL. Luckily, if you ensure that you use either both static libraries or both DLLs at the same time then the problem should go away. There doesn't seem to be an easier way around it at this time or, for that matter, an explanation for why it happens.

10. Why are mpatrol library functions not called from shared libraries on AIX?

    AIX uses static shared libraries instead of dynamic shared libraries, which means that all shared library bindings are resolved at link time rather than load time (i.e. you must specify which shared libraries resolve all of the undefined symbols that result when building a shared library). If you would like mpatrol library functions to be called from a shared library, you must rebuild the shared library with -lmpatrol on the link line. However, this means that you cannot override malloc(), etc., in shared libraries that you cannot rebuild unless you link statically with the archive library versions instead.