Autoconf, Automake, and Libtool: Linking an Executable

> | ## 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.

This document was generated by Gary V. Vaughan on February, 8 2006 using texi2html