gcc linker

Why does the order in which libraries are linked sometimes cause errors in GCC?


Why does the order in which libraries are linked sometimes cause errors in GCC?



The GNU ld linker is a so-called smart linker. It will keep track of the functions used by preceding static libraries, permanently tossing out those functions that are not used from its lookup tables. The result is that if you link a static library too early, then the functions in that library are no longer available to static libraries later on the link line.

The typical UNIX linker works from left to right, so put all your dependent libraries on the left, and the ones that satisfy those dependencies on the right of the link line. You may find that some libraries depend on others while at the same time other libraries depend on them. This is where it gets complicated. When it comes to circular references, fix your code!


  • 3

    Is this something with only gnu ld/gcc? Or is this something common with linkers?

    – Mike

    Sep 5, 2008 at 3:17

  • 2

    Apparently more Unix compilers have similar issues. MSVC isn’t entirely free of these issues, eiher, but they don’t appear to be that bad.

    – MSalters

    Apr 28, 2009 at 14:42

  • 6

    The MS dev tools don’t tend to show these issues as much because if you use an all-MS tool chain it ends up setting up the linker order properly, and you never notice the issue.

    Aug 28, 2009 at 20:59

  • 21

    The MSVC linker is less sensitive to this issue because it will search all libraries for an unreferenced symbol. Library order still can affect which symbol gets resolved if more than one library have the symbol. From MSDN: “Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and /DEFAULTLIB (Specify Default Library) directives, and then to any libraries at the beginning of the command line”

    Apr 24, 2012 at 6:19

  • 14

    “… smart linker …” – I believe it is classified as a “single pass” linker, not a “smart linker”.

    – jww

    Aug 28, 2018 at 3:34


Here’s an example to make it clear how things work with GCC when static libraries are involved. So let’s assume we have the following scenario:

  • myprog.o – containing main() function, dependent on libmysqlclient
  • libmysqlclient – static, for the sake of the example (you’d prefer the shared library, of course, as the libmysqlclient is huge); in /usr/local/lib; and dependent on stuff from libz
  • libz (dynamic)

How do we link this? (Note: examples from compiling on Cygwin using gcc 4.3.4)

gcc -L/usr/local/lib -lmysqlclient myprog.o
# undefined reference to `_mysql_init'
# myprog depends on libmysqlclient
# so myprog has to come earlier on the command line

gcc myprog.o -L/usr/local/lib -lmysqlclient
# undefined reference to `_uncompress'
# we have to link with libz, too

gcc myprog.o -lz -L/usr/local/lib -lmysqlclient
# undefined reference to `_uncompress'
# libz is needed by libmysqlclient
# so it has to appear *after* it on the command line

gcc myprog.o -L/usr/local/lib -lmysqlclient -lz
# this works