HACKING

   1 GNU M4
   2 ******
   3
   4 1. Introduction
   5 ===============
   6
   7 This file attempts to describe the processes we use to maintain M4,
   8 and is not part of a release distribution.
   9
  10
  11 2. Maintenance Notes
  12 ====================
  13
  14 * If you incorporate a change from somebody on the net:
  15   If it is a large change, you must make sure they have signed the
  16   appropriate paperwork, and be sure to add their name and email
  17   address to THANKS.  AUTHORS is built from the FSF list of copyright
  18   assignments, on fencepost.gnu.org.
  19
  20 * If somebody reports a new bug, write a test case, then mention his
  21   name in the ChangeLog entry.
  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 * Changes with user-visible effects must be mentioned in NEWS.
  28
  29 * New macros must be blind, or else prefixed with `m4' or `__', in
  30   order to minimize backward compatibility issues with previous
  31   releases of M4 when processing English text.
  32
  33 * GNU Coding Standards should be followed:
  34     http://www.gnu.org/prep/standards/
  35   Additionally, while GNU M4 is not yet POSIX compliant, we are trying
  36   to get closer to it (although some design decisions state that POSIX
  37   compliance should only happen when POSIXLY_CORRECT is in the
  38   environment or the -G option was passed on the command line):
  39     http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html
  40
  41 * Except for third-party files (libtool, gnulib, ...), all .c files
  42   should #include <config.h> before anything else (since there are some
  43   #defines in config.h that potentially impact system headers, such as
  44   when the user does ./configure --disable-assert).  This means that no
  45   .h files need to #include <config.h>.  However, users compiling
  46   external modules should be able to compile without <config.h>, since
  47   <config.h> is specific to the M4 build and is not installable.
  48
  49
  50 3. Bootstrapping
  51 ================
  52
  53 * The master M4 repository is stored in git.  You can obtain a read-only
  54   copy with:
  55     git clone git://git.sv.gnu.org/m4.git
  56   or
  57     cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/m4.git \
  58       co -d m4 HEAD
  59
  60   If you are a member of the savannah group for M4, a read-write
  61   copy can be obtained by:
  62     git clone <savannah-user>@git.sv.gnu.org:/srv/git/m4.git
  63
  64 * Before you can build from git, you need to bootstrap.  This requires:
  65   - A pre-installed version of GNU M4 1.4.5 or later, built from a
  66     package (recommend 1.4.11 or later)
  67   - Autoconf 2.62 or later
  68   - Automake 1.10a or later
  69   - Libtool 2.2 or later
  70   - Gettext 0.16 or later
  71   - Gperf 3.0 or later
  72   - Help2man 1.29 or later
  73   - LZMA Utils 4.32 or later (from <http://tukaani.org/lzma/>)
  74   - Texinfo 4.8 or later
  75   - Any prerequisites of the above (such as perl, tex)
  76   - A git checkout of gnulib.  A read-only copy of gnulib can be
  77     obtained by:
  78       git clone git://git.sv.gnu.org/gnulib.git
  79     or
  80       cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \
  81         co -d gnulib HEAD
  82
  83   If you are a member of the savannah group for gnulib, a read-write
  84   copy can be obtained by:
  85     git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git
  86
  87   Note that none of these bootstrapping dependencies should be required
  88   by a distributed release.
  89
  90 * Either add the gnulib directory to your PATH, or run
  91     GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
  92
  93 * When it is time for a release, it is a good idea to bootstrap with
  94   official releases of the autotools, rather than git builds, to reduce
  95   the pain of a user re-running bootstrap on the packaged M4.  However,
  96   files installed by Automake should be updated to the latest version
  97   from their respective upstream source, rather than the version that
  98   shipped with the automake release.
  99
 100
 101 4. Test Suite
 102 =============
 103
 104 * Use
 105     make check
 106   liberally, on as many platforms as you can.  Use as many compilers and
 107   linkers you can.
 108
 109 * Some of the testsuite is generated from the documentation.
 110   All instances of @example in doc/m4.texinfo that are not preceeded by
 111   "@comment ignore" are turned into tests in the tests directory.
 112
 113
 114 5. Editing 'ChangeLog'
 115 ======================
 116
 117 * When in doubt, check that emacs can syntax-color properly in
 118   change-log-mode.  And preferably use emacs 'C-x 4 a'
 119   (add-change-log-entry-other-window) to open ChangeLog with an
 120   appropriate new template.
 121
 122 * If this change is by a different author, or on a different date to the
 123   last entry start a new entry at the top of the file with the format
 124   (note two spaces between each field):
 125
 126 yyyy-mm-dd  Name of Author  <email@address>
 127
 128 *  If more than one person collaborated on the change, additional
 129    authors can be listed on subsequent lines, thus:
 130
 131 yyyy-mm-dd  Name of Main Author  <email@address>,
 132             Name of Contributor  <another@email.address>
 133
 134 * Where a change author did not supply a copyright assignment, but the
 135   changes they submitted were sufficiently trivial to commit in any case
 136   (see the GCS for guidelines on this), then flag this against their
 137   name in the header, thus:
 138
 139 yyyy-mm-dd  Name of Author  <email@address>  (tiny change)
 140
 141 * Preferably the next part should be a description of the overall
 142   purpose of the change, separated from the header by a blank line,
 143   indented by 1 tab, and filled at column 72.  The last character of the
 144   description should be a colon, :.
 145
 146 * Changes to each file come next.  Each new file starts on a new line,
 147   indented by 1 tab and starting with an asterisk and a space.  Multiple
 148   files can be listed here relative to $top_srcdir, and comma separated.
 149   Names of functions (or sections as appropriate) to which the change
 150   applies should be named inside parentheses and comma separated.  If
 151   this goes beyond column 72, then parens should be closed and re-opened
 152   on the next line:
 153
 154         * file, another/file, test/testcases/foo.test (func_foo)
 155         (func_bar, func_baz): Description of changes.
 156
 157 * If the change does not apply to particular functions (or sections),
 158   the section list can be omitted:
 159
 160         * file, another/file, test/testcases/foo.test: General changes.
 161
 162 * If the changes are particular to certain architectures, they should be
 163   listed after the functions in square brackets:
 164
 165         * file, another/file (func_foo) [linux, solaris]: Description of
 166         changes.
 167
 168 * Subsequent changes in other files that are related to the same overall
 169   enhancement or bugfix should be listed concurrently, without blank
 170   lines.  Always start a fresh line for a new file:
 171
 172         * file, another/file (func_foo) [linux, solaris]: Description of
 173         changes.
 174         * doc/foo.texi (Invoking Foo): Document.
 175         * NEWS: Updated.
 176
 177 * If the change is in response to a problem reported by someone other
 178   than the author, then credit them at the end of the description with:
 179
 180         Reported by Reporter Name <email@address>.
 181
 182 * See the GNU Coding Standards document for more details on ChangeLog
 183   formatting.
 184
 185
 186 6. Release Procedure
 187 ====================
 188
 189 * If you are an m4 maintainer, but have not yet registered your
 190   gpg public key and (preferred) email address with the FSF, send an
 191   email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
 192   the following:
 193
 194     (a) name of package(s) that you are the maintainer for, and your
 195         preferred email address.
 196
 197     (b) an ASCII armored copy of your GnuPG key, as an attachment.
 198         ("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
 199         this.)
 200
 201   When you have received acknowledgement of your message, the proper GPG
 202   keys will be registered on ftp-upload.gnu.org and only then will you be
 203   authorized to upload files to the FSF ftp machines.
 204
 205 * If you do not have access to the mailing list administrative interface,
 206   approach the list owners for the password.  Be sure to check the lists
 207   (esp. bug-m4) for outstanding bug reports also in the list of
 208   pending moderation requests.  This step is not strictly necessary.
 209
 210 * Make sure you have rsync installed.
 211
 212 * Make sure you have a copy of xdelta installed, and a copy of the previous
 213   release tarball in the build directory.
 214
 215 * Make sure your locale is sane, e.g. by exporting LC_ALL=C.
 216
 217 * Update the version number in configure.ac.
 218   See http://www.gnu.org/software/libtool/contribute.html for details of
 219   the numbering scheme (m4 uses the same scheme as libtool).
 220
 221 * Update NEWS, ChangeLog.
 222
 223 * Run ./bootstrap.
 224
 225 * Run ./configure (or create a build directory first and run configure
 226   from there, if you want to keep the build tree separate).
 227
 228 * Run `make distcheck'.  If there are any problems, fix them and start
 229   again.
 230
 231 * Run ./commit from the source tree.
 232
 233 * TODO - adjust this step to account for git:
 234   Run `make cvs-dist', which will build a release tarball (with `make
 235   distcheck') and tag the tree with release-$(VERSION).
 236
 237 * Run 'make deltas' (pass LASTRELEASE=maj.min[.mic[alpha]] if needed) to
 238   create both diff and xdelta files between the previous release tarball
 239   and the new.  TODO - is xdelta still worth using?
 240
 241 * Run '[../]./gnupload --to [dest].gnu.org:m4 [files]' to create
 242   detached gpg signature and clear signed directive files, and upload
 243   the combination to the correct location.  For an alpha release,
 244   gnupload will place files in alpha.gnu.org, in /incoming/alpha, and
 245   the xdelta file is not strictly necessary.  For a full release,
 246   gnupload will place files in ftp.gnu.org, in /incoming/ftp.
 247
 248 * Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
 249   autotools-announce@gnu.org.  If not an alpha send to info-gnu@gnu.org
 250   as well.
 251
 252 * Update version number in configure.ac to next alpha number.
 253   See http://www.gnu.org/software/libtool/contribute.html for details of
 254   the numbering scheme.
 255
 256 * Update NEWS, ChangeLog.
 257
 258 * Run ./commit.
 259
 260 * For non-alpha releases, update the webpages.  Replace manual.html with
 261   the new one (generate with `make web-manual').
 262
 263 * Update the M4 entry in the GNU Software directory, located at
 264   http://directory.fsf.org/GNU/gnum4.html.  To do this, check out the
 265   directory template:
 266     cvs -z3 -d:pserver:anonymous@cvs.sv.gnu.org:/sources/directory \
 267        co directory/gnum4.txt
 268   then mail the patch to bug-directory@gnu.org.
 269
 270
 271 7. Alpha release note template
 272 ==============================
 273
 274 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 275 Subject: GNU M4 @VERSION@ released (alpha release).
 276
 277 The GNU M4 Team is pleased to announce alpha release @VERSION@ of GNU
 278 M4.
 279
 280 GNU `m4' is an implementation of the traditional Unix macro processor.
 281 It is mostly SVR4 compatible, although it has some extensions (for
 282 example, handling more than 9 positional parameters to macros).  `m4'
 283 also has built-in functions for including files, running shell commands,
 284 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 285 `configure' scripts, but not for running them.
 286
 287 Here are the compressed sources:
 288
 289   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 290   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 291
 292 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 293
 294   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 295   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 296
 297 Here are the gpg detached signatures:
 298
 299   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 300   ftp://alpha.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 301   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 302   ftp://alpha.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 303
 304 You should download the signature named after any tarball you download,
 305 and then verify its integrity with, for example:
 306
 307   gpg --verify m4-@VERSION@.tar.gz.sig
 308
 309 If that command fails because you don't have the required public key,
 310 then run this command to import it:
 311
 312   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 313
 314 Here are the MD5 and SHA1 checksums:
 315
 316   @MD5SUM@ m4-@VERSION@.tar.gz
 317   @MD5SUM@ m4-@VERSION@.tar.bz2
 318   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 319   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 320   @SHA1SUM@ m4-@VERSION@.tar.gz
 321   @SHA1SUM@ m4-@VERSION@.tar.bz2
 322   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 323   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 324
 325 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 326
 327 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 328
 329 Alternatively, you can fetch the unbootstrapped sourcecode from git by
 330 using the following commands:
 331
 332   $ git clone git://git.sv.gnu.org/m4
 333   $ git checkout -b branch @GIT_RELEASE_TAG@
 334
 335 You will then need to have recent versions of Automake and Autoconf
 336 installed, and a recent checkout of gnulib, in order to bootstrap the
 337 checked out sources yourself.
 338
 339 New in @VERSION@: @RELEASE_DATE@
 340
 341   @EXCERPT_FROM_NEWS_FILE@
 342
 343 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 344 check' and any other information that might be useful in resolving the
 345 issue.
 346
 347
 348 8. Full release note template
 349 =============================
 350
 351 To: info-gnu@gnu.org
 352 To: m4-announce@gnu.org, m4-discuss@gnu.org, autotools-announce@gnu.org
 353 Subject: GNU M4 @VERSION@ released.
 354
 355 The GNU M4 Team is pleased to announce the release of GNU M4 @VERSION@.
 356
 357 GNU `m4' is an implementation of the traditional Unix macro processor.
 358 It is mostly SVR4 compatible, although it has some extensions (for
 359 example, handling more than 9 positional parameters to macros).  `m4'
 360 also has built-in functions for including files, running shell commands,
 361 doing arithmetic, etc.  Autoconf needs GNU `m4' for generating
 362 `configure' scripts, but not for running them.
 363
 364 This release has @SUMMARY_OF_IMPROVEMENTS_SINCE_LAST_RELEASE_ON_THIS_BRANCH@.
 365
 366 New in @VERSION@: @RELEASE_DATE@
 367
 368   @EXCERPT_FROM_NEWS_FILE@
 369
 370 m4-@VERSION@ is available now from ftp.gnu.org, along with diffs and
 371 xdeltas against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@ that are also
 372 available from ftp.gnu.org.  Please use a mirror to reduce stress on the
 373 main gnu machine:
 374
 375   http://www.gnu.org/order/ftp.html
 376
 377 Here are the compressed sources:
 378
 379   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz    [@SIZE@]
 380   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2   [@SIZE@]
 381
 382 Here are the xdeltas and diffs against m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@:
 383
 384   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz   [@SIZE@]
 385   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta    [@SIZE@]
 386
 387 Here are the gpg detached signatures:
 388
 389   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.gz.sig
 390   ftp://ftp.gnu.org/gnu/m4/m4-@VERSION@.tar.bz2.sig
 391   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz.sig
 392   ftp://ftp.gnu.org/gnu/m4/m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta.sig
 393
 394 You should download the signature named after any tarball you download,
 395 and then verify its integrity with, for example:
 396
 397   gpg --verify m4-@VERSION@.tar.gz.sig
 398
 399 If that command fails because you don't have the required public key,
 400 then run this command to import it:
 401
 402   gpg --keyserver wwwkeys.pgp.net --recv-keys @KEY@
 403
 404 Here are the MD5 and SHA1 checksums:
 405
 406   @MD5SUM@ m4-@VERSION@.tar.gz
 407   @MD5SUM@ m4-@VERSION@.tar.bz2
 408   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 409   @MD5SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 410   @SHA1SUM@ m4-@VERSION@.tar.gz
 411   @SHA1SUM@ m4-@VERSION@.tar.bz2
 412   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.diff.gz
 413   @SHA1SUM@ m4-@PREV_RELEASE_VERSION_ON_THIS_BRANCH@-@VERSION@.xdelta
 414
 415 This release was bootstrapped with @BOOTSTRAP_TOOLS_WITH_VERSIONS@.
 416
 417 Alternatively, you can fetch the unbootstrapped sourcecode from git by
 418 using the following commands:
 419
 420   $ git clone git://git.sv.gnu.org/m4
 421   $ git checkout -b branch @GIT_RELEASE_TAG@
 422
 423 You will then need to have the latest release versions of Automake
 424 (@AUTOMAKE_VERSION@) and Autoconf (@AUTOCONF_VERSION@) installed, as
 425 well as a git checkout of gnulib, in order to bootstrap the checked out
 426 sources yourself.
 427
 428 Please report bugs to <bug-m4@gnu.org>, along with the output of 'make
 429 check' and any other information that might be useful in resolving the
 430 issue.
 431
 432
 433 --
 434 Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
 435
 436 The canonical source of this file is maintained with the
 437 GNU M4 package.  Report bugs to bug-m4@gnu.org.
 438
 439 GNU M4 is free software: you can redistribute it and/or modify
 440 it under the terms of the GNU General Public License as published by
 441 the Free Software Foundation, either version 3 of the License, or
 442 (at your option) any later version.
 443
 444 GNU M4 is distributed in the hope that it will be useful,
 445 but WITHOUT ANY WARRANTY; without even the implied warranty of
 446 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 447 GNU General Public License for more details.
 448
 449 You should have received a copy of the GNU General Public License
 450 along with this program.  If not, see <http://www.gnu.org/licenses/>.
 451
 452 Local Variables:
 453 mode: text
 454 fill-column: 72
 455 End:
 456 vim:tw=72