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-release'.
 132   This will run distcheck to create the tarballs, commit the last
 133   NEWS/configure.ac/ChangeLog changes, tag the repository, sign
 134   the tarballs, and upload them.
 135   Use `make GNUPLOADFLAGS="--user key" cvs-release' to sign with
 136   a non-default key.
 137
 138 * Update version number in configure.ac to next alpha number.
 139   Re-run ./bootstrap and commit.
 140
 141 * Send announcement at least to autotools-announce@gnu.org, and
 142   automake@gnu.org.  If not an alpha, announcement must also go to
 143   info-gnu@gnu.org.
 144
 145 -----
 146
 147 Copyright (C) 2003 Free Software Foundation, Inc.
 148
 149 This file is part of GNU Automake.
 150
 151 GNU Automake is free software; you can redistribute it and/or modify
 152 it under the terms of the GNU General Public License as published by
 153 the Free Software Foundation; either version 2, or (at your option)
 154 any later version.
 155
 156 GNU Automake is distributed in the hope that it will be useful,
 157 but WITHOUT ANY WARRANTY; without even the implied warranty of
 158 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 159 GNU General Public License for more details.
 160
 161 You should have received a copy of the GNU General Public License
 162 along with autoconf; see the file COPYING.  If not, write to
 163 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 164 Boston, MA 02111-1307, USA.
 165
 166 Local Variables:
 167 mode: text
 168 End: