1 .\" You may copy, distribute and modify under the terms of the LDP General
2 .\" Public License as specified in the LICENSE file that comes with the
3 .\" gnumaniak distribution
5 .\" The author kindly requests that no comments regarding the "better"
6 .\" suitability or up-to-date notices of any info documentation alternative
7 .\" is added without contacting him first.
9 .\" (C) 1999-2002 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
12 .\" man pages are NOT obsolete!
13 .\" <ragnar@ragnar-hojland.com>
14 .TH LIBTOOL 301 "June 2002" "libtool 1.4.2"
16 \fBlibtool\fR \- compile, build, install and uninstall libraries
25 .RB [ \-\-mode=\fIMODE ]
30 Link Mode: [\fB\-l\fINAME\fR] [\fB\-o \fI OUTPUT\-FILE\fR] [\fB\-L\fILIBDIR\fR]
33 .RB [ \-avoid\-version ]
34 .RB [ "\-dlopen \fIFILE" ]
35 .RB [ "\-dlpreopen \fIFILE" ]
36 .RB [ \-export\-dynamic ]
37 .RB [ "\-\-export\-symbols \fIFILE" ]
38 .RB [ "\-\-export\-symbols \fIREGEX" ]
40 .RB [ \-no\-undefined ]
41 .RB [ "\-release \fIRELEASE" ]
42 .RB [ "\-rpath \fILIBDIR" ]
44 .RB [ "\-version\-info \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE" ]]
46 Execute Mode: [\fB\-dlopen \fIFILE\fR]
48 .BR libtool " [" \-\-features "] [" \-\-help "] [" \-\-version ]
51 simplifies the complexity of compiling, linking, installing and unistalling
52 both static and shared libraries so that the complete functionality of
53 different platforms is available via a generic interface but nasty quirks
54 are hidden from the programmer.
57 can operate in six modes: compile, execute, link, finish, install, uninstall.
59 For \fBcompile\fR mode, \fIMODE\-ARGS\fR is a compiler command to be used in
60 creating a standard object file. These arguments should begin with
61 the name of the C compiler, and contain the \fB\-c\fR compiler flag so that
62 only an object file is created.
64 \fBlibtool\fR determines the name of the output file by removing the
65 directory component from the source file name, then substituting the C
66 source code suffix `.c' with the library object suffix, `.lo'.
68 If shared libraries are being built, any necessary PIC generation
69 flags are substituted into the compilation command. The \fB\-static\fR
70 option will cause \fBlibtool\fR to generate `.o' files even if it was
71 configured with \fB\-\-disable\-static\fR
73 The \fB\-o\fR option is emulated on platforms that don't support it directly
74 (by locking and moving the object files generated by the compiler) so you
75 can use the usual syntax:
79 lightside:% libtool cc -c foo/x.c -o foo/x.lo
83 If the platform doesn't support \fB\-c\fR and \fB\-o\fR then it is
84 impossible to build `foo/x.lo' without overwriting an old `foo/x.o', and
85 that in this case you must make sure `foo/x.o' is (re)built after `foo/x.lo'
88 \fBlink\fR mode links together object files (including library objects)
89 to form another library or to create an executable program.
91 \fIMODE\-ARGS\fR consist of a command using the C compiler to create an
92 output file \fIOUTPUT\-FILE\fR (with the \fB\-o\fR flag) from several object
93 files. The type of file depends on the extension of \fIOUTPUT\-FILE\fR:
96 A libtool library is created, which must be built only from library objects
97 (`.lo' files). The \fB\-rpath\fR option is required. In the current
98 implementation, libtool libraries may not depend on other uninstalled
102 A standard library is created using \fBar\fR(1) and possibly \fBranlib\fR(1).
105 A reloadable object file is created from the input files (generally using
106 `ld \-r'). This method is often called ``partial linking''.
109 An executable program is created.
111 For \fBexecute\fR mode, the library path environment variable is
112 automatically set (and modified according \fB\-dlopen\fR), then a program
115 The first of the \fIMODE-ARGS\fR is treated as a program name, with the
116 rest as arguments to that program.
118 If any of the arguments are libtool executable wrappers, then they are
119 translated into the name of their corresponding uninstalled binary, and
120 any of their required library directories are added to the library path.
122 In \fBinstall\fR mode, libtool interprets \fIMODE\-ARGS\fR as an installation
123 command beginning with \fBcp\fR(1), or a BSD-compatible \fBinstall\fR(1)
126 The rest of the \fBMODE\-ARGS\fR are interpreted as arguments to that
129 The command is run, and any necessary unprivileged post-installation
130 commands are also completed.
132 \fBfinish\fR mode helps system administrators install libtool libraries
133 so that they can be located and linked into user programs.
135 Each \fIMODE\-ARG\fR is interpreted as the name of a library directory.
136 Running this command may require superuser privileges, so the
137 \fB\-\-dry\-run\fR option may be useful.
139 This mode deletes installed libraries (and other files).
141 The first \fIMODE\-ARG\fR is the name of the program to use to delete files
142 (typically `/bin/rm').
144 The remaining \fIMODE\-ARGS\fR are either flags for the deletion program
145 (beginning with a `\-'), or the names of files to delete.
150 Display libtool's configuration variables and exit.
153 Enables shell script trace mode, writing to standard output.
156 Don't create, modify, or delete any files, just show what commands
157 would be executed by \fBlibtool\fR.
160 Displays basic features regarding libtool and whether static and shared
161 library support is enabled.
164 Same as \fB\-\-mode=finish\fR.
167 Use \fIMODE\fR as the operation mode. By default, the
168 operation mode is inferred from the contents of \fIMODE\-ARGS\fR.
169 If \fIMODE\fR is specified, it must be one of the following:
173 Compile a source file into a libtool object.
176 Automatically set the library path so that another program
177 can use uninstalled libtool-generated programs or libraries.
180 Complete the installation of libtool libraries on the system.
183 Install libraries or executables.
186 Create a library or an executable.
189 Delete installed libraries or executables.
193 Display libtool configuration information and exit. This provides
194 a way for packages to determine whether shared or static libraries will be
198 Print a usage message on standard output and exit successfully. If
199 \fB\-\-mode=\fIMODE\fR is specified, help on selected mode is printed.
202 Print version information on standard output then exit successfully.
203 .SS Link Mode Options
206 \fIOUTPUT\-FILE\fR requires the installed library \fBlib\fINAME\fR. This
207 option is required even when \fIOUTPUT\-FILE\fR is not an executable.
209 .B \-o \fIOUTPUT\-FILE
210 Create \fIOUTPUT\-FILE\fR from the specified objects and libraries.
213 Search \fILIBDIR\fR for required libraries that have already been installed.
216 If \fIOUTPUT\-FILE\fR is an executable, add \fILIBDIR\fR to its run-time
217 path. If \fIOUTPUT-FILE\fR is a library, add `-RLIBDIR' to its
218 \fBDEPENDENCY_LIBS\fR so that, whenever the library is linked into an
219 executable, \fILIBDIR\fR will be added to its run-time path.
222 If \fIOUTPUT\-FILE\fR is a program, then do not link it against any
223 shared libraries at all. If \fIOUTPUT-FILE\fR is a library, then only
224 create a static library.
227 Tries to avoid using any kind of versioning (no version info is stored and
228 no symbolic links are created). This option has no effect on platforms which
232 Same as \fB\-dlpreopen \fIFILE\fR, if native dlopening is not
233 supported on the host platform or if the executable is linked using
234 \fB\-static\fR or \fB\-all\-static\fR. Otherwise, no effect.
236 If \fIFILE\fR is `self', then libtool will make sure that the executable can
237 \fBdlopen\fR(3) itself by using \fB\-export\-dynamic\fR or \fB\-dlpreopen\fR.
239 .B \-dlpreopen \fIFILE
240 Link \fIFILE\fR into the output program, and add its symbols to
241 \fBLT_PRELOADED_SYMBOLS\fR.
243 If \fIFILE\fR is `self', then the symbols of the output program itself will
244 be added to \fBLT_PRELOADED_SYMBOLS\fR.
247 Allow symbols from \fIOUTPUT\-FILE\fR to be resolved with \fBdlsym\fR(3).
249 .B \-export\-symbols \fIFILE
250 On platforms which support it, the linker will only export symbols listed in
251 \fIFILE\fR. The name of \fIFILE\fR must end in `.sym' and contain on symbol
252 per line. By default all symbols are exported.
254 .B \-export\-symbols\-regex \fIREGEX
255 As \fB\-export\-symbols\fR, except that only symbols that match the
256 \fIREGEX\fR \fBregex\fR(7) are exported.
259 Creates a library that can be dlopened. Module names don't need to be
260 prefixed with `lib', however in order to prevent name clashes `libname' and
261 `name' must not be used at the same time in your package.
264 Declare that \fIOUTPUT\-FILE\fR does not depend on any other libraries.
265 Some platforms cannot create shared libraries that depend on other
268 .B \-release \fIRELEASE
269 Specify that the library was generated by release \fIRELEASE\fR of your
270 package, so that users can easily tell which versions are newer
271 than others. Be warned that no two releases of your package will
272 be binary compatible if you use this flag. If you want binary
273 compatibility, use the \fB\-version\-info\fR flag.
276 If \fIOUTPUT\-FILE\fR is a library, it will eventually be installed in
280 If \fIOUTPUT\-FILE\fR is a program, then do not link it against any
281 uninstalled shared libtool libraries. If \fIOUTPUT\-FILE\fR is a
282 library, then only create a static library.
284 .B \-version\-info \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE\fR]]
285 If \fIOUTPUT\-FILE\fR is a libtool library, use interface version
286 information \fICURRENT\fR, \fIREVISION\fR, and \fIAGE\fR to build it
287 Do \fBnot\fR use this flag to specify package release information, rather
288 see the \fR\-release\fB flag.
289 .SS Execute Mode Options
292 Add the directory containing \fIFILE\fR to the library path.
295 has it's own versioning system for shared libraries. If you want to use this
296 system, you must use the \fB\-version\-info\fR option. This option accepts
297 an argument of the form \fICURRENT\fR[\fB:\fIREVISION\fR[\fB:\fIAGE\fR]]
300 Interface version, understanding interface as anything visible to the
301 "outside" world: variables, function prototypes, output format, etc.
304 Implementation version, relative to \fICURRENT\fR version.
307 The difference between the newest and oldest interfaces that this
308 library implements. In other words, the library implements all the
309 interface numbers in the range from `\fICURRENT \- \fIAGE\fR' to
310 \fICURRENT\fR, and any executable can use the library if it has been linked
311 against a library in this range.
313 If either \fIREVISION\fR or \fIAGE\fR are omitted, they default to 0. Also
314 note that \fIAGE\fR must be less than or equal to the \fICURRENT\fR
315 interface number. If two libraries have identical \fICURRENT\fR and \fIAGE\fR
316 numbers, then the dynamic linker chooses the library with the greater
319 Some versioning guidelines:
321 \fB\(bu\ 1.\fR Start with version information of `0:0:0' for each libtool
324 \fB\(bu\ 2.\fR Update the version information only immediately before a public
325 release of your software. More frequent updates are unnecessary,
326 and only guarantee that the current interface number gets larger
329 \fB\(bu\ 3.\fR If the library source code has changed at all since
330 the last update, then increment \fIREVISION\fR (\fIC\fB:\fIR\fB:\fIA\fR
331 becomes \fIC\fB:\fIR+1\fB:A\fR).
333 \fB\(bu\ 4.\fR If any interfaces have been added, removed, or changed since the
334 last update, increment \fICURRENT\fR, and set \fIREVISION\fR to 0.
336 \fB\(bu\ 5.\fR If any interfaces have been added since the last public release,
337 then increment \fIAGE\fR.
339 \fB\(bu\ 6.\fR If any interfaces have been removed since the last
340 public release, then set \fIAGE\fR to 0.
342 If you want to encode the package version in the library name, or use
343 another versioning system without conflicting with \fBlibtool\fR's
344 versioning, use \fB\-release\fR. `libbfd.so.2.7.0.2' for example, comes with
345 binutils\-2.7.0.2 and clearly conflicts with \fBlibtool\fR's versioning. We
346 can use `\-release 2.7.0' and end up with `libbfd\-2.7.0.so.0.0.0' which is ok.
348 Note that libraries with different \fICURRENT\fR version, and libraries with
349 different \fB\-release\fR, will be binary incompatible.
351 Writing a good library interface takes practice and thorough understanding
352 of the problem that the library is intended to solve. If you design a good
353 interface, it won't have to change often, you won't have to keep updating
354 documentation, and clients won't have to keep relearning how to use the
357 Some design guidelines:
359 \fB\(bu\fR Plan ahead
361 Try to make every interface minimal, so that you won't need to delete entry
364 \fB\(bu\fR Avoid interface changes
366 If you must redesign an interface, try to leave compatibility functions
367 behind so that clients don't need to rewrite their existing code.
369 \fB\(bu\fR Use opaque data types
371 The fewer data type definitions a client has access to, the
372 better. If possible, design your functions to accept a generic
373 pointer (which you can cast to an internal data type), and provide
374 access functions rather than allowing the client to directly
375 manipulate the data. That way, you have the freedom to change the
376 data structures without changing the interface.
378 \fB\(bu\fR Use header files
380 If you write each of your library's global functions and variables in
381 header files, and include them in your library source files, then the
382 compiler will let you know if you make any interface changes by
385 \fB\(bu\fR Use \fBstatic\fRs (or equivalent) whenever possible
387 The fewer global functions your library has, the more flexibility
388 you will have in changing them. \fBstatic\fR functions and variables may
389 change as often as you like, since clients cannot access them and therefore
390 they aren't considered interface changes.
391 .SH WRITING AUTOMAKE RULES
392 \fBlibtool\fR library support is implemented under the \fBLTLIBRARIES\fR
395 To link a program against a \fBlibtool\fR library, just use the
396 \fIprogram\fB_LDADD\fR variable to specify the library name. You may use
397 \fIprogram\fB_LDFLAGS\fR to pass any options to libtool, such as
400 To build a \fBlibtool\fR library, use \fIlib\fB_LTLIBRARIES\fR to specify the
401 library name and \fB, and, for example, \fIlib\fB_LDFLAGS\fR to pass the
402 \fB\-version\-info\fR option to \fBlibtool\fR. You will find an example in
405 You will also have to include some basic files in your package, or use
406 \fBlibtoolize\fR to do the work for you. Do not include the \fBlibtool\fR
410 Attempt to guess a canonical system name.
413 Canonical system name validation subroutine script.
416 Generate a libtool script for a given system.
419 A generic script implementing basic libtool functionality.
420 .SH DLOPENING MODULES
421 To use \fBlibtool\fR's dlopening support, you must use the macro
422 \fBAC_LIBTOOL_DLOPEN\fR in your \fBconfigure.in\fR, before
423 \fBAM_PROG_LIBTOOL\fR. Otherwise \fBlibtool\fR will assume there's no
424 dlopening mechanism available on the platform and will simulate it.
425 In order to use this simulation feature you must declare the objects you
426 want to dlopen by using the \fB\-dlopen\fR and \fB\-dlreopen\fR flags when
427 linking your executable. \fBlibtool\fR will link the object files and create
428 data structures holding the executable's symbol table:
432 struct lt_dlsymlist { const char *NAME; lt_ptr_t ADDRESS; }
436 \fINAME\fR holds an asciiz string with the symbol name, such as "fprintf".
437 \fIADDRESS\fR is a generic pointer to the appropriate object, such as
442 const lt_dlsymlist * lt_preloaded_symbols;
446 This array represents all the preloaded symbols linked into the executable.
447 For each \fB\-dlpreloaded\fR file there is an element with the \fINAME\fR of
448 the file and a \fIADDRESS\fR of `\fB0\fR', followed by all symbols exported from
449 this file. For the executable itself the special name \fB@PROGRAM@\fR is used.
450 The last element has a \fINAME\fR and \fIADDRESS\fR of `\fB0\fR'.
453 When linking either a library that is going to be dlopened or an executable
454 that is going to dlopen a module, remember to specify the \fB\-module\fR
457 If an executable needs to reference an external symbol of a library that you
458 are going to dlopen, use \fB\-export\-dynamic\fR when linking the executable.
460 Due variations in library names, your program needs to determine which is
461 the correct file to dlopen. A straightforward approach is to examine the
462 `\fB.la\fR' files, looking for the \fBdlname='\fIDLNAME\fB'\fR line, where
463 \fBDLNAME\fR is either empty if the library can't be dlopened, or holds the
464 dlname of the library.
467 We are about to create a library called `libbaz' from the source files
468 `foo.c', `bar.c', and then link `a.c' with `libbaz' to create an executable
470 .SS Creating The Library
471 \fB\(bu\fR Compile mode: since Linux supports shared libraries, \fBlibtool\fR
472 will generate two object files: one for the static library (`foo.lo') and
473 one for the shared library (`foo.o'). The \fB\-c\fR option is mandatory,
474 since we don't want the compiler to do the linking on its own.
478 lightside:~% libtool cc \-c foo.c
479 cc \-c \-fPIC \-DPIC foo.c -o .libs/foo.lo
480 cc \-c foo.c >/dev/null 2>&1
481 lightside:~% libtool cc -c bar.c
482 cc \-c \-fPIC \-DPIC bar.c -o .libs/bar.lo
483 cc \-c bar.c >/dev/null 2>&1
487 \fB\(bu\fR Link mode, build only a static library: We specify the `.o'
488 object files generated previously. The \fB\-o\fR option is mandatory.
492 lightside:~% libtool cc -o libbaz.a foo.o bar.o
493 ar cru libbaz.a foo.o bar.o
498 \fB\(bu\fR Link mode, build static and shared libraries: We specify the
499 `.lo' object files. Mandatory options are \fB\-o\fR like before, and
500 \fB\-rpath\fR to indicate which will be the installation directory for our
501 library. The library will be created in the `.libs' directory.
505 lightside:~% libtool cc \-o libbaz.la foo.lo bar.lo \e
506 \-rpath /usr/local/lib
507 cc \-shared \-Wl,\-soname \-Wl,libbaz.so.0 \e
508 \-o .libs/libbaz.so.0.0.0 foo.lo bar.lo
509 (cd .libs && ln \-s libbaz.so.0.0.0 libbaz.so.0)
510 (cd .libs && ln \-s libbaz.so.0.0.0 libbaz.so)
511 ar cru .libs/libbaz.a foo.o bar.o
512 ranlib .libs/libbaz.a
514 (cd .libs && ln \-s ../libbaz.la libbaz.la)
518 \fB\(bu\fR Install mode: This will run the necessary commands to install the
519 library in the specified path (in our case, `/usr/local/lib'). It will
520 install the shared (`.so') and static (`.a') libraries, as well as the
521 libtool file (`.la'), for unistallation and informational purposes.
523 Since this is often done as a privileged user, it's useful to specify the
524 \fB\-n\fR or \fB\-\-dry\-run\fR option to check the results.
528 lightside:/tmp% libtool \-n install libbaz.la /usr/local/lib
529 install .libs/libbaz.so.0.0.0 /usr/local/lib/libbaz.so.0.0.0
530 (cd /usr/local/lib && ln \-s libbaz.so.0.0.0 libbaz.so.0)
531 (cd /usr/local/lib && ln \-s libbaz.so.0.0.0 libbaz.so)
532 install libbaz.la /usr/local/lib/libbaz.la
533 install .libs/libbaz.a /usr/local/lib/libbaz.a
534 ranlib /usr/local/lib/libbaz.a
535 chmod 644 /usr/local/lib/libbaz.a
539 .SS Creating the Executable
540 First we compile `a.c'
548 If the library has already been installed you can proceed as usual
552 cc a.c \-lbaz \-L/usr/local/lib
556 If the library hasn't been installed yet, \fBlibtool\fR must be used to
557 do the linking, debugging and installation of the executable (this last thing,
558 once the library has been installed). Note that the real executable will be
559 in `.libs' until it is installed, and the the executable on the work
560 directory is merely a wrapper.
562 In order to avoid ambiguities, never use \fB\-l\fR or \fB\-L\fR to link
563 against an uninstalled shared library. Just specify the path to the `.la'
564 file. Installed libraries aren't a problem, as we see below (`\-lm').
568 lightside:~% libtool cc a.o libbaz.la \-o a -lm
569 cc a.o \-Wl,\-\-rpath \-Wl,/usr/local/lib \e
570 .libs/libbaz.so \-o .libs/a -lm
571 lightside:~% libtool gdb a
572 [snipped hairy debugging session]
573 lightside:~% libtool install \-c a /usr/local/bin/a
574 install \-c .libs/a /usr/local/bin/a
578 .SS Creating Makefile.am
579 \fB\(bu\fR\ First create a brief \fBconfigure.in\fR, remembering to add the
580 macros for \fBautomake\fR and \fBlibtool\fR.
584 AC_DEFUN(AM_INIT_AUTOMAKE)
586 AM_INIT_AUTOMAKE(a, 1.0)
593 \fB\(bu\fR\ Then the corresponding \fBMakefile.am\fR
598 lib_LTLIBRARIES=libbaz.la
599 libbaz_la_SOURCES = foo.c bar.c
600 libbaz_la_LDFLAGS = -version-info 0:0:0
602 bin_PROGRAMS = a a.debug
604 # Build a from a.c and libbaz.la
608 # Create a static debugging version
609 a_debug_SOURCES = a.c
610 a_debug_LDADD = libbaz.la
611 a_debug_LDFLAGS = \-static
615 \fB\(bu\fR\ And finally give it a try
619 lightside:~% aclocal; libtoolize; automake \-\-add\-missing; autoconf
620 lightside:~% ./configure; make
625 \fBlibtoolize\fR(1), \fBlibltdl\fR(3)
627 Report bugs to <bug-libtool@gnu.org>.
629 Man page by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
OSDN Git Service
