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