.\" You may copy, distribute and modify under the terms of the LDP General .\" Public License as specified in the LICENSE file that comes with the .\" gnumaniak distribution .\" .\" The author kindly requests that no comments regarding the "better" .\" suitability or up-to-date notices of any info documentation alternative .\" is added without contacting him first. .\" .\" (C) 1999 Ragnar Hojland Espinosa .\" .\" libtool man page .\" man pages are NOT obsolete! .\" .TH LIBTOOL 301 "December 1999" "libtool 1.3.4" .SH NAME \fBlibtool\fR \- compile, build, install and uninstall libraries .SH SYNOPSIS .B libtool .RB [ \-n ] .RB [ \-\-config ] .RB [ \-\-debug ] .RB [ \-\-dry\-run ] .RB [ \-\-finish ] .RB [ \-\-mode=\fIMODE ] .RB [ \-\-quiet ] .RB [ \-\-silent ] .RI [ MODE\-ARGS... ] Link Mode: [\fB\-l\fINAME\fR] [\fB\-o \fI OUTPUT\-FILE\fR] [\fB\-L\fILIBDIR\fR] [\fB\-R \fILIBDIR\fR] .RB [ \-all\-static ] .RB [ \-avoid\-version ] .RB [ "\-dlopen \fIFILE" ] .RB [ "\-dlpreopen \fIFILE" ] .RB [ \-export\-dynamic ] .RB [ "\-\-export\-symbols \fIFILE" ] .RB [ "\-\-export\-symbols \fIREGEX" ] .RB [ \-\-module ] .RB [ \-no\-undefined ] .RB [ "\-release \fIRELEASE" ] .RB [ "\-rpath \fILIBDIR" ] .RB [ \-static ] .RB [ "\-version\-info \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE" ]] Execute Mode: [\fB\-dlopen \fIFILE\fR] .BR libtool " [" \-\-features "] [" \-\-help "] [" \-\-version ] .SH DESCRIPTION .B libtool simplifies the complexity of compiling, linking, installing and unistalling both static and shared libraries so that the complete functionality of different platforms is available via a generic interface but nasty quirks are hidden from the programmer. .B libtool can operate in six modes: compile, execute, link, finish, install, uninstall. .SS Compile Mode For \fBcompile\fR mode, \fIMODE\-ARGS\fR 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 \fB\-c\fR compiler flag so that only an object file is created. \fBlibtool\fR determines the name of the output file by removing the directory component from the source file name, then substituting the C source code suffix `.c' with the library object suffix, `.lo'. If shared libraries are being built, any necessary PIC generation flags are substituted into the compilation command. The \fB\-static\fR option will cause \fBlibtool\fR to generate `.o' files even if it was configured with \fB\-\-disable\-static\fR The \fB\-o\fR option is emulated on platforms that don't support it directly (by locking and moving the object files generated by the compiler) so you can use the usual syntax: .sp .RS .nf lightside:% libtool cc -c foo/x.c -o foo/x.lo .fi .RE .sp If the platform doesn't support \fB\-c\fR and \fB\-o\fR then it is impossible to build `foo/x.lo' without overwriting an old `foo/x.o', and that in this case you must make sure `foo/x.o' is (re)built after `foo/x.lo' .SS Link Mode \fBlink\fR mode links together object files (including library objects) to form another library or to create an executable program. \fIMODE\-ARGS\fR consist of a command using the C compiler to create an output file \fIOUTPUT\-FILE\fR (with the \fB\-o\fR flag) from several object files. The type of file depends on the extension of \fIOUTPUT\-FILE\fR: .TP .B .la A libtool library is created, which must be built only from library objects (`.lo' files). The \fB\-rpath\fR option is required. In the current implementation, libtool libraries may not depend on other uninstalled libtool libraries. .TP .B .a A standard library is created using \fBar\fR(1) and possibly \fBranlib\fR(1). .TP .B .o .lo A reloadable object file is created from the input files (generally using `ld \-r'). This method is often called ``partial linking''. .TP .B other An executable program is created. .SS Execute Mode For \fBexecute\fR mode, the library path environment variable is automatically set (and modified according \fB\-dlopen\fR), then a program is executed. The first of the \fIMODE-ARGS\fR is treated as a program name, with the rest as arguments to that program. If any of the arguments 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. .SS Install Mode In \fBinstall\fR mode, libtool interprets \fIMODE\-ARGS\fR as an installation command beginning with \fBcp\fR(1), or a BSD-compatible \fBinstall\fR(1) program. The rest of the \fBMODE\-ARGS\fR are interpreted as arguments to that command. The command is run, and any necessary unprivileged post-installation commands are also completed. .SS Finish Mode \fBfinish\fR mode helps system administrators install libtool libraries so that they can be located and linked into user programs. Each \fIMODE\-ARG\fR is interpreted as the name of a library directory. Running this command may require superuser privileges, so the \fB\-\-dry\-run\fR option may be useful. .SS Uninstall Mode This mode deletes installed libraries (and other files). The first \fIMODE\-ARG\fR is the name of the program to use to delete files (typically `/bin/rm'). The remaining \fIMODE\-ARGS\fR are either flags for the deletion program (beginning with a `\-'), or the names of files to delete. .SH OPTIONS .SS Global Options .TP .B \-\-config Display libtool's configuration variables and exit. .TP .B \-\-debug Enables shell script trace mode, writing to standard output. .TP .B \-n, \-\-dry\-run Don't create, modify, or delete any files, just show what commands would be executed by \fBlibtool\fR. .TP .B \-\-finish Same as \fB\-\-mode=finish\fR. .TP .B \-\-mode=\fIMODE Use \fIMODE\fR as the operation mode. By default, the operation mode is inferred from the contents of \fIMODE\-ARGS\fR. If \fIMODE\fR is specified, it must be one of the following: .RS .TP .B compile Compile a source file into a libtool object. .TP .B execute Automatically set the library path so that another program can use uninstalled libtool-generated programs or libraries. .TP .B finish Complete the installation of libtool libraries on the system. .TP .B install Install libraries or executables. .TP .B link Create a library or an executable. .TP .B uninstall Delete installed libraries or executables. .RE .TP .B \-\-features Display libtool configuration information and exit. This provides a way for packages to determine whether shared or static libraries will be built. .TP .B "\-\-help" Print a usage message on standard output and exit successfully. If \fB\-\-mode=\fIMODE\fR is specified, help on selected mode is printed. .TP .B "\-\-version" Print version information on standard output then exit successfully. .SS Link Mode Options .TP .B -l\fINAME \fIOUTPUT\-FILE\fR requires the installed library \fBlib\fINAME\fR. This option is required even when \fIOUTPUT\-FILE\fR is not an executable. .TP .B \-o \fIOUTPUT\-FILE Create \fIOUTPUT\-FILE\fR from the specified objects and libraries. .TP .B \-L\fILIBDIR Search \fILIBDIR\fR for required libraries that have already been installed. .TP .B \-R \fILIBDIR If \fIOUTPUT\-FILE\fR is an executable, add \fILIBDIR\fR to its run-time path. If \fIOUTPUT-FILE\fR is a library, add `-RLIBDIR' to its \fBDEPENDENCY_LIBS\fR so that, whenever the library is linked into an executable, \fILIBDIR\fR will be added to its run-time path. .TP .B \-all\-static If \fIOUTPUT\-FILE\fR is a program, then do not link it against any shared libraries at all. If \fIOUTPUT-FILE\fR is a library, then only create a static library. .TP .B \-avoid\-version Tries to avoid using any kind of versioning (no version info is stored and no symbolic links are created). This option has no effect on platforms which require versioning. .TP .B \-dlopen \fIFILE Same as \fB\-dlpreopen \fIFILE\fR, if native dlopening is not supported on the host platform or if the executable is linked using \fB\-static\fR or \fB\-all\-static\fR. Otherwise, no effect. If \fIFILE\fR is `self', then libtool will make sure that the executable can \fBdlopen\fR(3) itself by using \fB\-export\-dynamic\fR or \fB\-dlpreopen\fR. .TP .B \-dlpreopen \fIFILE Link \fIFILE\fR into the output program, and add its symbols to \fBLT_PRELOADED_SYMBOLS\fR. If \fIFILE\fR is `self', then the symbols of the output program itself will be added to \fBLT_PRELOADED_SYMBOLS\fR. .TP .B \-export\-dynamic Allow symbols from \fIOUTPUT\-FILE\fR to be resolved with \fBdlsym\fR(3). .TP .B \-export\-symbols \fIFILE On platforms which support it, the linker will only export symbols listed in \fIFILE\fR. The name of \fIFILE\fR must end in `.sym' and contain on symbol per line. By default all symbols are exported. .TP .B \-export\-symbols\-regex \fIREGEX As \fB\-export\-symbols\fR, except that only symbols that match the \fIREGEX\fR \fBregex\fR(7) are exported. .TP .B \-module Creates a library that can be dlopened. Module names don't need to be prefixed with `lib', however in order to prevent name clashes `libname' and `name' must not be used at the same time in your package. .TP .B \-no\-undefined Declare that \fIOUTPUT\-FILE\fR does not depend on any other libraries. Some platforms cannot create shared libraries that depend on other libraries. .TP .B \-release \fIRELEASE Specify that the library was generated by release \fIRELEASE\fR 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 \fB\-version\-info\fR flag. .TP .B \-rpath \fILIBDIR If \fIOUTPUT\-FILE\fR is a library, it will eventually be installed in \fILIBDIR\fR. .TP .B \-static If \fIOUTPUT\-FILE\fR is a program, then do not link it against any uninstalled shared libtool libraries. If \fIOUTPUT\-FILE\fR is a library, then only create a static library. .TP .B \-version\-info \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE\fR]] If \fIOUTPUT\-FILE\fR is a libtool library, use interface version information \fICURRENT\fR, \fIREVISION\fR, and \fIAGE\fR to build it Do \fBnot\fR use this flag to specify package release information, rather see the \fR\-release\fB flag. .SS Execute Mode Options .TP .B \-dlopen \fIFILE Add the directory containing \fIFILE\fR to the library path. .SH VERSIONING .B libtool has it's own versioning system for shared libraries. If you want to use this system, you must use the \fB\-version\-info\fR option. This option accepts an argument of the form \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE\fR]] .TP .I CURRENT Interface version, understanding interface as anything visible to the "outside" world: variables, function prototypes, output format, etc. .TP .I REVISION Implementation version, relative to \fICURRENT\fR version. .TP .I AGE The difference between the newest and oldest interfaces that this library implements. In other words, the library implements all the interface numbers in the range from `\fICURRENT \- \fIAGE\fR' to \fICURRENT\fR, and any executable can use the library if it has been linked against a library in this range. .PP If either \fIREVISION\fR or \fIAGE\fR are omitted, they default to 0. Also note that \fIAGE\fR must be less than or equal to the \fICURRENT\fR interface number. If two libraries have identical \fICURRENT\fR and \fIAGE\fR numbers, then the dynamic linker chooses the library with the greater \fIREVISION\fR. Some versioning guidelines: \fB\(bu\ 1.\fR Start with version information of `0:0:0' for each libtool library. \fB\(bu\ 2.\fR Update the version information only immediately before a public release of your software. More frequent updates are unnecessary, and only guarantee that the current interface number gets larger faster. \fB\(bu\ 3.\fR If the library source code has changed at all since the last update, then increment \fIREVISION\fR (\fIC\fB:\fIR\fB:\fIA\fR becomes \fIC\fB:\fIR+1\fB:A\fR). \fB\(bu\ 4.\fR If any interfaces have been added, removed, or changed since the last update, increment \fICURRENT\fR, and set \fIREVISION\fR to 0. \fB\(bu\ 5.\fR If any interfaces have been added since the last public release, then increment \fIAGE\fR. \fB\(bu\ 6.\fR If any interfaces have been removed since the last public release, then set \fIAGE\fR to 0. If you want to encode the package version in the library name, or use another versioning system without conflicting with \fBlibtool\fR's versioning, use \fB\-release\fR. `libbfd.so.2.7.0.2' for example, comes with binutils\-2.7.0.2 and clearly conflicts with \fBlibtool\fR's versioning. We can use `\-release 2.7.0' and end up with `libbfd\-2.7.0.so.0.0.0' which is ok. Note that libraries with different \fICURRENT\fR version, and libraries with different \fB\-release\fR, will be binary incompatible. .SH INTERFACE DESIGN Writing a good library interface takes practice and thorough understanding of the problem that the library is intended to solve. If you design a good interface, it won't have to change often, you won't have to keep updating documentation, and clients won't have to keep relearning how to use the library. Some design guidelines: \fB\(bu\fR Plan ahead .br Try to make every interface minimal, so that you won't need to delete entry points very often. \fB\(bu\fR Avoid interface changes .br If you must redesign an interface, try to leave compatibility functions behind so that clients don't need to rewrite their existing code. \fB\(bu\fR Use opaque data types .br The fewer data type definitions a client has access to, the better. If possible, design your functions to accept a generic pointer (which you can cast to an internal data type), and provide access functions rather than allowing the client to directly manipulate the data. That way, you have the freedom to change the data structures without changing the interface. \fB\(bu\fR Use header files .br If you write each of your library's global functions and variables in header files, and include them in your library source files, then the compiler will let you know if you make any interface changes by accident. \fB\(bu\fR Use \fBstatic\fRs (or equivalent) whenever possible .br The fewer global functions your library has, the more flexibility you will have in changing them. \fBstatic\fR functions and variables may change as often as you like, since clients cannot access them and therefore they aren't considered interface changes. .SH WRITING AUTOMAKE RULES \fBlibtool\fR library support is implemented under the \fBLTLIBRARIES\fR primary. To link a program against a \fBlibtool\fR library, just use the \fIprogram\fB_LDADD\fR variable to specify the library name. You may use \fIprogram\fB_LDFLAGS\fR to pass any options to libtool, such as \fB\-static\fR. To build a \fBlibtool\fR library, use \fIlib\fB_LTLIBRARIES\fR to specify the library name and \fB, and, for example, \fIlib\fB_LDFLAGS\fR to pass the \fB\-version\-info\fR option to \fBlibtool\fR. You will find an example in the next section. You will also have to include some basic files in your package, or use \fBlibtoolize\fR to do the work for you. Do not include the \fBlibtool\fR script directly. .TP .B config.guess Attempt to guess a canonical system name. .TP .B config.sub Canonical system name validation subroutine script. .TP .B ltconfig Generate a libtool script for a given system. .TP .B ltmain.sh A generic script implementing basic libtool functionality. .SH DLOPENING MODULES To use \fBlibtool\fR's dlopening support, you must use the macro \fBAC_LIBTOOL_DLOPEN\fR in your \fBconfigure.in\fR, before \fBAM_PROG_LIBTOOL\fR. Otherwise \fBlibtool\fR will assume there's no dlopening mechanism available on the platform and will simulate it. In order to use this simulation feature you must declare the objects you want to dlopen by using the \fB\-dlopen\fR and \fB\-dlreopen\fR flags when linking your executable. \fBlibtool\fR will link the object files and create data structures holding the executable's symbol table: .sp .RS .nf struct lt_dlsymlist { const char *NAME; lt_ptr_t ADDRESS; } .fi .RE .sp \fINAME\fR holds an asciiz string with the symbol name, such as "fprintf". \fIADDRESS\fR is a generic pointer to the appropriate object, such as &fprintf. .sp .RS .nf const lt_dlsymlist * lt_preloaded_symbols; .fi .RE .sp This array represents all the preloaded symbols linked into the executable. For each \fB\-dlpreloaded\fR file there is an element with the \fINAME\fR of the file and a \fIADDRESS\fR of `\fB0\fR', followed by all symbols exported from this file. For the executable itself the special name \fB@PROGRAM@\fR is used. The last element has a \fINAME\fR and \fIADDRESS\fR of `\fB0\fR'. When linking either a library that is going to be dlopened or an executable that is going to dlopen a module, remember to specify the \fB\-module\fR flag. If an executable needs to reference an external symbol of a library that you are going to dlopen, use \fB\-export\-dynamic\fR when linking the executable. Due variations in library names, your program needs to determine which is the correct file to dlopen. A straightforward approach is to examine the `\fB.la\fR' files, looking for the \fBdlname='\fIDLNAME\fB'\fR line, where \fBDLNAME\fR is either empty if the library can't be dlopened, or holds the dlname of the library. .SH EXAMPLES We are about to create a library called `libbaz' from the source files `foo.c', `bar.c', and then link `a.c' with `libbaz' to create an executable named `a' .SS Creating The Library \fB\(bu\fR Compile mode: since Linux supports shared libraries, \fBlibtool\fR will generate two object files: one for the static library (`foo.lo') and one for the shared library (`foo.o'). The \fB\-c\fR option is mandatory, since we don't want the compiler to do the linking on its own. .sp .RS .nf lightside:~% libtool cc \-c foo.c cc \-c \-fPIC \-DPIC foo.c -o .libs/foo.lo cc \-c foo.c >/dev/null 2>&1 lightside:~% libtool cc -c bar.c cc \-c \-fPIC \-DPIC bar.c -o .libs/bar.lo cc \-c bar.c >/dev/null 2>&1 .fi .RE .sp \fB\(bu\fR Link mode, build only a static library: We specify the `.o' object files generated previously. The \fB\-o\fR option is mandatory. .sp .RS .nf lightside:~% libtool cc -o libbaz.a foo.o bar.o ar cru libbaz.a foo.o bar.o ranlib libbaz.a .fi .RE .sp \fB\(bu\fR Link mode, build static and shared libraries: We specify the `.lo' object files. Mandatory options are \fB\-o\fR like before, and \fB\-rpath\fR to indicate which will be the installation directory for our library. The library will be created in the `.libs' directory. .sp .RS .nf lightside:~% libtool cc \-o libbaz.la foo.lo bar.lo \e \-rpath /usr/local/lib cc \-shared \-Wl,\-soname \-Wl,libbaz.so.0 \e \-o .libs/libbaz.so.0.0.0 foo.lo bar.lo (cd .libs && ln \-s libbaz.so.0.0.0 libbaz.so.0) (cd .libs && ln \-s libbaz.so.0.0.0 libbaz.so) ar cru .libs/libbaz.a foo.o bar.o ranlib .libs/libbaz.a creating libbaz.la (cd .libs && ln \-s ../libbaz.la libbaz.la) .fi .RE .sp \fB\(bu\fR Install mode: This will run the necessary commands to install the library in the specified path (in our case, `/usr/local/lib'). It will install the shared (`.so') and static (`.a') libraries, as well as the libtool file (`.la'), for unistallation and informational purposes. Since this is often done as a privileged user, it's useful to specify the \fB\-n\fR or \fB\-\-dry\-run\fR option to check the results. .sp .RS .nf lightside:/tmp% libtool \-n install libbaz.la /usr/local/lib install .libs/libbaz.so.0.0.0 /usr/local/lib/libbaz.so.0.0.0 (cd /usr/local/lib && ln \-s libbaz.so.0.0.0 libbaz.so.0) (cd /usr/local/lib && ln \-s libbaz.so.0.0.0 libbaz.so) install libbaz.la /usr/local/lib/libbaz.la install .libs/libbaz.a /usr/local/lib/libbaz.a ranlib /usr/local/lib/libbaz.a chmod 644 /usr/local/lib/libbaz.a .fi .RE .sp .SS Creating the Executable First we compile `a.c' .sp .RS .nf cc \-c a.c .fi .RE .sp If the library has already been installed you can proceed as usual .sp .RS .nf cc a.c \-lbaz \-L/usr/local/lib .fi .RE .sp If the library hasn't been installed yet, \fBlibtool\fR must be used to do the linking, debugging and installation of the executable (this last thing, once the library has been installed). Note that the real executable will be in `.libs' until it is installed, and the the executable on the work directory is merely a wrapper. In order to avoid ambiguities, never use \fB\-l\fR or \fB\-L\fR to link against an uninstalled shared library. Just specify the path to the `.la' file. Installed libraries aren't a problem, as we see below (`\-lm'). .sp .RS .nf lightside:~% libtool cc a.o libbaz.la \-o a -lm cc a.o \-Wl,\-\-rpath \-Wl,/usr/local/lib \e .libs/libbaz.so \-o .libs/a -lm lightside:~% libtool gdb a [snipped hairy debugging session] lightside:~% libtool install \-c a /usr/local/bin/a install \-c .libs/a /usr/local/bin/a .fi .RE .sp .SS Creating Makefile.am \fB\(bu\fR\ First create a brief \fBconfigure.in\fR, remembering to add the macros for \fBautomake\fR and \fBlibtool\fR. .sp .RS .nf AC_DEFUN(AM_INIT_AUTOMAKE) AC_INIT(a.c) AM_INIT_AUTOMAKE(a, 1.0) AC_PROG_CC AM_PROG_LIBTOOL AC_OUTPUT(Makefile) .fi .RE .sp \fB\(bu\fR\ Then the corresponding \fBMakefile.am\fR .sp .RS .nf # Build the library lib_LTLIBRARIES=libbaz.la libbaz_la_SOURCES = foo.c bar.c libbaz_la_LDFLAGS = -version-info 0:0:0 bin_PROGRAMS = a a.debug # Build a from a.c and libbaz.la a_SOURCES = a.c a_LDADD = libbaz.la # Create a static debugging version a_debug_SOURCES = a.c a_debug_LDADD = libbaz.la a_debug_LDFLAGS = \-static .fi .RE .sp \fB\(bu\fR\ And finally give it a try .sp .RS .nf lightside:~% aclocal; libtoolize; automake \-\-add\-missing; autoconf lightside:~% ./configure; make .fi .RE .sp .SH SEE ALSO \fBlibtoolize\fR(1), \fBlibltdl\fR(3) .SH NOTES Report bugs to . .br Man page by Ragnar Hojland Espinosa