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 Libtool's home page is:
  12
  13     http://www.gnu.org/software/libtool/libtool.html
  14
  15 See the file NEWS for a description of recent changes to Libtool.
  16
  17 Please note that you can build GNU Libtool from this directory using a
  18 vendor Make program as long as this is an official release tarball;
  19 otherwise you will need GNU Make for sane VPATH support.  See the file
  20 INSTALL for complete generic instructions on how to build and install
  21 Libtool.  Also, see the file doc/notes.txt for some platform- specific
  22 information.
  23
  24 See the info node (libtool)Tested Platforms. (or the file doc/PLATFORMS)
  25 for a list of platforms that Libtool already supports.
  26
  27 Please try it on all the platforms you have access to:
  28
  29  * If it builds and passes the test suite (`gmake check'), please send
  30    a short note to the libtool mailing list <libtool@gnu.org> with a
  31    subject line including the string `[PLATFORM]', and containing the
  32    details from the end of `./libtool --help' in the body.
  33  * Otherwise, see `Reporting Bugs' below for how to help us fix any
  34    problems you discover.
  35
  36 To use Libtool, add the new generic library building commands to your
  37 Makefile, Makefile.in, or Makefile.am.  See the documentation for
  38 details.
  39
  40
  41 2. Reporting Bugs
  42 =================
  43
  44 If this distribution doesn't work for you, before you report the
  45 problem, at least try upgrading to the latest released version first,
  46 and see whether the issue persists.  If you feel able, you can also
  47 check whether the issue has been fixed in the development sources for
  48 the next release (see `Obtaining the Latest Sources' below).
  49
  50 Once you've determined that your bug is still not fixed in the latest
  51 version, please send a full report to <bug-libtool@gnu.org>, including:
  52
  53   1. the information from the end of the help message given by
  54      `./libtool --help', and the verbose output of any failed tests
  55      (see `The Test Suites' immediately below);
  56   2. complete instructions for how to reproduce your bug, along with
  57      the results you were expecting, and how they differ from what you
  58      actually see;
  59   3. a workaround or full fix for the bug, if you have it;
  60   4. a copy of `tests/testsuite.log' if you are experiencing failures
  61      in the Autotest testsuite.
  62   5. new test cases for the testsuite that demonstrate the bug are
  63      especially welcome, and will help to ensure that future releases
  64      don't reintroduce the problem - if you're not able to write a
  65      complete testsuite case, a simple standalone shell script is
  66      usually good enough to help us write a test for you.
  67
  68 If you have any other suggestions, or if you wish to port Libtool to a
  69 new platform, please send email to the mailing list <libtool@gnu.org>.
  70
  71 Please note that if you send us an non-trivial code for inclusion in a
  72 future release, we may ask you for a copyright assignment (for brief
  73 details see the `Copyright Assignment' section on our `Contributing'
  74 webpage <http://www.gnu.org/software/libtool/contribute.html>).
  75
  76
  77 3. The Test Suites
  78 ==================
  79
  80 Libtool comes with two integrated sets of tests to check that your build
  81 is sane.  You can run both test suites like this, assuming that `gmake'
  82 refers to GNU make:
  83
  84     gmake -k check
  85
  86 If you want to run the old testsuite only, do it like this:
  87
  88     gmake check TESTSUITEFLAGS=-V
  89
  90 If you want to run the new testsuite only, do it like this:
  91
  92     gmake check-local
  93
  94 The tests of the old test suite run in groups in the various demo
  95 subdirectories, so if one of the tests early in a group FAILs, the rest
  96 of the tests in that group will be SKIPped.  If you see a FAIL further
  97 into a group, even if a test with the same name PASSes in another test
  98 group, you need to take note of the name of the first test in the group
  99 if you want to rerun the group with FAILures to get verbose output.
 100
 101 To run a test group of the old test suite in isolation (say, you think
 102 you have fixed a bug, but don't want to rerun the entire suite), you can
 103 do it like this:
 104
 105     gmake check TESTSUITEFLAGS=-V TESTS="tests/cdemo-static.test \
 106         tests/cdemo-static-make.test tests/cdemo-static-exec.test"
 107
 108 Providing that you have a FAIL from the most recent group from a
 109 particular demo directory (like the cdemo-static.test group above), you
 110 can explore the state of the directory to help with debugging.
 111
 112 If you wish to report a test group failure to the libtool list, you need
 113 to send the verbose output of the FAILing group, along with the
 114 information from the end of `$(top_builddir)/libtool --help' to the bug
 115 report mailing list, <bug-libtool@gnu.org> with a subject line that
 116 includes the string `[TEST FAILURE]'.  The file test-suite.log contains
 117 the verbose output from all failed tests.
 118
 119 In order to enable debug shell tracing, you can set VERBOSE=debug when
 120 running the old test suite.
 121
 122 In the long run, Libtool will move to using only the new, Autotest-
 123 driven testsuite.  Its usage is documented in:
 124
 125     info Autoconf 'testsuite Invocation'
 126
 127 but simple help may also be obtained through:
 128
 129     gmake check-local TESTSUITEFLAGS='--help'
 130
 131 For verbose output, add the flag `-v', for running only a subset of the
 132 independent tests, merely specify them by number or by keyword, both of
 133 which are displayed with the `--list' flag.  For example, the `libtool'
 134 keyword is used for the tests that exercise only this script.  So it is
 135 possible to test an installed script, possibly from a different Libtool
 136 release, with:
 137
 138     gmake check-local \
 139         TESTSUITEFLAGS="-k libtool LIBTOOL=/path/to/libtool"
 140
 141 Some tests, like the one exercising max_cmd_len limits, make use of this
 142 to invoke the testsuite recursively on a subset of tests.  For these
 143 tests, the variable INNER_TESTSUITEFLAGS may be used.  It will be
 144 expanded right after the `-k libtool', without separating whitespace, so
 145 that further limiting of the recursive set of tests is possible.  For
 146 example, to run only the template tests within the max_cmd_len, use:
 147
 148     gmake check-local TESTSUITEFLAGS="-v -x -k max_cmd_len \
 149                       INNER_TESTSUITEFLAGS=',template -v -x'"
 150
 151 If you wish to report test failures to the libtool list, you need to
 152 send the file `tests/testsuite.log' to the bug report mailing list,
 153 <bug-libtool@gnu.org>.
 154
 155
 156 4. Obtaining the Latest Sources
 157 ===============================
 158
 159 * With the exception of ancient releases, all official GNU Libtool
 160   releases have a detached GPG signature file.  With this you can verify
 161   that the corresponding file (i.e. without the `.sig' suffix) is the
 162   same file that was released by the owner of it's GPG key ID.  First,
 163   be sure to download both the .sig file and the corresponding release,
 164   then run a command like this:
 165
 166     gpg --verify libtool-x.y.z.tar.gz.sig
 167
 168   If that command fails because you don't have the required public key,
 169   then run this command to import it:
 170
 171     gpg --keyserver keys.gnupg.net --recv-keys 2983D606
 172
 173   and then rerun the `gpg --verify' command.
 174
 175 * Official stable releases of GNU Libtool, along with these detached
 176   signature files are available from:
 177
 178     ftp://ftp.gnu.org/gnu/libtool
 179
 180   To reduce load on the main server, please use one of the mirrors
 181   listed at:
 182
 183     http://www.gnu.org/order/ftp.html
 184
 185 * Alpha quality pre-releases of GNU Libtool, also with detached
 186   signature files are available from:
 187
 188     ftp://alpha.gnu.org/gnu/libtool
 189
 190   and some of the mirrors listed at:
 191
 192     http://www.gnu.org/order/ftp.html
 193
 194 * Nightly snapshots of the unreleased development trunk of GNU Libtool
 195   are available from:
 196
 197     http://pogma.com/libtool
 198
 199   These files do not have signatures, but will allow you to easily
 200   determine whether the most recent development code still exhibits any
 201   bugs you have discovered, without requiring you to install a complete
 202   build environment and the extra tools needed to bootstrap a version
 203   control checkout.
 204
 205 * The master libtool repository is stored in git.
 206
 207   If you are a member of the savannah group for GNU Libtool, a writable
 208   copy of the libtool repository can be obtained by:
 209
 210     git clone <savannah-user>@git.sv.gnu.org:/srv/git/libtool.git
 211
 212   If you are behind a firewall that blocks the git protocol, you may
 213   find it useful to use
 214
 215     git config --global url.http://git.sv.gnu.org/r/.insteadof \
 216       git://git.sv.gnu.org/
 217
 218   to force git to transparently rewrite all savannah git references to
 219   use http.
 220
 221   If you are not a member of the savannah group for GNU Libtool, you can
 222   still fetch a read-only copy with either:
 223
 224     git clone git://git.sv.gnu.org/libtool.git
 225
 226   or using the CVS pserver protocol:
 227
 228     cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/libtool.git \
 229         co -d libtool HEAD
 230
 231 * Before you can build from git, you need to bootstrap.  This requires:
 232   - Autoconf 2.62 or later
 233   - Automake 1.11.1 or later
 234   - Help2man 1.29 or later
 235   - Xz 4.999.8beta or later (from <http://tukaani.org/xz>)
 236   - Texinfo 4.8 or later
 237   - Any prerequisites of the above (such as m4, perl, tex)
 238
 239   Note that these bootstrapping dependencies are much stricter than
 240   those required to use a destributed release for your own packages.
 241   After installation, GNU Libtool is designed to work either standalone,
 242   or optionally with:
 243   - Autoconf 2.59 or later
 244   - Automake 1.9.6 or later
 245
 246 * The `bootstrap' script sets up the source directory for you to hack,
 247   though it may take quite some time to run.  If you don't intend to
 248   re-run the test suite, you can speed up the `bootstrap' step by an
 249   order of magnitude if you call it like this instead:
 250
 251     reconfdirs='. libltdl' ./bootstrap
 252
 253
 254 5. Version Numbering
 255 ====================
 256
 257 People have complained that they find the version numbering scheme under
 258 which libtool is released confusing... so we've changed it!
 259
 260 It works like this:
 261
 262         <major-number>.<minor-number>
 263
 264 Releases with a <major-number> less than 1 were not yet feature
 265 complete.  Releases with a <major-number> of 1 used the old numbering
 266 scheme that everyone disliked so much.  Releases with a <major-number>
 267 of 2 us the new scheme described here.  If libtool ever undergoes a
 268 major rewrite or substantial restructuring, the <major-number> will be
 269 incremented again.
 270
 271 If we make a patch release to fix bugs in a stable release, we use a
 272 third number, so:
 273
 274       <major-number>.<minor-number>.<micro-number>
 275
 276 Version numbers are chosen to make it easy for users to decide two
 277 things:
 278
 279   Q: How `developed' is this release?
 280   A: The higher the number, the better!
 281   Q: How `stable' is this release?
 282   A: - If the <minor-number> is even, it is a stable release, `2.0'.
 283      - If the <minor-number> is odd, it is a development version with
 284        new features compared to the last stable release, `2.1a'.
 285      - If it has an `odd'[1] letter after the version number,  it is a
 286        snapshot direct from CVS, `2.1a'.
 287      - If it has an `even'[1] letter after the version number, it is an
 288        alpha quality release, `2.1b'.
 289      - If it has three numbers in the version, it is a patch release,
 290        fixing bugs from the stable release (with no new features), `2.0.1'.
 291
 292 [1] We always increment the letter in the repository before *and* after
 293     making a release tarball.  This means that "odd" letters
 294     (a,c,e,g...) only exist in the repository, and "even" letters are
 295     used instantaneously for an alpha release.  Since the odd lettered
 296     version numbers cover many states of the tree, we also qualify them
 297     by adding the cvs version of the ChangeLog:
 298
 299     $ libtool --version
 300     ltmain.sh (GNU libtool 1.1603 2004/09/12 22:02:07) 2.1a
 301
 302     Copyright (C) 2004  Free Software Foundation, Inc.
 303     This is free software; see the source for copying conditions.  There is NO
 304     warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 305
 306 For more details about version numbers, see:
 307
 308     http://www.gnu.org/software/libtool/contribute.html
 309 --
 310   Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
 311   Foundation, Inc.
 312   Written by Gary V. Vaughan, 2004
 313
 314   This file is part of GNU Libtool.
 315
 316 Copying and distribution of this file, with or without modification,
 317 are permitted in any medium without royalty provided the copyright
 318 notice and this notice are preserved.  This file is offered as-is,
 319 without warranty of any kind.
 320
 321
 322 Local Variables:
 323 mode: text
 324 fill-column: 72
 325 End:
 326 vim:tw=72