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