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