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 tarball.
   5 See also HACKING for more detailed contribution guidelines.
   6
   7 * Requirements
   8
   9 We've opted to keep only the highest-level sources in the GIT repository.
  10 This eases our maintenance burden, (fewer merges etc.), but imposes more
  11 requirements on anyone wishing to build from the just-checked-out sources.
  12 Note the requirements to build the released archive are much less and
  13 are just the requirements of the standard ./configure && make procedure.
  14 Specific development tools and versions will be checked for and listed by
  15 the bootstrap script.  See README-prereq for specific notes on obtaining
  16 these prerequisite tools.
  17
  18 Valgrind <http://valgrind.org/> is also highly recommended, if
  19 Valgrind supports your architecture. See also README-valgrind.
  20
  21 While building from a just-cloned source tree may require installing a
  22 few prerequisites, later, a plain 'git pull && make' should be sufficient.
  23
  24 * First GIT checkout
  25
  26 You can get a copy of the source repository like this:
  27
  28         $ git clone git://git.sv.gnu.org/coreutils
  29         $ cd coreutils
  30
  31 As an optional step, if you already have a copy of the gnulib git
  32 repository, then you can use it as a reference to reduce download
  33 time and disk space requirements:
  34
  35         $ export GNULIB_SRCDIR=/path/to/gnulib
  36
  37 The next step is to get and check other files needed to build,
  38 which are extracted from other source packages:
  39
  40         $ ./bootstrap
  41
  42 To use the most-recent gnulib (as opposed to the gnulib version that
  43 the package last synchronized to), do this next:
  44
  45         $ git submodule foreach git pull origin master
  46         $ git commit -m 'build: update gnulib submodule to latest' gnulib
  47
  48 And there you are!  Just
  49
  50         $ ./configure --quiet #[--enable-gcc-warnings] [*]
  51         $ make
  52         $ make check
  53
  54 At this point, there should be no difference between your local copy,
  55 and the GIT master copy:
  56
  57         $ git diff
  58
  59 should output no difference.
  60
  61 Enjoy!
  62
  63 [*] The --enable-gcc-warnings option is useful only with glibc
  64 and with a very recent version of gcc.  You'll probably also have
  65 to use recent system headers.  If you configure with this option,
  66 and spot a problem, please be sure to send the report to the bug
  67 reporting address of this package, and not to that of gnulib, even
  68 if the problem seems to originate in a gnulib-provided file.
  69
  70 * Submitting patches
  71
  72 If you develop a fix or a new feature, please send it to the
  73 appropriate bug-reporting address as reported by the --help option of
  74 each program.  One way to do this is to use vc-dwim
  75 <https://www.gnu.org/software/vc-dwim/>), as follows.
  76
  77   Run the command "vc-dwim --initialize" from the top-level directory
  78   of this package's git-cloned hierarchy.
  79
  80   Edit the (empty) ChangeLog file that this command creates, creating a
  81   properly-formatted entry according to the GNU coding standards
  82   <https://www.gnu.org/prep/standards/html_node/Change-Logs.html>.
  83
  84   Make your changes.
  85
  86   Run the command "vc-dwim" and make sure its output (the diff of all
  87   your changes) looks good.
  88
  89   Run "vc-dwim --commit".
  90
  91   Run the command "git format-patch --stdout -1", and email its output
  92   in, using the output's subject line.
  93
  94 -----
  95
  96 Copyright (C) 2002-2017 Free Software Foundation, Inc.
  97
  98 This program is free software: you can redistribute it and/or modify
  99 it under the terms of the GNU General Public License as published by
 100 the Free Software Foundation, either version 3 of the License, or
 101 (at your option) any later version.
 102
 103 This program is distributed in the hope that it will be useful,
 104 but WITHOUT ANY WARRANTY; without even the implied warranty of
 105 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 106 GNU General Public License for more details.
 107
 108 You should have received a copy of the GNU General Public License
 109 along with this program.  If not, see <http://www.gnu.org/licenses/>.