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