10.3 Linking an Executable

Continuing the parallel between the syntax used to compile with libtool and the syntax used when building old static libraries, linking an executable is a matter of combining compilation units into a binary in both cases. We tell the compiler which objects and libraries are required, and it creates an executable for us.

If you want to try this to see what libtool does on your machine, put the following code in a file `main.c', in the same directory as `hello.c' and `libhello.la', and run the example shell commands from there:

void hello (); int main (int argc, char *argv[]) { hello ("World"); return 0; }

To compile an executable which uses the non-Libtool `libhello.a' library built previously (see section 10.2 The Libtool Library), I would use the following commands:

$ gcc -o hello main.c libhello.a $ ./hello Hello, World!

To create a similar executable on the HP-UX host, using libtool this time:

$ libtool gcc -o hello main.c libhello.la libtool: link: warning: this platform does not like uninstalled libtool: link: warning: shared libraries. libtool: link: hello will be relinked during installation gcc -o .libs/hello main.c /tmp/hello/.libs/libhello.sl \ -Wl,+b -Wl,/tmp/hello/.libs:/usr/local/lib creating hello $ ls hello hello.lo libhello.la hello.c hello.o main.c $ ./hello Hello, World!

Notice that you linked against the Libtool library, `libhello.la', but otherwise the link command you used was not really very different from non-Libtool static library link command used earlier. Still, libtool does several things for you: it links with the shared archive rather than the static archive; and it sets the compiler options so that the program can be run in place, even though it is linked against the uninstalled Libtool library. Using a make rule without the benefit of libtool, it would be almost impossible to reliably link a program against an uninstalled shared library in this way, since the particular switches needed would be different between the various platforms you want the project to work with. Also without the extra compiler options libtool adds for you, the program will search only the standard library directories for a shared `libhello'.

The link warning tells you that libtool knows that on HP-UX the program will stop working if it is copied directly to the installation directory; To prevent it breaking, libtool will relink the program when it is installed, see 10.6 Installing a Library.

I discussed the creation of static Libtool libraries in Creating Static Libraries. If you link an executable against such a library, the library objects, by definition, can only be statically linked into your executable. Often this is what you want if the library is not intended for installation, or if you have temporarily disabled building of shared libraries in your development tree to speed up compilation while you are debugging.

Sometimes, this isn't what you want. You might need to install a complete Libtool library with shared and static components, but need to generate a static executable linked against the same library, like this:

$ libtool gcc -static -o hello main.c libhello.la gcc -o hello main.c ./.libs/libhello.a

In this case, the `-static' switch instructs libtool to choose the static component of any uninstalled Libtool library.

You could have specified `-all-static' instead, which instructs libtool to link the executable with only static libraries (wherever possible), for any Libtool or native libraries used.

Finally, you can also link executables against convenience libraries. This makes sense when the convenience library is being used as an alias (see section Creating Convenience Libraries). Notice how `libgraphics.la' expands to its own dependencies in the link command:

$ libtool gcc -o image loader.o libgraphics.la libtool: link: warning: this platform does not like uninstalled libtool: link: warning: shared libraries libtool: link: image will be relinked during installation gcc -o .libs/image loader.o -lpng -ltiff -ljpeg -lz \ -Wl,+b -Wl,/tmp/image/.libs:/usr/local/lib creating image

You can also link against convenience libraries being used as partially linked objects, so long as you are careful that each is linked only once. Remember that a partially linked object is just the same as any other object, and that if you load it twice (even from different libraries), you will get multiple definition errors when you try to link your executable. This is almost the same as using the `-static' switch on the libtool link line to link an executable with the static component of a normal Libtool library, except that the convenience library comprises PIC objects. When statically linking an executable, PIC objects are best avoided however, see 10.2.1 Position Independent Code.