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
 195 6. Editing `.am' Files
 196 ======================
 197
 198 * Always use $(...) and not ${...}
 199
 200 * Use `:', not `true'.  Use `exit 1', not `false'.
 201
 202 * Use `##' comments liberally.  Comment anything even remotely unusual.
 203
 204 * Never use basename or dirname.  Instead use sed.
 205
 206 * Do not use `cd' within back-quotes, use `$(lt__cd)' instead.
 207   Otherwise the directory name may be printed, depending on CDPATH.
 208
 209 * In general, if a loop is required, it should be silent.  Then the body
 210   of the loop itself should print each "important" command it runs.
 211
 212 * Use 4 extra spaces to indent continued dependencies.
 213
 214 * One needs to remember that for our whole logic for the different
 215   libltdl modes to function correctly, the thing we need to ensure
 216   *before the client runs libtoolize*, is that the subpackage case is
 217   correct (because all files may be symlinked there).  All others can
 218   and will be fixed in the `libtoolize --ltdl --(non)recursive' stage.
 219
 220
 221 7. Editing `.m4sh' Files
 222 ========================
 223
 224 * Use shell functions, but be careful not to assume local scope for
 225   variable names.  Don't use `return', instead echo the result of a
 226   function and call it from within backquotes.
 227
 228 * Function names should be prefixed `func_', the function header should
 229   look like this:
 230
 231   # func_foo [ OPTIONS ]
 232   # Description of what func_foo does and returns.
 233   func_foo ()
 234   {
 235       $opt_debug
 236       # contents of func_foo ...
 237   }
 238
 239   The `$opt_debug' is used to enable shell tracing (Korn shells reset
 240   this on function entry).
 241
 242 * For functions that are called frequently, if you need to return a
 243   value, don't cause unneccessary forking of the shell using echo as
 244   described above; instead set the return value in a variable named
 245   after the called function with a suffix of `_result'.  For example
 246   the function `func_quote_for_eval' stores its return value in the
 247   variable `$func_quote_for_eval_result'.
 248
 249 * Although sh-indentation is set to 2 (by the `Local Variables:' block
 250   at the end of .m4sh files), the left margin of the body of shell
 251   functions should begin indented by 4 spaces.
 252
 253 * Where there are large blocks of shell code with no m4 or m4sh
 254   expansions, put the entire block in an M4SH_VERBATIM call.  This
 255   saves both on copy-and-paste errors, and needing to remember to
 256   internally double the m4 quoting characters:
 257
 258   M4SH_VERBATIM([[
 259   my_sed_long_opt='1s/^\(--[^=]*\)=.*/\1/;q'
 260   ...
 261   ]])
 262
 263
 264 8. Editing `.m4' Files
 265 ======================
 266
 267 * Be careful with both `echo' and `$ECHO'.  As the latter may be one of
 268    echo
 269    print -r
 270    printf %s\n
 271    $CONFIG_SHELL $0 --fallback-echo
 272   it may not have more than one argument, its value may not be eval'ed
 273   and the argument may not start with a `-'.  As a rule of thumb, use
 274    echo ..              for literal (constant) strings without leading
 275                         hyphen and no backslashes within,
 276    $ECHO ".."           for strings without leading hyphen,
 277    $ECHO "X.." | $Xsed  otherwise.
 278
 279 * The Autoconf manual says that giving an empty parameter is equivalent
 280   to not giving it at all.  (In particular, the Autoconf manual doesn't
 281   explain that "FOO()" is calling macro FOO with one empty parameter.)
 282   To prevent misunderstanding, we should use m4_ifval to check whether
 283   a parameter is empty, and not $# to check for the number of parameters.
 284
 285 * Any time we add a macro to an older version, lt~obsolete.m4 needs to
 286   be updated in all newer versions.
 287
 288
 289 9. Abstraction layers in libltdl
 290 ================================
 291
 292 * The libltdl API uses a layered approach to differentiate internal and
 293   external interfaces, among other things.  To keep the abstraction
 294   consistent, files in a given layer may only use APIs from files in the
 295   lower layers.  The ASCII art boxes below represent this stack, from
 296   top to bottom...
 297
 298 * But first, outside of the stack, there is a convenience header that
 299   defines the internal interfaces (as evidenced by the `lt__' prefix to
 300   the filename!) shared between implementation files in the stack, that
 301   are however not exported to libltdl clients:
 302
 303         ,-------------.
 304         |lt__private.h|
 305         `-------------'
 306
 307 * The top layer of the stack is the libltdl API proper, which includes
 308   the relevant subsystems automatically.  Clients of libltdl need only
 309   invoke:
 310
 311   #include <ltdl.h>
 312
 313         ,------.
 314         |ltdl.h|
 315         +------+
 316         |ltdl.c|
 317         `------'
 318
 319 * The next layer is comprised of the subsystems of the exported libltdl
 320   API, which are implemented by files that are named with a leading `lt_'
 321   (single underscore!):
 322
 323         ,------------v---------------.
 324         | lt_error.h | lt_dlloader.h |
 325         +------------+---------------+
 326         | lt_error.c | lt_dlloader.c |
 327         `------------^---------------'
 328
 329 * The next file is used both by the headers that implement it (in which
 330   case its function is to avoid namespace clashes when linking with the
 331   GNU C library proper) and is included by code that wants to program
 332   against a glibc-like interface, in which case it serves to pull in all
 333   the glibc-like functionality used by libltdl with a simple:
 334
 335     #include <libltdl/lt__glibc.h>
 336
 337   It consists of a single file:
 338
 339         ,-----------.
 340         |lt__glibc.h|
 341         `-----------'
 342
 343 * Next to last is the libc abstraction layer, which provides a uniform
 344   API to various system libc interfaces that differ between hosts
 345   supported by libtool.  Typically, the files that implement this layer
 346   begin:
 347
 348     #if defined(LT_CONFIG_H)
 349     #  include LT_CONFIG_H
 350     #else
 351     #  include <config.h>
 352     #endif
 353     #include "lt_system.h"
 354
 355   Or if they are installed headers that must work outside the libtool
 356   source tree, simply:
 357
 358     #include <libltdl/lt_system.h>
 359
 360   This layer's interface is defined by files that are usually named with
 361   a leading `lt__':
 362
 363         ,--------------v-------------v------------v--------v---------.
 364         | lt__dirent.h | lt__alloc.h | lt__strl.h | argz.h | slist.h |
 365         +--------------+-------------+------------+--------+---------+
 366         | lt__dirent.c | lt__alloc.c | lt__strl.c | argz.c | slist.c |
 367         `--------------^-------------^------------^--------^---------'
 368
 369   (argz.h and slist.h are used independently of libltdl in other projects)
 370
 371 * At the bottom of the stack we have the system abstraction layer,
 372   which tries to smooth over the cracks where there are differences
 373   between host systems and compilers.  config.h is generated at
 374   configure time and is not installed; lt_system.h is an installed
 375   file and cannot use macros from config.h:
 376
 377         ,-----------.
 378         |../config.h|
 379         `-----------'
 380
 381         ,-----------.
 382         |lt_system.h|
 383         `-----------'
 384
 385 * Tacked on the side of this stack, attached via the lt_dlloader.h
 386   definitions are the various implementation modules for run-time module
 387   loading: preopen.c, dlopen.c etc.
 388
 389
 390 10. Licensing Rules
 391 ===================
 392
 393 GNU Libtool uses 3 different licenses for various of the files distributed
 394 herein, with 7 variations on license text.  It is important that you use
 395 the correct license text in each new file added.  Here are the texts
 396 along with some notes on when each is appropriate.  Appropriate commenting
 397 (shell, C etc) and decoration (m4sh etc) assumed throughout.
 398
 399 10.1. Notice preservation
 400
 401 Autoconf macros and files used to generate them need this license:
 402
 403    Copyright (C) <year list> Free Software Foundation, Inc.
 404    Written by <author>, <year>
 405
 406 This file is free software; the Free Software Foundation gives
 407 unlimited permission to copy and/or distribute it, with or without
 408 modifications, as long as this notice is preserved.
 409
 410
 411
 412 10.2. GPL
 413
 414 Everything else in the distribution has the following license text
 415 unless there is good reason to use one of the other license texts
 416 below:
 417
 418    Copyright (C) <year list> Free Software Foundation, Inc.
 419    Written by <author>, <year>
 420
 421   This file is part of GNU Libtool.
 422
 423 GNU Libtool is free software; you can redistribute it and/or
 424 modify it under the terms of the GNU General Public License as
 425 published by the Free Software Foundation; either version 2 of
 426 the License, or (at your option) any later version.
 427
 428 GNU Libtool is distributed in the hope that it will be useful,
 429 but WITHOUT ANY WARRANTY; without even the implied warranty of
 430 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 431 GNU General Public License for more details.
 432
 433 You should have received a copy of the GNU General Public License
 434 along with GNU Libtool; see the file COPYING.  If not, a copy
 435 can be downloaded from  http://www.gnu.org/licenses/gpl.html,
 436 or obtained by writing to the Free Software Foundation, Inc.,
 437 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 438
 439
 440
 441 10.3. GPL with Libtool exception clause
 442
 443 At the moment only `libltdl/README' needs the exception clause to
 444 allow projects that distribute a copy of the libltdl sources to also
 445 redistribute the README:
 446
 447
 448    Copyright (C) <year list> Free Software Foundation, Inc.
 449    Written by <author>, <year>
 450
 451    This file is part of GNU Libtool.
 452
 453 GNU Libtool is free software; you can redistribute it and/or
 454 modify it under the terms of the GNU General Public License as
 455 published by the Free Software Foundation; either version 2 of
 456 the License, or (at your option) any later version.
 457
 458 As a special exception to the GNU General Public License,
 459 if you distribute this file as part of a program or library that
 460 is built using GNU Libtool, you may include this file under the
 461 same distribution terms that you use for the rest of that program.
 462
 463 GNU Libtool is distributed in the hope that it will be useful,
 464 but WITHOUT ANY WARRANTY; without even the implied warranty of
 465 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 466 GNU General Public License for more details.
 467
 468 You should have received a copy of the GNU General Public License
 469 along with GNU Libtool; see the file COPYING.  If not, a copy
 470 can be downloaded from  http://www.gnu.org/licenses/gpl.html,
 471 or obtained by writing to the Free Software Foundation, Inc.,
 472 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 473
 474
 475
 476 10.4. GPL with Cvs-utils exception clause
 477
 478 GNU Libtool imports some m4sh infrastructure from the GNU Cvs-utils
 479 project, namely `getopt.m4sh' and `general.m4sh'.  Those files use
 480 the GPL with their own exception clause as follows:
 481
 482    Copyright (C) <year list> Free Software Foundation, Inc.
 483    Written by <author>, <year>
 484
 485    This file is part of GNU Cvs-utils.
 486
 487 GNU Cvs-utils is free software; you can redistribute it and/or
 488 modify it under the terms of the GNU General Public License as
 489 published by the Free Software Foundation; either version 2 of
 490 the License, or (at you option) any later version.
 491
 492 As a special exception to the GNU General Public License, if you
 493 distribute this file as part of a program or library that contains
 494 a configuration script generated by Autoconf, you may include this
 495 file under the same distribution terms that you use for the rest
 496 of that program.
 497
 498 GNU Cvs-utils is distributed in the hope that it will be useful,
 499 but WITHOUT ANY WARRANTY; without even the implied warranty of
 500 MERCHANTABILITY or FITNES FOR A PARTICULAR PURPOSE. See the GNU
 501 General Public License for more details.
 502
 503 You should have received a copy of the GNU General Public License
 504 along with GNU Libtool; see the file COPYING.  If not, a copy
 505 can be downloaded from  http://www.gnu.org/licenses/gpl.html,
 506 or obtained by writing to the Free Software Foundation, Inc.,
 507 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 508
 509
 510
 511 10.5. GPL with self extracting version
 512
 513 Some of the sources built atop Cvs-utils' m4sh framework use
 514 getopt.m4sh:func_version() to extract their --version output from
 515 the copyright block.  Those files also need the --version copyright
 516 text paragraph as follows:
 517
 518    <program name> (GNU @PACKAGE@) <version number>
 519    Written by <author> <email address>.
 520
 521    This file is part of <parent package name>.
 522
 523 Copyright (C) <year list> Free Software Foundation, Inc.
 524 This is free software; see the source for copying conditions.  There is NO
 525 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 526
 527 <program name> is free software; you can redistribute it and/or modify
 528 it under the terms of the GNU General Public License as published by
 529 the Free Software Foundation; either version 2 of the License, or
 530 (at your option) any later version.
 531
 532 <program name> is distributed in the hope that it will be useful, but
 533 WITHOUT ANY WARRANTY; without even the implied warranty of
 534 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 535 GNU General Public License for more details.
 536
 537 You should have received a copy of the GNU General Public License
 538 along with <program name>; see the file COPYING.  If not, a copy
 539 can be downloaded from http://www.gnu.org/licenses/gpl.html,
 540 or obtained by writing to the Free Software Foundation, Inc.,
 541 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 542
 543
 544
 545 10.6. GPL with self extracting version and Libtool exception clause
 546
 547 Although the libtool script is generated from `ltmain.m4sh' according
 548 to the rules in the preceding subsection, it also needs the Libtool
 549 exception clause so that it can be redistributed by other projects
 550 that use libtool:
 551
 552   <program name> (GNU @PACKAGE@@TIMESTAMP@) <version number>
 553   Written by <author> <email address>.
 554
 555   This file is part of GNU Libtool.
 556
 557 Copyright (C) <year list> Free Software Foundation, Inc.
 558 This is free software; see the source for copying conditions.  There is NO
 559 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 560
 561 <program name> is free software; you can redistribute it and/or modify
 562 it under the terms of the GNU General Public License as published by
 563 the Free Software Foundation; either version 2 of the License, or
 564 (at your option) any later version.
 565
 566 As a special exception to the GNU General Public License,
 567 if you distribute this file as part of a program or library that
 568 is built using GNU Libtool, you may include this file under the
 569 same distribution terms that you use for the rest of that program.
 570
 571 <program name> is distributed in the hope that it will be useful, but
 572 WITHOUT ANY WARRANTY; without even the implied warranty of
 573 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 574 GNU General Public License for more details.
 575
 576 You should have received a copy of the GNU General Public License
 577 along with <program name>; see the file COPYING.  If not, a copy
 578 can be downloaded from http://www.gnu.org/licenses/gpl.html,
 579 or obtained by writing to the Free Software Foundation, Inc.,
 580 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 581
 582
 583
 584 10.7. LGPL with Libtool exception clause
 585
 586 Finally, not only is Libltdl is LGPLed, but it is routinely
 587 redistributed inside projects that use it, so its sources need to use
 588 the following license text citing the LGPL along with Libtool's special
 589 exception clause:
 590
 591    Copyright (C) <year list> Free Software Foundation, Inc.
 592    Written by <author>, <year>
 593
 594    NOTE: The canonical source of this file is maintained with the
 595    GNU Libtool package.  Report bugs to bug-libtool@gnu.org.
 596
 597 GNU Libltdl is free software; you can redistribute it and/or
 598 modify it under the terms of the GNU Lesser General Public
 599 License as published by the Free Software Foundation; either
 600 version 2 of the License, or (at your option) any later version.
 601
 602 As a special exception to the GNU Lesser General Public License,
 603 if you distribute this file as part of a program or library that
 604 is built using GNU Libtool, you may include this file under the
 605 same distribution terms that you use for the rest of that program.
 606
 607 GNU Libltdl is distributed in the hope that it will be useful,
 608 but WITHOUT ANY WARRANTY; without even the implied warranty of
 609 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 610 GNU Lesser General Public License for more details.
 611
 612 You should have received a copy of the GNU Lesser General Public
 613 License along with GNU Libltdl; see the file COPYING.LIB.  If not, a
 614 copy can be downloaded from  http://www.gnu.org/licenses/lgpl.html,
 615 or obtained by writing to the Free Software Foundation, Inc.,
 616 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 617
 618
 619 11. Release Procedure
 620 =====================
 621
 622 * If you are a libtool maintainer, but have not yet registered your
 623   gpg public key and (preferred) email address with the FSF, send an
 624   email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
 625   the following:
 626
 627     (a) name of package(s) that you are the maintainer for, and your
 628         preferred email address.
 629
 630     (b) an ASCII armored copy of your GnuPG key, as an attachment.
 631         ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
 632         this.)
 633
 634   When you have received acknowledgement of your message, the proper GPG
 635   keys will be registered on ftp-upload.gnu.org and only then will you be
 636   authorized to upload files to the FSF ftp machines.
 637
 638 * If you do not have access to the mailing list administrative interface,
 639   approach the list owners for the password.  Be sure to check the lists
 640   (esp. bug-libtool) for outstanding bug reports also in the list of
 641   pending moderation requests.
 642
 643 * Make sure you have wget installed.
 644
 645 * Make sure you have a copy of xdelta installed, and a copy of the previous
 646   release tarball in the build directory.
 647
 648 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
 649
 650 * Double check that serial number updates in public m4 files weren't forgotten
 651   since last release (they should be updated in CVS along with commits that
 652   require it so that users can work with CVS snapshots).
 653
 654 * Update the LTDL_VERSION_INFO in libltdl/Makefile.inc for changes since
 655   the last release.
 656
 657 * Update the version number in configure.ac and libltdl/configure.ac.
 658   See http://www.gnu.org/software/libtool/contribute.html for details of
 659   the numbering scheme.
 660
 661 * Update NEWS, ChangeLog.
 662
 663 * Run ./bootstrap.
 664
 665 * Have some tea.  If you are running on less than 3.6GHz CPU, order
 666   a pizza too ;-)
 667
 668 * Run ./configure (or create a build directory first and run configure
 669   from there, if you want to keep the build tree separate).
 670
 671 * Run `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
 672   if you are running from a VPATH build directory, where `../' is the
 673   relative path to the directory with `configure' in it), which will
 674   fetch new versions of the files that are maintained outside of
 675   libtool.
 676
 677 * Run `make distcheck' and `make distcheck
 678   DISTCHECK_CONFIGURE_FLAGS=--disable-ltdl-install'.  Try a distcheck
 679   with --program-prefix=g.  If there are any problems, fix them and
 680   start again.
 681
 682 * Run ./commit from the source tree.
 683
 684 * Run `make -fMakefile.maint cvs-dist' (or `make -f../Makefile.maint
 685   cvs-dist' if you are running from a VPATH build directory, where `../'
 686   is the relative path to the directory with `configure' in it), which
 687   will build a release tarball (with `make distcheck'), tag the tree
 688   with release-$(VERSION) and generate the gpg signature files.
 689
 690 * Run 'make -f[../]Makefile.maint deltas' (pass
 691   LASTRELEASE=maj.min[.mic[alpha]] if needed) to create both diff and
 692   xdelta files between the previous release tarball and the new with
 693   detached gpg signature files and clear signed directive files.
 694
 695 * Upload release tarball, diff file and xdelta file, plus their associated
 696   detached gpg signature files and clear signed directive files to
 697   ftp-upload.gnu.org.  If the upload is destined for ftp.gnu.org, then the
 698   files should be placed in the /incoming/ftp directory.  If the upload is
 699   an alpha release destined for alpha.gnu.org, then the files should be
 700   placed in the /incoming/alpha directory.
 701
 702 * Send announcement to libtool@gnu.org and autotools-announce@gnu.org,
 703   if not an alpha send to info-gnu@gnu.org as well.
 704
 705 * Update version number in configure.ac and libltdl/configure.ac to next
 706   alpha number.  See http://www.gnu.org/software/libtool/contribute.html
 707   for details of the numbering scheme.
 708
 709 * Update NEWS, ChangeLog.
 710
 711 * Run ./commit.
 712
 713 * Update the webpages, libtool.html will need to indicate the latest
 714   release number and the news page should get a HTMLified copy of your
 715   release announcement.
 716
 717 * If not an alpha, replace manual.html with the new one
 718   (generate with `make -f[../]Makefile.maint web-manual').
 719
 720
 721
 722 12. Alpha release note template
 723 ===============================
 724
 725 To: libtool@gnu.org, autotools-announce@gnu.org
 726 Subject: GNU Libtool @VERSION@ released (alpha release).
 727
 728 The Libtool Team is pleased to announce alpha release @VERSION@ of GNU
 729 Libtool.
 730
 731 GNU Libtool hides the complexity of using shared libraries behind a
 732 consistent, portable interface. GNU Libtool ships with GNU libltdl,
 733 which hides the complexity of loading dynamic runtime libraries
 734 (modules) behind a consistent, portable interface.
 735
 736 Here are the compressed sources:
 737
 738   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
 739   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
 740
 741 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 742
 743   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 744   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 745
 746 Here are the gpg detached signatures:
 747
 748   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
 749   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
 750   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 751   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 752
 753 You should download the signature named after any tarball you download,
 754 and then verify its integrity with, for example:
 755
 756   gpg --verify libtool-@VERSION@.tar.gz.sig
 757
 758 Here are the MD5 and SHA1 checksums:
 759
 760   @MD5SUM@ libtool-@VERSION@.tar.gz
 761   @MD5SUM@ libtool-@VERSION@.tar.bz2
 762   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 763   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 764   @SHA1SUM@ libtool-@VERSION@.tar.gz
 765   @SHA1SUM@ libtool-@VERSION@.tar.bz2
 766   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 767   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 768
 769 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 770
 771 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
 772 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
 773 projects.
 774
 775 Alternatively, you can fetch the unbootstrapped source code from
 776 anonymous cvs by using the following command:
 777
 778   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/libtool \
 779     co -r @CVS_RELEASE_TAG@ libtool
 780
 781 You will then need to have recent (possibly as yet unreleased) versions
 782 of Automake and Autoconf installed to bootstrap the checked out
 783 sources yourself.
 784
 785 New in @VERSION@: @RELEASE_DATE@
 786
 787   @EXCERPT_FROM_NEWS_FILE@
 788
 789 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
 790 output of any failed test groups, and the output from `./libtool --config.'
 791 The README file explains how to capture the verbose test output.
 792
 793
 794
 795 13. Full release note template
 796 ==============================
 797
 798 To: info-gnu@gnu.org
 799 Cc: libtool@gnu.org, autotools-announce@gnu.org
 800 Subject: GNU Libtool @VERSION@ released.
 801
 802 The Libtool Team is pleased to announce the release of GNU Libtool
 803 @VERSION@.
 804
 805 GNU Libtool hides the complexity of using shared libraries behind a
 806 consistent, portable interface. GNU Libtool ships with GNU libltdl,
 807 which hides the complexity of loading dynamic runtime libraries
 808 (modules) behind a consistent, portable interface.
 809
 810 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 811
 812 New in @VERSION@: @RELEASE_DATE@
 813
 814   @EXCERPT_FROM_NEWS_FILE@
 815
 816 libtool-@VERSION@ is available now from ftp.gnu.org, along with
 817 diffs and xdeltas against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@
 818 that are also available from ftp.gnu.org.  Please
 819 use a mirror to reduce stress on the main gnu machine:
 820
 821   http://www.gnu.org/order/ftp.html
 822
 823 Here are the compressed sources:
 824
 825   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
 826   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
 827
 828 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 829
 830   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 831   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 832
 833 Here are the gpg detached signatures:
 834
 835   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
 836   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
 837   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 838   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 839
 840 You should download the signature named after any tarball you download,
 841 and then verify its integrity with, for example:
 842
 843   gpg --verify libtool-@VERSION@.tar.gz.sig
 844
 845 Here are the MD5 and SHA1 checksums:
 846
 847   @MD5SUM@ libtool-@VERSION@.tar.gz
 848   @MD5SUM@ libtool-@VERSION@.tar.bz2
 849   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 850   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 851   @SHA1SUM@ libtool-@VERSION@.tar.gz
 852   @SHA1SUM@ libtool-@VERSION@.tar.bz2
 853   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 854   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 855
 856 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
 857 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
 858 projects.
 859
 860 Alternatively, you can fetch the unbootstrapped source code from
 861 anonymous cvs by using the following command (just hit return when
 862 you are prompted for the password):
 863
 864   $ cvs -z3 -d :pserver:anonymous@cvs.sv.gnu.org:/sources/libtool \
 865     co -r @CVS_RELEASE_TAG@ libtool
 866
 867 You will then need to have the latest release versions of Automake
 868 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
 869 bootstrap the checked out sources yourself.
 870
 871 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
 872 output of any failed test groups, and the output from `./libtool --config.'
 873 The README file explains how to capture the verbose test output.
 874
 875
 876 --
 877   Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
 878   Written by Gary V. Vaughan, 2004
 879
 880   This file is part of GNU Libtool.  Report bugs to bug-libtool@gnu.org.
 881
 882 GNU Libtool is free software; you can redistribute it and/or
 883 modify it under the terms of the GNU General Public License as
 884 published by the Free Software Foundation; either version 2
 885 of the License, or (at your option) any later version.
 886
 887 GNU Libtool is distributed in the hope that it will be useful,
 888 but WITHOUT ANY WARRANTY; without even the implied warranty of
 889 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 890 GNU General Public License for more details.
 891
 892 You should have received a copy of the GNU General Public License
 893 along with GNU Libtool; see the file COPYING.  If not, a copyi
 894 can be downloaded from http://www.gnu.org/licenses/gpl.html,
 895 or obtained by writing to the Free Software Foundation, Inc.,
 896 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 897
 898 Local Variables:
 899 mode: text
 900 fill-column: 72
 901 End:
 902 vim:tw=72