README-hacking

   1 -*- outline -*-
   2
   3 These notes intend to help people working on the checked-out sources.
   4 These requirements do not apply when building from a distribution
   5 tarball.  Don't put this file into the distribution.  Don't mention it
   6 in the ChangeLog.  You may want to also see HACKING for
   7 maintainer-specific rules.
   8
   9 * Requirements
  10
  11 We've opted to keep only the highest-level sources in the GIT repository.
  12 This eases our maintenance burden, (fewer merges etc.), but imposes more
  13 requirements on anyone wishing to build from the just-checked-out sources.
  14 For example, you have to use recent stable versions of the maintainer
  15 tools we depend upon, including:
  16
  17 - Automake 1.11+ <https://www.gnu.org/software/automake/>
  18 - Help2man 1.29+ <https://www.gnu.org/software/help2man/>
  19 - M4 1.4.16+ <https://www.gnu.org/software/m4/>
  20 - Perl 5.006+ <https://www.cpan.org/>
  21 - Texinfo 4.11+ <https://www.gnu.org/software/texinfo/>
  22
  23 The following are useful as well, if you want to be able to run commands
  24 like "make dist-xz" or "make distcheck":
  25
  26 - Gzip <https://www.gnu.org/software/gzip/>
  27 - Tar <https://www.gnu.org/software/tar/>
  28 - XZ Utils <https://tukaani.org/xz/>
  29
  30 Although we try to keep the CVS mirror of the git repository usable,
  31 some of the tests in the testsuite will fail if git was not used to
  32 generate the version string.  Therefore, we recommend:
  33
  34 - Git 1.4.4+ <https://git-scm.com/>
  35
  36 You may find it useful to install the git-merge-changelog merge driver:
  37 https://git.savannah.gnu.org/cgit/gnulib.git/plain/lib/git-merge-changelog.c
  38
  39 then add the following to .git/config or ~/.gitconfig:
  40 [merge "merge-changelog"]
  41         name = GNU ChangeLog merge driver
  42         driver = git-merge-changelog %O %A %B
  43 [diff "texinfo"]
  44         funcname = ^@node[\t ][\t ]*\\([^,][^,]*\\)
  45
  46 Only building the initial full source tree will be a bit painful.
  47 Later, a plain 'git pull && make' should be sufficient.
  48
  49 If you want to test Autoconf on a machine without git, it may be
  50 easier to first bootstrap Autoconf on a different machine with git,
  51 run 'make dist', and copy the tarball to the machine under test.  It
  52 should always be possible to create a self-contained tarball which
  53 does not rely on the bootstrap-only tools.
  54
  55 * First GIT checkout
  56
  57 You can get an anonymous copy of the source repository using any one
  58 of these three methods, although the CVS mirror is less tested:
  59
  60   $ git clone git://git.sv.gnu.org/autoconf
  61   $ git clone https://git.sv.gnu.org/r/autoconf.git
  62   $ cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/autoconf.git \
  63       co -d autoconf HEAD
  64
  65 If you have a Savannah user name and commit rights to the Autoconf
  66 project, you should use this instead:
  67
  68   $ git clone <username>@git.sv.gnu.org:/srv/git/autoconf.git
  69
  70 The next step is to generate files like configure and Makefile.in:
  71
  72   $ cd autoconf
  73   $ ./bootstrap
  74
  75 The bootstrap script generates the same files ‘autoreconf -vi’ would,
  76 in a normal package, but it uses autoconf *from the git sources* to do
  77 it.  This means you do not need autoconf installed already, and you do
  78 not need to re-generate ‘configure’ after building Autoconf.
  79
  80 You can now build and test the package:
  81
  82   $ ./configure
  83   $ make
  84   $ make check
  85
  86 At this point, there should be no difference between your local copy,
  87 and the GIT master copy:
  88
  89   $ git diff
  90
  91 should output no difference.
  92
  93 The testsuite is run by 'make check'.  You may find it useful to run a
  94 subset of the testsuite; for example, all tests with the 'm4sugar'
  95 keyword as well as test 10:
  96
  97   $ make check TESTSUITEFLAGS='10 -k m4sugar'
  98
  99 You can pass options to configure scripts invoked by the testsuite by
 100 setting the configure_options variable:
 101
 102   $ make check TESTSUITEFLAGS='configure_options="CC=gcc-2.95"'
 103
 104 The test suite is not automatically parallelized by ‘make -j’.  If you
 105 want to parallelize the testsuite, you need to use TESTSUITEFLAGS for
 106 that, too:
 107
 108   $ make check TESTSUITEFLAGS=-j8
 109
 110 * Submitting patches
 111
 112 All patches should be submitted to <autoconf-patches@gnu.org> for
 113 review, in context or unified diff format against the latest sources.
 114 In most cases, a patch should include a test case, to ensure that
 115 regressions do not creep back in.  Remember to add documentation and a
 116 NEWS entry for anything that is visible to the user.
 117
 118 If your change is significant (i.e., if it adds more than ~10 lines),
 119 then you'll have to have a copyright assignment on file with the FSF.
 120 Since that involves first an email exchange between you and the FSF,
 121 and then the exchange (FSF to you, then back) of an actual sheet of paper
 122 with your signature on it, and finally, some administrative processing
 123 in Boston, the process can take a few weeks.
 124
 125 The forms to choose from are in gnulib's doc/Copyright/ directory.
 126 If you want to assign a single change, you should use the file,
 127 doc/Copyright/request-assign.changes:
 128
 129     https://git.sv.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.changes
 130
 131 If you would like to assign past and future autoconf work,
 132 you'd use doc/Copyright/request-assign.future:
 133
 134     https://git.sv.gnu.org/cgit/gnulib.git/tree/doc/Copyright/request-assign.future
 135
 136 Enjoy!
 137
 138 -----
 139
 140 Copyright (C) 2002-2017, 2020-2023 Free Software Foundation, Inc.
 141
 142 Copying and distribution of this file, with or without modification,
 143 are permitted in any medium without royalty provided the copyright
 144 notice and this notice are preserved.  This file is offered as-is,
 145 without warranty of any kind.