Update Debian changelog.
[packages/dc3dd.git] / README.coreutils
1 These are the GNU core utilities.  This package is the union of
2 the GNU fileutils, sh-utils, and textutils packages.
3
4 Most of these programs have significant advantages over their Unix
5 counterparts, such as greater speed, additional options, and fewer
6 arbitrary limits.
7
8 The programs that can be built with this package are:
9
10   [ arch base64 basename cat chcon chgrp chmod chown chroot cksum comm cp
11   csplit cut date dd df dir dircolors dirname du echo env expand expr
12   factor false fmt fold groups head hostid hostname id install join kill
13   link ln logname ls md5sum mkdir mkfifo mknod mktemp mv nice nl nohup
14   od paste pathchk pinky pr printenv printf ptx pwd readlink rm rmdir
15   runcon seq sha1sum sha224sum sha256sum sha384sum sha512sum shred shuf
16   sleep sort split stat stty su sum sync tac tail tee test touch tr true
17   tsort tty uname unexpand uniq unlink uptime users vdir wc who whoami yes
18
19 See the file NEWS for a list of major changes in the current release.
20
21 If you obtained this file as part of a "git clone", then see the
22 README-hacking file.  If this file came to you as part of a tar archive,
23 then see the file INSTALL for compilation and installation instructions.
24
25 These programs are intended to conform to POSIX (with BSD and other
26 extensions), like the rest of the GNU system.  By default they conform
27 to older POSIX (1003.2-1992), and therefore support obsolete usages
28 like "head -10" and "chown owner.group file".  This default is
29 overridden at build-time by the value of <unistd.h>'s _POSIX2_VERSION
30 macro, and this in turn can be overridden at runtime as described in
31 the documentation under "Standards conformance".
32
33 The ls, dir, and vdir commands are all separate executables instead of
34 one program that checks argv[0] because people often rename these
35 programs to things like gls, gnuls, l, etc.  Renaming a program
36 file shouldn't affect how it operates, so that people can get the
37 behavior they want with whatever name they want.
38
39 Special thanks to Paul Eggert, Brian Matthews, Bruce Evans, Karl Berry,
40 Kaveh Ghazi, and François Pinard for help with debugging and porting
41 these programs.  Many thanks to all of the people who have taken the
42 time to submit problem reports and fixes.  All contributed changes are
43 attributed in the ChangeLog files.
44
45 And thanks to the following people who have provided accounts for
46 portability testing on many different types of systems: Bob Proulx,
47 Christian Robert, François Pinard, Greg McGary, Harlan Stenn,
48 Joel N. Weber, Mark D. Roth, Matt Schalit, Nelson H. F. Beebe,
49 Réjean Payette, Sam Tardieu.
50
51 Thanks to Michael Stone for inflicting test releases of this package
52 on Debian's unstable distribution, and to all the kind folks who used
53 that distribution and found and reported bugs.
54
55 Note that each man page is now automatically generated from a template
56 and from the corresponding --help usage message.  Patches to the template
57 files (man/*.x) are welcome.  However, the authoritative documentation
58 is in texinfo form in the doc directory.
59
60
61 *****************************************
62 On Mac OS X 10.5.1 (Darwin 9.1), test failure
63 -----------------------------------------
64
65 Mac OS X 10.5.1 (Darwin 9.1) provides only partial (and incompatible)
66 ACL support, so although "./configure && make" succeeds, "make check"
67 exposes numerous failures.  The solution is to turn off ACL support
68 manually via "./configure --disable-acl".  For details, see
69 <http://thread.gmane.org/gmane.comp.gnu.coreutils.bugs/12292/focus=12318>.
70
71
72 *****************************************
73 Test failure with NLS and gettext <= 0.17
74 -----------------------------------------
75
76 Due to a conflict between libintl.h and gnulib's new xprintf module,
77 when you configure with NLS support, and with a gettext installation
78 older than 0.17.1 (not yet released, at the time of this writing),
79 then some tests fail, at least on NetBSD 1.6.  To work around it in
80 the mean time, you can configure with --disable-nls.  For details,
81 see <http://thread.gmane.org/gmane.comp.lib.gnulib.bugs/12015/>.
82
83
84 ***********************
85 Pre-C99 build failure
86 -----------------------
87
88 There is a new, implicit build requirement:
89 To build the coreutils from source, you should have a C99-conforming
90 compiler, due to the use of declarations after non-declaration statements
91 in several files in src/.  There is code in configure to find and, if
92 possible, enable an appropriate compiler.  However, if configure doesn't
93 find a C99 compiler, it continues nonetheless, and your build will fail.
94 If that happens, simply apply the included patch using the following
95 command, and then run make again:
96
97   cd src && patch < c99-to-c89.diff
98
99
100 ***********************
101 HPUX 11.x build failure
102 -----------------------
103
104 A known problem exists when compiling on HPUX on both hppa and ia64
105 in 64-bit mode (i.e. +DD64) on HP-UX 11.0, 11.11, and 11.23.  This
106 is not due to a bug in the package but instead due to a bug in the
107 system header file which breaks things in 64-bit mode.  The default
108 compilation mode is 32-bit and the software compiles fine using the
109 default mode.  To build this software in 64-bit mode you will need
110 to fix the system /usr/include/inttypes.h header file.  After
111 correcting that file the software also compiles fine in 64-bit mode.
112 Here is one possible patch to correct the problem:
113
114 --- /usr/include/inttypes.h.orig        Thu May 30 01:00:00 1996
115 +++ /usr/include/inttypes.h     Sun Mar 23 00:20:36 2003
116 @@ -489 +489 @@
117 -#ifndef __STDC_32_MODE__
118 +#ifndef __LP64__
119
120
121 ************************
122 OSF/1 4.0d build failure
123 ------------------------
124
125 If you use /usr/bin/make on an OSF/1 4.0d system, it will fail due
126 to the presence of the "[" target.  That version of make appears to
127 treat "[" as some syntax relating to locks.  To work around that,
128 the best solution is to use GNU make.  Otherwise, simply remove
129 all mention of "[$(EXEEXT)" from src/Makefile.
130
131
132
133 **********************
134 Running tests as root:
135 ----------------------
136
137 If you run the tests as root, note that a few of them create files
138 and/or run programs as a non-root user, `nobody' by default.
139 If you want to use some other non-root username, specify it via
140 the NON_ROOT_USERNAME environment variable.  Depending on the
141 permissions with which the working directories have been created,
142 using `nobody' may fail, because that user won't have the required
143 read and write access to the build and test directories.
144 I find that it is best to unpack and build as a non-privileged
145 user, and then to run the following command as that user in order
146 to run the privilege-requiring tests:
147
148   sudo env PATH="$PATH" NON_ROOT_USERNAME=$USER make -k check-root
149
150 If you can run the tests as root, please do so and report any
151 problems.  We get much less test coverage in that mode, and it's
152 arguably more important that these tools work well when run by
153 root than when run by less privileged users.
154
155
156 ***************
157 Reporting bugs:
158 ---------------
159
160 IMPORTANT: if you take the time to report a test failure,
161 please be sure to include the output of running `make check'
162 in verbose mode for each failing test.  For example,
163 if the test that fails is tests/mv/hard-link-1, then you
164 would run this command:
165
166   env VERBOSE=yes make check -C tests/mv TESTS=hard-link-1 >> log 2>&1
167
168 For some tests, you can get even more detail by including
169 DEBUG=yes in the environment:
170
171   env DEBUG=yes VERBOSE=yes make check -C tests/mv TESTS=hard-link-1 >> log 2>&1
172
173 and then include the contents of the file `log' in your bug report.
174
175 ***************************************
176
177 There are many tests, but nowhere near as many as we need.
178 Additions and corrections are very welcome.
179
180 If you see a problem that you've already reported, feel free to re-report
181 it -- it won't bother me to get a reminder.  Besides, the more messages I
182 get regarding a particular problem the sooner it'll be fixed -- usually.
183 If you sent a complete patch and, after a couple weeks you haven't
184 received any acknowledgement, please ping us.  A complete patch includes
185 a well-written ChangeLog entry, unified (diff -u format) diffs relative
186 to the most recent test release (or, better, relative to the latest
187 sources in the public repository), an explanation for why the patch is
188 necessary or useful, and if at all possible, enough information to
189 reproduce whatever problem prompted it.  Plus, you'll earn lots of
190 karma if you include a test case to exercise any bug(s) you fix.
191 Here are instructions for checking out the latest development sources:
192
193   http://savannah.gnu.org/git/?group=coreutils
194
195 If your patch adds a new feature, please try to get some sort of consensus
196 that it is a worthwhile change.  One way to do that is to send mail to
197 bug-coreutils@gnu.org including as much description and justification
198 as you can.  Based on the feedback that generates, you may be able to
199 convince us that it's worth adding.
200
201
202 WARNING:  Now that we use the ./bootstrap script, you should not run
203 autoreconf manually.  Doing that will overwrite essential source files
204 with older versions, which may make the package unbuildable or introduce
205 subtle bugs.
206
207
208 WARNING:  If you modify files like configure.in, m4/*.m4, aclocal.m4,
209 or any Makefile.am, then don't be surprised if what gets regenerated no
210 longer works.  To make things work, you'll have to be using appropriate
211 versions of automake and autoconf.  As for what versions are `appropriate',
212 use the versions of
213
214   * autoconf specified via AC_PREREQ in m4/jm-macros.m4
215   * automake specified via AM_INIT_AUTOMAKE in configure.ac
216
217 Usually it's fine to use versions that are newer than those specified.
218
219 All of these programs except `test' recognize the `--version' option.
220 When reporting bugs, please include in the subject line both the package
221 name/version and the name of the program for which you found a problem.
222
223 For general documentation on the coding and usage standards
224 this distribution follows, see the GNU Coding Standards,
225 http://www.gnu.org/prep/standards_toc.html.
226
227 Mail suggestions and bug reports for these programs to
228 the address on the last line of --help output.
229
230
231 ========================================================================
232
233 Copyright (C) 1998, 2002, 2003, 2004, 2005, 2006 Free Software
234 Foundation, Inc.
235
236 Permission is granted to copy, distribute and/or modify this document
237 under the terms of the GNU Free Documentation License, Version 1.2 or
238 any later version published by the Free Software Foundation; with no
239 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
240 Texts.  A copy of the license is included in the ``GNU Free
241 Documentation License'' file as part of this distribution.