Libtool

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

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.