README-hacking

Building from a Git repository				-*- outline -*-

These notes intend to help people working on the checked-out sources.
These requirements do not apply when building from a distribution tarball.
If this package has a file HACKING, please also read that file for
more detailed contribution guidelines.

* Requirements

We've opted to keep only the highest-level sources in the Git repository.
This eases our maintenance burden (fewer merges etc.), but imposes more
requirements on anyone wishing to build from the just-checked-out sources.
(The requirements to build from a release are much less and are just
the requirements of the standard './configure && make' procedure.)
Specific development tools and versions will be checked for and listed by
the bootstrap script.  See README-prereq for specific notes on obtaining
these prerequisite tools.

Valgrind <https://valgrind.org/> is also highly recommended, if
Valgrind supports your architecture.  See also README-valgrind
(if present).

While building from a just-cloned source tree may require installing a
few prerequisites, later, a plain 'git pull && make' typically suffices.

* First Git checkout

You can get a copy of the source repository like this:

        $ git clone https://git.savannah.gnu.org/git/<packagename>
        $ cd <packagename>

where '<packagename>' stands for 'coreutils' or whatever other package
you are building.

To use the most-recent Gnulib (as opposed to the Gnulib version that
the package last synchronized to), do this next:

        $ git submodule foreach git pull origin master
        $ git commit -m 'build: update gnulib submodule to latest' gnulib

As an optional step, if you already have a copy of the Gnulib Git
repository, then you can use it as a reference to reduce download
time and file system space requirements:

        $ export GNULIB_SRCDIR=/path/to/gnulib

The next steps are to get and check other files needed to build,
and complete the build:

        $ make -f cfg.mk

For reference the above command runs the following steps,
which can be done individually if required to give more control:

        $ ./bootstrap
        $ ./configure --quiet #[--disable-gcc-warnings] [*]
        $ make #[check]

At this point, there should be no difference between your local copy,
and the Git master copy:

        $ git diff

should output no difference.

Enjoy!

[*] By default GCC warnings are enabled when building from Git.
If you get warnings with recent GCC and Glibc with default
configure-time options, please report the warnings to the bug
reporting address of this package instead of to bug-gnulib,
even if the problem seems to originate in a Gnulib-provided file.
If you get warnings with other configurations, you can run
'./configure --disable-gcc-warnings' or 'make WERROR_CFLAGS='
to build quietly or verbosely, respectively.
-----

* Submitting patches

If you develop a fix or a new feature, please send it to the
appropriate bug-reporting address as reported by the --help option of
each program.  One way to do this is to use vc-dwim
<https://www.gnu.org/software/vc-dwim/>), as follows.

  Run the command "vc-dwim --initialize" from the top-level directory
  of this package's git-cloned hierarchy.

  Edit the (empty) ChangeLog file that this command creates, creating a
  properly-formatted entry according to the GNU coding standards
  <https://www.gnu.org/prep/standards/html_node/Change-Logs.html>.

  Make your changes.

  Run the command "vc-dwim" and make sure its output (the diff of all
  your changes) looks good.

  Run "vc-dwim --commit".

  Run the command "git format-patch --stdout -1", and email its output
  in, using the output's subject line.

-----

Copyright (C) 2002-2024 Free Software Foundation, Inc.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.