README

   1 GNU Libtool
   2 ***********
   3
   4 1. Introduction
   5 ===============
   6
   7 This is GNU Libtool, a generic library support script.  Libtool hides
   8 the complexity of using shared libraries behind a consistent, portable
   9 interface.
  10
  11 To use Libtool, add the new generic library building commands to your
  12 Makefile, Makefile.in, or Makefile.am.  See the documentation for
  13 details.
  14
  15 Libtool's home page is:
  16
  17   http://www.gnu.org/software/libtool/libtool.html
  18
  19 See the file NEWS for a description of recent changes to Libtool.
  20
  21 See the file INSTALL for generic instructions on how to build and install
  22 Libtool.  Please see the file doc/notes.txt for some platform-specific
  23 information.  Please note that you need GNU make to build Libtool.
  24
  25 See the info node (libtool)Tested Platforms. (or the file
  26 doc/PLATFORMS) for a list of platforms that Libtool supports.
  27
  28
  29 2. Reporting Bugs
  30 =================
  31
  32 If you have any suggestions or bug reports, or you wish to port Libtool
  33 to a new platform, please send electronic mail to the libtool mailing
  34 list <libtool@gnu.org> or bug reports to <bug-libtool@gnu.org>.  Be sure
  35 to send us your information from the end of the help message given by
  36 `./libtool --help'.
  37
  38
  39 3. The Test Suites
  40 ==================
  41
  42 Libtool comes with two integrated sets of tests to check that your build
  43 is sane.  You can run both test suites like this, assuming that `gmake'
  44 refers to GNU make:
  45
  46   gmake -k check
  47
  48 If you want to run the old testsuite only, do it like this:
  49
  50   gmake check TESTSUITEFLAGS=-V
  51
  52 If you want to run the new testsuite only, do it like this:
  53
  54   gmake check-local
  55
  56 The tests of the old test suite run in groups in the various demo
  57 subdirectories, so if one of the tests early in a group FAILs, the rest
  58 of the tests in that group will be SKIPped.  If you see a FAIL further
  59 into a group, even if a test with the same name PASSes in another test
  60 group, you need to take note of the name of the first test in the group
  61 if you want to rerun the group with FAILures to get verbose output.
  62
  63 To run a test group of the old test suite in isolation (say, you think
  64 you have fixed a bug, but don't want to rerun the entire suite), you can
  65 do it like this:
  66
  67   gmake check TESTS="tests/cdemo-static.test tests/cdemo-make.test \
  68                      tests/cdemo-exec.test" \
  69               TESTSUITEFLAGS=-V
  70
  71 Providing that you have a FAIL from the most recent group from a
  72 particular demo directory (like the cdemo-static.test group above), you
  73 can explore the state of the directory to help with debugging.
  74
  75 If you wish to report a test group failure to the libtool list, you need
  76 to send the verbose output of the FAILing group, along with the
  77 information from the end of `$(top_builddir)/libtool --help' to the bug
  78 report mailing list, <bug-libtool@gnu.org> with a subject line that
  79 includes the string `[TEST FAILURE]'.  From a Bourne compatible shell,
  80 you can generate verbose test output like this:
  81
  82   VERBOSE=yes gmake check \
  83   TESTS="tests/cdemo-static.test tests/cdemo-make.test tests/cdemo-exec.test" \
  84   TESTSUITEFLAGS=-V | tee cdemo-static-group.log
  85
  86 In order to enable debug shell tracing, use VERBOSE=debug instead of
  87 VERBOSE=yes.
  88
  89
  90 In the long run, Libtool will move to using only the new,
  91 Autotest-driven testsuite.  Its usage is documented in
  92
  93   info Autoconf 'testsuite Invocation'
  94
  95 but simple help may also be obtained through
  96
  97   gmake check-local TESTSUITEFLAGS='--help'
  98
  99 For verbose output, add the flag `-v', for running only a subset of the
 100 independent tests, merely specify them by number or by keyword, both of
 101 which are displayed with the `--list' flag.  For example, the `libtool'
 102 keyword is used for the tests that exercise only this script.  So it is
 103 possible to test an installed script, possibly from a different Libtool
 104 release, with
 105   gmake check-local TESTSUITEFLAGS="-k libtool LIBTOOL=/path/to/libtool"
 106
 107 If you wish to report test failures to the libtool list, you need to
 108 send the file `tests/testsuite.log' to the bug report mailing list,
 109 <bug-libtool@gnu.org>.
 110
 111 4. Version Numbering
 112 ====================
 113
 114 People have complained that they find the version numbering scheme under
 115 which libtool is released confusing... so we've changed it!
 116
 117 It works like this:
 118
 119         <major-number>.<minor-number>
 120
 121 Releases with a <major-number> less than 1 were not yet feature
 122 complete.  Releases with a <major-number> of 1 used the old numbering
 123 scheme that everyone disliked so much.  Releases with a <major-number>
 124 of 2 us the new scheme described here.  If libtool ever undergoes a
 125 major rewrite or substantial restructuring, the <major-number> will be
 126 incremented again.
 127
 128 If we make a patch release to fix bugs in a stable release, we use a
 129 third number, so:
 130
 131       <major-number>.<minor-number>.<micro-number>
 132
 133 Version numbers are chosen to make it easy for users to decide two
 134 things:
 135
 136   Q: How `developed' is this release?
 137   A: The higher the number, the better!
 138   Q: How `stable' is this release?
 139   A: - If the <minor-number> is even, it is a stable release, `2.0'.
 140      - If the <minor-number> is odd, it is a development version with
 141        new features compared to the last stable release, `2.1a'.
 142      - If it has an `odd'[1] letter after the version number,  it is a
 143        snapshot direct from CVS, `2.1a'.
 144      - If it has an `even'[1] letter after the version number, it is an
 145        alpha quality release, `2.1b'.
 146      - If it has three numbers in the version, it is a patch release,
 147        fixing bugs from the stable release (with no new features), `2.0.1'.
 148
 149 [1] We always increment the letter in the repository before *and* after
 150     making a release tarball.  This means that "odd" letters
 151     (a,c,e,g...) only exist in the repository, and "even" letters are
 152     used instantaneously for an alpha release.  Since the odd lettered
 153     version numbers cover many states of the tree, we also qualify them
 154     by adding the cvs version of the ChangeLog:
 155
 156     $ libtool --version
 157     ltmain.sh (GNU libtool 1.1603 2004/09/12 22:02:07) 2.1a
 158
 159     Copyright (C) 2004  Free Software Foundation, Inc.
 160     This is free software; see the source for copying conditions.  There is NO
 161     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 162
 163 For more details about version numbers, see:
 164
 165     http://www.gnu.org/software/libtool/contribute.html
 166
 167 --
 168   Copyright (C) 2004, 2005, 2006, 2007, 2008  Free Software Foundation, Inc.
 169   Written by Gary V. Vaughan, 2004
 170
 171   This file is part of GNU Libtool.
 172
 173 GNU Libtool is free software; you can redistribute it and/or
 174 modify it under the terms of the GNU General Public License as
 175 published by the Free Software Foundation; either version 2
 176 of the License, or (at your option) any later version.
 177
 178 GNU Libtool is distributed in the hope that it will be useful,
 179 but WITHOUT ANY WARRANTY; without even the implied warranty of
 180 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 181 GNU General Public License for more details.
 182
 183 You should have received a copy of the GNU General Public License
 184 along with GNU Libtool; see the file COPYING.  If not, a copy
 185 can be downloaded from http://www.gnu.org/licenses/gpl.html, or
 186 obtained by writing to the Free Software Foundation, Inc.,
 187 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
 188
 189
 190 Local Variables:
 191 mode: text
 192 fill-column: 72
 193 End:
 194 vim:tw=72