libtool/README

GNU Libtool
***********

1. Introduction
===============

This is GNU Libtool, a generic library support script.  Libtool hides
the complexity of using shared libraries behind a consistent, portable
interface.

Libtool's home page is:

    http://www.gnu.org/software/libtool/libtool.html

See the file NEWS for a description of recent changes to Libtool.

Please note that you can build GNU Libtool from this directory using a
vendor Make program as long as this is an official release tarball;
otherwise you will need GNU Make for sane VPATH support.  See the file
INSTALL for complete generic instructions on how to build and install
Libtool.  Also, see the file doc/notes.txt for some platform- specific
information.

See the info node (libtool)Tested Platforms. (or the file doc/PLATFORMS)
for a list of platforms that Libtool already supports.

Please try it on all the platforms you have access to:

 * If it builds and passes the test suite (`gmake check'), please send
   a short note to the libtool mailing list <libtool@gnu.org> with a
   subject line including the string `[PLATFORM]', and containing the
   details from the end of `./libtool --help' in the body.
 * Otherwise, see `Reporting Bugs' below for how to help us fix any
   problems you discover.

To use Libtool, add the new generic library building commands to your
Makefile, Makefile.in, or Makefile.am.  See the documentation for
details.


2. Reporting Bugs
=================

If this distribution doesn't work for you, before you report the
problem, at least try upgrading to the latest released version first,
and see whether the issue persists.  If you feel able, you can also
check whether the issue has been fixed in the development sources for
the next release (see `Obtaining the Latest Sources' below).

Once you've determined that your bug is still not fixed in the latest
version, please send a full report to <bug-libtool@gnu.org>, including:

  1. the information from the end of the help message given by
     `./libtool --help', and the verbose output of any failed tests
     (see `The Test Suites' immediately below);
  2. complete instructions for how to reproduce your bug, along with
     the results you were expecting, and how they differ from what you
     actually see;
  3. a workaround or full fix for the bug, if you have it;
  4. a copy of `tests/testsuite.log' if you are experiencing failures
     in the Autotest testsuite.
  5. new test cases for the testsuite that demonstrate the bug are
     especially welcome, and will help to ensure that future releases
     don't reintroduce the problem - if you're not able to write a
     complete testsuite case, a simple standalone shell script is
     usually good enough to help us write a test for you.

If you have any other suggestions, or if you wish to port Libtool to a
new platform, please send email to the mailing list <libtool@gnu.org>.

Please note that if you send us an non-trivial code for inclusion in a
future release, we may ask you for a copyright assignment (for brief
details see the `Copyright Assignment' section on our `Contributing'
webpage <http://www.gnu.org/software/libtool/contribute.html>).


3. The Test Suites
==================

Libtool comes with two integrated sets of tests to check that your build
is sane.  You can run both test suites like this, assuming that `gmake'
refers to GNU make:

    gmake -k check

If you want to run the old testsuite only, do it like this:

    gmake check TESTSUITEFLAGS=-V

If you want to run the new testsuite only, do it like this:

    gmake check-local

The tests of the old test suite run in groups in the various demo
subdirectories, so if one of the tests early in a group FAILs, the rest
of the tests in that group will be SKIPped.  If you see a FAIL further
into a group, even if a test with the same name PASSes in another test
group, you need to take note of the name of the first test in the group
if you want to rerun the group with FAILures to get verbose output.

To run a test group of the old test suite in isolation (say, you think
you have fixed a bug, but don't want to rerun the entire suite), you can
do it like this:

    gmake check TESTSUITEFLAGS=-V TESTS="tests/cdemo-static.test \
        tests/cdemo-static-make.test tests/cdemo-static-exec.test"

Providing that you have a FAIL from the most recent group from a
particular demo directory (like the cdemo-static.test group above), you
can explore the state of the directory to help with debugging.

If you wish to report a test group failure to the libtool list, you need
to send the verbose output of the FAILing group, along with the
information from the end of `$(top_builddir)/libtool --help' to the bug
report mailing list, <bug-libtool@gnu.org> with a subject line that
includes the string `[TEST FAILURE]'.  The file test-suite.log contains
the verbose output from all failed tests.

In order to enable debug shell tracing, you can set VERBOSE=debug when
running the old test suite.

In the long run, Libtool will move to using only the new, Autotest-
driven testsuite.  Its usage is documented in:

    info Autoconf 'testsuite Invocation'

but simple help may also be obtained through:

    gmake check-local TESTSUITEFLAGS='--help'

For verbose output, add the flag `-v', for running only a subset of the
independent tests, merely specify them by number or by keyword, both of
which are displayed with the `--list' flag.  For example, the `libtool'
keyword is used for the tests that exercise only this script.  So it is
possible to test an installed script, possibly from a different Libtool
release, with:

    gmake check-local \
        TESTSUITEFLAGS="-k libtool LIBTOOL=/path/to/libtool"

Some tests, like the one exercising max_cmd_len limits, make use of this
to invoke the testsuite recursively on a subset of tests.  For these
tests, the variable INNER_TESTSUITEFLAGS may be used.  It will be
expanded right after the `-k libtool', without separating whitespace, so
that further limiting of the recursive set of tests is possible.  For
example, to run only the template tests within the max_cmd_len, use:

    gmake check-local TESTSUITEFLAGS="-v -x -k max_cmd_len \
		      INNER_TESTSUITEFLAGS=',template -v -x'"

If you wish to report test failures to the libtool list, you need to
send the file `tests/testsuite.log' to the bug report mailing list,
<bug-libtool@gnu.org>.


4. Obtaining the Latest Sources
===============================

* With the exception of ancient releases, all official GNU Libtool
  releases have a detached GPG signature file.  With this you can verify
  that the corresponding file (i.e. without the `.sig' suffix) is the
  same file that was released by the owner of it's GPG key ID.  First,
  be sure to download both the .sig file and the corresponding release,
  then run a command like this:

    gpg --verify libtool-x.y.z.tar.gz.sig

  If that command fails because you don't have the required public key,
  then run this command to import it:

    gpg --keyserver keys.gnupg.net --recv-keys 2983D606

  and then rerun the `gpg --verify' command.

* Official stable releases of GNU Libtool, along with these detached
  signature files are available from:

    ftp://ftp.gnu.org/gnu/libtool

  To reduce load on the main server, please use one of the mirrors
  listed at:

    http://www.gnu.org/order/ftp.html

* Alpha quality pre-releases of GNU Libtool, also with detached
  signature files are available from:

    ftp://alpha.gnu.org/gnu/libtool

  and some of the mirrors listed at:

    http://www.gnu.org/order/ftp.html

* Nightly snapshots of the unreleased development trunk of GNU Libtool
  are available from:

    http://pogma.com/libtool

  These files do not have signatures, but will allow you to easily
  determine whether the most recent development code still exhibits any
  bugs you have discovered, without requiring you to install a complete
  build environment and the extra tools needed to bootstrap a version
  control checkout.

* The master libtool repository is stored in git.

  If you are a member of the savannah group for GNU Libtool, a writable
  copy of the libtool repository can be obtained by:

    git clone <savannah-user>@git.sv.gnu.org:/srv/git/libtool.git

  If you are behind a firewall that blocks the git protocol, you may
  find it useful to use

    git config --global url.http://git.sv.gnu.org/r/.insteadof \
      git://git.sv.gnu.org/

  to force git to transparently rewrite all savannah git references to
  use http.

  If you are not a member of the savannah group for GNU Libtool, you can
  still fetch a read-only copy with either:

    git clone git://git.sv.gnu.org/libtool.git

  or using the CVS pserver protocol:

    cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/libtool.git \
        co -d libtool HEAD

* Before you can build from git, you need to bootstrap.  This requires:
  - Autoconf 2.62 or later
  - Automake 1.11.1 or later
  - Help2man 1.29 or later
  - Xz 4.999.8beta or later (from <http://tukaani.org/xz>)
  - Texinfo 4.8 or later
  - Any prerequisites of the above (such as m4, perl, tex)

  Note that these bootstrapping dependencies are much stricter than
  those required to use a destributed release for your own packages.
  After installation, GNU Libtool is designed to work either standalone,
  or optionally with:
  - Autoconf 2.59 or later
  - Automake 1.9.6 or later

* The `bootstrap' script sets up the source directory for you to hack,
  though it may take quite some time to run.  If you don't intend to
  re-run the test suite, you can speed up the `bootstrap' step by an
  order of magnitude if you call it like this instead:

    reconfdirs='. libltdl' ./bootstrap


5. Version Numbering
====================

People have complained that they find the version numbering scheme under
which libtool is released confusing... so we've changed it!

It works like this:

	<major-number>.<minor-number>

Releases with a <major-number> less than 1 were not yet feature
complete.  Releases with a <major-number> of 1 used the old numbering
scheme that everyone disliked so much.  Releases with a <major-number>
of 2 us the new scheme described here.  If libtool ever undergoes a
major rewrite or substantial restructuring, the <major-number> will be
incremented again.

If we make a patch release to fix bugs in a stable release, we use a
third number, so:

      <major-number>.<minor-number>.<micro-number>

Version numbers are chosen to make it easy for users to decide two
things:

  Q: How `developed' is this release?
  A: The higher the number, the better!
  Q: How `stable' is this release?
  A: - If the <minor-number> is even, it is a stable release, `2.0'.
     - If the <minor-number> is odd, it is a development version with
       new features compared to the last stable release, `2.1a'.
     - If it has an `odd'[1] letter after the version number,  it is a
       snapshot direct from CVS, `2.1a'.
     - If it has an `even'[1] letter after the version number, it is an
       alpha quality release, `2.1b'.
     - If it has three numbers in the version, it is a patch release,
       fixing bugs from the stable release (with no new features), `2.0.1'.

[1] We always increment the letter in the repository before *and* after
    making a release tarball.  This means that "odd" letters
    (a,c,e,g...) only exist in the repository, and "even" letters are
    used instantaneously for an alpha release.  Since the odd lettered
    version numbers cover many states of the tree, we also qualify them
    by adding the cvs version of the ChangeLog:

    $ libtool --version
    ltmain.sh (GNU libtool 1.1603 2004/09/12 22:02:07) 2.1a

    Copyright (C) 2004  Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

For more details about version numbers, see:

    http://www.gnu.org/software/libtool/contribute.html
--
  Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software
  Foundation, Inc.
  Written by Gary V. Vaughan, 2004

  This file is part of GNU Libtool.

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without warranty of any kind.


Local Variables:
mode: text
fill-column: 72
End:
vim:tw=72