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