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 COPYING, INSTALL,
  30   ansi2knr.1, ansi2knr.c, config.guess config.sub, install-sh, mdate-sh,
  31   missing, mkinstalldirs, texinfo.tex
  32
  33 * Changes other than bug fixes must be mentioned in NEWS
  34
  35
  36 ================================================================
  37 = Naming
  38
  39 * We've adopted the convention that internal AC_SUBSTs should be
  40   named with a leading `am__', and internally generated targets should
  41   be named with a leading `am--'.  This convention is very new
  42   (as of Feb 7 2001) and so it isn't yet universally used.  But all
  43   new code should use it.
  44
  45   We used to use `_am_' as the prefix for an internal AC_SUBST.
  46   However, it turns out that NEWS-OS 4.2R complains if a Makefile
  47   variable begins with `_'.  Yay for them.  I changed the target
  48   naming convention just to be safe.
  49
  50 ================================================================
  51 = Editing `.am' files
  52
  53 * Always use $(...) and not ${...}
  54
  55 * Use `:', not `true'.  Use `exit 1', not `false'.
  56
  57 * Use `##' comments liberally.  Comment anything even remotely
  58   unusual.
  59
  60 * Never use basename or dirname.  Instead use sed
  61
  62 * Do not use `cd' within back-quotes, use `$(am__cd)' instead.
  63   Otherwise the directory name may be printed, depending on CDPATH.
  64
  65 * For install and uninstall rules, if a loop is required, it should be
  66   silent.  Then the body of the loop itself should print each
  67   "important" command it runs.  The printed commands should be preceded
  68   by a single space.
  69
  70
  71 ================================================================
  72 = Editing automake.in and aclocal.in
  73
  74 * Indent using GNU style.  For historical reasons, the perl code
  75   contains portions indented using Larry Wall's style (perl-mode's
  76   default), and other portions using the GNU style (cperl-mode's
  77   default).  Write new code using GNU style.
  78
  79 * Perl 5 is now OK.
  80
  81
  82 ================================================================
  83 = Working with CVS
  84
  85 * To regenerate dependent files created by aclocal and automake,
  86   use the `bootstrap' script.  It uses the code from the source
  87   tree, so the resulting files (aclocal.m4 and Makefile.in) should
  88   be the same as you would get if you install this version of
  89   automake and use it to generate those files.
  90
  91 * Dependent files aclocal.m4, configure and Makefile.in in all
  92   directories should be up to date in the CVS repository, so that
  93   the changes in them can be easily noticed and analyzed.
  94
  95
  96 ================================================================
  97 = Test suite
  98
  99 * Use "make check" and "make maintainer-check" liberally
 100
 101 * Make sure each test file is executable
 102
 103
 104 ================================================================
 105 = Release procedure
 106
 107 * Fetch new versions of the files that are maintained by the FSF.
 108   Commit.  Unfortunately you need an FSF account to do this.
 109   (You can also use `make fetch', but that is still woefully incomplete.)
 110
 111 * Update NEWS.  For an alpha release, update README-alpha.
 112
 113 * Update the version number in configure.in.
 114   (The idea is that every other alpha number will be a net release.
 115   The repository will always have its own "odd" number so we can easily
 116   distinguish net and repo versions.)
 117
 118 * Configure, build, and install.
 119
 120 * Run aclocal, automake, and autoconf.
 121
 122 * Commit
 123
 124 * Run `make cvs-dist'
 125
 126 * Put new release on ftp site and send announcement to automake list.
 127   If not an alpha, announcement must also go to FSF:
 128   Put the files on a public ftp site and send a message to
 129   ftp-upload@gnu.org.
 130   Then send the announcement to info-gnu@gnu.org.
 131
 132 * Update version number in configure.in to next alpha number.
 133   Re-run autoconf and commit.