Scatter/Gather thoughts

by Johan Petersson

Linking libstdc++ statically

Christopher Baus writes about his problems linking libstdc++ statically. Yes, making C++ binaries that will work properly in different Linux distributions is somewhat painful. The problem is not so much linking libstdc++ statically – it is just a library, after all – but the runtime support required by C++ code in general, to enable features like RTTI and exception handling.

The runtime support code used by different parts of a C++ application needs to be compatible. If one part of the program needs to dynamic_cast or catch objects provided by another, both parts must agree on certain implementation details: how to find vtables, how to unwind the stack, and so on.

For C++ and a few other GCC-supported languages with similar features, such details are specified by a C++ ABI. Whenever the ABI used by GCC changes you'll end up with incompatible libraries produced by the different GCC versions. The same is true for plain C, but the C ABI is much simpler and has been around a lot longer so it's fairly stable.

As far as I know C++ ABI changes have been introduced with every major release of GCC (i.e. those with different first or second version number components). To make matters worse, most major Linux distributions use GCC snapshots and/or patch their GCC versions, making it virtually impossible to know exactly what GCC versions you might be dealing with when you distribute binaries.

Note that this problem cannot, in general, be solved by linking statically. First of all, code compiled against different ABIs is simply not binary compatible. It doesn't matter if you manage to link binary incompatible code together, because it will never work properly. Secondly, the language runtime support typically rely on some data being shared, e.g. to access some kind of lock or global data structure (similar to how C programs need a shared errno).

Shared data implies that whenever more than one part of a program needs the runtime support, and any of those parts is dynamically loaded, the runtime support needs to be loaded dynamically too. Otherwise, the different program parts would end up with copies of the data rather than one shared instance. That's the reason for putting the language runtime support code in a dynamic library by default.

There are many different workarounds and no perfect solution, but a fairly workable compromise is to link all C++ code into an executable while using dynamically loaded C libraries only. This way there is only one part of the program that needs the C++ runtime support mechanisms, which can therefore be linked in statically. You can mix and match statically and dynamically linked C libraries, but no C++ code (or any code using the C++ runtime support) may be linked dynamically if this is to work.

Now, the practical problem people run into when trying to link libstdc++ statically is that g++, the GCC front-end for compiling and linking C++, adds the proper libraries and start-up code for C++ automatically and will link some of this code dynamically by default:

g++ -o example example.cpp

ldd example =>  (0xffffe000) => /usr/lib/gcc/i686-pc-linux-gnu/3.4.3/ (0xb7f17000) => /lib/ (0xb7ef3000) => /usr/lib/gcc/i686-pc-linux-gnu/3.4.3/ (0xb7eea000) => /lib/ (0xb7dd0000)
    /lib/ (0xb7feb000)

The resulting binary links to a shared version of libstdc++, the standard C++ library, and a shared version of libgcc, a GCC runtime support library required for exception handling among other things. This binary won't work on a machine with different versions of those libraries, but since it doesn't need any other dynamically loaded C++ libraries, the incompatibility can be removed by linking libstdc++ and libgcc statically.

Consulting the GCC man page, you'll find the GCC option -static-libgcc mentioned. It makes the compiler link libgcc statically rather than dynamically. Except when it doesn't:

g++ -static-libgcc -o example example.cpp

ldd example =>  (0xffffe000) => /usr/lib/gcc/i686-pc-linux-gnu/3.4.3/ (0xb7f17000) => /lib/ (0xb7ef3000) => /usr/lib/gcc/i686-pc-linux-gnu/3.4.3/ (0xb7eea000) => /lib/ (0xb7dd0000)
    /lib/ (0xb7feb000)

What happened here? Remember what I said earlier about not loading any C++ code dynamically? Since we are still linking dynamically to libstdc++, the runtime support code in libgcc must also be linked dynamically. g++ ignored the -static-libgcc flag because linking libgcc statically would not result in a program that works properly. We need to link statically to both libraries, or neither.

You can ask g++ to tell you exactly what steps are involved in linking a C++ program (try the -v flag if you are curious) and invoke a slightly different set of commands in order to link your application with static versions of libstdc++ and libgcc. But integrating that into your own build process is painful, error-prone, and specific to the machine and compiler version you use.

There's no -static-libstdc++ option to go along with -static-libgcc, but you can let the compiler tell you the path to the static libstdc++ library it would use, and let g++ look for libraries in a directory where it will only find the static version (in this case our build directory):

ln -s `g++ -print-file-name=libstdc++.a`

g++ -static-libgcc -L. -o example example.cpp

ldd example =>  (0xffffe000) => /lib/ (0xb7ef3000) => /lib/ (0xb7dd0000)
    /lib/ (0xb7feb000)

Once again, for this to work reliably you must not use dynamically loaded C++ code, including code loaded with dlopen. In particular, statically linking the runtime support code is contraindicated when creating dynamically loadable C++ libraries. Depending on your linker it might be possible, but planning to distribute such binaries is still very much an order for a super-sized can of worms.

Update: As of GCC 4.5 there is now a -static-libstdc++ compiler option which does what you'd expect it to do. (Thanks to Tim Hutt for pointing this out.)

1 June, 2005