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