Merging caption and installation sections for all packages in chapters 5 and 6.

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

1 files changed, 169 insertions, 1 deletions

diff --git a/chapter05/glibc.xml b/chapter05/glibc.xml
index 1a2fa38aa..3077438b4 100644
--- a/chapter05/glibc.xml
+++ b/chapter05/glibc.xml
@@ -7,7 +7,175 @@ Estimated required disk space:  &glibc-compsize-tools;</screen>
 
 &aa-glibc-shortdesc;
 &aa-glibc-dep;
-&c5-glibc-inst;
+
+<sect2><title>&nbsp;</title><para>&nbsp;</para></sect2>
+
+<sect2>
+<title>Glibc installation</title>
+
+<para>Before starting to install Glibc, you must <userinput>cd</userinput>
+into the <filename>glibc-&glibc-version;</filename> directory and unpack
+Glibc-linuxthreads in that directory, not in the directory where you usually
+unpack all the sources.</para>
+
+<note><para>We are going to run the test suite for Glibc in this chapter.
+However, it's worth pointing out that running the Glibc test suite here
+is considered not as important as running it in
+<xref linkend="chapter06"/>.</para></note>
+
+<para>This package is known to behave badly when you have changed its
+default optimization flags (including the -march and -mcpu options).
+Therefore, if you have defined any environment variables that override
+default optimizations, such as CFLAGS and CXXFLAGS, we recommend unsetting
+them when building Glibc.</para>
+
+<para>Basically, compiling Glibc in any other way than the book suggests
+is putting the stability of your system at risk.</para>
+
+<para>Though it is a harmless message, the install stage of Glibc will
+complain about the absence of <filename>/tools/etc/ld.so.conf</filename>.
+Fix this annoying little warning with:</para>
+
+<screen><userinput>mkdir /tools/etc
+touch /tools/etc/ld.so.conf</userinput></screen>
+
+<para>Also, Glibc has a subtle problem when compiled with GCC &gcc-version;.
+Apply the following patch to fix this:</para>
+
+<screen><userinput>patch -Np1 -i ../&glibc-sscanf-patch;</userinput></screen>
+
+<para>The Glibc documentation recommends building Glibc outside of the source
+directory in a dedicated build directory:</para>
+
+<screen><userinput>mkdir ../glibc-build
+cd ../glibc-build</userinput></screen>
+
+<para>Next, prepare Glibc to be compiled:</para>
+
+<screen><userinput>../glibc-&glibc-version;/configure --prefix=/tools \
+&nbsp;&nbsp;&nbsp;&nbsp;--disable-profile --enable-add-ons \
+&nbsp;&nbsp;&nbsp;&nbsp;--with-headers=/tools/include \
+&nbsp;&nbsp;&nbsp;&nbsp;--with-binutils=/tools/bin \
+&nbsp;&nbsp;&nbsp;&nbsp;--without-gd</userinput></screen>
+
+<para>The meaning of the configure options:</para>
+
+<itemizedlist>
+<listitem><para><userinput>--disable-profile</userinput>: This disables the
+building of the libraries with profiling information. Omit this option if you
+plan to do profiling.</para></listitem>
+
+<listitem><para><userinput>--enable-add-ons</userinput>: This enables any
+add-ons that were installed with Glibc, in our case Linuxthreads.</para></listitem>
+
+<listitem><para><userinput>--with-binutils=/tools/bin</userinput> and
+<userinput>--with-headers=/tools/include</userinput>: Strictly speaking
+these switches are not required. But they ensure nothing can go wrong with
+regard to what kernel headers and Binutils programs get used during the
+Glibc build.</para></listitem>
+
+<listitem><para><userinput> --without-gd</userinput>: This switch ensures
+that we don't build the <userinput>memusagestat</userinput> program, which
+strangely enough insists on linking against the host's libraries (libgd,
+libpng, libz, and so forth).</para></listitem>
+</itemizedlist>
+
+<para>During this stage you might see the following warning:</para>
+
+<blockquote><screen>configure: WARNING:
+*** These auxiliary programs are missing or incompatible versions: msgfmt
+*** some features will be disabled.
+*** Check the INSTALL file for required versions.</screen></blockquote>
+
+<para>The missing or incompatible <filename>msgfmt</filename> program is
+generally harmless, but it's believed it can sometimes cause problems when
+running the test suite.</para>
+
+<para>Compile the package:</para>
+
+<screen><userinput>make</userinput></screen>
+
+<para>Run the test suite:</para>
+
+<screen><userinput>make check</userinput></screen>
+
+<para>The Glibc test suite is highly dependent on certain functions of your host
+system, in particular the kernel. Additionally, here in this chapter 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 <xref linkend="chapter06"/>. 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 <emphasis>math</emphasis> tests sometimes fail when running
+on systems where the CPU is not a relatively new genuine Intel or authentic AMD.
+Certain optimization settings are also known to be a factor here.</para></listitem>
+
+<listitem><para>The <emphasis>gettext</emphasis> test sometimes fails due to
+host system issues. The exact reasons are not yet clear.</para></listitem>
+
+<listitem><para>The <emphasis>atime</emphasis> test sometimes fails when the
+LFS partition is mounted with the <emphasis>noatime</emphasis> option, or due
+to other file system quirks.</para></listitem>
+
+<listitem><para>The <emphasis>shm</emphasis> test might fail when the host
+system is running the devfs file system but doesn't have the tmpfs file system
+mounted at <filename>/dev/shm</filename> due to lack of support for tmpfs in
+the kernel.</para></listitem>
+
+<listitem><para>When running on older and slower hardware, some tests might
+fail due to test timeouts being exceeded.</para></listitem>
+</itemizedlist>
+
+<para>In summary, don't worry too much if you see Glibc test suite failures
+here in this chapter. The Glibc in <xref linkend="chapter06"/> is the one we'll
+ultimately end up using so that is the one we would really like to see pass.
+But please keep in mind, even in <xref linkend="chapter06"/> some failures
+could still occur -- the <emphasis>math</emphasis>
+tests for example. When experiencing a failure, make a note of it, then
+continue 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 peruse the log
+file and examine the total number of failures.</para>
+
+<para>Now install the package:</para>
+
+<screen><userinput>make install</userinput></screen>
+
+<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. The "internationalization" of GNU programs works by means of
+<emphasis>locales</emphasis>. We'll install the Glibc locales now:</para>
+
+<screen><userinput>make localedata/install-locales</userinput></screen>
+
+<para>An alternative to running the previous command is to install only
+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> source. However, there are a number
+of locales that are essential for the tests of future packages to pass, in
+particular, the <emphasis>libstdc++</emphasis> tests from GCC.  The following
+instructions, instead of the install-locales target above, will install
+the minimum set of locales necessary for the tests to run successfully:</para>
+
+<screen><userinput>mkdir -p /tools/lib/locale
+localedef -i de_DE -f ISO-8859-1 de_DE
+localedef -i de_DE@euro -f ISO-8859-15 de_DE@euro
+localedef -i en_HK -f ISO-8859-1 en_HK
+localedef -i en_PH -f ISO-8859-1 en_PH
+localedef -i en_US -f ISO-8859-1 en_US
+localedef -i es_MX -f ISO-8859-1 es_MX
+localedef -i fr_FR -f ISO-8859-1 fr_FR
+localedef -i fr_FR@euro -f ISO-8859-15 fr_FR@euro
+localedef -i it_IT -f ISO-8859-1 it_IT
+localedef -i ja_JP -f EUC-JP ja_JP</userinput></screen>
+
+</sect2>
 
 </sect1>