Rearrange "How things are going to be done" section. Simplify seds in "Locking in Glibc" and "Re-adjusting the toolchain" sections. Miscellaneous other fixes.

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

chapter01/changelog.xml

@@ -95,6 +95,10 @@
 </itemizedlist>
 </para></listitem>
 
+<listitem><para>October 6th, 2003 [greg]: Simplify seds in "Locking in Glibc"
+and "Re-adjusting the toolchain" sections. Rearrange "How things are going to be
+done" section.</para></listitem>
+
 <listitem><para>October 5th, 2003 [greg]: Chapter 5: Add new section "Toolchain
 technical notes". Integrate and scale back the old "Why we use static linking"
 section. Closes Bug 658.</para></listitem>

chapter01/how.xml

@@ -9,15 +9,15 @@ programs like a compiler, linker and shell to build the new system. Normally
 all the required tools are available if you selected <quote>development</quote>
 as one of the options when you installed your distribution.</para>
 
-<para>In Chapter 3 you will first create a new Linux native partition and
-filesystem, the place where your new LFS system will be compiled and installed.
-Then in Chapter 4 you download all the packages and patches required to build
-an LFS system, and store them on the new filesystem.</para>
+<para>In Chapter 3 you will first create a new Linux native partition and file
+system, the place where your new LFS system will be compiled and installed. Then
+in Chapter 4 you download all the packages and patches required to build an LFS
+system, and store them on the new file system.</para>
 
-<para>Chapter 5 will then discuss the installation of a number of packages that 
-will form the basic development suite (or tool-set) which is used to build the 
-actual system in Chapter 6. Some of these packages are needed to resolve 
-circular dependencies. For example, to compile a compiler you need a 
+<para>Chapter 5 will then discuss the installation of a number of packages that
+will form the basic development suite (or toolchain) which is used to build the
+actual system in Chapter 6. Some of these packages are needed to resolve
+circular dependencies. For example, to compile a compiler you need a
 compiler.</para>
 
 <para>The first thing to be done in Chapter 5 is build a first pass of the 
@@ -25,35 +25,17 @@ toolchain, which is made up of Binutils and GCC. The programs from these
 packages will be linked statically in order for them to be used independently 
 of the host system. The second thing to do is build Glibc, the C library. Glibc 
 will be compiled by the toolchain programs we just built in the first 
-pass.</para>
+pass. The third thing to do is build a second pass of the toolchain. This time
+the toolchain will be dynamically linked against the newly built Glibc. The
+remaining Chapter 5 packages are all built using this second pass toolchain and
+dynamically linked against the new host-independent Glibc. When this is done,
+the LFS installation process will no longer depend on the host distribution,
+with the exception of the running kernel.</para>
 
-<para>The third thing to do is build a second pass of the toolchain. This time 
-the toolchain will be dynamically linked against the newly built Glibc. The 
-remaining Chapter 5 packages are all built using this second pass toolchain and 
-dynamically linked against the new host-independent Glibc. When this is done, 
-the LFS installation process will no longer depend on the host distribution, 
-with the exception of the running kernel. This is known as <quote>self 
-contained</quote> and <quote>self hosted</quote>. There is a discussion of the 
-differences between statically and dynamically linked programs at the beginning 
-of Chapter 5.</para>
-
-<para>You may be asking yourself <quote>that seems like a lot of work, just to 
-get away from my host distribution</quote>. Let us take a few minutes to 
-discuss this question. The work involved in building the packages in Chapter 5 
-is to ensure that as little information as possible from your host makes it into
-your brand new LFS system. When you build the first two packages in Chapter 5,
-Binutils and GCC, they will be compiled statically.  This means that the 
-version of the C library on your host distribution will be embedded inside all 
-the binary programs you just compiled. This has the potential to cause
-problems for you down the road. The host's Glibc is usually an unknown
-quantity and might even contain bugs or anything else we don't know about 
-until it is too late. A well known issue is that statically linked binaries 
-compiled on a Glibc-2.2.x based system that contain calls to the
-<emphasis>getpwuid()</emphasis> function crash when run on a Glibc-2.3.x based
-system. Seeing as we are about to build a Glibc-2.3.x based system, we need to
-shield ourselves from problems of this nature. The procedure employed in
-Chapter 5 achieves this goal. With all these things in mind, you can see that
-the extra effort to compile Binutils and GCC twice is well worth it.</para>
+<para>You may be asking yourself <quote>that seems like a lot of work, just to
+get away from my host distribution?</quote>. A full technical and in-depth
+explanation is provided at the start of Chapter 5, including some notes on the
+differences between statically and dynamically linked programs.</para>
 
 <para>In Chapter 6 your real LFS system will be built. The chroot (change root) 
 program is used to enter a virtual environment and start a new shell whose root 

chapter05/gcc-pass2-inst.xml

@@ -155,7 +155,7 @@ to continue on.</para>
 <note><para>At this point it is strongly recommended to repeat the sanity check
 we performed earlier in the chapter. Refer back to the "Locking in" Glibc section
 and repeat the check. If the results are wrong then most likely, you forgot to
-apply the abovementioned GCC Specs patch.</para></note>
+apply the above mentioned GCC Specs patch.</para></note>
 
 </sect2>
 

chapter05/lockingglibc.xml

@@ -23,16 +23,20 @@ Binutils build and source directories.</para>
 to the new dynamic linker. A simple sed will accomplish this:</para>
    
 <para><screen><userinput>SPECFILE=/tools/lib/gcc-lib/*/*/specs
-sed -e 's@/lib/ld.so.1@/tools/lib/ld.so.1@g' \
-&nbsp;&nbsp;&nbsp;&nbsp;-e 's@/lib/ld-linux.so.2@/tools/lib/ld-linux.so.2@g' \
+sed -e 's@/lib/ld-linux.so.2@/tools/lib/ld-linux.so.2@g' \
 &nbsp;&nbsp;&nbsp;&nbsp;$SPECFILE > tempspecfile
 mv tempspecfile $SPECFILE
 unset SPECFILE</userinput></screen></para>
 
-<para>We recommend that you cut-and-paste the above rather than try and type it 
-all in. Or you can edit the specs file by hand if you want to: just replace 
-"/lib/ld-linux.so.2" with "/tools/lib/ld-linux.so.2" and "/lib/ld.so.1" with 
-"/tools/lib/ld.so.1".</para>
+<para>We recommend that you cut-and-paste the above rather than try and type it
+all in. Or you can edit the specs file by hand if you want to: just replace any
+occurrence of "/lib/ld-linux.so.2" with "/tools/lib/ld-linux.so.2".</para>
+
+<important><para>If you are working on a platform where the name of the dynamic
+linker is something other than <filename>ld-linux.so.2</filename>, you
+<emphasis>must</emphasis> substitute <filename>ld-linux.so.2</filename> with the
+name of your platform's dynamic linker in the above commands. Refer back to the
+"Toolchain technical notes" section if necessary.</para></important>
 
 <para>Lastly, there is a possibility that some include files from the host
 system have found their way into GCC's private include dir. This can happen

chapter05/toolchaintechnotes.xml

@@ -122,8 +122,8 @@ adjusted ld, which has a hard-wired search path limited to
 file to point to our new dynamic linker in
 <filename class="directory">/tools/lib</filename>. This last step is
 <emphasis>vital</emphasis> to the whole process. As mentioned above, a
-hard-wired path to a dynamic linker is embedded into every executable binary.
-You can inspect this by running:
+hard-wired path to a dynamic linker is embedded into every ELF shared
+executable. You can inspect this by running:
 <userinput>`readelf -l &lt;name of binary&gt; | grep interpreter`</userinput>.
 By amending the GCC specs file, we are ensuring that every program compiled from
 here through the end of Chapter 5 will use our new dynamic linker in

chapter06/adjustingtoolchain.xml

@@ -17,8 +17,8 @@ adjusted linker by running the following from within the
 <note><para>If you somehow missed the earlier warning to retain the Binutils
 source and build directories from the second pass in Chapter 5 or otherwise
 accidentally deleted them or just don't have access to them, don't worry, all is
-not lost. Just ignore this step. The result will be that the next package,
-Binutils, will link against the Glibc libraries in
+not lost. Just ignore the above command. The result will be that the next
+package, Binutils, will link against the Glibc libraries in
 <filename class="directory">/tools</filename> rather than
 <filename class="directory">/usr</filename>. This is not ideal, however, our
 testing has shown that the resulting Binutils program binaries should be
@@ -41,8 +41,7 @@ to the new dynamic linker. Just like earlier on, we use a sed to accomplish
 this:</para>
 
 <para><screen><userinput>SPECFILE=/tools/lib/gcc-lib/*/*/specs
-sed -e 's@/tools/lib/ld.so.1@/lib/ld.so.1@g' \
-&nbsp;&nbsp;&nbsp;&nbsp;-e 's@/tools/lib/ld-linux.so.2@/lib/ld-linux.so.2@g' \
+sed -e 's@/tools/lib/ld-linux.so.2@/lib/ld-linux.so.2@g' \
 &nbsp;&nbsp;&nbsp;&nbsp;$SPECFILE > newspecfile
 mv newspecfile $SPECFILE
 unset SPECFILE</userinput></screen></para>
@@ -51,6 +50,12 @@ unset SPECFILE</userinput></screen></para>
 before, it is a good idea to check the specs file to ensure the intended
 changes were actually made.</para>
 
+<important><para>If you are working on a platform where the name of the dynamic
+linker is something other than <filename>ld-linux.so.2</filename>, you
+<emphasis>must</emphasis> substitute <filename>ld-linux.so.2</filename> with the
+name of your platform's dynamic linker in the above commands. Refer back to the
+"Toolchain technical notes" section if necessary.</para></important>
+
 <caution><para>It is imperative at this point to stop and ensure that the
 basic functions (compiling and linking) of the adjusted toolchain are working
 as expected. For this we are going to perform a simple sanity check:</para>

chapter06/gcc-inst.xml

@@ -24,7 +24,9 @@ compilers. Instructions for building these can be found at
 patch -Np1 -i ../gcc-&gcc-suppress-libiberty-patch-version;.patch</userinput></screen></para>
 
 <para>The second patch here suppresses the installation of libiberty from GCC,
-as we will use the one provided by binutils instead.</para>
+as we will use the one provided by binutils instead. Be careful
+<emphasis>not</emphasis> to apply the GCC specs patch from Chapter 5
+here.</para>
 
 <para>The GCC documentation recommends building GCC outside of the source
 directory in a dedicated build directory:</para>

index.xml

@@ -3,8 +3,8 @@
 				"/usr/share/docbook/docbookx.dtd" [
 
 
-<!ENTITY version "20031006">
-<!ENTITY releasedate "October 6th, 2003">
+<!ENTITY version "20031007">
+<!ENTITY releasedate "October 7th, 2003">
 <!ENTITY nbsp " ">
 
 <!ENTITY ftp-root "ftp://ftp.linuxfromscratch.org">