README
1GNU Libtool
2***********
3
4Introduction
5============
6
7This is GNU Libtool, a generic library support script. Libtool hides
8the complexity of using shared libraries behind a consistent, portable
9interface.
10
11To use libtool, add the new generic library building commands to your
12Makefile, Makefile.in, or Makefile.am. See the documentation for
13details.
14
15See the info node (libtool)Tested Platforms. (or the file
16doc/PLATFORMS) for a list of platforms that libtool supports.
17
18Libtool's home page is:
19
20 http://www.gnu.org/software/libtool/libtool.html
21
22See the file NEWS for a description of recent changes to libtool.
23
24See the file INSTALL for instructions on how to build and install
25libtool.
26
27Version Numbering
28=================
29
30Note the version numbers in the libtool-1.5.x series are a little strange,
31the micro version (x) jumps by two on each release. The version in cvs always
32has an odd micro version, while only released versions have even micro versions.
33This will change again in the future. For more information about version
34numbers see:
35
36 http://www.gnu.org/software/libtool/contribute.html
37
38
39Reporting Bugs
40==============
41
42If you have any suggestions or bug reports, or you wish to port
43libtool to a new platform, please send electronic mail to the libtool
44mailing list <libtool@gnu.org> or bug reports to <bug-libtool@gnu.org>.
45Be sure to include the version of libtool that you are using - you can find
46out with `./libtool --version'. Also give as much information as necessary on
47your OS, compiler and other build tools.
48
49
50The Test Suite
51==============
52
53Libtool comes with an integrated set of tests to check that your build
54is sane. You can run the entire suite like this:
55
56 make check
57
58The tests run in groups in the various demo subdirectories, so if one
59of the tests early in a group FAILs, the rest of the tests in that
60group will be SKIPPED. If you see a FAIL further into a group, even
61if a test with the same name PASSes in another test group, you need to
62take note of the name of the first test in the group if you want to
63rerun the group with FAILures to get verbose output.
64
65To run a test group in isolation (say, you think you have fixed a bug,
66but don't want to rerun the entire suite), you can do it like this:
67
68 env TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' make check
69
70Providing that you have a FAIL from the most recent group from a
71particular demo directory (like the cdemo-static.test group above), you
72can explore the state of the directory to help with debugging.
73
74If you wish to report a test group failure to the libtool list, you
75need to send the verbose output of the FAILing group, along with
76information such as the host OS, compiler tools, shell etc. to the
77bug report mailing list, <bug-libtool@gnu.org>. You can generate verbose
78test output like this:
79
80 env VERBOSE=1 TESTS='cdemo-static.test cdemo-make.test cdemo-exec.test' \
81 make check
82
83Alternatively, because each test is a shell script, in a non VPATH build,
84you can simply execute the tests, they will be verbose.
85
86Notes
87=====
88
891) Some HP-UX sed programs are horribly broken, and cannot handle
90libtool's requirements, so users may report unusual problems. There
91is no workaround except to install a working sed (such as GNU sed) on
92these systems.
93
942) The vendor-distributed NCR MP-RAS cc programs emits copyright
95on standard error that confuse tests on size of conftest.err. The
96workaround is to specify CC when run configure with CC='cc -Hnocopyr'.
97
983) Any earlier DG/UX system with ELF executables, such as R3.10 or
99R4.10, is also likely to work, but hasn't been explicitly tested.
100
1014) On Reliant Unix libtool has only been tested with the Siemens C-compiler
102and an old version of gcc provided by Marco Walther.
103
1045) libtool.m4, ltdl.m4 and the configure.ac files are marked to use
105autoconf-mode, which is distributed with GNU Emacs 21, Autoconf itself, and
106all recent releases of XEmacs.
107
1086) The default shell on UNICOS 9, a ksh 88e variant, is too buggy to
109correctly execute the libtool script. Users are advised to install a
110modern shell such as GNU bash.
111
1127) Note in some cases you might need to put ABI-changing compiler flags
113into the compiler name. For example, use of
114 configure CC='gcc -m32'
115rather than
116 configure CC=gcc CFLAGS=-m32 LDFLAGS=-m32
117might help with this Libtool release. This will be fixed in Libtool-2.0.
118
1198) Note that use of libltdl and a native dlopening mechanism for the
120same module within one program is not supported. This includes modules
121loaded through inter-module dependencies.
122
1239) Note that newer Sun Studio Fortran compilers might need Autoconf macros
124not yet present in 2.59 but only in CVS Autoconf.
125
12610) Note that Sun C++ compiler versions before 5.6 may need some special
127setup to link properly against shared versions of the C++ standard libraries.
128See http://lists.gnu.org/archive/html/libtool/2005-08/msg00088.html for
129more information.
130