README

   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.