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 https://git.savannah.gnu.org/git/<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 [1]:
  50
  51         $ ./bootstrap
  52
  53 And there you are!  Just
  54
  55         $ ./configure --quiet #[--disable-gcc-warnings] [2]
  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 Enjoy!
  67
  68 [1] You can also bootstrap in two phases: first, './bootstrap --pull'
  69 fetches auxiliary files from the network, and then './bootstrap --gen'
  70 generates files by using local tools without accessing the net.
  71 Although './bootstrap' by default does both phases, auditable builds
  72 can do them separately.
  73
  74 [2] By default GCC warnings are enabled when building from Git.
  75 If you get warnings with recent GCC and Glibc with default
  76 configure-time options, please report the warnings to the bug
  77 reporting address of this package instead of to bug-gnulib,
  78 even if the problem seems to originate in a Gnulib-provided file.
  79 If you get warnings with other configurations, you can run
  80 './configure --disable-gcc-warnings' or 'make WERROR_CFLAGS='
  81 to build quietly or verbosely, respectively.
  82 -----
  83
  84 * Submitting patches
  85
  86 If you develop a fix or a new feature, please send it to the
  87 appropriate bug-reporting address as reported by the --help option of
  88 each program.  One way to do this is to use vc-dwim
  89 <https://www.gnu.org/software/vc-dwim/>), as follows.
  90
  91   Run the command "vc-dwim --initialize" from the top-level directory
  92   of this package's git-cloned hierarchy.
  93
  94   Edit the (empty) ChangeLog file that this command creates, creating a
  95   properly-formatted entry according to the GNU coding standards
  96   <https://www.gnu.org/prep/standards/html_node/Change-Logs.html>.
  97
  98   Make your changes.
  99
 100   Run the command "vc-dwim" and make sure its output (the diff of all
 101   your changes) looks good.
 102
 103   Run "vc-dwim --commit".
 104
 105   Run the command "git format-patch --stdout -1", and email its output
 106   in, using the output's subject line.
 107
 108 -----
 109
 110 Copyright (C) 2002-2024 Free Software Foundation, Inc.
 111
 112 This program is free software: you can redistribute it and/or modify
 113 it under the terms of the GNU General Public License as published by
 114 the Free Software Foundation, either version 3 of the License, or
 115 (at your option) any later version.
 116
 117 This program is distributed in the hope that it will be useful,
 118 but WITHOUT ANY WARRANTY; without even the implied warranty of
 119 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 120 GNU General Public License for more details.
 121
 122 You should have received a copy of the GNU General Public License
 123 along with this program.  If not, see <https://www.gnu.org/licenses/>.