dd: improve doc of stderr output
[coreutils.git] / README-hacking
1 -*- outline -*-
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 See also HACKING for more detailed contribution guidelines.
7 * Requirements
9 We've opted to keep only the highest-level sources in the GIT repository.
10 This eases our maintenance burden, (fewer merges etc.), but imposes more
11 requirements on anyone wishing to build from the just-checked-out sources.
12 Note the requirements to build the released archive are much less and
13 are just the requirements of the standard ./configure && make procedure.
14 Specific development tools and versions will be checked for and listed by
15 the bootstrap script.  See README-prereq for specific notes on obtaining
16 these prerequisite tools.
18 Valgrind <http://valgrind.org/> is also highly recommended, if
19 Valgrind supports your architecture. See also README-valgrind.
21 While building from a just-cloned source tree may require installing a
22 few prerequisites, later, a plain 'git pull && make' should be sufficient.
24 * First GIT checkout
26 You can get a copy of the source repository like this:
28         $ git clone git://git.sv.gnu.org/coreutils
29         $ cd coreutils
31 As an optional step, if you already have a copy of the gnulib git
32 repository, then you can use it as a reference to reduce download
33 time and disk space requirements:
35         $ export GNULIB_SRCDIR=/path/to/gnulib
37 The next step is to get and check other files needed to build,
38 which are extracted from other source packages:
40         $ ./bootstrap
42 To use the most-recent gnulib (as opposed to the gnulib version that
43 the package last synchronized to), do this next:
45         $ git submodule foreach git pull origin master
46         $ git commit -m 'build: update gnulib submodule to latest' gnulib
48 And there you are!  Just
50         $ ./configure --quiet #[--enable-gcc-warnings] [*]
51         $ make
52         $ make check
54 At this point, there should be no difference between your local copy,
55 and the GIT master copy:
57         $ git diff
59 should output no difference.
61 Enjoy!
63 [*] The --enable-gcc-warnings option is useful only with glibc
64 and with a very recent version of gcc.  You'll probably also have
65 to use recent system headers.  If you configure with this option,
66 and spot a problem, please be sure to send the report to the bug
67 reporting address of this package, and not to that of gnulib, even
68 if the problem seems to originate in a gnulib-provided file.
70 * Submitting patches
72 If you develop a fix or a new feature, please send it to the
73 appropriate bug-reporting address as reported by the --help option of
74 each program.  One way to do this is to use vc-dwim
75 <https://www.gnu.org/software/vc-dwim/>), as follows.
77   Run the command "vc-dwim --initialize" from the top-level directory
78   of this package's git-cloned hierarchy.
80   Edit the (empty) ChangeLog file that this command creates, creating a
81   properly-formatted entry according to the GNU coding standards
82   <https://www.gnu.org/prep/standards/html_node/Change-Logs.html>.
84   Make your changes.
86   Run the command "vc-dwim" and make sure its output (the diff of all
87   your changes) looks good.
89   Run "vc-dwim --commit".
91   Run the command "git format-patch --stdout -1", and email its output
92   in, using the output's subject line.
94 -----
96 Copyright (C) 2002-2019 Free Software Foundation, Inc.
98 This program is free software: you can redistribute it and/or modify
99 it under the terms of the GNU General Public License as published by
100 the Free Software Foundation, either version 3 of the License, or
101 (at your option) any later version.
103 This program is distributed in the hope that it will be useful,
104 but WITHOUT ANY WARRANTY; without even the implied warranty of
106 GNU General Public License for more details.
108 You should have received a copy of the GNU General Public License
109 along with this program.  If not, see <https://www.gnu.org/licenses/>.