Making the test suites in chapter 5 more clearly optional.

git-svn-id: http://svn.linuxfromscratch.org/LFS/trunk/BOOK@3248 4aa44e1e-78dd-0310-a6d2-fbcd4c07a689

appendixa/expect-shortdesc.xml

@@ -4,7 +4,7 @@
 
 <para><emphasis>Installed program</emphasis>: expect</para>
 
-<para><emphasis>Installed library</emphasis>: libexpect5.39.a</para>
+<para><emphasis>Installed library</emphasis>: libexpect&expect-version;.a</para>
 
 </sect2>
 

chapter02/abouttestsuites.xml

@@ -5,37 +5,36 @@
 <para>Most packages provide a test suite. Running the test suite for a newly
 built package is generally a good idea, as it can provide a nice sanity check
 that everything compiled correctly. A test suite that passes its set of checks
-usually proves that the package is functioning mostly as the developer
+usually proves that the package is functioning as the developer intended. It
-intended. It does not, however, guarantee that the package is totally bug
+does not, however, guarantee that the package is totally bug free.</para>
-free.</para>
 
 <para>Some test suites are more important than others. For example, the test
-suites for the core toolchain packages -- GCC, Binutils, and Glibc (the C
+suites for the core toolchain packages -- GCC, Binutils, and Glibc -- are of
-library) -- are of the utmost importance due to their central role in a
+the utmost importance due to their central role in a properly functioning
-properly functioning system. But be warned, the test suites for GCC and Glibc
+system. But be warned, the test suites for GCC and Glibc can take a very long
-can take a very long time to complete, especially on slower hardware.</para>
+time to complete, especially on slower hardware.</para>
 
-<para>Experience has shown us that there is little to be gained from running
+<note><para>Experience has shown us that there is little to be gained from running
-the test suites in <xref linkend="chapter-temporary-tools"/>. There can be no escaping the
+the test suites in <xref linkend="chapter-temporary-tools"/>. There can be no
-fact that the host system always exerts influence on the tests in that chapter,
+escaping the fact that the host system always exerts some influence on the
-often causing weird and inexplicable failures. Not only that, the tools built
+tests in that chapter, often causing weird and inexplicable failures. Not only
-in <xref linkend="chapter-temporary-tools"/> are temporary and eventually discarded. For the
+that, the tools built in <xref linkend="chapter-temporary-tools"/> are
-average reader of this book we recommend <emphasis>not</emphasis> to run the
+temporary and eventually discarded. For the average reader of this book we
-test suites in <xref linkend="chapter-temporary-tools"/>. The instructions for running those
+recommend <emphasis>not</emphasis> to run the test suites in <xref
-test suites are still provided for the benefit of testers and developers, but
+linkend="chapter-temporary-tools"/>. The instructions for running those test
-they are strictly optional for everyone else.</para>
+suites are still provided for the benefit of testers and developers, but they
+are strictly optional for everyone else.</para></note>
 
-<para>As you progress through the book and encounter the commands to run the
+<para>A common problem when running the test suites for Binutils and GCC is
-various test suites, we'll guide you on the relative importance of the test
+running out of pseudo terminals (PTYs for short). The symptom is a very high
-suite in question, so that you can decide for yourself whether to run that one
+number of failing tests. This can happen for several reasons, but the most
-or not.</para>
+likely cause is that the host system doesn't have the
-
-<note><para>A common problem when running the test suites for Binutils and GCC
-is running out of pseudo terminals (PTYs for short). The symptom is an
-unusually high number of failing tests. This can happen for a number of
-reasons. Most likely is that the host system doesn't have the
 <emphasis>devpts</emphasis> file system set up correctly. We'll discuss this in
-more detail later on in <xref linkend="chapter-temporary-tools"/>.</para></note>
+more detail later on in <xref linkend="chapter-temporary-tools"/>.</para>
+
+<para>Sometimes package test suites will give false failures. You can
+consult the LFS Wiki at <ulink url="&wiki-root;"/> to verify that these
+failures are normal. This applies to all tests throughout the book.</para>
 
 </sect1>
 

chapter04/chapter04.xml

@@ -167,7 +167,7 @@ M4 (&m4-version;) - &m4-size;:
 <ulink url="http://freshmeat.net/projects/gnum4/"/>
 
 Make (&make-version;) - &make-size;:
-<ulink url="http://freshmeat.net/projects/gnumake"/>
+<ulink url="http://freshmeat.net/projects/gnumake/"/>
 
 Make_devices (&makedev-version;) - &makedev-size;:
 <ulink url="&lfs-root;~alex/make_devices-&makedev-version;.bz2"/>

chapter05/bash.xml

@@ -26,11 +26,8 @@ patch:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Bash test
+<userinput>make tests</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make tests</userinput></screen>
 
 <para>Then install it and its documentation:</para>
 

chapter05/coreutils.xml

@@ -18,14 +18,15 @@ And for the patch:
 <title>Installation of Coreutils</title>
 
 <para>Coreutils has an issue when compiled against Glibc-&glibc-version;.
-Without the patch below, some of the Coreutils utilities (head, tail, sort etc)
+Without the patch below, some of the Coreutils utilities
-will reject their traditional syntax which has been in use for approximately 30
+(<command>head</command>, <command>tail</command>, <command>sort</command>,
-years. The old syntax is so pervasive that compatibility must be preserved until
+and others) will reject their traditional syntax which has been in use for
-the many places where it is used can be updated. More details are provided in
+approximately 30 years. This old syntax is so pervasive that compatibility
-the comments inside the patch itself. Use of this patch is by no means
+should be preserved until the many places where it is used can be updated.
-compulsory but opting not to use it means you'll have deal with the consequences
+More details on this are provided in the comments inside the patch itself. Use
-yourself, i.e. patch the many software packages that use the old syntax. Apply
+of this patch is by no means compulsory, but not using it means you'll have to
-the patch:</para>
+deal with the consequences yourself: patch the many packages that use the old
+syntax. Therefore, better apply the patch:</para>
 
 <screen><userinput>patch -Np1 -i ../&coreutils-posixver-patch;</userinput></screen>
 
@@ -37,20 +38,11 @@ the patch:</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Coreutils
+<userinput>make RUN_EXPENSIVE_TESTS=yes check</userinput>. The
-test suite anyway, the following command will do so:</para>
+<emphasis>RUN_EXPENSIVE_TESTS=yes</emphasis> parameter tells the test suite to
-
+run several additional tests that are considered relatively expensive on some
-<screen><userinput>make RUN_EXPENSIVE_TESTS=yes check</userinput></screen>
+platforms but generally are not a problem on Linux.)</para>
-
-<para>The meaning of the make parameter:</para>
-
-<itemizedlist>
-<listitem><para><userinput>RUN_EXPENSIVE_TESTS=yes</userinput>: This tells the
-test suite to run several additional tests that are considered relatively
-expensive on some platforms. However, they are generally not a problem on
-Linux.</para></listitem>
-</itemizedlist>
 
 <para>And install the package:</para>
 

chapter05/expect.xml

@@ -44,16 +44,13 @@ libraries, both of which may possibly reside on the host system.</para></listite
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Expect test
+<userinput>make test</userinput>. However, the Expect test suite is known to
-suite anyway, the following command will do so. However, you should be aware
+experience failures under certain host conditions that are not fully
-that the Expect test suite is sometimes known to experience failures under
+understood. Therefore, test suite failures here are not surprising, and are not
-certain host conditions that are not fully understood. Therefore, test suite
+considered critical.)</para>
-failures here are not surprising, but are not considered critical:</para>
 
-<screen><userinput>make test</userinput></screen>
+<para>And install it:</para>
-
-<para>And install:</para>
 
 <screen><userinput>make SCRIPTS="" install</userinput></screen>
 

chapter05/findutils.xml

@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Findutils
+<userinput>make check</userinput>.)</para>
-test suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>And install the package:</para>
 

chapter05/gawk.xml

@@ -23,11 +23,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Gawk test
+<userinput>make check</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>And install it:</para>
 

chapter05/gettext.xml

@@ -21,16 +21,12 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue: <userinput>make
-temporary tools here in this chapter. If you still want to run the Gettext test
+check</userinput>. This takes a very long time, around 6 SBUs. Moreover, the
-suite anyway, the following command will do so. However, you should be aware
+Gettext test suite is known to experience failures under certain host
-that the Gettext test suite is known to experience failures under certain host
+conditions -- for example when it finds a Java compiler on the host (but an
-conditions -- for example, when it finds a Java compiler on the host (Note: an
+experimental patch to disable Java is available from the LFS Patches
-experimental patch to disable Java is available from the patches project). Not
+project).)</para>
-only that, the Gettext test suite takes an excessive amount of time to run and
-is not considered critical:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>And install the package:</para>
 

chapter05/grep.xml

@@ -34,11 +34,8 @@ use the code from Glibc, which is known to be slightly buggy.</para></listitem>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Grep test
+<userinput>make check</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>Then install them and their documentation:</para>
 

chapter05/kernelheaders.xml

@@ -38,7 +38,7 @@ symlink:</para>
 cp include/asm/* /tools/include/asm
 cp -R include/asm-generic /tools/include</userinput></screen>
 
-<para>Install the cross-platform kernel header files:</para>
+<para>And finally install the cross-platform kernel header files:</para>
 
 <screen><userinput>cp -R include/linux /tools/include</userinput></screen>
 

chapter05/make.xml

@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Make test
+<userinput>make check</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>Then install it and its documentation:</para>
 

chapter05/patch.xml

@@ -13,13 +13,12 @@
 <sect2>
 <title>Installation of Patch</title>
 
-<para>Prepare Patch for compilation:</para>
+<para>Prepare Patch for compilation (the preprocessor flag
+<emphasis>-D_GNU_SOURCE</emphasis> is only needed on the PowerPC platform, on
+other architectures you can leave it out):</para>
 
 <screen><userinput>CPPFLAGS=-D_GNU_SOURCE ./configure --prefix=/tools</userinput></screen>
 
-<para>The preprocessor flag <emphasis>-D_GNU_SOURCE</emphasis> is only needed
-on the PowerPC platform. On other architectures you can leave it out.</para>
-
 <para>Compile the program:</para>
 
 <screen><userinput>make</userinput></screen>

chapter05/sed.xml

@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Sed test
+<userinput>make check</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>Then install it and its documentation:</para>
 

chapter05/tar.xml

@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Tar test
+<userinput>make check</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>Then install them and their documentation:</para>
 

chapter05/tcl.xml

@@ -32,28 +32,15 @@ chapter.</para>
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Tcl test
+<userinput>TZ=UTC make test</userinput>. However, the Tcl test suite is known
-suite anyway, the following command will do so. However, you should be aware
+to experience failures under certain host conditions that are not fully
-that the Tcl test suite is sometimes known to experience failures under certain
+understood. Therefore, test suite failures here are not surprising, and are not
-host conditions that are not fully understood. Therefore, test suite failures
+considered critical. The <emphasis>TZ=UTC</emphasis> parameter sets the time
-here are not surprising, but are not considered critical:</para>
+zone to Coordinated Universal Time (UTC) also known as Greenwich Mean Time
-
+(GMT), but only for the duration of the test suite run. This ensures the clock
-<screen><userinput>TZ=UTC make test</userinput></screen>
+tests are exercised correctly. More information on the TZ environment variable
-
+will be given later on in <xref linkend="chapter-bootscripts"/>.)</para>
-<para>The meaning of the make parameter:</para>
-
-<itemizedlist>
-<listitem><para><userinput>TZ=UTC</userinput>: This sets the time zone to
-Coordinated Universal Time (UTC) also known as Greenwich Mean Time (GMT), but
-only for the duration of the test suite run. This ensures the clock tests are
-exercised correctly. More information on the TZ environment variable will be
-given later on in <xref linkend="chapter-bootscripts"/>.</para></listitem>
-</itemizedlist>
-
-<para>Sometimes package test suites will give false failures. You can
-consult the LFS Wiki at <ulink url="&wiki-root;"/> to verify that these
-failures are normal. This applies to all tests throughout the book.</para>
 
 <para>Install the package:</para>
 
@@ -69,7 +56,7 @@ will need its internal headers.</para></warning>
 <!-- HACK - Force some whitespace to appease tidy -->
 <literallayout></literallayout>
 
-<para>Make a necessary symbolic link:</para>
+<para>And make a necessary symbolic link:</para>
 
 <screen><userinput>ln -s tclsh8.4 /tools/bin/tclsh</userinput></screen>
 

chapter05/texinfo.xml

@@ -21,11 +21,8 @@
 
 <screen><userinput>make</userinput></screen>
 
-<para>As discussed earlier, we don't recommend running the test suites for the
+<para>(If you insist on testing the results, then issue:
-temporary tools here in this chapter. If you still want to run the Texinfo test
+<userinput>make check</userinput>.)</para>
-suite anyway, the following command will do so:</para>
-
-<screen><userinput>make check</userinput></screen>
 
 <para>Then install them and their documentation:</para>