libtool/HACKING

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

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

This file attempts to describe the processes we use to maintain libtool,
and is not part of a release distribution.

2. Maintenance Notes
====================

* If you incorporate a change from somebody on the net:
  If it is a large change, you must make sure they have signed the
  appropriate paperwork, and be sure to add their name and email
  address to THANKS

* If a change fixes a test, mention the test in the ChangeLog entry.

* If somebody reports a new bug, mention his name in the ChangeLog entry
  and in the test case you write.

* The correct response to most actual bugs is to write a new test case
  which demonstrates the bug.  Then fix the bug, re-run the test suite,
  and check everything in.

* Some files in the libtool package are not owned by libtool.  These
  files should never be edited here.  These files are:
	COPYING
	INSTALL
	config/
	    + config.guess
	    + config.sub
	    + depcomp
	    + install-sh
	    + mdate-sh
	    + missing
	    + texinfo.tex
	doc/
	    + fdl.texi
	libltdl/
	    + COPYING.LIB
  The ones that are important for a release can be udated with,
  `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
  if you are running from a VPATH build directory, where `../' is the
  relative path to the directory with `configure' in it).

* Changes other than bug fixes must be mentioned in NEWS


3. Test Suite
=============

* Use "make check" liberally, on as many platforms as you can.  Use as
  many compilers and linkers you can.


4. Naming
=========

* We've adopted the convention that exported Autoconf macros should be
  named with a leading `LT_' and be documented in the libtool manual.
  Internal macros begin with `_LT_' if they are visible to aclocal, or
  potentially part of an AC_DEFUN/AC_REQUIRE path, or else `_lt_' if
  they are very low level.  This convention was only introduced just
  before libtool-2.0, so there may still be exceptions in the existing
  code.  But all new code should use it.

* All shell variables used internally by libtool's Autoconf macros
  should be named with the a leading `lt_' (not that they cannot clash
  with the `_lt_' macro namespace).


5. Editing 'ChangeLog'
======================

* When in doubt, check that emacs can syntax-color properly in
  change-log-mode.  And preferably use emacs 'C-x 4 a'
  (add-change-log-entry-other-window) to open ChangeLog with an
  appropriate new template.

* If this change is by a different author, or on a different date to the
  last entry start a new entry at the top of the file with the format
  (note two spaces between each field):

yyyy-mm-dd  Name of Author  <email@address>

*  If more than one person collaborated on the change, additional
   authors can be listed on subsequent lines, thus:

yyyy-mm-dd  Name of Main Author  <email@address>,
            Name of Contributor  <another@email.address>

* Where a change author did not supply a copyright assignment, but the
  changes they submitted were sufficiently trivial to commit in any case
  (see the GCS for guidelines on this), then flag this against their
  name in the header, thus:

yyyy-mm-dd  Name of Author  <email@address>  (tiny change)

* In ChangeLog.2004 and earlier, 'Name of Author' was sometimes the name
  of the author of the ChangeLog when the person who made the change
  being documented didn't supply one.   In that case separated from
  the previous field by a blank line and indented by 1 tab (note, only
  1 space between fields here) you will see:

	From Author of Actual Change <email@address>:

  As of now, don't do that anymore, since the GNU Coding Standards say
  that the author of the change must be credited in the main entry
  header for legal purposes.

* Preferably the next part should be a description of the overall
  purpose of the change, separated from the header by a blank line,
  indented by 1 tab, and filled at column 72.  The last character of the
  description should be a colon, :.

* Changes to each file come next.  Each new file starts on a new line,
  indented by 1 tab and starting with an asterisk and a space.  Multiple
  files can be listed here relative to $top_srcdir, and comma separated.
  Names of functions (or sections as appropriate) to which the change
  applies should be named inside parentheses and comma separated.  If
  this goes beyond column 72, then parens should be closed and re-opened
  on the next line:

	* file, another/file, test/testcases/foo.test (func_foo)
	(func_bar, func_baz): Description of changes.

* If the change does not apply to particular functions (or sections),
  the section list can be omitted:

	* file, another/file, test/testcases/foo.test: General changes.

* If the changes are particular to certain architectures, they should be
  listed after the functions in square brackets:

	* file, another/file (func_foo) [linux, solaris]: Description of
	changes.

* Subsequent changes in other files that are related to the same overall
  enhancement or bugfix should be listed concurrently, without blank
  lines.  Always start a fresh line for a new file:

	* file, another/file (func_foo) [linux, solaris]: Description of
	changes.
	* doc/foo.texi (Invoking Foo): Document.
	* NEWS: Updated.

* If the change is in response to a problem reported by someone other
  than the author, then credit them at the end of the description with:

	Reported by Reporter Name <email@address>.

* See the GNU Coding Standards document for more details on ChangeLog
  formatting.


2005-01-08  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>  (tiny change),
            Peter O'Gorman  <peter@pogma.com>

	This is the overall description of the purpose of this change
	and any useful background for a model ChangeLog entry:

	* HACKING: Updated copyright.  This isn't attached to a
	particular section of the file, so it comes first.
	(Editing 'ChangeLog'): New section.  This applies to the same
	file, but since it applies to a particular section it starts on
	a new line.
	(Introduction, Maintenance Notes, Test Suite, Naming)
	(Editing '.am' Files): If I had changed all these sections in
	the same way, I can list them like this, being careful to close
	and reopen the parentheses when starting a new line.  The colon
	only comes after the last section before this description.
	* NEWS: Updated.
	Reported by Bob Friesenhahn <bfriesen@simple.dallas.tx.us>.


6. Editing `.am' Files
======================

* Always use $(...) and not ${...}

* Use `:', not `true'.  Use `exit 1', not `false'.

* Use `##' comments liberally.  Comment anything even remotely unusual.

* Never use basename or dirname.  Instead use sed.

* Do not use `cd' within back-quotes, use `$(lt__cd)' instead.
  Otherwise the directory name may be printed, depending on CDPATH.

* In general, if a loop is required, it should be silent.  Then the body
  of the loop itself should print each "important" command it runs.

* Use 4 extra spaces to indent continued dependencies.

* One needs to remember that for our whole logic for the different
  libltdl modes to function correctly, the thing we need to ensure
  *before the client runs libtoolize*, is that the subpackage case is
  correct (because all files may be symlinked there).  All others can
  and will be fixed in the `libtoolize --ltdl --(non)recursive' stage.


7. Editing `.m4sh' Files
========================

* Use shell functions, but be careful not to assume local scope for
  variable names.  Don't use `return', instead echo the result of a
  function and call it from within backquotes.

* Function names should be prefixed `func_', the function header should
  look like this:

  # func_foo [ OPTIONS ]
  # Description of what func_foo does and returns.
  func_foo ()
  {
      $opt_debug
      # contents of func_foo ...
  }

  The `$opt_debug' is used to enable shell tracing (Korn shells reset
  this on function entry).

* For functions that are called frequently, if you need to return a
  value, don't cause unneccessary forking of the shell using echo as
  described above; instead set the return value in a variable named
  after the called function with a suffix of `_result'.  For example
  the function `func_quote_for_eval' stores its return value in the
  variable `$func_quote_for_eval_result'.

* Although sh-indentation is set to 2 (by the `Local Variables:' block
  at the end of .m4sh files), the left margin of the body of shell
  functions should begin indented by 4 spaces.


8. Editing `.m4' Files
======================

* Be careful with both `echo' and `$ECHO'.  As the latter may be one of
   echo
   print -r
   printf %s\n
   $CONFIG_SHELL $0 --fallback-echo
  it may not have more than one argument, its value may not be eval'ed
  and the argument may not start with a `-'.  As a rule of thumb, use
   echo ..		for literal (constant) strings without leading
			hyphen and no backslashes within,
   $ECHO ".."		for strings without leading hyphen,
   $ECHO "X.." | $Xsed	otherwise.

* The Autoconf manual says that giving an empty parameter is equivalent
  to not giving it at all.  (In particular, the Autoconf manual doesn't
  explain that "FOO()" is calling macro FOO with one empty parameter.)
  To prevent misunderstanding, we should use m4_ifval to check whether
  a parameter is empty, and not $# to check for the number of parameters.

* Any time we add a macro to an older version, lt~obsolete.m4 needs to
  be updated in all newer versions.


9. Abstraction layers in libltdl
================================

* The libltdl API uses a layered approach to differentiate internal and
  external interfaces, among other things.  To keep the abstraction
  consistent, files in a given layer may only use APIs from files in the
  lower layers.  The exception to this is lt__glibc.h which serves a
  dual purpose, as explained later.

* At the bottom of the stack we have the system abstraction layer,
  which tries to smooth over the cracks where there are differences
  between host systems and compilers.  config.h is generated at
  configure time and is not installed; lt_system.h is an installed
  file and cannot use macros from config.h:

	lt_system.h	../config.h

* Next up is the libc abstraction layer, which provides a uniform api
  to various system libc interfaces that differ between hosts supported
  by libtool.  Typically, the files that implement this layer begin:

  #if defined(HAVE_CONFIG_H)
  #  if defined(LT_CONFIG_H)
  #    include LT_CONFIG_H
  #  else
  #    include <config.h>
  #  endif
  #endif
  #include "lt_system.h"

  Or if they are installed headers that must work outside the libtool
  source tree, simply:

  #include <libltdl/lt_system.h>

  This layer's interface is defined by files that are usually named with
  a leading `lt__':

	,------------.	,-----------.	,------.	,-------.
	|lt__dirent.h|	|lt__alloc.h|	|argz.h|	|slist.h|
	+------------+	+-----------+	+------+	+-------+
	|lt__dirent.c|	|lt__alloc.c|	|argz.c|	|slist.c|
	`------------'	`-----------'	`------'	`-------'

  The exceptions here are argz.h and slist.h which are used
  independently of libltdl in other projects.

* There is also a sub-layer that can be used either by the headers that
  implement it, in which case its function is to avoid namespace clashes
  when linked with the GNU C library; Or it can be included by code that
  wants to program against a glibc like interface, where it also serves
  the function of pulling in all the glibc-like functionality used by
  libltdl from a single:

  #include <libltdl/lt__glibc.h>

  It consists of the single file:

	lt__glibc.h

* The next layer are the subsystems of the exported libltdl API, which
  are defined by files that are named with a leading `lt_' (no double
  underscore!):

	,----------.	,-------------.
	|lt_error.h|	|lt_dlloader.h|
	+----------+	+-------------+
	|lt_error.c|	|lt_dlloader.c|
	`----------'	`-------------'


* The top layer of the stack is the libltdl API proper, which includes
  the subsystems automatically:

	,------.
	|ltdl.h|
	+------+
	|ltdl.c|
	`------'

* And finally, there is an additional internal only layer (as evidenced
  by the `lt__' prefix to the filename!) that defines additional
  internal interfaces that are not exported to libltdl clients, but are
  shared between internal files:

	lt__private.h


10. Release Procedure
====================

* If you are a libtool maintainer, but have not yet registered your
  gpg public key and (preferred) email address with the FSF, send an
  email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
  the following:

    (a) name of package(s) that you are the maintainer for, and your
        preferred email address.

    (b) an ASCII armored copy of your GnuPG key, as an attachment.
	("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
	this.)

  When you have received acknowledgement of your message, the proper GPG
  keys will be registered on ftp-upload.gnu.org and only then will you be
  authorized to upload files to the FSF ftp machines.

* If you do not have access to the mailing list administrative interface,
  approach the list owners for the password.  Be sure to check the lists
  (esp. bug-libtool) for outstanding bug reports also in the list of
  pending moderation requests.

* Make sure you have wget installed.

* Make sure you have a copy of xdelta installed, and a copy of the previous
  release tarball in the build directory.

* Make sure your locale is sane, e.g. by exporting LC_ALL=C.

* Double check that serial number updates in public m4 files weren't forgotten
  since last release (they should be updated in CVS along with commits that
  require it so that users can work with CVS snapshots).

* Update the libltdl VERSION_INFO in Makefile.am for changes since the last
  release.

* Update the version number in configure.ac.
  See http://www.gnu.org/software/libtool/contribute.html for details of
  the numbering scheme.

* Update NEWS, ChangeLog.

* Run ./bootstrap.

* Have some tea.  If you are running on less than 3.6GHz CPU, order
  a pizza too ;-)

* Run ./configure (or create a build directory first and run configure
  from there, if you want to keep the build tree separate).

* Run `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
  if you are running from a VPATH build directory, where `../' is the
  relative path to the directory with `configure' in it), which will
  fetch new versions of the files that are maintained outside of
  libtool.

* Run `make distcheck' and `make distcheck
  DISTCHECK_CONFIGURE_FLAGS=--disable-ltdl-install'.  If there are any
  problems, fix them and start again.

* Run ./commit from the source tree.

* Run `make -fMakefile.maint cvs-dist' (or `make -f../Makefile.maint
  cvs-dist' if you are running from a VPATH build directory, where `../'
  is the relative path to the directory with `configure' in it), which
  will build a release tarball (with `make distcheck'), tag the tree
  with release-$(VERSION) and generate the gpg signature files.

* Run 'make -f[../]Makefile.maint deltas' (pass
  LASTRELEASE=maj.min[.mic[alpha]] if needed) to create both diff and
  xdelta files between the previous release tarball and the new with
  detached gpg signature files and clear signed directive files.

* Upload release tarball, diff file and xdelta file, plus their associated
  detached gpg signature files and clear signed directive files to
  ftp-upload.gnu.org.  If the upload is destined for ftp.gnu.org, then the
  files should be placed in the /incoming/ftp directory.  If the upload is
  an alpha release destined for alpha.gnu.org, then the files should be
  placed in the /incoming/alpha directory.

* Send announcement to libtool@gnu.org and autotools-announce@gnu.org,
  if not an alpha send to info-gnu@gnu.org as well.

* Update version number in configure.ac to next alpha number.
  See http://www.gnu.org/software/libtool/contribute.html for details of
  the numbering scheme.

* Update NEWS, ChangeLog.

* Run ./commit.

* Update the webpages, libtool.html will need to indicate the latest
  release number and the news page should get a HTMLified copy of your
  release announcement.

* If not an alpha, replace manual.html with the new one
  (generate with `make -f[../]Makefile.maint web-manual').



11. Alpha release note template
===============================

To: libtool@gnu.org, autotools-announce@gnu.org
Subject: GNU Libtool @VERSION@ released (alpha release).

The Libtool Team is pleased to announce alpha release @VERSION@ of GNU
Libtool.

GNU Libtool hides the complexity of using shared libraries behind a
consistent, portable interface. GNU Libtool ships with GNU libltdl,
which hides the complexity of loading dynamic runtime libraries
(modules) behind a consistent, portable interface.

Here are the compressed sources:

  ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
  ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2

Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:

  ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta

Here are the gpg detached signatures:

  ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
  ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
  ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
  ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig

You should download the signature named after any tarball you download,
and then verify its integrity with, for example:

  gpg --verify libtool-@VERSION.tar.gz.sig

Here are the MD5 and SHA1 checksums:

  @MD5SUM@ libtool-@VERSION@.tar.gz
  @MD5SUM@ libtool-@VERSION@.tar.bz2
  @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
  @SHA1SUM@ libtool-@VERSION@.tar.gz
  @SHA1SUM@ libtool-@VERSION@.tar.bz2
  @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta

This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.

This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
projects.

Alternatively, you can fetch the unbootstrapped sourcecode from
anonymous cvs by using the following commands:

  $ export CVS_RSH=ssh
  $ cvs -z3 -d :ext:anoncvs@savannah.gnu.org:/cvsroot/libtool \
  co -r @CVS_RELEASE_TAG@ libtool

You will then need to have recent (possibly as yet unreleased) versions
of Automake and Autoconf installed to bootstrap the checked out
sources yourself.

New in @VERSION@: @RELEASE_DATE@

  @EXCERPT_FROM_NEWS_FILE@

Please report bugs to <bug-libtool@gnu.org>, along with the verbose
output of any failed test groups, and the output from `./libtool --help.'



12. Full release note template
==============================

To: info-gnu@gnu.org
Cc: libtool@gnu.org, autotools-announce@gnu.org
Subject: GNU Libtool @VERSION@ released.

The Libtool Team is pleased to announce the release of GNU Libtool
@VERSION@.

GNU Libtool hides the complexity of using shared libraries behind a
consistent, portable interface. GNU Libtool ships with GNU libltdl,
which hides the complexity of loading dynamic runtime libraries
(modules) behind a consistent, portable interface.

This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.

New in @VERSION@: @RELEASE_DATE@

  @EXCERPT_FROM_NEWS_FILE@

libtool-@VERSION@ is available now from ftp.gnu.org, along with
diffs and xdeltas against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@
that are also available from ftp.gnu.org.  Please
use a mirror to reduce stress on the main gnu machine:

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

Here are the compressed sources:

  ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
  ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2

Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:

  ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta

Here are the gpg detached signatures:

  ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
  ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
  ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
  ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig

You should download the signature named after any tarball you download,
and then verify its integrity with, for example:

  gpg --verify libtool-@VERSION.tar.gz.sig

Here are the MD5 and SHA1 checksums:

  @MD5SUM@ libtool-@VERSION@.tar.gz
  @MD5SUM@ libtool-@VERSION@.tar.bz2
  @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
  @SHA1SUM@ libtool-@VERSION@.tar.gz
  @SHA1SUM@ libtool-@VERSION@.tar.bz2
  @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
  @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta

This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
projects.

Alternatively, you can fetch the unbootstrapped sourcecode from
anonymous cvs by using the following commands (just hit return when
you are prompted for the password):

  $ export CVS_RSH=ssh
  $ cvs -z3 -d :ext:anoncvs@savannah.gnu.org:/cvsroot/libtool \
  co -r @CVS_RELEASE_TAG@ libtool

You will then need to have the latest release versions of Automake
(@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
bootstrap the checked out sources yourself.

Please report bugs to <bug-libtool@gnu.org>, along with the verbose
output of any failed test groups, and the output from `./libtool --help.'


-- 
Copyright (C) 2004, 2005 Free Software Foundation, Inc.

The canonical source of this file is maintained with the
GNU Libtool package.  Report bugs to bug-libtool@gnu.org.

GNU Libtool is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

As a special exception to the GNU General Public License,
if you distribute this file as part of a program or library that
is built using GNU libtool, you may include it under the same
distribution terms that you use for the rest of that program.

GNU Libtool is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with GNU Libtool; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301  USA


Local Variables:
mode: text
fill-column: 72
End: