README-hacking

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