From e3d60359380e9b472623c18995b3a77a32c56a67 Mon Sep 17 00:00:00 2001 From: =?utf8?q?P=C3=A1draig=20Brady?= Date: Sat, 13 Aug 2022 20:48:12 +0100 Subject: [PATCH] doc: README: split out ancillary information The README was becoming too long and contained quite a bit of info only pertaining to rarely used systems, so... * README: Split out install specific info to README-install. Also remove a few stale lines, and reorder a few items. * README-install: A new file split from README. * Makefile.am [EXTRA_DIST]: Explicitly reference new README-install file for distribution, since automake only auto adds README. * TODO: Reference the HPUX info now in README-install. --- Makefile.am | 1 + README | 136 +++++++------------------------------------------ README-install | 111 ++++++++++++++++++++++++++++++++++++++++ TODO | 2 +- 4 files changed, 130 insertions(+), 120 deletions(-) create mode 100644 README-install diff --git a/Makefile.am b/Makefile.am index 733b32214f..346ed36740 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,6 +24,7 @@ EXTRA_DIST = \ .prev-version \ .version \ .vg-suppressions \ + README-install \ THANKS.in \ THANKS-to-translators \ THANKStt.in \ diff --git a/README b/README index a18fcf611d..954c8190c8 100644 --- a/README +++ b/README @@ -21,7 +21,8 @@ See the file NEWS for a list of major changes in the current release. If you obtained this file as part of a "git clone", then see the README-hacking file. If this file came to you as part of a tar archive, -then see the file INSTALL for compilation and installation instructions. +then see the file INSTALL for general compilation and installation +instructions, or README-install for system and coreutils specific instructions. Like the rest of the GNU system, these programs mostly conform to POSIX, with BSD and other extensions. For closer conformance, or @@ -57,97 +58,17 @@ files (man/*.x) are welcome. However, the authoritative documentation is in texinfo form in the doc directory. -********************* -Pre-C99 build failure ---------------------- - -In 2009 we added this requirement: -To build the coreutils from source, you must have a C99-conforming -compiler, due to the use of declarations after non-declaration statements -in several files in src/. There is code in configure to find and, if -possible, enable an appropriate compiler. However, if configure doesn't -find a C99 compiler, it continues nonetheless, and your build will fail. -There used to be a "c99-to-c89.diff" patch you could apply to convert -to code that even an old pre-c99 compiler can handle, but it was too -tedious to maintain, so has been removed. - - -*********************** -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 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: - ---- /usr/include/inttypes.h.orig Thu May 30 01:00:00 1996 -+++ /usr/include/inttypes.h Sun Mar 23 00:20:36 2003 -@@ -489 +489 @@ --#ifndef __STDC_32_MODE__ -+#ifndef __LP64__ - - -************************ -OSF/1 4.0d and AIX build failures ------------------------- - -If you use /usr/bin/make on these systems, the build will fail due -to the presence of the "[" target. OSF/1 make(1) appears to -treat "[" as some syntax relating to locks, while AIX make(1) -appears to skip the "[" target. To work around these issues -the best solution is to use GNU make. Otherwise, simply remove -all mention of "[$(EXEEXT)" from src/Makefile. - - -************************ -32 bit time_t build failures ------------------------- - -On systems where it's determined that 64 bit time_t is supported -(indicated by touch -t ), but that coreutils -would be built with a narrower time_t, the build will fail. -This can be allowed by passing TIME_T_32_BIT_OK=yes to configure, -or avoided by enabling 64 bit builds. For example GCC on AIX defaults -to 32 bit, and to enable the 64 bit ABI one can use: -./configure CFLAGS=-maix64 LDFLAGs=-maix64 AR='ar -X64' - - -************************************************* -"make check" failure on IRIX 6.5 and Solaris <= 9 -------------------------------------------------- - -Using the vendor make program to run "make check" fails on these two systems. -If you want to run all of the tests there, use GNU make. - - - -********************** -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 -the NON_ROOT_USERNAME environment variable. Depending on the -permissions with which the working directories have been created, -using 'nobody' may fail, because that user won't have the required -read and write access to the build and test directories. -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 PATH="$PATH" NON_ROOT_USERNAME=$USER make -k check-root +*************** +Feature requests: +--------------- -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. +If you would like to add a new feature, please try to get some sort of +consensus that it is a worthwhile change. One way to do that is to send +mail to coreutils@gnu.org including as much description and justification +as you can. Based on the feedback that generates, you may be able to +convince us that it's worth adding. Please also consult the list of +previously discussed but ultimately rejected feature requests at: +https://www.gnu.org/software/coreutils/rejected_requests.html *************** @@ -157,6 +78,10 @@ Reporting bugs: Send bug reports, questions, comments, etc. to bug-coreutils@gnu.org. To suggest a patch, see the files README-hacking and HACKING for tips. +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. + If you have a problem with 'sort', try running 'sort --debug', as it can often help find and fix problems without having to wait for an answer to a bug report. If the debug output does not suffice to fix @@ -181,7 +106,7 @@ 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 -it -- it won't bother me to get a reminder. Besides, the more messages I +it -- it won't bother us to get a reminder. Besides, the more messages we get regarding a particular problem the sooner it'll be fixed -- usually. If you sent a complete patch and, after a couple weeks you haven't received any acknowledgement, please ping us. A complete patch includes @@ -195,30 +120,6 @@ Here are instructions for checking out the latest development sources: https://savannah.gnu.org/git/?group=coreutils -If your patch adds a new feature, please try to get some sort of consensus -that it is a worthwhile change. One way to do that is to send mail to -coreutils@gnu.org including as much description and justification -as you can. Based on the feedback that generates, you may be able to -convince us that it's worth adding. Please also consult the list of -previously discussed but ultimately rejected feature requests at: -https://www.gnu.org/software/coreutils/rejected_requests.html - - -WARNING: Now that we use the ./bootstrap script, you should not run -autoreconf manually. Doing that will overwrite essential source files -with older versions, which may make the package unbuildable or introduce -subtle bugs. - - -WARNING: If you modify files like configure.in, m4/*.m4, aclocal.m4, -or any Makefile.am, then don't be surprised if what gets regenerated no -longer works. To make things work, you'll have to be using appropriate -versions of the tools listed in bootstrap.conf's buildreq string. - -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 at: https://www.gnu.org/prep/standards/ @@ -226,9 +127,6 @@ https://www.gnu.org/prep/standards/ For any copyright year range specified as YYYY-ZZZZ in this package note that the range specifies every single year in that closed interval. -Mail suggestions and bug reports for these programs to -the address on the last line of --help output. - ======================================================================== diff --git a/README-install b/README-install new file mode 100644 index 0000000000..0c5bcf4706 --- /dev/null +++ b/README-install @@ -0,0 +1,111 @@ +Please see the file INSTALL for generic build and installation instructions. +This file details coreutils and system specific build instructions. + + +********************* +Pre-C99 build failure +--------------------- + +In 2009 we added this requirement: +To build the coreutils from source, you must have a C99-conforming +compiler, due to the use of declarations after non-declaration statements +in several files in src/. There is code in configure to find and, if +possible, enable an appropriate compiler. However, if configure doesn't +find a C99 compiler, it continues nonetheless, and your build will fail. +There used to be a "c99-to-c89.diff" patch you could apply to convert +to code that even an old pre-c99 compiler can handle, but it was too +tedious to maintain, so has been removed. + + +*********************** +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 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: + +--- /usr/include/inttypes.h.orig Thu May 30 01:00:00 1996 ++++ /usr/include/inttypes.h Sun Mar 23 00:20:36 2003 +@@ -489 +489 @@ +-#ifndef __STDC_32_MODE__ ++#ifndef __LP64__ + + +************************ +OSF/1 4.0d and AIX build failures +------------------------ + +If you use /usr/bin/make on these systems, the build will fail due +to the presence of the "[" target. OSF/1 make(1) appears to +treat "[" as some syntax relating to locks, while AIX make(1) +appears to skip the "[" target. To work around these issues +the best solution is to use GNU make. Otherwise, simply remove +all mention of "[$(EXEEXT)" from src/Makefile. + + +************************ +32 bit time_t build failures +------------------------ + +On systems where it's determined that 64 bit time_t is supported +(indicated by touch -t ), but that coreutils +would be built with a narrower time_t, the build will fail. +This can be allowed by passing TIME_T_32_BIT_OK=yes to configure, +or avoided by enabling 64 bit builds. For example GCC on AIX defaults +to 32 bit, and to enable the 64 bit ABI one can use: +./configure CFLAGS=-maix64 LDFLAGs=-maix64 AR='ar -X64' + + +************************************************* +"make check" failure on IRIX 6.5 and Solaris <= 9 +------------------------------------------------- + +Using the vendor make program to run "make check" fails on these two systems. +If you want to run all of the tests there, use GNU make. + + + +********************** +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 +the NON_ROOT_USERNAME environment variable. Depending on the +permissions with which the working directories have been created, +using 'nobody' may fail, because that user won't have the required +read and write access to the build and test directories. +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 PATH="$PATH" NON_ROOT_USERNAME=$USER make -k check-root + +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. + + + +********************** +autotools considerations: +---------------------- + +WARNING: Now that we use the ./bootstrap script, you should not run +autoreconf manually. Doing that will overwrite essential source files +with older versions, which may make the package unbuildable or introduce +subtle bugs. + +WARNING: If you modify files like configure.in, m4/*.m4, aclocal.m4, +or any Makefile.am, then don't be surprised if what gets regenerated no +longer works. To make things work, you'll have to be using appropriate +versions of the tools listed in bootstrap.conf's buildreq string. diff --git a/TODO b/TODO index e1348f0f17..6c141b6448 100644 --- a/TODO +++ b/TODO @@ -49,7 +49,7 @@ no longer incurs the overhead of saving src. dev/ino and dest. filename in the hash table. Write an autoconf test to work around build failure in HPUX's 64-bit mode. -See notes in README -- and remove them once there's a work-around. +See notes in README-install -- and remove them once there's a work-around. Integrate use of sendfile, suggested here: https://lists.gnu.org/r/bug-fileutils/2003-03/msg00030.html -- 2.47.2