GNU Libtool - The GNU Portable Library ToolCopyright © 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
Originally by Gordon Matzigkeit, 1996.
Home | News | Documentation | Future Directions | Contributing | Administration
Maintainership
GNU Libtool was conceived, designed and implemented by:
GNU Libtool's Dynamic Loader library (libltdl) was conceived, designed and implemented by:
GNU Libtool and libltdl have previously been maintained, enhanced, ported and otherwise advanced by:
GNU Libtool and libltdl are currently being cajoled, bullied, rewritten and otherwise dragged into the future by:
The following people also enjoy write access under the given rules:
Applying Patches
Currently we five have admin access to the libtool repository and co-ordinate changes on the libtool-patches list. We observe the following rules when changing the repository:
- All changes to the trunk of the repository must be posted to libtool-patches.
- After a patch has been posted it can be commited after it has been approved by one of the maintainers (not the same one that submitted the patch!).
- A veto from one maintainer puts the patch on hold until the submitter and the objecter can reach a concensus.
- If a patch is not vetoed within 72 hours of posting, any maintainer can apply it to the repository as if it had been approved.
- Obvious bug fixes do not need explicit approval, though they must be posted to libtool-patches for informational purposes.
- Changes committed to development branches do not need explicit approval, though they should be posted to libtool-patches for informational purposes.
- All commits to the repository are performed with either the commit script in the top-level directory of the CVS tree, or else the equivalent clcommit script in the as-yet unreleased cvs-utils.
Submitting Bug Reports
There is a special list for reporting bugs, bug-libtool@gnu.org, to enable the developers to track submitted bug reports. If you think you have found a bug in libtool, then you should, in the first instance send as complete a report as possible to this list. Ideally, you should include the text you get by running config.guess, the text you see when you run configure, and if you can, a patch made with diff -u5 which fixes the problem. If you can send a small script, modelled after the scripts in the tests directory of the distribution which fails with the unpatched distribution, but passes with your patch applied we can add the test to the distribution to make sure the bug doesn't reappear.
Submitting Patches
Every patch must have several pieces of information before we can properly evaluate it.
- A description of the bug and how your patch fixes this bug. For new features a description of the feature and your implementation. Patches which include new test cases are especially welcome.
- A ChangeLog entry as plaintext; see the various ChangeLog files for format and content.
Note that, unlike some other projects, we do require ChangeLogs also for documentation (i.e., .texi files).- The patch itself. If you are accessing the CVS repository at gnu.org, use "cvs update; cvs diff -u "; else, use "diff -u OLD NEW". If your version of diff does not support these options, then get the latest version of GNU diff.
- If your changes add a new feature, please provide documentation as a patch to the texinfo docs.
If you develop your changes in a cvs checkout tree, The cvsdiff utility from the unreleased cvs-utils project will create a suitable file for you to send to us.
If you want to be certain that your patch doesn't get lost among the noise on the mailing list, you can also upload a copy to the patch manager at savannah. Please bear in mind that not all of the maintainers have easy access to the web, so, until savannah is able to mirror new patches directly to the patch list, you will need to manually send a copy there too. If you only want to submit your patch once, then send it to the libtool-patches@gnu.org mailing list and not the savannah patch manager.
When you have submitted your patch, somebody will tell you what to do next. If the patch is small, just send it directly to the list. Be sure to send the patch as a mime text attachment, or pasted directly into the mail. Uuencoded patches, or patches otherwise rendered unreadable by peculiar mime encoding make it much harder for the libtool developers to read and/or apply your patch. If your patch is very large (more than a hundred kilobytes), try to upload the patch itself to savannah and post only a link to the mailing list.
Persistent contributors who submit high quality patches may be given direct cvs access. You have been warned.
Coding Standards
All contributions must conform to the GNU Coding Standards. Submissions which do not conform to the standards will be returned with a request to reformat the changes.
ChangeLog entries are formatted according to some specific rules:
- Related changes that form a single logical change to the sources are grouped together into a continuous block -- in other words blank lines occur between logical groups of related changes.
- There is exactly one commit to the repository for each logical change, as represented by a block of (unseparated) descriptions in the ChangeLog.
- If it helps, a descriptive block describing the purpose of the change can be added before the first file entry. Consider adding descriptive text to the documentation before you add ChangeLog descriptions.
Copyright Assignment
Before we can accept non-trivial code contributions from you, we need a copyright assignment on file with the FSF. A description of the process is available here. This boils down to the following instructions:
- If you've developed some addition or patch to Libtool that you would like to contribute, you should send mail to the libtool-patches list, or to one of the Libtool maintainers asking for an appropriate form. We might ask you for some more information at this point.
- You will be sent a short form by email which you should fill in and email back to the FSF.
- Once the FSF have received this email, they will send you a paper copy of the full copyright assignment papers for you to sign and post back to them.
- As soon as the signed paperwork is filed at the FSF we can accept your changes into the soure tree.
- Individual small changes (fewer than 10 lines of code) can, however, be accepted without a copyright assignment form on file.
Release Numbering
Libtool is about to change its version numbering system to follow the rules described below. This will begin as libtool-1.6 is branched, when the trunk will become version 1.7a.
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 it has an `odd' letter after the version number, it is a snapshot direct from CVS; If it has an `even' letter after the version number, it is alpha quality; If it has two numbers only in the version, it is a new stable point release; If it has three numbers in the version, it is a patch release, fixing bugs from the point release but with no new features.
Release Numbering Type HEAD branch-1-6 branch-1-8 CVS tag Version # CVS tag Version # CVS tag Version # point release release-1-6 1.6 CVS 1.7a 1.6.1a alpha release release-1-7b 1.7b CVS 1.7c patch release release-1-6-2 1.6.2 CVS 1.6.3a alpha release release-1-7d 1.7d CLOSED OPENED point release release-1-8 1.8 CVS 1.9a 1.8.1a alpha release release-1-9b 1.9b CVS 1.9c patch release release-1-8-2 1.8.2 CVS 1.8.3a To make this happen, the maintainers only have one release branch open at a time from which we make a point release with an incremented `minor' version (the second number) compared to the HEAD branch version at the time it is opened. After that patch releases are made from that release branch with even numbered `micro' versions (the third number) -- the odd numbered `micro' versions represent the CVS revisions in between.
We also put a letter on the end of `odd' micro revisions in CVS, so that the users can tell it is an untested build if they use it. Additionally it would allow us to make `beta' quality releases from the release branch with an `odd' micro revision and `even' letter, if we decide that is useful. We decided not to make the `micro' revisions the same between CVS revisions and patch releases so that users don't get confused about whether say libtool-1.6.1a is newer or older than libtool-1.6.1.
Similarly, we stick to even `minor' version numbers on release branches and odd `minor' version numbers on the trunk, so that we don't have confusion about whether libtool-1.5b is newer than libtool-1.5, or libtool-1.5.1.
CVS conventions
The source for libtool is managed collaboratively in CVS on the FSF Savannah system. The conventions set out below represent how we plan to do things from here on in, although historically, the tree has not been maintained in quite the same way. Don't be surprised if things don't seem to follow these conventions prior to branch-1-6!
- The CVS trunk (or HEAD branch), which you get if you don't specify a tag when you checkout, represents the latest development of the code. This means that HEAD guarantees you the latest, greatest code and the most stability problems!
- Each stable release is held on its own branch from the HEAD so that bug fixes can be applied independently to release versions.
- Feel free to create a development branch to share your development, but be careful to tag the branch point and merge points in your branch and in HEAD to make merging as straight forward as it ever can be with CVS. The convention is described below.
CVS tag names
Libtool releases three types of source tarball from CVS:
- Alpha releases are the lowest quality tarballs we build. They come from the head, and indicate that a new point release is coming. You can distinguish an alpha by its `even' lettered version suffix: 1.7b and 1.7d for example. Alpha releases are tagged in CVS as release-[major]-[minor][letter]: release-1-7b and release-1-7d here.
- Point releases are normally reasonable stable, and are the first release made from a new release branch. You can distinguish a point release, because in has only major and minor parts in its version number: 1.6 and 1.8 for example. Point releases are tagged in CVS as release-[major]-[minor]: release-1-6 and release-1-8 here.
- Patch releases are only ever made from the most recent release branch and never contain any new features over the point release they fix. You can distinguish a patch release, because it carries a numeric micro version suffix: 1.6.2 and 1.6.4 for example. Patch releases are tagged in CVS as release-[major]-[minor]-[micro].
CVS tags and libtool version numbers.In addition to the official releases made by the libtool team, people often like to install a self built CVS snapshot. You can distinguish a snapshot by its `odd' lettered version: where `odd' means `a', `c', `e', `g', etc.
Branching
In libtool we use two types of branches:
The branching process for each is slightly different:
- Release branches are made immediately prior to rolling a new point release. The point release should be made from the branch.
- Development branches are made on demand if a complex experimental feature needs to be developed before integrating into the trunk for the next point release.
- For a Release branch, the trunk is checked out, and the branch tagged. The version number is updated in the branch, checked in and the release rolled. As soon as the release is made, the version number in the branch is updated again and checked in.
- Make sure the trunk is checked out and up to date:
$ cvs -z3 -d :ext:gary@cvs.sv.gnu.org:/sources/libtool co libtool ... $ cd libtool $ cvs update -Pd ...- Tag the branch in the repository:
$ cvs tag -b branch-2-2 ...- Switch your working copy into the new branch:
$ cvs update -Pd -r branch-2-2 ...- There is more to this that does not relate directly to CVS management, described in HACKING But for the purposes of describing the branch process, next bump the version number and commit back to the repository:
$ grep AC_INIT configure.ac AC_INIT([libtool], [2.1e], [bug-libtool@gnu.org]) $ sed '/^AC_INIT/ s@2.1e@2.2@' configure.ac > tmp && mv tmp configure.ac $ grep AC_INIT configure.ac AC_INIT([libtool], [2.2], [bug-libtool@gnu.org]) $ cvs commit -m "* configure.ac: Bumped version to 2.2." ...- Tag the release in the repository:
$ cvs tag release-2-2- Roll the release, then bump the version again:
$ sed '/^AC_INIT/ s@2.2@2.2.1a@' configure.ac > tmp && mv tmp configure.ac $ grep AC_INIT configure.ac AC_INIT([libtool], [2.2.1a], [bug-libtool@gnu.org]) $ cvs commit -m "* configure.ac: Bumped version to 2.2.1a" ...- For a Development branch, more tagging is needed because we need to be able to merge the branch back into the trunk when the feature is complete.
- Make sure the trunk is checked out and up to date:
$ cvs -z3 -d :ext:gary@cvs.sv.gnu.org:/sources/libtool co libtool ... $ cd libtool $ cvs update -Pd ...- Tag the branchpoint in the HEAD branch:
$ cvs tag binary-branchpoint ...- Create the branch from the branchpoint:
$ cvs rtag -b -r binary-branchpoint binary-branch libtool ...- Switch your working copy into the new branch before you make any edits:
$ cvs update -Pd -r binary-branch ...Merging
Merging branches back into the trunk can be a difficult process at the best of times. Here is the process we use to minimise the difficulties:
- Check out the branch that needs to be merged, and make sure it is up to date, before tagging to help with subsequent merges:
$ cvs -z3 -d :ext:gary@cvs.sv.gnu.org:/sources/libtool co -r binary-branch libtool ... $ cd libtool $ cvs update -Pd ... $ cvs tag binary-to-HEAD-merge-1 ...- Switch your working copy to the target branch (HEAD in this case), and tag it incase you need to get back if the merge goes wrong and needs to be redone:
$ cvs update -Pd -A ... $ cvs tag pre-binary-to-HEAD-merge-1 ...- For the first merge from a branch, you should use the branch name so that any added or deleted files are considered as part of the merge:
$ cvs update -kk -j binary-branch ...- For subsequent merges, the process is the same until the merge command itself, which must also specify the previous merge tag to avoid CVS trying to merge the previous changes again:
$ cvs update -kk -j binary-to-HEAD-merge-1 -j binary-branch ...- Once the merged working copy has been tested for regressions, it should be checked back in using the commit script:
$ ./commit
Home | News | Documentation | Future Directions | Contributing | Administration
Return to GNU's home page.Please send FSF & GNU inquiries & questions to gnu@gnu.org. There are also other ways to contact the FSF.
Please send comments on these web pages to webmasters@www.gnu.org, send other questions to gnu@gnu.org.
This article, Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
$Date: 2005/12/20 13:41:29 $ $Author: rwild $