Whole document tree

Libtool

This file documents GNU Libtool, a script that allows package developers to provide generic shared library support. This edition documents version 1.4.2a.

See section 12.2 Reporting bugs, for information on how to report problems with libtool.

1. Introduction		What the heck is libtool?
2. The libtool paradigm		How libtool's view of libraries is different.
3. Using libtool		Example of using libtool to build libraries.
4. Invoking libtool		Running the libtool script.
5. Integrating libtool with your package		Using libtool in your own packages.
6. Library interface versions		Using library interface versions.
7. Tips for interface design		Tips for library interface design.
8. Inter-library dependencies		Libraries that depend on other libraries.
9. Dlopened modules		dlopening libtool-created libraries.
10. Using libltdl		Libtool's portable dlopen wrapper library.
11. Using libtool with other languages		Using libtool without a C compiler.
12. Troubleshooting		When libtool doesn't work as advertised.
13. Maintenance notes for libtool		Information used by the libtool maintainer.
GNU Free Documentation License		License for this manual.
Index		Full index.

Introduction

1.1 Motivation for writing libtool		Why does GNU need a libtool?
1.2 Implementation issues		The problems that need to be addressed.
1.3 Other implementations		How other people have solved these issues.
1.4 A postmortem analysis of other implementations		Learning from past difficulties.

Using libtool

3.1 Creating object files		Compiling object files for libraries.
3.2 Linking libraries		Creating libraries from object files.
3.3 Linking executables		Linking object files against libtool libraries.
3.4 Debugging executables		Running GDB on libtool-generated programs.
3.5 Installing libraries		Making libraries available to users.
3.6 Installing executables		Making programs available to users.
3.7 Linking static libraries		When shared libraries are not wanted.

Invoking libtool

4.1 Compile mode		Creating library object files.
4.2 Link mode		Generating executables and libraries.
4.3 Execute mode		Debugging libtool-generated programs.
4.4 Install mode		Making libraries and executables public.
4.5 Finish mode		Completing a library installation.
4.6 Uninstall mode		Removing installed executables and libraries.
4.7 Clean mode		Removing uninstalled executables and libraries.

Integrating libtool with your package

5.1 Writing `Makefile' rules for libtool
5.2 Using Automake with libtool		Automatically supporting libtool.
5.3 Configuring libtool		Configuring libtool for a host system.
5.4 Including libtool in your package		What files to distribute with your package.
5.5 Static-only libraries		Sometimes shared libraries are just a pain.

Configuring libtool

5.3.1 The AC_PROG_LIBTOOL macro

Configuring libtool in `configure.in'.

Including libtool in your package

5.4.1 Invoking libtoolize		libtoolize command line options.
5.4.2 Autoconf `.o' macros		Autoconf macros that set object file names.

Library interface versions

6.1 What are library interfaces?
6.2 Libtool's versioning system
6.3 Updating library version information		Changing version information before releases.
6.4 Managing release information		Breaking binary compatibility for aesthetics.

Tips for interface design

7.1 Writing C header files

How to write portable include files.

Dlopened modules

9.1 Building modules to dlopen		Creating dlopenable objects and libraries.
9.2 Dlpreopening		Dlopening that works on static platforms.
9.3 Finding the correct name to dlopen		Choosing the right file to dlopen.
9.4 Unresolved dlopen issues		Unresolved problems that need your attention.

Using libltdl

10.1 How to use libltdl in your programs
10.2 Creating modules that can be dlopened
10.3 Using libtldl in a multi threaded environment		Registering callbacks for multi-thread safety.
10.4 Data associated with loaded modules		Associating data with loaded modules.
10.5 How to create and register new module loaders		Creating user defined module loaders.
10.6 How to distribute libltdl with your package

Using libtool with other languages

11.1 Writing libraries for C++

Troubleshooting

12.1 The libtool test suite		Libtool's self-tests.
12.2 Reporting bugs		How to report problems with libtool.

The libtool test suite

12.1.1 Description of test suite		The contents of the test suite.
12.1.2 When tests fail		What to do when a test fails.

Maintenance notes for libtool

13.1 Porting libtool to new systems		How to port libtool to new systems.
13.2 Tested platforms		When libtool was last tested.
13.3 Platform quirks		Information about different library systems.
13.4 libtool script contents		Configuration information that libtool uses.
13.5 Cheap tricks		Making libtool maintainership easier.

Porting libtool to new systems

13.1.1 Information sources		Where to find relevant documentation
13.1.2 Porting inter-library dependencies support		Implementation details explained

Platform quirks

13.3.1 References		Finding more information.
13.3.2 Compilers		Creating object files from source files.
13.3.3 Reloadable objects		Binding object files together.
13.3.4 Multiple dependencies		Removing duplicate dependant libraries.
13.3.5 Archivers		Programs that create static archives.

1. Introduction

In the past, if a source code package developer wanted to take advantage of the power of shared libraries, he needed to write custom support code for each platform on which his package ran. He also had to design a configuration interface so that the package installer could choose what sort of libraries were built.

GNU Libtool simplifies the developer's job by encapsulating both the platform-specific dependencies, and the user interface, in a single script. GNU Libtool is designed so that the complete functionality of each host type is available via a generic interface, but nasty quirks are hidden from the programmer.

GNU Libtool's consistent interface is reassuring... users don't need to read obscure documentation in order to have their favorite source package build shared libraries. They just run your package configure script (or equivalent), and libtool does all the dirty work.

There are several examples throughout this document. All assume the same environment: we want to build a library, `libhello', in a generic way.

`libhello' could be a shared library, a static library, or both... whatever is available on the host system, as long as libtool has been ported to it.

This chapter explains the original design philosophy of libtool. Feel free to skip to the next chapter, unless you are interested in history, or want to write code to extend libtool in a consistent way.

1.1 Motivation for writing libtool		Why does GNU need a libtool?
1.2 Implementation issues		The problems that need to be addressed.
1.3 Other implementations		How other people have solved these issues.
1.4 A postmortem analysis of other implementations		Learning from past difficulties.

1.1 Motivation for writing libtool

Since early 1995, several different GNU developers have recognized the importance of having shared library support for their packages. The primary motivation for such a change is to encourage modularity and reuse of code (both conceptually and physically) in GNU programs.

Such a demand means that the way libraries are built in GNU packages needs to be general, to allow for any library type the package installer might want. The problem is compounded by the absence of a standard procedure for creating shared libraries on different platforms.

The following sections outline the major issues facing shared library support in GNU, and how shared library support could be standardized with libtool.

The following specifications were used in developing and evaluating this system:

1. The system must be as elegant as possible.

2. The system must be fully integrated with the GNU Autoconf and Automake utilities, so that it will be easy for GNU maintainers to use. However, the system must not require these tools, so that it can be used by non-GNU packages.

3. Portability to other (non-GNU) architectures and tools is desirable.

1.2 Implementation issues

The following issues need to be addressed in any reusable shared library system, specifically libtool:

1. The package installer should be able to control what sort of libraries are built.

2. It can be tricky to run dynamically linked programs whose libraries have not yet been installed. LD_LIBRARY_PATH must be set properly (if it is supported), or programs fail to run.

3. The system must operate consistently even on hosts which don't support shared libraries.

4. The commands required to build shared libraries may differ wildly from host to host. These need to be determined at configure time in a consistent way.

5. It is not always obvious with which suffix a shared library should be installed. This makes it difficult for `Makefile' rules, since they generally assume that file names are the same from host to host.

6. The system needs a simple library version number abstraction, so that shared libraries can be upgraded in place. The programmer should be informed how to design the interfaces to the library to maximize binary compatibility.

7. The install `Makefile' target should warn the package installer to set the proper environment variables (LD_LIBRARY_PATH or equivalent), or run ldconfig.

1.3 Other implementations

Even before libtool was developed, many free software packages built and installed their own shared libraries. At first, these packages were examined to avoid reinventing existing features.

Now it is clear that none of these packages have documented the details of shared library systems that libtool requires. So, other packages have been more or less abandoned as influences.

1.4 A postmortem analysis of other implementations

In all fairness, each of the implementations that were examined do the job that they were intended to do, for a number of different host systems. However, none of these solutions seem to function well as a generalized, reusable component.

Most were too complex to use (much less modify) without understanding exactly what the implementation does, and they were generally not documented.

The main difficulty is that different vendors have different views of what libraries are, and none of the packages which were examined seemed to be confident enough to settle on a single paradigm that just works.

Ideally, libtool would be a standard that would be implemented as series of extensions and modifications to existing library systems to make them work consistently. However, it is not an easy task to convince operating system developers to mend their evil ways, and people want to build shared libraries right now, even on buggy, broken, confused operating systems.

For this reason, libtool was designed as an independent shell script. It isolates the problems and inconsistencies in library building that plague `Makefile' writers by wrapping the compiler suite on different platforms with a consistent, powerful interface.

With luck, libtool will be useful to and used by the GNU community, and that the lessons that were learned in writing it will be taken up by designers of future library systems.

2. The libtool paradigm

At first, libtool was designed to support an arbitrary number of library object types. After libtool was ported to more platforms, a new paradigm gradually developed for describing the relationship between libraries and programs.

In summary, "libraries are programs with multiple entry points, and more formally defined interfaces."

Version 0.7 of libtool was a complete redesign and rewrite of libtool to reflect this new paradigm. So far, it has proved to be successful: libtool is simpler and more useful than before.

The best way to introduce the libtool paradigm is to contrast it with the paradigm of existing library systems, with examples from each. It is a new way of thinking, so it may take a little time to absorb, but when you understand it, the world becomes simpler.

3. Using libtool

It makes little sense to talk about using libtool in your own packages until you have seen how it makes your life simpler. The examples in this chapter introduce the main features of libtool by comparing the standard library building procedure to libtool's operation on two different platforms:

`a23'

An Ultrix 4.2 platform with only static libraries.

`burger'

A NetBSD/i386 1.2 platform with shared libraries.

You can follow these examples on your own platform, using the preconfigured libtool script that was installed with libtool (see section 5.3 Configuring libtool).

Source files for the following examples are taken from the `demo' subdirectory of the libtool distribution. Assume that we are building a library, `libhello', out of the files `foo.c' and `hello.c'.

Note that the `foo.c' source file uses the cos math library function, which is usually found in the standalone math library, and not the C library (see section `Trigonometric Functions' in The GNU C Library Reference Manual). So, we need to add -lm to the end of the link line whenever we link `foo.o' or `foo.lo' into an executable or a library (see section 8. Inter-library dependencies).

The same rule applies whenever you use functions that don't appear in the standard C library... you need to add the appropriate -lname flag to the end of the link line when you link against those objects.

After we have built that library, we want to create a program by linking `main.o' against `libhello'.

3.1 Creating object files		Compiling object files for libraries.
3.2 Linking libraries		Creating libraries from object files.
3.3 Linking executables		Linking object files against libtool libraries.
3.4 Debugging executables		Running GDB on libtool-generated programs.
3.5 Installing libraries		Making libraries available to users.
3.6 Installing executables		Making programs available to users.
3.7 Linking static libraries		When shared libraries are not wanted.

3.1 Creating object files

To create an object file from a source file, the compiler is invoked with the `-c' flag (and any other desired flags):

burger$ gcc -g -O -c main.c burger$

The above compiler command produces an object file, `main.o', from the source file `main.c'.

For most library systems, creating object files that become part of a static library is as simple as creating object files that are linked to form an executable:

burger$ gcc -g -O -c foo.c burger$ gcc -g -O -c hello.c burger$

Shared libraries, however, may only be built from position-independent code (PIC). So, special flags must be passed to the compiler to tell it to generate PIC rather than the standard position-dependent code.

Since this is a library implementation detail, libtool hides the complexity of PIC compiler flags by using separate library object files (which end in `.lo' instead of `.o'). On systems without shared libraries (or without special PIC compiler flags), these library object files are identical to "standard" object files.

To create library object files for `foo.c' and `hello.c', simply invoke libtool with the standard compilation command as arguments (see section 4.1 Compile mode):

a23$ libtool gcc -g -O -c foo.c gcc -g -O -c foo.c echo timestamp > foo.lo a23$ libtool gcc -g -O -c hello.c gcc -g -O -c hello.c echo timestamp > hello.lo a23$

Note that libtool creates two files for each invocation. The `.lo' file is a library object, which may be built into a shared library, and the `.o' file is a standard object file. On `a23', the library objects are just timestamps, because only static libraries are supported.

On shared library systems, libtool automatically inserts the PIC generation flags into the compilation command, so that the library object and the standard object differ:

burger$ libtool gcc -g -O -c foo.c gcc -g -O -c -fPIC -DPIC foo.c mv -f foo.o foo.lo gcc -g -O -c foo.c >/dev/null 2>&1 burger$ libtool gcc -g -O -c hello.c gcc -g -O -c -fPIC -DPIC hello.c mv -f hello.o hello.lo gcc -g -O -c hello.c >/dev/null 2>&1 burger$

Notice that the second run of GCC has its output discarded. This is done so that compiler warnings aren't annoyingly duplicated.

3.2 Linking libraries

Without libtool, the programmer would invoke the ar command to create a static library:

burger$ ar cru libhello.a hello.o foo.o burger$

But of course, that would be too simple, so many systems require that you run the ranlib command on the resulting library (to give it better karma, or something):

burger$ ranlib libhello.a burger$

It seems more natural to use the C compiler for this task, given libtool's "libraries are programs" approach. So, on platforms without shared libraries, libtool simply acts as a wrapper for the system ar (and possibly ranlib) commands.

Again, the libtool library name differs from the standard name (it has a `.la' suffix instead of a `.a' suffix). The arguments to libtool are the same ones you would use to produce an executable named `libhello.la' with your compiler (see section 4.2 Link mode):

a23$ libtool gcc -g -O -o libhello.la foo.o hello.o libtool: cannot build libtool library `libhello.la' from non-libtool \ objects a23$

Aha! Libtool caught a common error... trying to build a library from standard objects instead of library objects. This doesn't matter for static libraries, but on shared library systems, it is of great importance.

So, let's try again, this time with the library object files. Remember also that we need to add -lm to the link command line because `foo.c' uses the cos math library function (see section 3. Using libtool).

Another complication in building shared libraries is that we need to specify the path to the directory in which they (eventually) will be installed (in this case, `/usr/local/lib')(1):

a23$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \ -rpath /usr/local/lib -lm mkdir .libs ar cru .libs/libhello.a foo.o hello.o ranlib .libs/libhello.a creating libhello.la a23$

Now, let's try the same trick on the shared library platform:

burger$ libtool gcc -g -O -o libhello.la foo.lo hello.lo \ -rpath /usr/local/lib -lm mkdir .libs ld -Bshareable -o .libs/libhello.so.0.0 foo.lo hello.lo -lm ar cru .libs/libhello.a foo.o hello.o ranlib .libs/libhello.a creating libhello.la burger$

Now that's significantly cooler... libtool just ran an obscure ld command to create a shared library, as well as the static library.

Note how libtool creates extra files in the `.libs' subdirectory, rather than the current directory. This feature is to make it easier to clean up the build directory, and to help ensure that other programs fail horribly if you accidentally forget to use libtool when you should.

3.3 Linking executables

If you choose at this point to install the library (put it in a permanent location) before linking executables against it, then you don't need to use libtool to do the linking. Simply use the appropriate `-L' and `-l' flags to specify the library's location.

Some system linkers insist on encoding the full directory name of each shared library in the resulting executable. Libtool has to work around this misfeature by special magic to ensure that only permanent directory names are put into installed executables.

The importance of this bug must not be overlooked: it won't cause programs to crash in obvious ways. It creates a security hole, and possibly even worse, if you are modifying the library source code after you have installed the package, you will change the behaviour of the installed programs!

So, if you want to link programs against the library before you install it, you must use libtool to do the linking.

Here's the old way of linking against an uninstalled library:

burger$ gcc -g -O -o hell.old main.o libhello.a -lm burger$

Libtool's way is almost the same(2) (see section 4.2 Link mode):

a23$ libtool gcc -g -O -o hell main.o libhello.la -lm gcc -g -O -o hell main.o ./.libs/libhello.a -lm a23$

That looks too simple to be true. All libtool did was transform `libhello.la' to `./.libs/libhello.a', but remember that `a23' has no shared libraries.

On `burger' the situation is different:

burger$ libtool gcc -g -O -o hell main.o libhello.la -lm gcc -g -O -o .libs/hell main.o -L./.libs -R/usr/local/lib -lhello -lm creating hell burger$

Now assume `libhello.la' had already been installed, and you want to link a new program with it. You could figure out where it lives by yourself, then run:

burger$ gcc -g -O -o test test.o -L/usr/local/lib -lhello

However, unless `/usr/local/lib' is in the standard library search path, you won't be able to run test. However, if you use libtool to link the already-installed libtool library, it will do The Right Thing (TM) for you:

burger$ libtool gcc -g -O -o test test.o /usr/local/lib/libhello.la gcc -g -O -o .libs/test test.o -Wl,--rpath -Wl,/usr/local/lib /usr/local/lib/libhello.a -lm creating test burger$

Note that libtool added the necessary run-time path flag, as well as `-lm', the library libhello.la depended upon. Nice, huh?

Since libtool created a wrapper script, you should use libtool to install it and debug it too. However, since the program does not depend on any uninstalled libtool library, it is probably usable even without the wrapper script. Libtool could probably be made smarter to avoid the creation of the wrapper script in this case, but this is left as an exercise for the reader.

Notice that the executable, hell, was actually created in the `.libs' subdirectory. Then, a wrapper script was created in the current directory.

On NetBSD 1.2, libtool encodes the installation directory of `libhello', by using the `-R/usr/local/lib' compiler flag. Then, the wrapper script guarantees that the executable finds the correct shared library (the one in `./.libs') until it is properly installed.

Let's compare the two different programs:

burger$ time ./hell.old Welcome to GNU Hell! ** This is not GNU Hello. There is no built-in mail reader. ** 0.21 real 0.02 user 0.08 sys burger$ time ./hell Welcome to GNU Hell! ** This is not GNU Hello. There is no built-in mail reader. ** 0.63 real 0.09 user 0.59 sys burger$

The wrapper script takes significantly longer to execute, but at least the results are correct, even though the shared library hasn't been installed yet.

So, what about all the space savings that shared libraries are supposed to yield?

burger$ ls -l hell.old libhello.a -rwxr-xr-x 1 gord gord 15481 Nov 14 12:11 hell.old -rw-r--r-- 1 gord gord 4274 Nov 13 18:02 libhello.a burger$ ls -l .libs/hell .libs/libhello.* -rwxr-xr-x 1 gord gord 11647 Nov 14 12:10 .libs/hell -rw-r--r-- 1 gord gord 4274 Nov 13 18:44 .libs/libhello.a -rwxr-xr-x 1 gord gord 12205 Nov 13 18:44 .libs/libhello.so.0.0 burger$

Well, that sucks. Maybe I should just scrap this project and take up basket weaving.

Actually, it just proves an important point: shared libraries incur overhead because of their (relative) complexity. In this situation, the price of being dynamic is eight kilobytes, and the payoff is about four kilobytes. So, having a shared `libhello' won't be an advantage until we link it against at least a few more programs.

3.4 Debugging executables

If `hell' was a complicated program, you would certainly want to test and debug it before installing it on your system. In the above section, you saw how the libtool wrapper script makes it possible to run the program directly, but unfortunately, this mechanism interferes with the debugger:

burger$ gdb hell GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is no warranty for GDB; type "show warranty" for details. GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. "hell": not in executable format: File format not recognized (gdb) quit burger$

Sad. It doesn't work because GDB doesn't know where the executable lives. So, let's try again, by invoking GDB directly on the executable:

burger$ gdb .libs/hell trick:/home/src/libtool/demo$ gdb .libs/hell GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is no warranty for GDB; type "show warranty" for details. GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. (gdb) break main Breakpoint 1 at 0x8048547: file main.c, line 29. (gdb) run Starting program: /home/src/libtool/demo/.libs/hell /home/src/libtool/demo/.libs/hell: can't load library 'libhello.so.2' Program exited with code 020. (gdb) quit burger$

Argh. Now GDB complains because it cannot find the shared library that `hell' is linked against. So, we must use libtool in order to properly set the library path and run the debugger. Fortunately, we can forget all about the `.libs' directory, and just run it on the executable wrapper (see section 4.3 Execute mode):

burger$ libtool gdb hell GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is no warranty for GDB; type "show warranty" for details. GDB 4.16 (i386-unknown-netbsd), (C) 1996 Free Software Foundation, Inc. (gdb) break main Breakpoint 1 at 0x8048547: file main.c, line 29. (gdb) run Starting program: /home/src/libtool/demo/.libs/hell Breakpoint 1, main (argc=1, argv=0xbffffc40) at main.c:29 29 printf ("Welcome to GNU Hell!\n"); (gdb) quit The program is running. Quit anyway (and kill it)? (y or n) y burger$

3.5 Installing libraries

Installing libraries on a non-libtool system is quite straightforward... just copy them into place:(3)

burger$ su Password: ******** burger# cp libhello.a /usr/local/lib/libhello.a burger#

Oops, don't forget the ranlib command:

burger# ranlib /usr/local/lib/libhello.a burger#

Libtool installation is quite simple, as well. Just use the install or cp command that you normally would (see section 4.4 Install mode):

a23# libtool cp libhello.la /usr/local/lib/libhello.la cp libhello.la /usr/local/lib/libhello.la cp .libs/libhello.a /usr/local/lib/libhello.a ranlib /usr/local/lib/libhello.a a23#

Note that the libtool library `libhello.la' is also installed, to help libtool with uninstallation (see section 4.6 Uninstall mode) and linking (see section 3.3 Linking executables) and to help programs with dlopening (see section 9. Dlopened modules).

Here is the shared library example:

burger# libtool install -c libhello.la /usr/local/lib/libhello.la install -c .libs/libhello.so.0.0 /usr/local/lib/libhello.so.0.0 install -c libhello.la /usr/local/lib/libhello.la install -c .libs/libhello.a /usr/local/lib/libhello.a ranlib /usr/local/lib/libhello.a burger#

It is safe to specify the `-s' (strip symbols) flag if you use a BSD-compatible install program when installing libraries. Libtool will either ignore the `-s' flag, or will run a program that will strip only debugging and compiler symbols from the library.

Once the libraries have been put in place, there may be some additional configuration that you need to do before using them. First, you must make sure that where the library is installed actually agrees with the `-rpath' flag you used to build it.

Then, running `libtool -n --finish libdir' can give you further hints on what to do (see section 4.5 Finish mode):

burger# libtool -n --finish /usr/local/lib PATH="$PATH:/sbin" ldconfig -m /usr/local/lib ----------------------------------------------------------------- Libraries have been installed in: /usr/local/lib To link against installed libraries in a given directory, LIBDIR, you must use the `-LLIBDIR' flag during linking. You will also need to do one of the following: - add LIBDIR to the `LD_LIBRARY_PATH' environment variable during execution - add LIBDIR to the `LD_RUN_PATH' environment variable during linking - use the `-RLIBDIR' linker flag See any operating system documentation about shared libraries for more information, such as the ld and ld.so manual pages. ----------------------------------------------------------------- burger#

After you have completed these steps, you can go on to begin using the installed libraries. You may also install any executables that depend on libraries you created.

3.6 Installing executables

If you used libtool to link any executables against uninstalled libtool libraries (see section 3.3 Linking executables), you need to use libtool to install the executables after the libraries have been installed (see section 3.5 Installing libraries).

So, for our Ultrix example, we would run:

a23# libtool install -c hell /usr/local/bin/hell install -c hell /usr/local/bin/hell a23#

On shared library systems, libtool just ignores the wrapper script and installs the correct binary:

burger# libtool install -c hell /usr/local/bin/hell install -c .libs/hell /usr/local/bin/hell burger#

3.7 Linking static libraries

Why return to ar and ranlib silliness when you've had a taste of libtool? Well, sometimes it is desirable to create a static archive that can never be shared. The most frequent case is when you have a set of object files that you use to build several different programs. You can create a "convenience library" out of those objects, and link programs with the library, instead of listing all object files for every program. This technique is often used to overcome GNU automake's lack of support for linking object files built from sources in other directories, because it supports linking with libraries from other directories. This limitation applies to GNU automake up to release 1.4; newer releases should support sources in other directories.

If you just want to link this convenience library into programs, then you could just ignore libtool entirely, and use the old ar and ranlib commands (or the corresponding GNU automake `_LIBRARIES' rules). You can even install a convenience library (but you probably don't want to) using libtool:

burger$ libtool ./install-sh -c libhello.a /local/lib/libhello.a ./install-sh -c libhello.a /local/lib/libhello.a ranlib /local/lib/libhello.a burger$

Using libtool for static library installation protects your library from being accidentally stripped (if the installer used the `-s' flag), as well as automatically running the correct ranlib command.

But libtool libraries are more than just collections of object files: they can also carry library dependency information, which old archives do not. If you want to create a libtool static convenience library, you can omit the `-rpath' flag and use `-static' to indicate that you're only interested in a static library. When you link a program with such a library, libtool will actually link all object files and dependency libraries into the program.

If you omit both `-rpath' and `-static', libtool will create a convenience library that can be used to create other libtool libraries, even shared ones. Just like in the static case, the library behaves as an alias to a set of object files and dependency libraries, but in this case the object files are suitable for inclusion in shared libraries. But be careful not to link a single convenience library, directly or indirectly, into a single program or library, otherwise you may get errors about symbol redefinitions.

When GNU automake is used, you should use noinst_LTLIBRARIES instead of lib_LTLIBRARIES for convenience libraries, so that the `-rpath' option is not passed when they are linked.

As a rule of thumb, link a libtool convenience library into at most one libtool library, and never into a program, and link libtool static convenience libraries only into programs, and only if you need to carry library dependency information to the user of the static convenience library.

Another common situation where static linking is desirable is in creating a standalone binary. Use libtool to do the linking and add the `-all-static' flag.

4. Invoking libtool

The libtool program has the following synopsis:

libtool [option]... [mode-arg]...

and accepts the following options:

`--config'

Display libtool configuration variables and exit.

`--debug'

Dump a trace of shell script execution to standard output. This produces a lot of output, so you may wish to pipe it to less (or more) or redirect to a file.

`-n'

`--dry-run'

Don't create, modify, or delete any files, just show what commands would be executed by libtool.

`--features'

Display basic configuration options. This provides a way for packages to determine whether shared or static libraries will be built.

`--preserve-dup-deps'

Do not remove duplicate dependencies in libraries. When building packages with static libraries, the libraries may depend circularly on each other (shared libs can too, but for those it doesn't matter), so there are situations, where -la -lb -la is required, and the second -la may not be stripped or the link will fail. In cases where these duplications are required, this option will preserve them, only stripping the libraries that libtool knows it can safely.

`--finish'

Same as `--mode=finish'.

`--help'

Display a help message and exit. If `--mode=mode' is specified, then detailed help for mode is displayed.

`--mode=mode'

Use mode as the operation mode. By default, the operation mode is inferred from the mode-args.

If mode is specified, it must be one of the following:

`compile'

Compile a source file into a libtool object.

`execute'

Automatically set the library path so that another program can use uninstalled libtool-generated programs or libraries.

`finish'

Complete the installation of libtool libraries on the system.

`install'

Install libraries or executables.

`link'

Create a library or an executable.

`uninstall'

Delete installed libraries or executables.

`clean'

Delete uninstalled libraries or executables.

`--version'

Print libtool version information and exit.

The mode-args are a variable number of arguments, depending on the selected operation mode. In general, each mode-arg is interpreted by programs libtool invokes, rather than libtool itself.

4.1 Compile mode		Creating library object files.
4.2 Link mode		Generating executables and libraries.
4.3 Execute mode		Debugging libtool-generated programs.
4.4 Install mode		Making libraries and executables public.
4.5 Finish mode		Completing a library installation.
4.6 Uninstall mode		Removing installed executables and libraries.
4.7 Clean mode		Removing uninstalled executables and libraries.

4.1 Compile mode

For compile mode, mode-args is a compiler command to be used in creating a `standard' object file. These arguments should begin with the name of the C compiler, and contain the `-c' compiler flag so that only an object file is created.

Libtool determines the name of the output file by removing the directory component from the source file name, then substituting the source code suffix (e.g. `.c' for C source code) with the library object suffix, `.lo'.

If shared libraries are being built, any necessary PIC generation flags are substituted into the compilation command. You can pass compiler and linker specific flags using `-Wc,flag' and `-Xcompiler flag' or `-Wl,flag' and `-Xlinker flag', respectively.

If the `-static' option is given, then a `.o' file is built, even if libtool was configured with `--disable-static'.

Note that the `-o' option is now fully supported. It is emulated on the platforms that don't support it (by locking and moving the objects), so it is really easy to use libtool, just with minor modifications to your Makefiles. Typing for example

libtool gcc -c foo/x.c -o foo/x.lo

will do what you expect.

Note, however, that, if the compiler does not support `-c' and `-o', it is impossible to compile `foo/x.c' without overwriting an existing `./x.o'. Therefore, if you do have a source file `./x.c', make sure you introduce dependencies in your `Makefile' to make sure `./x.o' (or `./x.lo') is re-created after any sub-directory's `x.lo':

x.o x.lo: foo/x.lo bar/x.lo

This will also ensure that make won't try to use a temporarily corrupted `x.o' to create a program or library. It may cause needless recompilation on platforms that support `-c' and `-o' together, but it's the only way to make it safe for those that don't.

4.2 Link mode

Link mode links together object files (including library objects) to form another library or to create an executable program.

mode-args consist of a command using the C compiler to create an output file (with the `-o' flag) from several object files.

The following components of mode-args are treated specially:

`-all-static'

If output-file is a program, then do not link it against any shared libraries at all. If output-file is a library, then only create a static library.

`-avoid-version'

Tries to avoid versioning (see section 6. Library interface versions) for libraries and modules, i.e. no version information is stored and no symbolic links are created. If the platform requires versioning, this option has no effect.

`-dlopen file'

Same as `-dlpreopen file', if native dlopening is not supported on the host platform (see section 9. Dlopened modules) or if the program is linked with `-static' or `-all-static'. Otherwise, no effect. If file is self libtool will make sure that the program can dlopen itself, either by enabling -export-dynamic or by falling back to `-dlpreopen self'.

`-dlpreopen file'

Link file into the output program, and add its symbols to lt_preloaded_symbols (see section 9.2 Dlpreopening). If file is self, the symbols of the program itself will be added to lt_preloaded_symbols. If file is force libtool will make sure that lt_preloaded_symbols is always defined, regardless of whether it's empty or not.

`-export-dynamic'

Allow symbols from output-file to be resolved with dlsym (see section 9. Dlopened modules).

`-export-symbols symfile'

Tells the linker to export only the symbols listed in symfile. The symbol file should end in `.sym' and must contain the name of one symbol per line. This option has no effect on some platforms. By default all symbols are exported.

`-export-symbols-regex regex'

Same as `-export-symbols', except that only symbols matching the regular expression regex are exported. By default all symbols are exported.

`-Llibdir'

Search libdir for required libraries that have already been installed.

`-lname'

output-file requires the installed library `libname'. This option is required even when output-file is not an executable.

`-module'

Creates a library that can be dlopened (see section 9. Dlopened modules). This option doesn't work for programs. Module names don't need to be prefixed with 'lib'. In order to prevent name clashes, however, 'libname' and 'name' must not be used at the same time in your package.

`-no-fast-install'

Disable fast-install mode for the executable output-file. Useful if the program won't be necessarily installed.

`-no-install'

Link an executable output-file that can't be installed and therefore doesn't need a wrapper script. Useful if the program is only used in the build tree, e.g., for testing or generating other files.

`-no-undefined'

Declare that output-file does not depend on any other libraries. Some platforms cannot create shared libraries that depend on other libraries (see section 8. Inter-library dependencies).

`-o output-file'

Create output-file from the specified objects and libraries.

`-release release'

Specify that the library was generated by release release of your package, so that users can easily tell which versions are newer than others. Be warned that no two releases of your package will be binary compatible if you use this flag. If you want binary compatibility, use the `-version-info' flag instead (see section 6. Library interface versions).

`-rpath libdir'

If output-file is a library, it will eventually be installed in libdir. If output-file is a program, add libdir to the run-time path of the program.

`-R libdir'

If output-file is a program, add libdir to its run-time path. If output-file is a library, add -Rlibdir to its dependency_libs, so that, whenever the library is linked into a program, libdir will be added to its run-time path.

`-static'

If output-file is a program, then do not link it against any uninstalled shared libtool libraries. If output-file is a library, then only create a static library.

`-version-info current[:revision[:age]]'

If output-file is a libtool library, use interface version information current, revision, and age to build it (see section 6. Library interface versions). Do not use this flag to specify package release information, rather see the `-release' flag.

`-Wl,flag'

`-Xlinker flag'

Pass a linker specific flag directly to the linker.

If the output-file ends in `.la', then a libtool library is created, which must be built only from library objects (`.lo' files). The `-rpath' option is required. In the current implementation, libtool libraries may not depend on other uninstalled libtool libraries (see section 8. Inter-library dependencies).

If the output-file ends in `.a', then a standard library is created using ar and possibly ranlib.

If output-file ends in `.o' or `.lo', then a reloadable object file is created from the input files (generally using `ld -r'). This method is often called partial linking.

Otherwise, an executable program is created.

4.3 Execute mode

For execute mode, the library path is automatically set, then a program is executed.

The first of the mode-args is treated as a program name, with the rest as arguments to that program.

The following components of mode-args are treated specially:

`-dlopen file'

Add the directory containing file to the library path.

This mode sets the library path environment variable according to any `-dlopen' flags.

If any of the args are libtool executable wrappers, then they are translated into the name of their corresponding uninstalled binary, and any of their required library directories are added to the library path.

4.4 Install mode

In install mode, libtool interprets mode-args as an installation command beginning with cp, or a BSD-compatible install program.

The rest of the mode-args are interpreted as arguments to that command.

The command is run, and any necessary unprivileged post-installation commands are also completed.

4.5 Finish mode

Finish mode helps system administrators install libtool libraries so that they can be located and linked into user programs.

Each mode-arg is interpreted as the name of a library directory. Running this command may require superuser privileges, so the `--dry-run' option may be useful.

4.6 Uninstall mode

Uninstall mode deletes installed libraries, executables and objects.

The first mode-arg is the name of the program to use to delete files (typically `/bin/rm').

The remaining mode-args are either flags for the deletion program (beginning with a `-'), or the names of files to delete.

4.7 Clean mode

Clean mode deletes uninstalled libraries, executables, objects and libtool's temporary files associated with them.

The first mode-arg is the name of the program to use to delete files (typically `/bin/rm').

The remaining mode-args are either flags for the deletion program (beginning with a `-'), or the names of files to delete.

5. Integrating libtool with your package

This chapter describes how to integrate libtool with your packages so that your users can install hassle-free shared libraries.

5.1 Writing `Makefile' rules for libtool
5.2 Using Automake with libtool		Automatically supporting libtool.
5.3 Configuring libtool		Configuring libtool for a host system.
5.4 Including libtool in your package		What files to distribute with your package.
5.5 Static-only libraries		Sometimes shared libraries are just a pain.

5.1 Writing `Makefile' rules for libtool

Libtool is fully integrated with Automake (see section `Introduction' in The Automake Manual), starting with Automake version 1.2.

If you want to use libtool in a regular `Makefile' (or `Makefile.in'), you are on your own. If you're not using Automake 1.2, and you don't know how to incorporate libtool into your package you need to do one of the following:

1. Download Automake (version 1.2 or later) from your nearest GNU mirror, install it, and start using it.

2. Learn how to write `Makefile' rules by hand. They're sometimes complex, but if you're clever enough to write rules for compiling your old libraries, then you should be able to figure out new rules for libtool libraries (hint: examine the `Makefile.in' in the `demo' subdirectory of the libtool distribution... note especially that it was automatically generated from the `Makefile.am' by Automake).

5.2 Using Automake with libtool

Libtool library support is implemented under the `LTLIBRARIES' primary.

Here are some samples from the Automake `Makefile.am' in the libtool distribution's `demo' subdirectory.

First, to link a program against a libtool library, just use the `program_LDADD' variable:

bin_PROGRAMS = hell hell.debug # Build hell from main.c and libhello.la hell_SOURCES = main.c hell_LDADD = libhello.la # Create an easier-to-debug version of hell. hell_debug_SOURCES = main.c hell_debug_LDADD = libhello.la hell_debug_LDFLAGS = -static

The flags `-dlopen' or `-dlpreopen' (see section 4.2 Link mode) would fit better in the program_LDADD variable. Unfortunately, GNU automake, up to release 1.4, doesn't accept these flags in a program_LDADD variable, so you have the following alternatives:

• add them to program_LDFLAGS, and list the libraries in program_DEPENDENCIES, then wait for a release of GNU automake that accepts these flags where they belong;

• surround the flags between quotes, but then you must set program_DEPENDENCIES too:

  program_LDADD = "-dlopen" libfoo.la program_DEPENDENCIES = libfoo.la

• set and `AC_SUBST' variables DLOPEN and DLPREOPEN in `configure.in' and use `@DLOPEN@' and `@DLPREOPEN@' as replacements for the explicit flags `-dlopen' and `-dlpreopen' in `program_LDADD'. Automake will discard `AC_SUBST'ed variables from dependencies, so it will behave exactly as we expect it to behave when it accepts these flags in `program_LDADD'. But hey!, this is ugly!

You may use the `program_LDFLAGS' variable to stuff in any flags you want to pass to libtool while linking `program' (such as `-static' to avoid linking uninstalled shared libtool libraries).

Building a libtool library is almost as trivial... note the use of `libhello_la_LDFLAGS' to pass the `-version-info' (see section 6. Library interface versions) option to libtool:

# Build a libtool library, libhello.la for installation in libdir. lib_LTLIBRARIES = libhello.la libhello_la_SOURCES = hello.c foo.c libhello_la_LDFLAGS = -version-info 3:12:1

The `-rpath' option is passed automatically by Automake (except for libraries listed as noinst_LTLIBRARIES), so you should not specify it.

See section `The Automake Manual' in The Automake Manual, for more information.

5.3 Configuring libtool

Libtool requires intimate knowledge of your compiler suite and operating system in order to be able to create shared libraries and link against them properly. When you install the libtool distribution, a system-specific libtool script is installed into your binary directory.

However, when you distribute libtool with your own packages (see section 5.4 Including libtool in your package), you do not always know which compiler suite and operating system are used to compile your package.

For this reason, libtool must be configured before it can be used. This idea should be familiar to anybody who has used a GNU configure script. configure runs a number of tests for system features, then generates the `Makefiles' (and possibly a `config.h' header file), after which you can run make and build the package.

Libtool adds its own tests to your configure script in order to generate a libtool script for the installer's host machine.

5.3.1 The AC_PROG_LIBTOOL macro

Configuring libtool in `configure.in'.

5.3.1 The AC_PROG_LIBTOOL macro

If you are using GNU Autoconf (or Automake), you should add a call to AC_PROG_LIBTOOL to your `configure.in' file. This macro adds many new tests to the configure script so that the generated libtool script will understand the characteristics of the host:

Macro: AC_PROG_LIBTOOL

Macro: AM_PROG_LIBTOOL

Add support for the `--enable-shared' and `--disable-shared' configure flags.(4) AM_PROG_LIBTOOL was the old name for this macro, and although supported at the moment is deprecated.

By default, this macro turns on shared libraries if they are available, and also enables static libraries if they don't conflict with the shared libraries. You can modify these defaults by calling either the AC_DISABLE_SHARED or AC_DISABLE_STATIC macros:

# Turn off shared libraries during beta-testing, since they # make the build process take too long. AC_DISABLE_SHARED AC_PROG_LIBTOOL

The user may specify modified forms of the configure flags `--enable-shared' and `--enable-static' to choose whether shared or static libraries are built based on the name of the package. For example, to have shared `bfd' and `gdb' libraries built, but not shared `libg++', you can run all three configure scripts as follows:

trick$ ./configure --enable-shared=bfd,gdb

In general, specifying `--enable-shared=pkgs' is the same as configuring with `--enable-shared' every package named in the comma-separated pkgs list, and every other package with `--disable-shared'. The `--enable-static=pkgs' flag behaves similarly, but it uses `--enable-static' and `--disable-static'. The same applies to the `--enable-fast-install=pkgs' flag, which uses `--enable-fast-install' and `--disable-fast-install'.

The package name `default' matches any packages which have not set their name in the PACKAGE environment variable.

This macro also sets the shell variable LIBTOOL_DEPS, that you can use to automatically update the libtool script if it becomes out-of-date. In order to do that, add to your `configure.in':

AC_PROG_LIBTOOL AC_SUBST(LIBTOOL_DEPS)

and, to `Makefile.in' or `Makefile.am':

LIBTOOL_DEPS = @LIBTOOL_DEPS@ libtool: $(LIBTOOL_DEPS) $(SHELL) ./config.status --recheck

If you are using GNU automake, you can omit the assignment, as automake will take care of it. You'll obviously have to create some dependency on `libtool'.

Macro: AC_LIBTOOL_DLOPEN

Enable checking for dlopen support. This macro should be used if the package makes use of the `-dlopen' and `-dlpreopen' flags, otherwise libtool will assume that the system does not support dlopening. The macro must be called before AC_PROG_LIBTOOL.

Macro: AC_LIBTOOL_WIN32_DLL

This macro should be used if the package has been ported to build clean dlls on win32 platforms. Usually this means that any library data items are exported with __declspec(dllexport) and imported with __declspec(dllimport). If this macro is not used, libtool will assume that the package libraries are not dll clean and will build only static libraries on win32 hosts.

This macro must be called before AC_PROG_LIBTOOL, and provision must be made to pass `-no-undefined' to libtool in link mode from the package Makefile. Naturally, if you pass `-no-undefined', you must ensure that all the library symbols really are defined at link time!

Macro: AC_DISABLE_FAST_INSTALL

Change the default behaviour for AC_PROG_LIBTOOL to disable optimization for fast installation. The user may still override this default, depending on platform support, by specifying `--enable-fast-install'.

Macro: AC_DISABLE_SHARED

Macro: AM_DISABLE_SHARED

Change the default behaviour for AC_PROG_LIBTOOL to disable shared libraries. The user may still override this default by specifying `--enable-shared'.

Macro: AC_DISABLE_STATIC

Macro: AM_DISABLE_STATIC

Change the default behaviour for AC_PROG_LIBTOOL to disable static libraries. The user may still override this default by specifying `--enable-static'.

The tests in AC_PROG_LIBTOOL also recognize the following environment variables:

Variable: CC

The C compiler that will be used by the generated libtool. If this is not set, AC_PROG_LIBTOOL will look for gcc or cc.

Variable: CFLAGS

Compiler flags used to generate standard object files. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: CPPFLAGS

C preprocessor flags. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: LD

The system linker to use (if the generated libtool requires one). If this is not set, AC_PROG_LIBTOOL will try to find out what is the linker used by CC.

Variable: LDFLAGS

The flags to be used by libtool when it links a program. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: LIBS

The libraries to be used by AC_PROG_LIBTOOL when it links a program. If this is not set, AC_PROG_LIBTOOL will not use any such flags. It affects only the way AC_PROG_LIBTOOL runs tests, not the produced libtool.

Variable: NM

Program to use rather than checking for nm.

Variable: RANLIB

Program to use rather than checking for ranlib.

Variable: LN_S

A command that creates a link of a program, a soft-link if possible, a hard-link otherwise. AC_PROG_LIBTOOL will check for a suitable program if this variable is not set.

Variable: DLLTOOL

Program to use rather than checking for dlltool. Only meaningful for Cygwin/MS-Windows.

Variable: OBJDUMP

Program to use rather than checking for objdump. Only meaningful for Cygwin/MS-Windows.

Variable: AS

Program to use rather than checking for as. Only used on Cygwin/MS-Windows at the moment.

When you invoke the libtoolize program (see section 5.4.1 Invoking libtoolize), it will tell you where to find a definition of AC_PROG_LIBTOOL. If you use Automake, the aclocal program will automatically add AC_PROG_LIBTOOL support to your configure script.

Nevertheless, it is advisable to include a copy of `libtool.m4' in `acinclude.m4', so that, even if `aclocal.m4' and `configure' are rebuilt for any reason, the appropriate libtool macros will be used. The alternative is to hope the user will have a compatible version of `libtool.m4' installed and accessible for aclocal. This may lead to weird errors when versions don't match.

5.4 Including libtool in your package

In order to use libtool, you need to include the following files with your package:

`config.guess'

Attempt to guess a canonical system name.

`config.sub'

Canonical system name validation subroutine script.

`ltmain.sh'

A generic script implementing basic libtool functionality.

Note that the libtool script itself should not be included with your package. See section 5.3 Configuring libtool.

You should use the libtoolize program, rather than manually copying these files into your package.

5.4.1 Invoking libtoolize		libtoolize command line options.
5.4.2 Autoconf `.o' macros		Autoconf macros that set object file names.

5.4.1 Invoking libtoolize

The libtoolize program provides a standard way to add libtool support to your package. In the future, it may implement better usage checking, or other features to make libtool even easier to use.

The libtoolize program has the following synopsis:

libtoolize [option]...

and accepts the following options:

`--automake'

Work silently, and assume that Automake libtool support is used.

`libtoolize --automake' is used by Automake to add libtool files to your package, when AC_PROG_LIBTOOL appears in your `configure.in'.

`--copy'

`-c'

Copy files from the libtool data directory rather than creating symlinks.

`--debug'

Dump a trace of shell script execution to standard output. This produces a lot of output, so you may wish to pipe it to less (or more) or redirect to a file.

`--dry-run'

`-n'

Don't run any commands that modify the file system, just print them out.

`--force'

`-f'

Replace existing libtool files. By default, libtoolize won't overwrite existing files.

`--help'

Display a help message and exit.

`--ltdl'

Install libltdl in a subdirectory of your package.

`--ltdl-tar'

Add the file libltdl.tar.gz to your package.

`--version'

Print libtoolize version information and exit.

If libtoolize detects an explicit call to AC_CONFIG_AUX_DIR (see section `The Autoconf Manual' in The Autoconf Manual) in your `configure.in', it will put the files in the specified directory.

libtoolize displays hints for adding libtool support to your package, as well.

5.4.2 Autoconf `.o' macros

The Autoconf package comes with a few macros that run tests, then set a variable corresponding to the name of an object file. Sometimes it is necessary to use corresponding names for libtool objects.

Here are the names of variables that list libtool objects:

Variable: LTALLOCA

Substituted by AC_FUNC_ALLOCA (see section `The Autoconf Manual' in The Autoconf Manual). Is either empty, or contains `alloca.lo'.

Variable: LTLIBOBJS

Substituted by AC_REPLACE_FUNCS (see section `The Autoconf Manual' in The Autoconf Manual), and a few other functions.

Unfortunately, the stable release of Autoconf (2.13, at the time of this writing) does not have any way for libtool to provide support for these variables. So, if you depend on them, use the following code immediately before the call to AC_OUTPUT in your `configure.in':

LTLIBOBJS=`echo "$LIBOBJS" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` AC_SUBST(LTLIBOBJS) LTALLOCA=`echo "$ALLOCA" | sed 's/\.[^.]* /.lo /g;s/\.[^.]*$/.lo/'` AC_SUBST(LTALLOCA) AC_OUTPUT(...)

5.5 Static-only libraries

When you are developing a package, it is often worthwhile to configure your package with the `--disable-shared' flag, or to override the defaults for AC_PROG_LIBTOOL by using the AC_DISABLE_SHARED Autoconf macro (see section The AC_PROG_LIBTOOL macro). This prevents libtool from building shared libraries, which has several advantages:

• compilation is twice as fast, which can speed up your development cycle,

• debugging is easier because you don't need to deal with any complexities added by shared libraries, and

• you can see how libtool behaves on static-only platforms.

You may want to put a small note in your package `README' to let other developers know that `--disable-shared' can save them time. The following example note is taken from the GIMP(5) distribution `README':

The GIMP uses GNU Libtool in order to build shared libraries on a variety of systems. While this is very nice for making usable binaries, it can be a pain when trying to debug a program. For that reason, compilation of shared libraries can be turned off by specifying the `--disable-shared' option to `configure'.

6. Library interface versions

The most difficult issue introduced by shared libraries is that of creating and resolving runtime dependencies. Dependencies on programs and libraries are often described in terms of a single name, such as sed. So, one may say "libtool depends on sed," and that is good enough for most purposes.

However, when an interface changes regularly, we need to be more specific: "Gnus 5.1 requires Emacs 19.28 or above." Here, the description of an interface consists of a name, and a "version number."

Even that sort of description is not accurate enough for some purposes. What if Emacs 20 changes enough to break Gnus 5.1?

The same problem exists in shared libraries: we require a formal version system to describe the sorts of dependencies that programs have on shared libraries, so that the dynamic linker can guarantee that programs are linked only against libraries that provide the interface they require.

6.1 What are library interfaces?
6.2 Libtool's versioning system
6.3 Updating