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