* src/dircolors.hin: Mention that ORPHAN refers not just to dangling symlinks.
[platform/upstream/coreutils.git] / README
diff --git a/README b/README
index 0de5305..2e946de 100644 (file)
--- a/README
+++ b/README
@@ -7,13 +7,14 @@ arbitrary limits.
 
 The programs that can be built with this package are:
 
-  [ basename cat chgrp chmod chown chroot cksum comm cp csplit cut date dd
-  df dir dircolors dirname du echo env expand expr factor false fmt fold
+  [ base64 basename cat chgrp chmod chown chroot cksum comm cp csplit cut date
+  dd df dir dircolors dirname du echo env expand expr factor false fmt fold
   ginstall groups head hostid hostname id join kill link ln logname ls
   md5sum mkdir mkfifo mknod mv nice nl nohup od paste pathchk pinky pr
-  printenv printf ptx pwd readlink rm rmdir seq sha1sum shred sleep sort
-  split stat stty su sum sync tac tail tee test touch tr true tsort tty
-  uname unexpand uniq unlink uptime users vdir wc who whoami yes
+  printenv printf ptx pwd readlink rm rmdir seq sha1sum sha224sum sha256sum
+  sha384sum sha512sum shred sleep sort split stat stty su sum sync tac tail
+  tee test touch tr true tsort tty uname unexpand uniq unlink uptime users
+  vdir wc who whoami yes
 
 See the file NEWS for a list of major changes in the current release.
 
@@ -34,18 +35,18 @@ file shouldn't affect how it operates, so that people can get the
 behavior they want with whatever name they want.
 
 Special thanks to Paul Eggert, Brian Matthews, Bruce Evans, Karl Berry,
-Kaveh Ghazi, and François Pinard for help with debugging and porting
+Kaveh Ghazi, and François Pinard for help with debugging and porting
 these programs.  Many thanks to all of the people who have taken the
 time to submit problem reports and fixes.  All contributed changes are
-attributed in the ChangeLog file.
+attributed in the ChangeLog files.
 
 And thanks to the following people who have provided accounts for
 portability testing on many different types of systems: Bob Proulx,
-Christian Robert, François Pinard, Greg McGary, Harlan Stenn,
+Christian Robert, François Pinard, Greg McGary, Harlan Stenn,
 Joel N. Weber, Mark D. Roth, Matt Schalit, Nelson H. F. Beebe,
-Réjean Payette, Sam Tardieu.
+Réjean Payette, Sam Tardieu.
 
-Thanks to Michael Stone for inflicting test releases of the fileutils
+Thanks to Michael Stone for inflicting test releases of this package
 on Debian's unstable distribution, and to all the kind folks who used
 that distribution and found and reported bugs.
 
@@ -58,19 +59,20 @@ If you run the tests on a SunOS4.1.4 system, expect the ctime-part of
 the ls `time-1' test to fail.  I believe that is due to a bug in the
 way Sun implemented link(2) and chmod(2).
 
-***************************************
-Last-minute notes, before coreutils-5.0
----------------------------------------
+
+***********************
+HPUX 11.x build failure
+-----------------------
 
 A known problem exists when compiling on HPUX on both hppa and ia64
-in 64-bit mode (i.e. +DD64) on all known HPUX 11.x versions.  This
+in 64-bit mode (i.e. +DD64) on HP-UX 11.0, 11.11, and 11.23.  This
 is not due to a bug in the package but instead due to a bug in the
 system header file which breaks things in 64-bit mode.  The default
 compilation mode is 32-bit and the software compiles fine using the
 default mode.  To build this software in 64-bit mode you will need
 to fix the system /usr/include/inttypes.h header file.  After
 correcting that file the software also compiles fine in 64-bit mode.
-Here is one possible patch to correct the problem.
+Here is one possible patch to correct the problem:
 
 --- /usr/include/inttypes.h.orig       Thu May 30 01:00:00 1996
 +++ /usr/include/inttypes.h    Sun Mar 23 00:20:36 2003
@@ -78,6 +80,11 @@ Here is one possible patch to correct the problem.
 -#ifndef __STDC_32_MODE__
 +#ifndef __LP64__
 
+
+**********************
+Running tests as root:
+----------------------
+
 If you run the tests as root, note that a few of them create files
 and/or run programs as a non-root user, `nobody' by default.
 If you want to use some other non-root username, specify it via
@@ -89,16 +96,36 @@ I find that it is best to unpack and build as a non-privileged
 user, and then to run the following command as that user in order
 to run the privilege-requiring tests:
 
-  sudo env NON_ROOT_USERNAME=$USER make check
+  sudo env NON_ROOT_USERNAME=$USER make -k check
 
 If you can run the tests as root, please do so and report any
 problems.  We get much less test coverage in that mode, and it's
 arguably more important that these tools work well when run by
 root than when run by less privileged users.
 
+
+***************
+Reporting bugs:
+---------------
+
+IMPORTANT: if you take the time to report a test failure,
+please be sure to include the output of running `make check'
+in verbose mode for each failing test.  For example,
+if the test that fails is tests/mv/hard-link-1, then you
+would run this command:
+
+  env VERBOSE=yes make check -C tests/mv TESTS=hard-link-1 >> log 2>&1
+
+For some tests, you can get even more detail by including
+DEBUG=yes in the environment:
+
+  env DEBUG=yes VERBOSE=yes make check -C tests/mv TESTS=hard-link-1 >> log 2>&1
+
+and then include the contents of the file `log' in your bug report.
+
 ***************************************
 
-There are pretty many tests, but nowhere near as many as we need.
+There are many tests, but nowhere near as many as we need.
 Additions and corrections are very welcome.
 
 If you see a problem that you've already reported, feel free to re-report
@@ -135,9 +162,9 @@ use the versions of
 
 Usually it's fine to use versions that are newer than those specified.
 
-These programs all recognize the `--version' option.  When reporting
-bugs, please include in the subject line both the package name/version
-and the name of the program for which you found a problem.
+All of these programs except `test' recognize the `--version' option.
+When reporting bugs, please include in the subject line both the package
+name/version and the name of the program for which you found a problem.
 
 For general documentation on the coding and usage standards
 this distribution follows, see the GNU Coding Standards,