HACKING

   1 ================================================================
   2 = This file
   3
   4 * This file attempts to describe the rules to use when hacking
   5   automake.
   6
   7 * Don't put this file into the distribution.  Don't mention it in the
   8   ChangeLog.
   9
  10
  11 ================================================================
  12 = Administrivia
  13
  14 * If you incorporate a change from somebody on the net:
  15   First, if it is a large change, you must make sure they have signed the
  16   appropriate paperwork.
  17   Second, be sure to add their name and email address to THANKS
  18
  19 * If a change fixes a test, mention the test in the ChangeLog entry.
  20
  21 * If somebody reports a new bug, mention his name in the ChangeLog entry
  22   and in the test case you write.  Put him into THANKS.
  23
  24 * The correct response to most actual bugs is to write a new test case
  25   which demonstrates the bug.  Then fix the bug, re-run the test suite,
  26   and check everything in.
  27
  28 * Some files in the automake package are not owned by automake.  These
  29   files should never be edited here.  These files are
  30       COPYING (from FSF),
  31       INSTALL (autoconf-patches@gnu.org),
  32       config.guess, config.sub (config-patches@gnu.org),
  33       texinfo.tex (bug-texinfo@gnu.org),
  34   Most of them are updated before release with `make fetch'.
  35
  36 * Changes other than bug fixes must be mentioned in NEWS
  37
  38
  39 ================================================================
  40 = Naming
  41
  42 * We've adopted the convention that internal AC_SUBSTs should be
  43   named with a leading `am__', and internally generated targets should
  44   be named with a leading `am--'.  This convention is very new
  45   (as of Feb 7 2001) and so it isn't yet universally used.  But all
  46   new code should use it.
  47
  48   We used to use `_am_' as the prefix for an internal AC_SUBST.
  49   However, it turns out that NEWS-OS 4.2R complains if a Makefile
  50   variable begins with `_'.  Yay for them.  I changed the target
  51   naming convention just to be safe.
  52
  53 ================================================================
  54 = Editing `.am' files
  55
  56 * Always use $(...) and not ${...}
  57
  58 * Use `:', not `true'.  Use `exit 1', not `false'.
  59
  60 * Use `##' comments liberally.  Comment anything even remotely
  61   unusual.
  62
  63 * Never use basename or dirname.  Instead use sed
  64
  65 * Do not use `cd' within back-quotes, use `$(am__cd)' instead.
  66   Otherwise the directory name may be printed, depending on CDPATH.
  67
  68 * For install and uninstall rules, if a loop is required, it should be
  69   silent.  Then the body of the loop itself should print each
  70   "important" command it runs.  The printed commands should be preceded
  71   by a single space.
  72
  73
  74 ================================================================
  75 = Editing automake.in and aclocal.in
  76
  77 * Indent using GNU style.  For historical reasons, the perl code
  78   contains portions indented using Larry Wall's style (perl-mode's
  79   default), and other portions using the GNU style (cperl-mode's
  80   default).  Write new code using GNU style.
  81
  82 * Don't use & for function calls, unless required.
  83   The use of & prevents prototypes from being checked.
  84   Just as above, don't change massively all the code to strip the
  85   &, just convert the old code as you work on it, and write new
  86   code without.
  87
  88 * Perl 5 is now OK.
  89
  90
  91 ================================================================
  92 = Working with CVS
  93
  94 * To regenerate dependent files created by aclocal and automake,
  95   use the `bootstrap' script.  It uses the code from the source
  96   tree, so the resulting files (aclocal.m4 and Makefile.in) should
  97   be the same as you would get if you install this version of
  98   automake and use it to generate those files.
  99
 100 * Dependent files aclocal.m4, configure and Makefile.in in all
 101   directories should be up to date in the CVS repository, so that
 102   the changes in them can be easily noticed and analyzed.
 103
 104
 105 ================================================================
 106 = Test suite
 107
 108 * Use "make check" and "make maintainer-check" liberally
 109
 110 * Make sure each test file is executable
 111
 112
 113 ================================================================
 114 = Release procedure
 115
 116 * Fetch new versions of the files that are maintained by the FSF.
 117   Commit.  Unfortunately you need an FSF account to do this.
 118   (You can also use `make fetch', but that is still woefully incomplete.)
 119
 120 * Update NEWS.  For an alpha release, update README-alpha.
 121
 122 * Update the version number in configure.ac.
 123   (The idea is that every other alpha number will be a net release.
 124   The repository will always have its own "odd" number so we can easily
 125   distinguish net and repo versions.)
 126
 127 * Update ChangeLog.
 128
 129 * Run ./bootstrap, ./configure, make.
 130
 131 * Run `make cvs-dist'.
 132   This will run distcheck to create the tarball, commit the last
 133   NEWS/configure.ac/ChangeLog changes, and tag the repository.
 134
 135 * Update version number in configure.ac to next alpha number.
 136   Re-run ./bootstrap and commit.
 137
 138 * gpg -ba -o automake-VERSION.tar.gz.sig automake-VERSION.tar.gz
 139   gpg -ba -o automake-VERSION.tar.bz2.sig automake-VERSION.tar.bz2
 140   echo 'directory: automake' >automake-VERSION.tar.gz.directive
 141   gpg --clearsign automake-VERSION.tar.gz.directive
 142   cp automake-VERSION.tar.{gz,bz2}.directive.asc
 143
 144   scp automake-VERSION.tar.{gz,bz2}{,.sig} sources.redhat.com:~ftp/pub/automake
 145
 146   For alpha releases:
 147     ncftpput ftp-upload.gnu.org /incoming/alpha \
 148              automake-VERSION.tar.{gz,bz2}{,.directive.asc,.sig}
 149   For "real" releases:
 150     ncftpput ftp-upload.gnu.org /incoming/ftp \
 151              automake-VERSION.tar.{gz,bz2}{,.directive.asc,.sig}
 152
 153   Send announcement at least to autotools-announce@gnu.org, and
 154   automake@gnu.org.  If not an alpha, announcement must also go to
 155   info-gnu@gnu.org.
 156
 157 -----
 158
 159 Copyright (C) 2003 Free Software Foundation, Inc.
 160
 161 This file is part of GNU Automake.
 162
 163 GNU Automake is free software; you can redistribute it and/or modify
 164 it under the terms of the GNU General Public License as published by
 165 the Free Software Foundation; either version 2, or (at your option)
 166 any later version.
 167
 168 GNU Automake is distributed in the hope that it will be useful,
 169 but WITHOUT ANY WARRANTY; without even the implied warranty of
 170 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 171 GNU General Public License for more details.
 172
 173 You should have received a copy of the GNU General Public License
 174 along with autoconf; see the file COPYING.  If not, write to
 175 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 176 Boston, MA 02111-1307, USA.
 177
 178 Local Variables:
 179 mode: text
 180 End: