7 This file attempts to describe the processes we use to maintain libtool,
8 and is not part of a release distribution.
13 * If you incorporate a change from somebody on the net:
14 If it is a large change, you must make sure they have signed the
15 appropriate paperwork, and be sure to add their name and email
18 * If a change fixes a test, mention the test in the ChangeLog entry.
20 * If somebody reports a new bug, mention his name in the ChangeLog entry
21 and in the test case you write.
23 * The correct response to most actual bugs is to write a new test case
24 which demonstrates the bug. Then fix the bug, re-run the test suite,
25 and check everything in.
27 * Some files in the libtool package are not owned by libtool. These
28 files should never be edited here. These files are:
43 The ones that are important for a release can be udated with,
44 `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
45 if you are running from a VPATH build directory, where `../' is the
46 relative path to the directory with `configure' in it).
48 * Changes other than bug fixes must be mentioned in NEWS
54 * Use "make check" liberally, on as many platforms as you can. Use as
55 many compilers and linkers you can.
61 * We've adopted the convention that exported Autoconf macros should be
62 named with a leading `LT_' and be documented in the libtool manual.
63 Internal macros begin with `_LT_' if they are visible to aclocal, or
64 potentially part of an AC_DEFUN/AC_REQUIRE path, or else `_lt_' if
65 they are very low level. This convention was only introduced just
66 before libtool-2.0, so there may still be exceptions in the existing
67 code. But all new code should use it.
69 * All shell variables used internally by libtool's Autoconf macros
70 should be named with the a leading `lt_' (not that they cannot clash
71 with the `_lt_' macro namespace).
74 5. Editing 'ChangeLog'
75 ======================
77 * When in doubt, check that emacs can syntax-color properly in
78 change-log-mode. And preferably use emacs 'C-x 4 a'
79 (add-change-log-entry-other-window) to open ChangeLog with an
80 appropriate new template.
82 * If this change is by a different author, or on a different date to the
83 last entry start a new entry at the top of the file with the format
84 (note two spaces between each field):
86 yyyy-mm-dd Name of Author <email@address>
88 * If more than one person collaborated on the change, additional
89 authors can be listed on subsequent lines, thus:
91 yyyy-mm-dd Name of Main Author <email@address>,
92 Name of Contributor <another@email.address>
94 * Where a change author did not supply a copyright assignment, but the
95 changes they submitted were sufficiently trivial to commit in any case
96 (see the GCS for guidelines on this), then flag this against their
97 name in the header, thus:
99 yyyy-mm-dd Name of Author <email@address> (tiny change)
101 * In ChangeLog.2004 and earlier, 'Name of Author' was sometimes the name
102 of the author of the ChangeLog when the person who made the change
103 being documented didn't supply one. In that case separated from
104 the previous field by a blank line and indented by 1 tab (note, only
105 1 space between fields here) you will see:
107 From Author of Actual Change <email@address>:
109 As of now, don't do that anymore, since the GNU Coding Standards say
110 that the author of the change must be credited in the main entry
111 header for legal purposes.
113 * Preferably the next part should be a description of the overall
114 purpose of the change, separated from the header by a blank line,
115 indented by 1 tab, and filled at column 72. The last character of the
116 description should be a colon, :.
118 * Changes to each file come next. Each new file starts on a new line,
119 indented by 1 tab and starting with an asterisk and a space. Multiple
120 files can be listed here relative to $top_srcdir, and comma separated.
121 Names of functions (or sections as appropriate) to which the change
122 applies should be named inside parentheses and comma separated. If
123 this goes beyond column 72, then parens should be closed and re-opened
126 * file, another/file, test/testcases/foo.test (func_foo)
127 (func_bar, func_baz): Description of changes.
129 * If the change does not apply to particular functions (or sections),
130 the section list can be omitted:
132 * file, another/file, test/testcases/foo.test: General changes.
134 * If the changes are particular to certain architectures, they should be
135 listed after the functions in square brackets:
137 * file, another/file (func_foo) [linux, solaris]: Description of
140 * Subsequent changes in other files that are related to the same overall
141 enhancement or bugfix should be listed concurrently, without blank
142 lines. Always start a fresh line for a new file:
144 * file, another/file (func_foo) [linux, solaris]: Description of
146 * doc/foo.texi (Invoking Foo): Document.
149 * If the change is in response to a problem reported by someone other
150 than the author, then credit them at the end of the description with:
152 Reported by Reporter Name <email@address>.
154 * See the GNU Coding Standards document for more details on ChangeLog
158 2005-01-08 Ralf Wildenhues <Ralf.Wildenhues@gmx.de> (tiny change),
159 Peter O'Gorman <peter@pogma.com>
161 This is the overall description of the purpose of this change
162 and any useful background for a model ChangeLog entry:
164 * HACKING: Updated copyright. This isn't attached to a
165 particular section of the file, so it comes first.
166 (Editing 'ChangeLog'): New section. This applies to the same
167 file, but since it applies to a particular section it starts on
169 (Introduction, Maintenance Notes, Test Suite, Naming)
170 (Editing '.am' Files): If I had changed all these sections in
171 the same way, I can list them like this, being careful to close
172 and reopen the parentheses when starting a new line. The colon
173 only comes after the last section before this description.
175 Reported by Bob Friesenhahn <bfriesen@simple.dallas.tx.us>.
178 6. Editing `.am' Files
179 ======================
181 * Always use $(...) and not ${...}
183 * Use `:', not `true'. Use `exit 1', not `false'.
185 * Use `##' comments liberally. Comment anything even remotely unusual.
187 * Never use basename or dirname. Instead use sed.
189 * Do not use `cd' within back-quotes, use `$(lt__cd)' instead.
190 Otherwise the directory name may be printed, depending on CDPATH.
192 * In general, if a loop is required, it should be silent. Then the body
193 of the loop itself should print each "important" command it runs.
196 7. Editing `.m4sh' Files
197 ========================
199 * Use shell functions, but be careful not to assume local scope for
200 variable names. Don't use `return', instead echo the result of a
201 function and call it from within backquotes.
203 * Function names should be prefixed `func_', the function header should
206 # func_foo [ OPTIONS ]
207 # Description of what func_foo does and returns.
211 # contents of func_foo ...
214 The `$opt_debug' is used to enable shell tracing (Korn shells reset
215 this on function entry).
217 * For functions that are called frequently, if you need to return a
218 value, don't cause unneccessary forking of the shell using echo as
219 described above; instead set the return value in a variable named
220 after the called function with a suffix of `_result'. For example
221 the function `func_quote_for_eval' stores its return value in the
222 variable `$func_quote_for_eval_result'.
224 * Although sh-indentation is set to 2 (by the `Local Variables:' block
225 at the end of .m4sh files), the left margin of the body of shell
226 functions should begin indented by 4 spaces.
229 8. Editing `.m4' Files
230 ======================
232 * Be careful with both `echo' and `$ECHO'. As the latter may be one of
236 $CONFIG_SHELL $0 --fallback-echo
237 it may not have more than one argument, its value may not be eval'ed
238 and the argument may not start with a `-'. As a rule of thumb, use
239 echo .. for literal (constant) strings without leading
240 hyphen and no backslashes within,
241 $ECHO ".." for strings without leading hyphen,
242 $ECHO "X.." | $Xsed otherwise.
244 * The Autoconf manual says that giving an empty parameter is equivalent
245 to not giving it at all. (In particular, the Autoconf manual doesn't
246 explain that "FOO()" is calling macro FOO with one empty parameter.)
247 To prevent misunderstanding, we should use m4_ifval to check whether
248 a parameter is empty, and not $# to check for the number of parameters.
250 * Any time we add a macro to an older version, lt~obsolete.m4 needs to
251 be updated in all newer versions.
254 9. Abstraction layers in libltdl
255 ================================
257 * The libltdl API uses a layered approach to differentiate internal and
258 external interfaces, among other things. To keep the abstraction
259 consistent, files in a given layer may only use APIs from files in the
260 lower layers. The exception to this is lt__glibc.h which serves a
261 dual purpose, as explained later.
263 * At the bottom of the stack we have the system abstraction layer,
264 which tries to smooth over the cracks where there are differences
265 between host systems and compilers. config.h is generated at
266 configure time and is not installed; lt_system.h is an installed
267 file and cannot use macros from config.h:
269 lt_system.h ../config.h
271 * Next up is the libc abstraction layer, which provides a uniform api
272 to various system libc interfaces that differ between hosts supported
273 by libtool. Typically, the files that implement this layer begin:
275 #if defined(HAVE_CONFIG_H)
276 # if defined(LT_CONFIG_H)
277 # include LT_CONFIG_H
282 #include "lt_system.h"
284 Or if they are installed headers that must work outside the libtool
287 #include <libltdl/lt_system.h>
289 This layer's interface is defined by files that are usually named with
292 ,------------. ,-----------. ,------. ,-------.
293 |lt__dirent.h| |lt__alloc.h| |argz.h| |slist.h|
294 +------------+ +-----------+ +------+ +-------+
295 |lt__dirent.c| |lt__alloc.c| |argz.c| |slist.c|
296 `------------' `-----------' `------' `-------'
298 The exceptions here are argz.h and slist.h which are used
299 independently of libltdl in other projects.
301 * There is also a sub-layer that can be used either by the headers that
302 implement it, in which case its function is to avoid namespace clashes
303 when linked with the GNU C library; Or it can be included by code that
304 wants to program against a glibc like interface, where it also serves
305 the function of pulling in all the glibc-like functionality used by
306 libltdl from a single:
308 #include <libltdl/lt__glibc.h>
310 It consists of the single file:
314 * The next layer are the subsystems of the exported libltdl API, which
315 are defined by files that are named with a leading `lt_' (no double
318 ,----------. ,-------------.
319 |lt_error.h| |lt_dlloader.h|
320 +----------+ +-------------+
321 |lt_error.c| |lt_dlloader.c|
322 `----------' `-------------'
325 * The top layer of the stack is the libltdl API proper, which includes
326 the subsystems automatically:
334 * And finally, there is an additional internal only layer (as evidenced
335 by the `lt__' prefix to the filename!) that defines additional
336 internal interfaces that are not exported to libltdl clients, but are
337 shared between internal files:
342 10. Release Procedure
345 * If you are a libtool maintainer, but have not yet registered your
346 gpg public key and (preferred) email address with the FSF, send an
347 email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
350 (a) name of package(s) that you are the maintainer for, and your
351 preferred email address.
353 (b) an ASCII armored copy of your GnuPG key, as an attachment.
354 ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
357 When you have received acknowledgement of your message, the proper GPG
358 keys will be registered on ftp-upload.gnu.org and only then will you be
359 authorized to upload files to the FSF ftp machines.
361 * If you do not have access to the mailing list administrative interface,
362 approach the list owners for the password. Be sure to check the lists
363 (esp. bug-libtool) for outstanding bug reports also in the list of
364 pending moderation requests.
366 * Make sure you have wget installed.
368 * Make sure you have a copy of xdelta installed, and a copy of the previous
369 release tarball in the build directory.
371 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
373 * Double check that serial number updates in public m4 files weren't forgotten
374 since last release (they should be updated in CVS along with commits that
375 require it so that users can work with CVS snapshots).
377 * Update the libltdl VERSION_INFO in Makefile.am for changes since the last
380 * Update the version number in configure.ac.
381 See http://www.gnu.org/software/libtool/contribute.html for details of
382 the numbering scheme.
384 * Update NEWS, ChangeLog.
388 * Have some tea. If you are running on less than 3.6GHz CPU, order
391 * Run ./configure (or create a build directory first and run configure
392 from there, if you want to keep the build tree separate).
394 * Run `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
395 if you are running from a VPATH build directory, where `../' is the
396 relative path to the directory with `configure' in it), which will
397 fetch new versions of the files that are maintained outside of
400 * Run `make distcheck' and `make distcheck
401 DISTCHECK_CONFIGURE_FLAGS=--disable-ltdl-install'. If there are any
402 problems, fix them and start again.
404 * Run ./commit from the source tree.
406 * Run `make -fMakefile.maint cvs-dist' (or `make -f../Makefile.maint
407 cvs-dist' if you are running from a VPATH build directory, where `../'
408 is the relative path to the directory with `configure' in it), which
409 will build a release tarball (with `make distcheck'), tag the tree
410 with release-$(VERSION) and generate the gpg signature files.
412 * Run 'make -f[../]Makefile.maint deltas' (pass
413 LASTRELEASE=maj.min[.mic[alpha]] if needed) to create both diff and
414 xdelta files between the previous release tarball and the new with
415 detached gpg signature files and clear signed directive files.
417 * Upload release tarball, diff file and xdelta file, plus their associated
418 detached gpg signature files and clear signed directive files to
419 ftp-upload.gnu.org. If the upload is destined for ftp.gnu.org, then the
420 files should be placed in the /incoming/ftp directory. If the upload is
421 an alpha release destined for alpha.gnu.org, then the files should be
422 placed in the /incoming/alpha directory.
424 * Send announcement to libtool@gnu.org and autotools-announce@gnu.org,
425 if not an alpha send to info-gnu@gnu.org as well.
427 * Update version number in configure.ac to next alpha number.
428 See http://www.gnu.org/software/libtool/contribute.html for details of
429 the numbering scheme.
431 * Update NEWS, ChangeLog.
435 * Update the webpages, libtool.html will need to indicate the latest
436 release number and the news page should get a HTMLified copy of your
437 release announcement.
439 * If not an alpha, replace manual.html with the new one
440 (generate with `make -f[../]Makefile.maint web-manual').
444 11. Alpha release note template
445 ===============================
447 To: libtool@gnu.org, autotools-announce@gnu.org
448 Subject: GNU Libtool @VERSION@ released (alpha release).
450 The Libtool Team is pleased to announce alpha release @VERSION@ of GNU
453 GNU Libtool hides the complexity of using shared libraries behind a
454 consistent, portable interface. GNU Libtool ships with GNU libltdl,
455 which hides the complexity of loading dynamic runtime libraries
456 (modules) behind a consistent, portable interface.
458 Here are the compressed sources:
460 ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
461 ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
463 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
465 ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
466 ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
468 Here are the gpg detached signatures:
470 ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
471 ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
472 ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
473 ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
475 You should download the signature named after any tarball you download,
476 and then verify its integrity with, for example:
478 gpg --verify libtool-@VERSION.tar.gz.sig
480 Here are the MD5 and SHA1 checksums:
482 @MD5SUM@ libtool-@VERSION@.tar.gz
483 @MD5SUM@ libtool-@VERSION@.tar.bz2
484 @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
485 @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
486 @SHA1SUM@ libtool-@VERSION@.tar.gz
487 @SHA1SUM@ libtool-@VERSION@.tar.bz2
488 @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
489 @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
491 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
493 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
494 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
497 Alternatively, you can fetch the unbootstrapped sourcecode from
498 anonymous cvs by using the following commands:
501 $ cvs -z3 -d :ext:anoncvs@savannah.gnu.org:/cvsroot/libtool \
502 co -r @CVS_RELEASE_TAG@ libtool
504 You will then need to have recent (possibly as yet unreleased) versions
505 of Automake and Autoconf installed to bootstrap the checked out
508 New in @VERSION@: @RELEASE_DATE@
510 @EXCERPT_FROM_NEWS_FILE@
512 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
513 output of any failed test groups, and the output from `./libtool --help.'
517 12. Full release note template
518 ==============================
521 Cc: libtool@gnu.org, autotools-announce@gnu.org
522 Subject: GNU Libtool @VERSION@ released.
524 The Libtool Team is pleased to announce the release of GNU Libtool
527 GNU Libtool hides the complexity of using shared libraries behind a
528 consistent, portable interface. GNU Libtool ships with GNU libltdl,
529 which hides the complexity of loading dynamic runtime libraries
530 (modules) behind a consistent, portable interface.
532 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
534 New in @VERSION@: @RELEASE_DATE@
536 @EXCERPT_FROM_NEWS_FILE@
538 libtool-@VERSION@ is available now from ftp.gnu.org, along with
539 diffs and xdeltas against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@
540 that are also available from ftp.gnu.org. Please
541 use a mirror to reduce stress on the main gnu machine:
543 http://www.gnu.org/order/ftp.html
545 Here are the compressed sources:
547 ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
548 ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
550 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
552 ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
553 ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
555 Here are the gpg detached signatures:
557 ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
558 ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
559 ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
560 ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
562 You should download the signature named after any tarball you download,
563 and then verify its integrity with, for example:
565 gpg --verify libtool-@VERSION.tar.gz.sig
567 Here are the MD5 and SHA1 checksums:
569 @MD5SUM@ libtool-@VERSION@.tar.gz
570 @MD5SUM@ libtool-@VERSION@.tar.bz2
571 @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
572 @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
573 @SHA1SUM@ libtool-@VERSION@.tar.gz
574 @SHA1SUM@ libtool-@VERSION@.tar.bz2
575 @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
576 @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
578 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
579 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
582 Alternatively, you can fetch the unbootstrapped sourcecode from
583 anonymous cvs by using the following commands (just hit return when
584 you are prompted for the password):
587 $ cvs -z3 -d :ext:anoncvs@savannah.gnu.org:/cvsroot/libtool \
588 co -r @CVS_RELEASE_TAG@ libtool
590 You will then need to have the latest release versions of Automake
591 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
592 bootstrap the checked out sources yourself.
594 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
595 output of any failed test groups, and the output from `./libtool --help.'
599 Copyright (C) 2004, 2005 Free Software Foundation, Inc.
601 The canonical source of this file is maintained with the
602 GNU Libtool package. Report bugs to bug-libtool@gnu.org.
604 GNU Libtool is free software; you can redistribute it and/or
605 modify it under the terms of the GNU General Public License as
606 published by the Free Software Foundation; either version 2
607 of the License, or (at your option) any later version.
609 As a special exception to the GNU General Public License,
610 if you distribute this file as part of a program or library that
611 is built using GNU libtool, you may include it under the same
612 distribution terms that you use for the rest of that program.
614 GNU Libtool is distributed in the hope that it will be useful,
615 but WITHOUT ANY WARRANTY; without even the implied warranty of
616 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
617 General Public License for more details.
619 You should have received a copy of the GNU General Public License
620 along with GNU Libtool; if not, write to the Free Software
621 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA