HACKING

   1 GNU Libtool
   2 ***********
   3
   4 1. Introduction
   5 ===============
   6
   7 This file attempts to describe the processes we use to maintain libtool,
   8 and is not part of a release distribution.
   9
  10 2. Maintenance Notes
  11 ====================
  12
  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
  16   address to THANKS
  17
  18 * If a change fixes a test, mention the test in the ChangeLog entry.
  19
  20 * If somebody reports a new bug, mention his name in the ChangeLog entry
  21   and in the test case you write.
  22
  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.
  26
  27 * Some files in the libtool package are not owned by libtool.  These
  28   files should never be edited here.  These files are:
  29         COPYING
  30         INSTALL
  31         config/
  32             + config.guess
  33             + config.sub
  34             + depcomp
  35             + install-sh
  36             + mdate-sh
  37             + missing
  38             + texinfo.tex
  39         doc/
  40             + fdl.texi
  41         libltdl/
  42             + COPYING.LIB
  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).
  47
  48 * Changes other than bug fixes must be mentioned in NEWS
  49
  50
  51 3. Test Suite
  52 =============
  53
  54 * When writing tests, make sure the link invocation (first argument to
  55   AT_CHECK) is on a single line so that 'testsuite -x' displays the
  56   whole thing.
  57
  58 * Use
  59     make check TESTSUITEFLAGS=-V
  60     make check-local
  61   liberally, on as many platforms as you can.  Use as many compilers and
  62   linkers you can.
  63
  64 * The new Autotest testsuite uses keywords to denote test features:
  65     autoconf            needs Autoconf
  66     automake            needs Automake
  67     libltdl             exercises the `libltdl' library
  68     libtool             exercises the `libtool' script
  69     libtoolize          exercises the `libtoolize' script
  70     recursive           runs the suite recursively, with a modified
  71                         `libtool' script and with `-k libtool'
  72     CXX F77 FC GCJ      exercises a language other than C
  73
  74
  75 4. Naming
  76 =========
  77
  78 * We've adopted the convention that exported Autoconf macros should be
  79   named with a leading `LT_' and be documented in the libtool manual.
  80   Internal macros begin with `_LT_' if they are visible to aclocal, or
  81   potentially part of an AC_DEFUN/AC_REQUIRE path, or else `_lt_' if
  82   they are very low level.  This convention was only introduced just
  83   before libtool-2.0, so there may still be exceptions in the existing
  84   code.  But all new code should use it.
  85
  86 * All shell variables used internally by libtool's Autoconf macros
  87   should be named with the a leading `lt_' (not that they cannot clash
  88   with the `_lt_' macro namespace).
  89
  90
  91 5. Editing 'ChangeLog'
  92 ======================
  93
  94 * When in doubt, check that emacs can syntax-color properly in
  95   change-log-mode.  And preferably use emacs 'C-x 4 a'
  96   (add-change-log-entry-other-window) to open ChangeLog with an
  97   appropriate new template.
  98
  99 * If this change is by a different author, or on a different date to the
 100   last entry start a new entry at the top of the file with the format
 101   (note two spaces between each field):
 102
 103 yyyy-mm-dd  Name of Author  <email@address>
 104
 105 *  If more than one person collaborated on the change, additional
 106    authors can be listed on subsequent lines, thus:
 107
 108 yyyy-mm-dd  Name of Main Author  <email@address>,
 109             Name of Contributor  <another@email.address>
 110
 111 * Where a change author did not supply a copyright assignment, but the
 112   changes they submitted were sufficiently trivial to commit in any case
 113   (see the GCS for guidelines on this), then flag this against their
 114   name in the header, thus:
 115
 116 yyyy-mm-dd  Name of Author  <email@address>  (tiny change)
 117
 118 * In ChangeLog.2004 and earlier, 'Name of Author' was sometimes the name
 119   of the author of the ChangeLog when the person who made the change
 120   being documented didn't supply one.   In that case separated from
 121   the previous field by a blank line and indented by 1 tab (note, only
 122   1 space between fields here) you will see:
 123
 124         From Author of Actual Change <email@address>:
 125
 126   As of now, don't do that anymore, since the GNU Coding Standards say
 127   that the author of the change must be credited in the main entry
 128   header for legal purposes.
 129
 130 * Preferably the next part should be a description of the overall
 131   purpose of the change, separated from the header by a blank line,
 132   indented by 1 tab, and filled at column 72.  The last character of the
 133   description should be a colon, :.
 134
 135 * Changes to each file come next.  Each new file starts on a new line,
 136   indented by 1 tab and starting with an asterisk and a space.  Multiple
 137   files can be listed here relative to $top_srcdir, and comma separated.
 138   Names of functions (or sections as appropriate) to which the change
 139   applies should be named inside parentheses and comma separated.  If
 140   this goes beyond column 72, then parens should be closed and re-opened
 141   on the next line:
 142
 143         * file, another/file, test/testcases/foo.test (func_foo)
 144         (func_bar, func_baz): Description of changes.
 145
 146 * If the change does not apply to particular functions (or sections),
 147   the section list can be omitted:
 148
 149         * file, another/file, test/testcases/foo.test: General changes.
 150
 151 * If the changes are particular to certain architectures, they should be
 152   listed after the functions in square brackets:
 153
 154         * file, another/file (func_foo) [linux, solaris]: Description of
 155         changes.
 156
 157 * Subsequent changes in other files that are related to the same overall
 158   enhancement or bugfix should be listed concurrently, without blank
 159   lines.  Always start a fresh line for a new file:
 160
 161         * file, another/file (func_foo) [linux, solaris]: Description of
 162         changes.
 163         * doc/foo.texi (Invoking Foo): Document.
 164         * NEWS: Updated.
 165
 166 * If the change is in response to a problem reported by someone other
 167   than the author, then credit them at the end of the description with:
 168
 169         Reported by Reporter Name <email@address>.
 170
 171 * See the GNU Coding Standards document for more details on ChangeLog
 172   formatting.
 173
 174
 175 2005-01-08  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>  (tiny change),
 176             Peter O'Gorman  <peter@pogma.com>
 177
 178         This is the overall description of the purpose of this change
 179         and any useful background for a model ChangeLog entry:
 180
 181         * HACKING: Updated copyright.  This isn't attached to a
 182         particular section of the file, so it comes first.
 183         (Editing 'ChangeLog'): New section.  This applies to the same
 184         file, but since it applies to a particular section it starts on
 185         a new line.
 186         (Introduction, Maintenance Notes, Test Suite, Naming)
 187         (Editing '.am' Files): If I had changed all these sections in
 188         the same way, I can list them like this, being careful to close
 189         and reopen the parentheses when starting a new line.  The colon
 190         only comes after the last section before this description.
 191         * NEWS: Updated.
 192         Reported by Bob Friesenhahn <bfriesen@simple.dallas.tx.us>.
 193
 194 * You may find it useful to install the git-merge-changelog merge driver:
 195   http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
 196
 197 6. Editing `.am' Files
 198 ======================
 199
 200 * Always use $(...) and not ${...}
 201
 202 * Use `:', not `true'.  Use `exit 1', not `false'.
 203
 204 * Use `##' comments liberally.  Comment anything even remotely unusual.
 205
 206 * Never use basename or dirname.  Instead use sed.
 207
 208 * Do not use `cd' within back-quotes, use `$(lt__cd)' instead.
 209   Otherwise the directory name may be printed, depending on CDPATH.
 210
 211 * In general, if a loop is required, it should be silent.  Then the body
 212   of the loop itself should print each "important" command it runs.
 213
 214 * Use 4 extra spaces to indent continued dependencies.
 215
 216 * One needs to remember that for our whole logic for the different
 217   libltdl modes to function correctly, the thing we need to ensure
 218   *before the client runs libtoolize*, is that the subpackage case is
 219   correct (because all files may be symlinked there).  All others can
 220   and will be fixed in the `libtoolize --ltdl --(non)recursive' stage.
 221
 222
 223 7. Editing `.m4sh' Files
 224 ========================
 225
 226 * Use shell functions, but be careful not to assume local scope for
 227   variable names.  Don't use `return', instead echo the result of a
 228   function and call it from within backquotes.
 229
 230 * Function names should be prefixed `func_', the function header should
 231   look like this:
 232
 233   # func_foo [ OPTIONS ]
 234   # Description of what func_foo does and returns.
 235   func_foo ()
 236   {
 237       $opt_debug
 238       # contents of func_foo ...
 239   }
 240
 241   The `$opt_debug' is used to enable shell tracing (Korn shells reset
 242   this on function entry).
 243
 244 * For functions that are called frequently, if you need to return a
 245   value, don't cause unneccessary forking of the shell using echo as
 246   described above; instead set the return value in a variable named
 247   after the called function with a suffix of `_result'.  For example
 248   the function `func_quote_for_eval' stores its return value in the
 249   variable `$func_quote_for_eval_result'.
 250
 251 * Although sh-indentation is set to 2 (by the `Local Variables:' block
 252   at the end of .m4sh files), the left margin of the body of shell
 253   functions should begin indented by 4 spaces.
 254
 255 * Where there are large blocks of shell code with no m4 or m4sh
 256   expansions, put the entire block in an M4SH_VERBATIM call.  This
 257   saves both on copy-and-paste errors, and needing to remember to
 258   internally double the m4 quoting characters:
 259
 260   M4SH_VERBATIM([[
 261   my_sed_long_opt='1s/^\(--[^=]*\)=.*/\1/;q'
 262   ...
 263   ]])
 264
 265
 266 8. Editing `.m4' Files
 267 ======================
 268
 269 * Be careful with both `echo' and `$ECHO'.  As the latter may be one of
 270    echo
 271    print -r
 272    printf %s\n
 273    $CONFIG_SHELL $0 --fallback-echo
 274   it may not have more than one argument, its value may not be eval'ed
 275   and the argument may not start with a `-'.  As a rule of thumb, use
 276    echo ..              for literal (constant) strings without leading
 277                         hyphen and no backslashes within,
 278    $ECHO ".."           for strings without leading hyphen,
 279    $ECHO "X.." | $Xsed  otherwise.
 280
 281 * The Autoconf manual says that giving an empty parameter is equivalent
 282   to not giving it at all.  (In particular, the Autoconf manual doesn't
 283   explain that "FOO()" is calling macro FOO with one empty parameter.)
 284   To prevent misunderstanding, we should use m4_ifval to check whether
 285   a parameter is empty, and not $# to check for the number of parameters.
 286
 287 * Any time we add a macro to an older version, lt~obsolete.m4 needs to
 288   be updated in all newer versions.
 289
 290
 291 9. Abstraction layers in libltdl
 292 ================================
 293
 294 * The libltdl API uses a layered approach to differentiate internal and
 295   external interfaces, among other things.  To keep the abstraction
 296   consistent, files in a given layer may only use APIs from files in the
 297   lower layers.  The ASCII art boxes below represent this stack, from
 298   top to bottom...
 299
 300 * But first, outside of the stack, there is a convenience header that
 301   defines the internal interfaces (as evidenced by the `lt__' prefix to
 302   the filename!) shared between implementation files in the stack, that
 303   are however not exported to libltdl clients:
 304
 305         ,-------------.
 306         |lt__private.h|
 307         `-------------'
 308
 309 * The top layer of the stack is the libltdl API proper, which includes
 310   the relevant subsystems automatically.  Clients of libltdl need only
 311   invoke:
 312
 313   #include <ltdl.h>
 314
 315         ,------.
 316         |ltdl.h|
 317         +------+
 318         |ltdl.c|
 319         `------'
 320
 321 * The next layer is comprised of the subsystems of the exported libltdl
 322   API, which are implemented by files that are named with a leading `lt_'
 323   (single underscore!):
 324
 325         ,------------v---------------.
 326         | lt_error.h | lt_dlloader.h |
 327         +------------+---------------+
 328         | lt_error.c | lt_dlloader.c |
 329         `------------^---------------'
 330
 331 * The next file is used both by the headers that implement it (in which
 332   case its function is to avoid namespace clashes when linking with the
 333   GNU C library proper) and is included by code that wants to program
 334   against a glibc-like interface, in which case it serves to pull in all
 335   the glibc-like functionality used by libltdl with a simple:
 336
 337     #include <libltdl/lt__glibc.h>
 338
 339   It consists of a single file:
 340
 341         ,-----------.
 342         |lt__glibc.h|
 343         `-----------'
 344
 345 * Next to last is the libc abstraction layer, which provides a uniform
 346   API to various system libc interfaces that differ between hosts
 347   supported by libtool.  Typically, the files that implement this layer
 348   begin:
 349
 350     #if defined(LT_CONFIG_H)
 351     #  include LT_CONFIG_H
 352     #else
 353     #  include <config.h>
 354     #endif
 355     #include "lt_system.h"
 356
 357   Or if they are installed headers that must work outside the libtool
 358   source tree, simply:
 359
 360     #include <libltdl/lt_system.h>
 361
 362   This layer's interface is defined by files that are usually named with
 363   a leading `lt__':
 364
 365         ,--------------v-------------v------------v--------v---------.
 366         | lt__dirent.h | lt__alloc.h | lt__strl.h | argz.h | slist.h |
 367         +--------------+-------------+------------+--------+---------+
 368         | lt__dirent.c | lt__alloc.c | lt__strl.c | argz.c | slist.c |
 369         `--------------^-------------^------------^--------^---------'
 370
 371   (argz.h and slist.h are used independently of libltdl in other projects)
 372
 373 * At the bottom of the stack we have the system abstraction layer,
 374   which tries to smooth over the cracks where there are differences
 375   between host systems and compilers.  config.h is generated at
 376   configure time and is not installed; lt_system.h is an installed
 377   file and cannot use macros from config.h:
 378
 379         ,-----------.
 380         |../config.h|
 381         `-----------'
 382
 383         ,-----------.
 384         |lt_system.h|
 385         `-----------'
 386
 387 * Tacked on the side of this stack, attached via the lt_dlloader.h
 388   definitions are the various implementation modules for run-time module
 389   loading: preopen.c, dlopen.c etc.
 390
 391
 392 10. Licensing Rules
 393 ===================
 394
 395 GNU Libtool uses 3 different licenses for various of the files distributed
 396 herein, with 7 variations on license text.  It is important that you use
 397 the correct license text in each new file added.  Here are the texts
 398 along with some notes on when each is appropriate.  Appropriate commenting
 399 (shell, C etc) and decoration (m4sh etc) assumed throughout.
 400
 401 10.1. Notice preservation
 402
 403 Autoconf macros and files used to generate them need this license:
 404
 405    Copyright (C) <year list> Free Software Foundation, Inc.
 406    Written by <author>, <year>
 407
 408 This file is free software; the Free Software Foundation gives
 409 unlimited permission to copy and/or distribute it, with or without
 410 modifications, as long as this notice is preserved.
 411
 412
 413
 414 10.2. GPL
 415
 416 Everything else in the distribution has the following license text
 417 unless there is good reason to use one of the other license texts
 418 below:
 419
 420    Copyright (C) <year list> Free Software Foundation, Inc.
 421    Written by <author>, <year>
 422
 423   This file is part of GNU Libtool.
 424
 425 GNU Libtool is free software; you can redistribute it and/or
 426 modify it under the terms of the GNU General Public License as
 427 published by the Free Software Foundation; either version 2 of
 428 the License, or (at your option) any later version.
 429
 430 GNU Libtool is distributed in the hope that it will be useful,
 431 but WITHOUT ANY WARRANTY; without even the implied warranty of
 432 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 433 GNU General Public License for more details.
 434
 435 You should have received a copy of the GNU General Public License
 436 along with GNU Libtool; see the file COPYING.  If not, a copy
 437 can be downloaded from  http://www.gnu.org/licenses/gpl.html,
 438 or obtained by writing to the Free Software Foundation, Inc.,
 439 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 440
 441
 442
 443 10.3. GPL with Libtool exception clause
 444
 445 At the moment only `libltdl/README' needs the exception clause to
 446 allow projects that distribute a copy of the libltdl sources to also
 447 redistribute the README:
 448
 449
 450    Copyright (C) <year list> Free Software Foundation, Inc.
 451    Written by <author>, <year>
 452
 453    This file is part of GNU Libtool.
 454
 455 GNU Libtool is free software; you can redistribute it and/or
 456 modify it under the terms of the GNU General Public License as
 457 published by the Free Software Foundation; either version 2 of
 458 the License, or (at your option) any later version.
 459
 460 As a special exception to the GNU General Public License,
 461 if you distribute this file as part of a program or library that
 462 is built using GNU Libtool, you may include this file under the
 463 same distribution terms that you use for the rest of that program.
 464
 465 GNU Libtool is distributed in the hope that it will be useful,
 466 but WITHOUT ANY WARRANTY; without even the implied warranty of
 467 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 468 GNU General Public License for more details.
 469
 470 You should have received a copy of the GNU General Public License
 471 along with GNU Libtool; see the file COPYING.  If not, a copy
 472 can be downloaded from  http://www.gnu.org/licenses/gpl.html,
 473 or obtained by writing to the Free Software Foundation, Inc.,
 474 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 475
 476
 477
 478 10.4. GPL with Cvs-utils exception clause
 479
 480 GNU Libtool imports some m4sh infrastructure from the GNU Cvs-utils
 481 project, namely `getopt.m4sh' and `general.m4sh'.  Those files use
 482 the GPL with their own exception clause as follows:
 483
 484    Copyright (C) <year list> Free Software Foundation, Inc.
 485    Written by <author>, <year>
 486
 487    This file is part of GNU Cvs-utils.
 488
 489 GNU Cvs-utils is free software; you can redistribute it and/or
 490 modify it under the terms of the GNU General Public License as
 491 published by the Free Software Foundation; either version 2 of
 492 the License, or (at you option) any later version.
 493
 494 As a special exception to the GNU General Public License, if you
 495 distribute this file as part of a program or library that contains
 496 a configuration script generated by Autoconf, you may include this
 497 file under the same distribution terms that you use for the rest
 498 of that program.
 499
 500 GNU Cvs-utils is distributed in the hope that it will be useful,
 501 but WITHOUT ANY WARRANTY; without even the implied warranty of
 502 MERCHANTABILITY or FITNES FOR A PARTICULAR PURPOSE. See the GNU
 503 General Public License for more details.
 504
 505 You should have received a copy of the GNU General Public License
 506 along with GNU Libtool; see the file COPYING.  If not, a copy
 507 can be downloaded from  http://www.gnu.org/licenses/gpl.html,
 508 or obtained by writing to the Free Software Foundation, Inc.,
 509 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 510
 511
 512
 513 10.5. GPL with self extracting version
 514
 515 Some of the sources built atop Cvs-utils' m4sh framework use
 516 getopt.m4sh:func_version() to extract their --version output from
 517 the copyright block.  Those files also need the --version copyright
 518 text paragraph as follows:
 519
 520    <program name> (GNU @PACKAGE@) <version number>
 521    Written by <author> <email address>.
 522
 523    This file is part of <parent package name>.
 524
 525 Copyright (C) <year list> Free Software Foundation, Inc.
 526 This is free software; see the source for copying conditions.  There is NO
 527 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 528
 529 <program name> is free software; you can redistribute it and/or modify
 530 it under the terms of the GNU General Public License as published by
 531 the Free Software Foundation; either version 2 of the License, or
 532 (at your option) any later version.
 533
 534 <program name> is distributed in the hope that it will be useful, but
 535 WITHOUT ANY WARRANTY; without even the implied warranty of
 536 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 537 GNU General Public License for more details.
 538
 539 You should have received a copy of the GNU General Public License
 540 along with <program name>; see the file COPYING.  If not, a copy
 541 can be downloaded from http://www.gnu.org/licenses/gpl.html,
 542 or obtained by writing to the Free Software Foundation, Inc.,
 543 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 544
 545
 546
 547 10.6. GPL with self extracting version and Libtool exception clause
 548
 549 Although the libtool script is generated from `ltmain.m4sh' according
 550 to the rules in the preceding subsection, it also needs the Libtool
 551 exception clause so that it can be redistributed by other projects
 552 that use libtool:
 553
 554   <program name> (GNU @PACKAGE@@TIMESTAMP@) <version number>
 555   Written by <author> <email address>.
 556
 557   This file is part of GNU Libtool.
 558
 559 Copyright (C) <year list> Free Software Foundation, Inc.
 560 This is free software; see the source for copying conditions.  There is NO
 561 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 562
 563 <program name> is free software; you can redistribute it and/or modify
 564 it under the terms of the GNU General Public License as published by
 565 the Free Software Foundation; either version 2 of the License, or
 566 (at your option) any later version.
 567
 568 As a special exception to the GNU General Public License,
 569 if you distribute this file as part of a program or library that
 570 is built using GNU Libtool, you may include this file under the
 571 same distribution terms that you use for the rest of that program.
 572
 573 <program name> is distributed in the hope that it will be useful, but
 574 WITHOUT ANY WARRANTY; without even the implied warranty of
 575 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 576 GNU General Public License for more details.
 577
 578 You should have received a copy of the GNU General Public License
 579 along with <program name>; see the file COPYING.  If not, a copy
 580 can be downloaded from http://www.gnu.org/licenses/gpl.html,
 581 or obtained by writing to the Free Software Foundation, Inc.,
 582 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 583
 584
 585
 586 10.7. LGPL with Libtool exception clause
 587
 588 Finally, not only is Libltdl is LGPLed, but it is routinely
 589 redistributed inside projects that use it, so its sources need to use
 590 the following license text citing the LGPL along with Libtool's special
 591 exception clause:
 592
 593    Copyright (C) <year list> Free Software Foundation, Inc.
 594    Written by <author>, <year>
 595
 596    NOTE: The canonical source of this file is maintained with the
 597    GNU Libtool package.  Report bugs to bug-libtool@gnu.org.
 598
 599 GNU Libltdl is free software; you can redistribute it and/or
 600 modify it under the terms of the GNU Lesser General Public
 601 License as published by the Free Software Foundation; either
 602 version 2 of the License, or (at your option) any later version.
 603
 604 As a special exception to the GNU Lesser General Public License,
 605 if you distribute this file as part of a program or library that
 606 is built using GNU Libtool, you may include this file under the
 607 same distribution terms that you use for the rest of that program.
 608
 609 GNU Libltdl is distributed in the hope that it will be useful,
 610 but WITHOUT ANY WARRANTY; without even the implied warranty of
 611 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 612 GNU Lesser General Public License for more details.
 613
 614 You should have received a copy of the GNU Lesser General Public
 615 License along with GNU Libltdl; see the file COPYING.LIB.  If not, a
 616 copy can be downloaded from  http://www.gnu.org/licenses/lgpl.html,
 617 or obtained by writing to the Free Software Foundation, Inc.,
 618 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 619
 620
 621 11. Release Procedure
 622 =====================
 623
 624 * If you are a libtool maintainer, but have not yet registered your
 625   gpg public key and (preferred) email address with the FSF, send an
 626   email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
 627   the following:
 628
 629     (a) name of package(s) that you are the maintainer for, and your
 630         preferred email address.
 631
 632     (b) an ASCII armored copy of your GnuPG key, as an attachment.
 633         ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
 634         this.)
 635
 636   When you have received acknowledgement of your message, the proper GPG
 637   keys will be registered on ftp-upload.gnu.org and only then will you be
 638   authorized to upload files to the FSF ftp machines.
 639
 640 * If you do not have access to the mailing list administrative interface,
 641   approach the list owners for the password.  Be sure to check the lists
 642   (esp. bug-libtool) for outstanding bug reports also in the list of
 643   pending moderation requests.
 644
 645 * Make sure you have wget installed.
 646
 647 * Make sure you have a copy of xdelta installed, and a copy of the previous
 648   release tarball in the build directory.
 649
 650 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
 651
 652 * Double check that serial number updates in public m4 files weren't forgotten
 653   since last release (they should be updated in CVS along with commits that
 654   require it so that users can work with CVS snapshots).
 655
 656 * Update the LTDL_VERSION_INFO in libltdl/Makefile.inc for changes since
 657   the last release.
 658
 659 * Update the version number in configure.ac and libltdl/configure.ac.
 660   See http://www.gnu.org/software/libtool/contribute.html for details of
 661   the numbering scheme.
 662
 663 * Update NEWS, ChangeLog.
 664
 665 * Run ./bootstrap.
 666
 667 * Have some tea.  If you are running on less than 3.6GHz CPU, order
 668   a pizza too ;-)
 669
 670 * Run ./configure (or create a build directory first and run configure
 671   from there, if you want to keep the build tree separate).
 672
 673 * Run `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
 674   if you are running from a VPATH build directory, where `../' is the
 675   relative path to the directory with `configure' in it), which will
 676   fetch new versions of the files that are maintained outside of
 677   libtool.
 678
 679 * Run `make distcheck' and `make distcheck
 680   DISTCHECK_CONFIGURE_FLAGS=--disable-ltdl-install'.  Try a distcheck
 681   with --program-prefix=g.  If there are any problems, fix them and
 682   start again.
 683
 684 * Run ./commit from the source tree.
 685
 686 * Run `make -fMakefile.maint cvs-dist' (or `make -f../Makefile.maint
 687   cvs-dist' if you are running from a VPATH build directory, where `../'
 688   is the relative path to the directory with `configure' in it), which
 689   will build a release tarball (with `make distcheck'), tag the tree
 690   with release-$(VERSION) and generate the gpg signature files.
 691
 692 * Run 'make -f[../]Makefile.maint deltas' (pass
 693   LASTRELEASE=maj.min[.mic[alpha]] if needed) to create both diff and
 694   xdelta files between the previous release tarball and the new with
 695   detached gpg signature files and clear signed directive files.
 696
 697 * Upload release tarball, diff file and xdelta file, plus their associated
 698   detached gpg signature files and clear signed directive files to
 699   ftp-upload.gnu.org.  If the upload is destined for ftp.gnu.org, then the
 700   files should be placed in the /incoming/ftp directory.  If the upload is
 701   an alpha release destined for alpha.gnu.org, then the files should be
 702   placed in the /incoming/alpha directory.
 703
 704 * Send announcement to libtool@gnu.org and autotools-announce@gnu.org,
 705   if not an alpha send to info-gnu@gnu.org as well.
 706
 707 * Update version number in configure.ac and libltdl/configure.ac to next
 708   alpha number.  See http://www.gnu.org/software/libtool/contribute.html
 709   for details of the numbering scheme.
 710
 711 * Update NEWS, ChangeLog.
 712
 713 * Run ./commit.
 714
 715 * Update the webpages, libtool.html will need to indicate the latest
 716   release number and the news page should get a HTMLified copy of your
 717   release announcement.
 718
 719 * If not an alpha, replace manual.html with the new one
 720   (generate with `make -f[../]Makefile.maint web-manual').
 721
 722
 723
 724 12. Alpha release note template
 725 ===============================
 726
 727 To: libtool@gnu.org, autotools-announce@gnu.org
 728 Subject: GNU Libtool @VERSION@ released (alpha release).
 729
 730 The Libtool Team is pleased to announce alpha release @VERSION@ of GNU
 731 Libtool.
 732
 733 GNU Libtool hides the complexity of using shared libraries behind a
 734 consistent, portable interface. GNU Libtool ships with GNU libltdl,
 735 which hides the complexity of loading dynamic runtime libraries
 736 (modules) behind a consistent, portable interface.
 737
 738 Here are the compressed sources:
 739
 740   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
 741   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
 742
 743 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 744
 745   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 746   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 747
 748 Here are the gpg detached signatures:
 749
 750   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
 751   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
 752   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 753   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 754
 755 You should download the signature named after any tarball you download,
 756 and then verify its integrity with, for example:
 757
 758   gpg --verify libtool-@VERSION@.tar.gz.sig
 759
 760 Here are the MD5 and SHA1 checksums:
 761
 762   @MD5SUM@ libtool-@VERSION@.tar.gz
 763   @MD5SUM@ libtool-@VERSION@.tar.bz2
 764   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 765   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 766   @SHA1SUM@ libtool-@VERSION@.tar.gz
 767   @SHA1SUM@ libtool-@VERSION@.tar.bz2
 768   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 769   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 770
 771 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 772
 773 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
 774 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
 775 projects.
 776
 777 Alternatively, you can fetch the unbootstrapped source code from
 778 anonymous cvs by using the following command:
 779
 780   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/libtool \
 781     co -r @CVS_RELEASE_TAG@ libtool
 782
 783 You will then need to have recent (possibly as yet unreleased) versions
 784 of Automake and Autoconf installed to bootstrap the checked out
 785 sources yourself.
 786
 787 New in @VERSION@: @RELEASE_DATE@
 788
 789   @EXCERPT_FROM_NEWS_FILE@
 790
 791 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
 792 output of any failed test groups, and the output from `./libtool --config.'
 793 The README file explains how to capture the verbose test output.
 794
 795
 796
 797 13. Full release note template
 798 ==============================
 799
 800 To: info-gnu@gnu.org
 801 Cc: libtool@gnu.org, autotools-announce@gnu.org
 802 Subject: GNU Libtool @VERSION@ released.
 803
 804 The Libtool Team is pleased to announce the release of GNU Libtool
 805 @VERSION@.
 806
 807 GNU Libtool hides the complexity of using shared libraries behind a
 808 consistent, portable interface. GNU Libtool ships with GNU libltdl,
 809 which hides the complexity of loading dynamic runtime libraries
 810 (modules) behind a consistent, portable interface.
 811
 812 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 813
 814 New in @VERSION@: @RELEASE_DATE@
 815
 816   @EXCERPT_FROM_NEWS_FILE@
 817
 818 libtool-@VERSION@ is available now from ftp.gnu.org, along with
 819 diffs and xdeltas against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@
 820 that are also available from ftp.gnu.org.  Please
 821 use a mirror to reduce stress on the main gnu machine:
 822
 823   http://www.gnu.org/order/ftp.html
 824
 825 Here are the compressed sources:
 826
 827   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
 828   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
 829
 830 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 831
 832   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 833   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 834
 835 Here are the gpg detached signatures:
 836
 837   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
 838   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
 839   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 840   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 841
 842 You should download the signature named after any tarball you download,
 843 and then verify its integrity with, for example:
 844
 845   gpg --verify libtool-@VERSION@.tar.gz.sig
 846
 847 Here are the MD5 and SHA1 checksums:
 848
 849   @MD5SUM@ libtool-@VERSION@.tar.gz
 850   @MD5SUM@ libtool-@VERSION@.tar.bz2
 851   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 852   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 853   @SHA1SUM@ libtool-@VERSION@.tar.gz
 854   @SHA1SUM@ libtool-@VERSION@.tar.bz2
 855   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 856   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 857
 858 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
 859 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
 860 projects.
 861
 862 Alternatively, you can fetch the unbootstrapped source code from
 863 anonymous cvs by using the following command (just hit return when
 864 you are prompted for the password):
 865
 866   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/libtool \
 867     co -r @CVS_RELEASE_TAG@ libtool
 868
 869 You will then need to have the latest release versions of Automake
 870 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
 871 bootstrap the checked out sources yourself.
 872
 873 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
 874 output of any failed test groups, and the output from `./libtool --config.'
 875 The README file explains how to capture the verbose test output.
 876
 877
 878 --
 879   Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
 880   Written by Gary V. Vaughan, 2004
 881
 882   This file is part of GNU Libtool.  Report bugs to bug-libtool@gnu.org.
 883
 884 GNU Libtool is free software; you can redistribute it and/or
 885 modify it under the terms of the GNU General Public License as
 886 published by the Free Software Foundation; either version 2
 887 of the License, or (at your option) any later version.
 888
 889 GNU Libtool is distributed in the hope that it will be useful,
 890 but WITHOUT ANY WARRANTY; without even the implied warranty of
 891 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 892 GNU General Public License for more details.
 893
 894 You should have received a copy of the GNU General Public License
 895 along with GNU Libtool; see the file COPYING.  If not, a copyi
 896 can be downloaded from http://www.gnu.org/licenses/gpl.html,
 897 or obtained by writing to the Free Software Foundation, Inc.,
 898 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 899
 900 Local Variables:
 901 mode: text
 902 fill-column: 72
 903 End:
 904 vim:tw=72