Chapter 5 - Glibc: Add notes regarding test suite issues.

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

5 files changed, 64 insertions, 20 deletions

diff --git a/chapter01/changelog.xml b/chapter01/changelog.xml
index 510e558a8..3ea1d1865 100644
--- a/chapter01/changelog.xml
+++ b/chapter01/changelog.xml
@@ -194,7 +194,7 @@ markup. Dropped the removal of program files from the Stripping section in
 Chapter 5.</para></listitem>
 
 <listitem><para>September 14th, 2003 [greg]: Chapter 6 - Create essential
-symlinks: Add symlink /usr/lib/libgcc_s.so.1 to allow gcc abi_check to run.
+symlinks: Add symlink /usr/lib/libgcc_s.so.1 to allow GCC abi_check to run.
 Future NPTL needs this as well.</para></listitem>
 
 <listitem><para>September 13th, 2003 [jwrober]: Added PLFS hint text to the 
@@ -299,7 +299,7 @@ wording to reflect the removal of the /usr/lib/cpp symlink.</para></listitem>
 <listitem><para>September 5th, 2003 [jeremy]: Corrected perl libc patch to -2,
 changing the old /stage1 structure to /tools</para></listitem>
 
-<listitem><para>September 5th, 2003 [matt]: Chapter 6 - Updated gcc specs patch
+<listitem><para>September 5th, 2003 [matt]: Chapter 6 - Updated GCC specs patch
 and upgraded to man-1.5m2</para></listitem>
 
 <listitem><para>September 4th, 2003 [jeremy]: Chapter 6 - Creating
diff --git a/chapter05/glibc-inst.xml b/chapter05/glibc-inst.xml
index 83b64eb69..4bae896d4 100644
--- a/chapter05/glibc-inst.xml
+++ b/chapter05/glibc-inst.xml
@@ -77,21 +77,65 @@ libpng, libz, and so forth).</para></listitem>
 *** Check the INSTALL file for required versions.</screen></blockquote>
 
 <para>The missing or incompatible <filename>msgfmt</filename> program is
-generally harmless and shouldn't cause us any problems.</para>
+generally harmless, but it's believed it can sometimes cause problems when
+running the test suite.</para>
 
-<para>Continue with compiling the package:</para>
+<para>Compile the package:</para>
 
-<para><screen><userinput>make
-make check
-make install</userinput></screen></para>
+<para><screen><userinput>make</userinput></screen></para>
 
-<para>The glibc make check process is highly dependent on certain functions
-of your host operating system.  The most common is a host that fails to mount
-a tmpfs filesystem at /dev/shm, which may cause glibc tests to fail.</para>
+<para>Run the test suite:</para>
 
-<para>The locales (used by Glibc to make your Linux system respond in a
-different language) weren't installed when you ran the previous command,
-so we have to do that ourselves now:</para>
+<para><screen><userinput>make check</userinput></screen></para>
+
+<para>The Glibc test suite is highly dependent on certain functions of your host
+system, in particular the kernel. Additionally, here in Chapter 5, some tests
+can be adversely affected by existing tools or environmental issues on the host
+system. Of course, these won't be a problem when we run the Glibc test suite
+inside the chroot environment of Chapter 6. In general, the Glibc test suite is
+always expected to pass. However, as mentioned above, some failures are
+unavoidable in certain circumstances. Here is a list of the most common issues
+we are aware of:</para>
+
+<itemizedlist>
+<listitem><para>The math tests sometimes fail when running on systems where the 
+CPU is not a relatively new genuine Intel or genuine AMD. Certain optimization
+settings are also known to be a factor here.</para></listitem>
+
+<listitem><para>The gettext test sometimes fails due to host system issues. The
+exact reasons are not yet clear.</para></listitem>
+
+<listitem><para>The atime test sometimes fails when the LFS parition is mounted
+with the noatime option or due to other file system quirks.</para></listitem>
+
+<listitem><para>In general, when running on slower hardware, some tests might
+fail due to test timeouts being exceeded.</para></listitem>
+
+<listitem><para>The shm test might fail in the circumstances of the host system
+running the devfs file system but not having the tmpfs filesystem mounted at
+/dev/shm due to lack of support for tmpfs in the kernel.</para></listitem>
+</itemizedlist>
+
+<para>In summary, don't worry too much if you see Glibc test suite failures here
+in Chapter 5. The Glibc in Chapter 6 is the one we'll ultimately end up using so
+that is the one we would really like to pass. But please keep in mind, even in
+Chapter 6 some failures could still occur, the math tests for example. When
+experiencing a failure, note the failure then continue on by reissuing the
+<userinput>make check</userinput>. The test suite should pick up where it left
+off and continue on. You can circumvent this stop-start sequence by issuing a
+<userinput>make -k check</userinput>. But If you do that, be sure to log the
+output so that you can later on peruse the log file and examine the total number
+of failures.</para>
+
+<para>Now install the package:</para>
+
+<para><screen><userinput>make install</userinput></screen></para>
+
+<para>Different countries and cultures have varying conventions for how to
+communicate. These conventions range from very simple ones, such as the format
+for representing dates and times, to very complex ones, such as the language
+spoken. This "internationalization" works by means of locales. We'll install the
+Glibc locales now:</para>
 
 <para><screen><userinput>make localedata/install-locales</userinput></screen></para>
 
@@ -99,10 +143,10 @@ so we have to do that ourselves now:</para>
 those locales which you need or want. This can be achieved by using the
 <userinput>localedef</userinput> command. Information on this can be
 found in the <filename>INSTALL</filename> file in the
-<filename>glibc-&glibc-version;</filename> tree. However, there are a
+<filename>glibc-&glibc-version;</filename> source. However, there are a
 number of locales that are essential for the tests of future packages
 to pass correctly, in particular, the libstdc++ tests from GCC.  The following 
-instructions, in place of the install-locales command above, will install 
+instructions, instead of the install-locales command above, will install 
 the minimum set of locales necessary for the tests to run successfully:</para>
 
 <para><screen><userinput>mkdir -p /tools/lib/locale
diff --git a/chapter06/aboutdebug.xml b/chapter06/aboutdebug.xml
index 141bc93d9..e8e179b09 100644
--- a/chapter06/aboutdebug.xml
+++ b/chapter06/aboutdebug.xml
@@ -21,10 +21,10 @@ with debugging symbols: 1200 KB</para></listitem>
 <listitem><para>a bash binary
 without debugging symbols: 480 KB</para></listitem>
 
-<listitem><para>glibc and gcc files (/lib and /usr/lib)
+<listitem><para>Glibc and GCC files (/lib and /usr/lib)
 with debugging symbols: 87 MB</para></listitem>
 
-<listitem><para>glibc and gcc files
+<listitem><para>Glibc and GCC files
 without debugging symbols: 16 MB</para></listitem>
 
 </itemizedlist>
diff --git a/chapter06/kernel-exp-headers.xml b/chapter06/kernel-exp-headers.xml
index 699c67d8c..9829fe2c9 100644
--- a/chapter06/kernel-exp-headers.xml
+++ b/chapter06/kernel-exp-headers.xml
@@ -17,7 +17,7 @@ post by Linus Torvalds to the Linux Kernel Mailing List points out:</para>
 
 And yes, this is what I do. My /usr/src/linux still has the old 2.2.13 
 header files, even though I haven't run a 2.2.13 kernel in a _loong_ 
-time. But those headers were what glibc was compiled against, so those 
+time. But those headers were what Glibc was compiled against, so those 
 headers are what matches the library object files. 
 
 And this is actually what has been the suggested environment for at 
@@ -28,7 +28,7 @@ sources should go into "/usr/src/linux" even though that hasn't been
 true in a _loong_ time.</screen>
 
 <para>The essential part is where Linus states that the header files should be
-<emphasis>the ones which glibc was compiled against</emphasis>. These are
+<emphasis>the ones which Glibc was compiled against</emphasis>. These are
 the headers that should be used when you later compile other packages, as they
 are the ones that match the object-code library files. By copying the headers,
 we ensure that they remain available if later you upgrade your kernel.</para>
diff --git a/chapter06/pwdgroup.xml b/chapter06/pwdgroup.xml
index bd565daf9..5b20f9b90 100644
--- a/chapter06/pwdgroup.xml
+++ b/chapter06/pwdgroup.xml
@@ -44,7 +44,7 @@ use the group's name.</para>
 <para>Lastly, we re-login to the chroot environment.  User name and group name
 resolution will start working immediately after the 
 <filename>/etc/passwd</filename> and <filename>/etc/group</filename> files are 
-created, because we installed a full glibc in Chapter 5.  This will get rid of 
+created, because we installed a full Glibc in Chapter 5.  This will get rid of 
 the <quote>I have no name!</quote> prompt.</para>
 
 <para><screen><userinput>exec /tools/bin/bash --login +h</userinput></screen></para>