--- README-hacking | 110 ++++++++++++++++++++++++++++++++++++------------- README-prereq | 36 ++++++++++++++++ 2 files changed, 118 insertions(+), 28 deletions(-) create mode 100644 README-prereq
diff --git a/README-hacking b/README-hacking index 0efda0d..44cb75b 100644 --- a/README-hacking +++ b/README-hacking @@ -1,56 +1,112 @@ --*- outline -*- +Building from a Git repository -*- outline -*- -These notes intend to help people working on the CVS version of -this package. +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 -Only the sources are installed in the CVS repository (to ease the -maintenance, merges etc.), therefore you will have to get the latest -stable versions of the maintainer tools we depend upon, including: - -- Automake <https://www.gnu.org/software/automake/> -- Autoconf <https://www.gnu.org/software/autoconf/> -- Tar <https://www.gnu.org/software/tar/> -- Wget <https://www.gnu.org/software/wget/> +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 <http://valgrind.org/> is also highly recommended, if -Valgrind supports your architecture. +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 git://git.sv.gnu.org/<packagename> + $ cd <packagename> -Only building the initial full source tree will be a bit painful, -later, a plain `cvs update -P && make' should be sufficient. +where '<packagename>' stands for 'coreutils' or whatever other package +you are building. -* First CVS checkout +To use the most-recent Gnulib (as opposed to the Gnulib version that +the package last synchronized to), do this next: -Obviously, if you are reading these notes, you did manage to check out -this package from CVS. The next step is to get other files needed to -build, which are extracted from other source packages: + $ 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 step is to get and check other files needed to build, +which are extracted from other source packages: $ ./bootstrap And there you are! Just - $ ./configure + $ ./configure --quiet #[--disable-gcc-warnings] [*] $ make $ make check At this point, there should be no difference between your local copy, -and the CVS master copy: +and the Git master copy: - $ cvs diff + $ 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-2006, 2009-2021 Free Software Foundation, Inc. +Copyright (C) 2002-2021 Free Software Foundation, Inc. -This program is free software; you can redistribute it and/or modify +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, or (at your option) -any later version. +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 @@ -58,6 +114,4 @@ 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, write to the Free Software -Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA -02110-1301, USA. +along with this program. If not, see <https://www.gnu.org/licenses/>. diff --git a/README-prereq b/README-prereq new file mode 100644 index 0000000..d12d1da --- /dev/null +++ b/README-prereq @@ -0,0 +1,36 @@ +This gives some notes on obtaining the tools required for development. +These tools can be used by the 'bootstrap' and 'configure' scripts, +as well as by 'make'. They include: + +- Autoconf <https://www.gnu.org/software/autoconf/> +- Automake <https://www.gnu.org/software/automake/> +- Git <https://git-scm.com/> +- M4 <https://www.gnu.org/software/m4/> +- Make <https://www.gnu.org/software/make/> +- Perl <https://www.cpan.org/> +- Tar <https://www.gnu.org/software/tar/> +- Texinfo <https://www.gnu.org/software/texinfo/> +- Wget <http://www.gnu.org/software/wget/> +- XZ Utils <https://tukaani.org/xz/> + +It is generally better to use official packages for your system. +If a package is not officially available you can build it from source +and install it into a directory that you can then use to build this +package. If some packages are available but are too old, install the +too-old versions first as they may be needed to build newer versions. + +Here is an example of how to build a program from source. This +example is for Autoconf; a similar approach should work for the other +developer prerequisites. This example assumes Autoconf 2.71; it +should be OK to use a later version of Autoconf, if available. + + prefix=$HOME/prefix # (or wherever else you choose) + export PATH=$prefix/bin:$PATH + wget https://ftp.gnu.org/pub/gnu/autoconf/autoconf-2.71.tar.gz + gzip -d <autoconf-2.71.tar.gz | tar xf - + cd autoconf-2.71 + ./configure --prefix=$prefix + make install + +Once the prerequisites are installed, you can build this package as +described in README-hacking. -- 2.32.0
