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 * Use "make check" liberally, on as many platforms as you can.  Use as
  55   many compilers and linkers you can.
  56
  57
  58 4. Naming
  59 =========
  60
  61 * We've adopted the convention that exported Autoconf macros should be
  62   named with a leading `LT_' and be documented in the libtool manual.
  63   Internal macros begin with `_LT_' if they are visible to aclocal, or
  64   potentially part of an AC_DEFUN/AC_REQUIRE path, or else `_lt_' if
  65   they are very low level.  This convention was only introduced just
  66   before libtool-2.0, so there may still be exceptions in the existing
  67   code.  But all new code should use it.
  68
  69 * All shell variables used internally by libtool's Autoconf macros
  70   should be named with the a leading `lt_' (not that they cannot clash
  71   with the `_lt_' macro namespace).
  72
  73
  74 5. Editing 'ChangeLog'
  75 ======================
  76
  77 * When in doubt, check that emacs can syntax-color properly in
  78   change-log-mode.  And preferably use emacs 'C-x 4 a'
  79   (add-change-log-entry-other-window) to open ChangeLog with an
  80   appropriate new template.
  81
  82 * If this change is by a different author, or on a different date to the
  83   last entry start a new entry at the top of the file with the format
  84   (note two spaces between each field):
  85
  86 yyyy-mm-dd  Name of Author  <email@address>
  87
  88 *  If more than one person collaborated on the change, additional
  89    authors can be listed on subsequent lines, thus:
  90
  91 yyyy-mm-dd  Name of Main Author  <email@address>,
  92             Name of Contributor  <another@email.address>
  93
  94 * Where a change author did not supply a copyright assignment, but the
  95   changes they submitted were sufficiently trivial to commit in any case
  96   (see the GCS for guidelines on this), then flag this against their
  97   name in the header, thus:
  98
  99 yyyy-mm-dd  Name of Author  <email@address>  (tiny change)
 100
 101 * In ChangeLog.2004 and earlier, 'Name of Author' was sometimes the name
 102   of the author of the ChangeLog when the person who made the change
 103   being documented didn't supply one.   In that case separated from
 104   the previous field by a blank line and indented by 1 tab (note, only
 105   1 space between fields here) you will see:
 106
 107         From Author of Actual Change <email@address>:
 108
 109   As of now, don't do that anymore, since the GNU Coding Standards say
 110   that the author of the change must be credited in the main entry
 111   header for legal purposes.
 112
 113 * Preferably the next part should be a description of the overall
 114   purpose of the change, separated from the header by a blank line,
 115   indented by 1 tab, and filled at column 72.  The last character of the
 116   description should be a colon, :.
 117
 118 * Changes to each file come next.  Each new file starts on a new line,
 119   indented by 1 tab and starting with an asterisk and a space.  Multiple
 120   files can be listed here relative to $top_srcdir, and comma separated.
 121   Names of functions (or sections as appropriate) to which the change
 122   applies should be named inside parentheses and comma separated.  If
 123   this goes beyond column 72, then parens should be closed and re-opened
 124   on the next line:
 125
 126         * file, another/file, test/testcases/foo.test (func_foo)
 127         (func_bar, func_baz): Description of changes.
 128
 129 * If the change does not apply to particular functions (or sections),
 130   the section list can be omitted:
 131
 132         * file, another/file, test/testcases/foo.test: General changes.
 133
 134 * If the changes are particular to certain architectures, they should be
 135   listed after the functions in square brackets:
 136
 137         * file, another/file (func_foo) [linux, solaris]: Description of
 138         changes.
 139
 140 * Subsequent changes in other files that are related to the same overall
 141   enhancement or bugfix should be listed concurrently, without blank
 142   lines.  Always start a fresh line for a new file:
 143
 144         * file, another/file (func_foo) [linux, solaris]: Description of
 145         changes.
 146         * doc/foo.texi (Invoking Foo): Document.
 147         * NEWS: Updated.
 148
 149 * If the change is in response to a problem reported by someone other
 150   than the author, then credit them at the end of the description with:
 151
 152         Reported by Reporter Name <email@address>.
 153
 154 * See the GNU Coding Standards document for more details on ChangeLog
 155   formatting.
 156
 157
 158 2005-01-08  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>  (tiny change),
 159             Peter O'Gorman  <peter@pogma.com>
 160
 161         This is the overall description of the purpose of this change
 162         and any useful background for a model ChangeLog entry:
 163
 164         * HACKING: Updated copyright.  This isn't attached to a
 165         particular section of the file, so it comes first.
 166         (Editing 'ChangeLog'): New section.  This applies to the same
 167         file, but since it applies to a particular section it starts on
 168         a new line.
 169         (Introduction, Maintenance Notes, Test Suite, Naming)
 170         (Editing '.am' Files): If I had changed all these sections in
 171         the same way, I can list them like this, being careful to close
 172         and reopen the parentheses when starting a new line.  The colon
 173         only comes after the last section before this description.
 174         * NEWS: Updated.
 175         Reported by Bob Friesenhahn <bfriesen@simple.dallas.tx.us>.
 176
 177
 178 6. Editing `.am' Files
 179 ======================
 180
 181 * Always use $(...) and not ${...}
 182
 183 * Use `:', not `true'.  Use `exit 1', not `false'.
 184
 185 * Use `##' comments liberally.  Comment anything even remotely unusual.
 186
 187 * Never use basename or dirname.  Instead use sed.
 188
 189 * Do not use `cd' within back-quotes, use `$(am__cd)' instead.
 190   Otherwise the directory name may be printed, depending on CDPATH.
 191
 192 * In general, if a loop is required, it should be silent.  Then the body
 193   of the loop itself should print each "important" command it runs.
 194
 195
 196 7. Editing `.m4sh' Files
 197 ========================
 198
 199 * Use shell functions, but be careful not to assume local scope for
 200   variable names.  Don't use `return', instead echo the result of a
 201   function and call it from within backquotes.
 202
 203 * Function names should be prefixed `func_'.
 204
 205 * For functions that are called frequently, if you need to return a
 206   value, don't cause unneccessary forking of the shell using echo as
 207   described above; instead set the return value in a variable named
 208   after the called function with a suffix of `_result'.  For example
 209   the function `func_quote_for_eval' stores its return value in the
 210   variable `$func_quote_for_eval_result'.
 211
 212 * Although sh-indentation is set to 2 (by the `Local Variables:' block
 213   at the end of .m4sh files), the left margin of the body of shell
 214   functions should begin indented by 4 spaces.
 215
 216
 217 8. Abstraction layers in libltdl
 218 ================================
 219
 220 * The libltdl API uses a layered approach to differentiate internal and
 221   external interfaces, among other things.  To keep the abstraction
 222   consistent, files in a given layer may only use APIs from files in the
 223   lower layers.  The exception to this is lt__glibc.h which serves a
 224   dual purpose, as explained later.
 225
 226 * At the bottom of the stack we have the system abstraction layer,
 227   which tries to smooth over the cracks where there are differences
 228   between host systems and compilers.  config.h is generated at
 229   configure time and is not installed; lt_system.h is an installed
 230   file and cannot use macros from config.h:
 231
 232         lt_system.h     ../config.h
 233
 234 * Next up is the libc abstraction layer, which provides a uniform api
 235   to various system libc interfaces that differ between hosts supported
 236   by libtool.  Typically, the files that implement this layer begin:
 237
 238   #if defined(HAVE_CONFIG_H)
 239   #  include HAVE_CONFIG_H
 240   #endif
 241   #include "lt_system.h"
 242
 243   Or if they are installed headers that must work outside the libtool
 244   source tree, simply:
 245
 246   #include <libltdl/lt_system.h>
 247
 248   This layer's interface is defined by files that are usually named with
 249   a leading `lt__':
 250
 251         ,------------.  ,-----------.   ,------.        ,-------.
 252         |lt__dirent.h|  |lt__alloc.h|   |argz.h|        |slist.h|
 253         +------------+  +-----------+   +------+        +-------+
 254         |lt__dirent.c|  |lt__alloc.c|   |argz.c|        |slist.c|
 255         `------------'  `-----------'   `------'        `-------'
 256
 257   The exceptions here are argz.h and slist.h which are used
 258   independently of libltdl in other projects.
 259
 260 * There is also a sub-layer that can be used either by the headers that
 261   implement it, in which case its function is to avoid namespace clashes
 262   when linked with the GNU C library; Or it can be included by code that
 263   wants to program against a glibc like interface, where it also serves
 264   the function of pulling in all the glibc-like functionality used by
 265   libltdl from a single:
 266
 267   #include <libltdl/lt__glibc.h>
 268
 269   It consists of the single file:
 270
 271         lt__glibc.h
 272
 273 * The next layer are the subsystems of the exported libltdl API, which
 274   are defined by files that are named with a leading `lt_' (no double
 275   underscore!):
 276
 277         ,----------.    ,-------------.
 278         |lt_error.h|    |lt_dlloader.h|
 279         +----------+    +-------------+
 280         |lt_error.c|    |lt_dlloader.c|
 281         `----------'    `-------------'
 282
 283
 284 * The top layer of the stack is the libltdl API proper, which includes
 285   the subsystems automatically:
 286
 287         ,------.
 288         |ltdl.h|
 289         +------+
 290         |ltdl.c|
 291         `------'
 292
 293 * And finally, there is an additional internal only layer (as evidenced
 294   by the `lt__' prefix to the filename!) that defines additional
 295   internal interfaces that are not exported to libltdl clients, but are
 296   shared between internal files:
 297
 298         lt__private.h
 299
 300
 301 9. Release Procedure
 302 ====================
 303
 304 * If you are a libtool maintainer, but have not yet registered your
 305   gpg public key and (preferred) email address with the FSF, send an
 306   email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
 307   the following:
 308
 309     (a) name of package(s) that you are the maintainer for, and your
 310         preferred email address.
 311
 312     (b) an ASCII armored copy of your GnuPG key, as an attachment.
 313         ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
 314         this.)
 315
 316   When you have received acknowledgement of your message, the proper GPG
 317   keys will be registered on ftp-upload.gnu.org and only then will you be
 318   authorized to upload files to the FSF ftp machines.
 319
 320 * Make sure you have wget installed.
 321
 322 * Make sure you have a copy of xdelta installed, and a copy of the previous
 323   release tarball in the build directory.
 324
 325 * Update the version number in configure.ac.
 326   See http://www.gnu.org/software/libtool/contribute.html for details of
 327   the numbering scheme.
 328
 329 * Update NEWS, ChangeLog.
 330
 331 * Run ./bootstrap.
 332
 333 * Have some tea.  If you are running on less than 3.6GHz CPU, order
 334   a pizza too ;-)
 335
 336 * Run ./configure (or create a build directory first and run configure
 337   from there, if you want to keep the build tree separate).
 338
 339 * Run `make -fMakefile.maint fetch' (or `make -f../Makefile.maint fetch'
 340   if you are running from a VPATH build directory, where `../' is the
 341   relative path to the directory with `configure' in it), which will
 342   fetch new versions of the files that are maintained outside of
 343   libtool.
 344
 345 * Run `make distcheck'.  If there are any problems, fix them and start
 346   again.
 347
 348 * Run ./commit from the source tree.
 349
 350 * Run `make -fMakefile.maint cvs-dist' (or `make -f../Makefile.maint
 351   cvs-dist' if you are running from a VPATH build directory, where `../'
 352   is the relative path to the directory with `configure' in it), which
 353   will build a release tarball (with `make distcheck'), tag the tree
 354   with release-$(VERSION) and generate the gpg signature files.
 355
 356 * Run 'make -f[../]Makefile.maint deltas' (pass
 357   LASTRELEASE=min.maj[.mic[alpha]] if needed) to create both diff and
 358   xdelta files between the previous release tarball and the new with
 359   detached gpg signature files and clear signed directive files.
 360
 361 * Upload release tarball, diff file and xdelta file, plus their associated
 362   detached gpg signature files and clear signed directive files to
 363   ftp-upload.gnu.org.  If the upload is destined for ftp.gnu.org, then the
 364   files should be placed in the /incoming/ftp directory.  If the upload is
 365   an alpha release destined for alpha.gnu.org, then the files should be
 366   placed in the /incoming/alpha directory.
 367
 368 * Send announcement to libtool@gnu.org and autotools-announce@gnu.org,
 369   if not an alpha send to info-gnu@gnu.org as well.
 370
 371 * Update version number in configure.ac to next alpha number.
 372   See http://www.gnu.org/software/libtool/contribute.html for details of
 373   the numbering scheme.
 374
 375 * Update NEWS, ChangeLog.
 376
 377 * Run ./commit.
 378
 379 * Update the webpages, libtool.html will need to indicate the latest
 380   release number and the news page should get a HTMLified copy of your
 381   release announcement.
 382
 383 * If not an alpha, replace manual.html with the new one
 384   (generate with `make -f[../]Makefile.maint web-manual').
 385
 386
 387
 388 10. Alpha release note template
 389 ===============================
 390
 391 To: libtool@gnu.org, autotools-announce@gnu.org
 392 Subject: GNU Libtool @VERSION@ released (alpha release).
 393
 394 The Libtool Team is pleased to announce alpha release @VERSION@ of GNU
 395 Libtool.
 396
 397 GNU Libtool hides the complexity of using shared libraries behind a
 398 consistent, portable interface. GNU Libtool ships with GNU libltdl,
 399 which hides the complexity of loading dynamic runtime libraries
 400 (modules) behind a consistent, portable interface.
 401
 402 Here are the compressed sources:
 403
 404   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
 405   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
 406
 407 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 408
 409   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 410   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 411
 412 Here are the gpg detached signatures:
 413
 414   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
 415   ftp://alpha.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
 416   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 417   ftp://alpha.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 418
 419 You should download the signature named after any tarball you download,
 420 and then verify its integrity with, for example:
 421
 422   gpg --verify libtool-@VERSION.tar.gz.sig
 423
 424 Here are the MD5 and SHA1 checksums:
 425
 426   @MD5SUM@ libtool-@VERSION@.tar.gz
 427   @MD5SUM@ libtool-@VERSION@.tar.bz2
 428   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 429   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 430   @SHA1SUM@ libtool-@VERSION@.tar.gz
 431   @SHA1SUM@ libtool-@VERSION@.tar.bz2
 432   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 433   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 434
 435 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 436
 437 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
 438 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
 439 projects.
 440
 441 Alternatively, you can fetch the unbootstrapped sourcecode from
 442 anonymous cvs by using the following commands:
 443
 444   $ export CVS_RSH=ssh
 445   $ cvs -z3 -d :ext:anoncvs@savannah.gnu.org:/cvsroot/libtool \
 446   co -r @CVS_RELEASE_TAG@ libtool
 447
 448 You will then need to have recent (possibly as yet unreleased) versions
 449 of Automake and Autoconf installed to bootstrap the checked out
 450 sources yourself.
 451
 452 New in @VERSION@: @RELEASE_DATE@
 453
 454   @EXCERPT_FROM_NEWS_FILE@
 455
 456 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
 457 output of any failed test groups, and the output from `./libtool --help.'
 458
 459
 460
 461 11. Full release note template
 462 ==============================
 463
 464 To: info-gnu@gnu.org
 465 Cc: libtool@gnu.org, autotools-announce@gnu.org
 466 Subject: GNU Libtool @VERSION@ released.
 467
 468 The Libtool Team is pleased to announce the release of GNU Libtool
 469 @VERSION@.
 470
 471 GNU Libtool hides the complexity of using shared libraries behind a
 472 consistent, portable interface. GNU Libtool ships with GNU libltdl,
 473 which hides the comlexity of loading dynamic runtime libraries
 474 (modules) behind a consistent, portable interface.
 475
 476 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 477
 478 New in @VERSION@: @RELEASE_DATE@
 479
 480   @EXCERPT_FROM_NEWS_FILE@
 481
 482 libtool-@VERSION@ is available now from ftp.gnu.org, along with
 483 diffs and xdeltas against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@
 484 that are also available from ftp.gnu.org.  Please
 485 use a mirror to reduce stress on the main gnu machine:
 486
 487   http://www.gnu.org/order/ftp.html
 488
 489 Here are the compressed sources:
 490
 491   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz
 492   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2
 493
 494 Here are the xdeltas and diffs against libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 495
 496   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 497   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 498
 499 Here are the gpg detached signatures:
 500
 501   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.gz.sig
 502   ftp://ftp.gnu.org/gnu/libtool/libtool-@VERSION@.tar.bz2.sig
 503   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 504   ftp://ftp.gnu.org/gnu/libtool/libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 505
 506 You should download the signature named after any tarball you download,
 507 and then verify its integrity with, for example:
 508
 509   gpg --verify libtool-@VERSION.tar.gz.sig
 510
 511 Here are the MD5 and SHA1 checksums:
 512
 513   @MD5SUM@ libtool-@VERSION@.tar.gz
 514   @MD5SUM@ libtool-@VERSION@.tar.bz2
 515   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 516   @MD5SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 517   @SHA1SUM@ libtool-@VERSION@.tar.gz
 518   @SHA1SUM@ libtool-@VERSION@.tar.bz2
 519   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 520   @SHA1SUM@ libtool-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 521
 522 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@,
 523 but is useable with @COMPATIBLE_AUTOTOOL_VERSIONS@ in your own
 524 projects.
 525
 526 Alternatively, you can fetch the unbootstrapped sourcecode from
 527 anonymous cvs by using the following commands (just hit return when
 528 you are prompted for the password):
 529
 530   $ export CVS_RSH=ssh
 531   $ cvs -z3 -d :ext:anoncvs@savannah.gnu.org:/cvsroot/libtool \
 532   co -r @CVS_RELEASE_TAG@ libtool
 533
 534 You will then need to have the latest release versions of Automake
 535 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed to
 536 bootstrap the checked out sources yourself.
 537
 538 Please report bugs to <bug-libtool@gnu.org>, along with the verbose
 539 output of any failed test groups, and the output from `./libtool --help.'
 540
 541
 542 --
 543 Copyright (C) 2004, 2005 Free Software Foundation, Inc.
 544
 545 The canonical source of this file is maintained with the
 546 GNU Libtool package.  Report bugs to bug-libtool@gnu.org.
 547
 548 GNU Libtool is free software; you can redistribute it and/or
 549 modify it under the terms of the GNU General Public License as
 550 published by the Free Software Foundation; either version 2
 551 of the License, or (at your option) any later version.
 552
 553 As a special exception to the GNU General Public License,
 554 if you distribute this file as part of a program or library that
 555 is built using GNU libtool, you may include it under the same
 556 distribution terms that you use for the rest of that program.
 557
 558 GNU Libtool is distributed in the hope that it will be useful,
 559 but WITHOUT ANY WARRANTY; without even the implied warranty of
 560 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 561 General Public License for more details.
 562
 563 You should have received a copy of the GNU General Public License
 564 along with GNU Libtool; if not, write to the Free Software
 565 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 566 02111-1307  USA
 567
 568
 569 Local Variables:
 570 mode: text
 571 fill-column: 72
 572 End: