Trunk is now identical to Testing

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

6 files changed, 271 insertions, 4 deletions

diff --git a/chapter04/aboutlfs.xml b/chapter04/aboutlfs.xml
index 2c270a08a..64f20f1b4 100644
--- a/chapter04/aboutlfs.xml
+++ b/chapter04/aboutlfs.xml
@@ -7,6 +7,29 @@
 <title>About $LFS</title>
 <?dbhtml filename="aboutlfs.html"?>
 
-<para>See testing</para>
+<para>Throughout this book, the environment variable <envar>LFS</envar> will
+be used several times. It is paramount that this variable is always defined.
+It should be set to the mount point chosen for the LFS partition.
+Check that the <envar>LFS</envar> variable is set up properly with:</para>
+
+<screen><userinput>echo $LFS</userinput></screen>
+
+<para>Make sure the output shows the path to the LFS partition's mount
+point, which is <filename class="directory">/mnt/lfs</filename> if the
+provided example was followed. If the output is incorrect, the
+variable can be set with:</para>
+
+<screen><userinput>export LFS=/mnt/lfs</userinput></screen>
+
+<para>Having this variable set is beneficial in that commands such as
+<command>mkdir $LFS/tools</command> can be typed literally. The shell
+will automatically replace <quote>$LFS</quote> with
+<quote>/mnt/lfs</quote> (or whatever the variable was set to) when it
+processes the command line.</para>
+
+<para>Do not forget to check that <envar>$LFS</envar> is set whenever
+you leave and reenter the current working environment (as when doing a
+<quote>su</quote> to <emphasis>root</emphasis> or another user).</para>
 
 </sect1>
+
diff --git a/chapter04/aboutsbus.xml b/chapter04/aboutsbus.xml
index d99ac1f0f..34e1a1ef4 100644
--- a/chapter04/aboutsbus.xml
+++ b/chapter04/aboutsbus.xml
@@ -7,6 +7,44 @@
 <title>About SBUs</title>
 <?dbhtml filename="aboutsbus.html"?>
 
-<para>See testing</para>
+<para>Many people would like to know beforehand approximately how long
+it takes to compile and install each package. Because Linux From
+Scratch can be built on many different systems, it is impossible to
+provide accurate time estimates.  The biggest package (Glibc) will
+take approximately 20 minutes on the fastest systems, but could take
+up to three days on slower systems! Instead of providing actual times,
+the Static Build Unit (SBU) measure will be
+used instead.</para>
+
+<para>The SBU measure works as follows. The first package to be compiled
+from this book is the statically-linked Binutils in <xref
+linkend="chapter-temporary-tools"/>.  The time it takes to compile
+this package is what will be referred to as the Static Build Unit
+or SBU. All other compile times will be expressed relative to this
+time.</para>
+
+<para>For example, consider a package whose compilation time is 4.5
+SBUs. This means that if a system took 10 minutes to compile and
+install the static Binutils, it will take
+<emphasis>approximately</emphasis> 45 minutes to build this example
+package. Fortunately, most build times are shorter than the one
+for Binutils.</para>
+
+<para>Please note that if the system compiler on the host is GCC-2.x based, the
+SBUs listed may be somewhat understated. This is because the SBU is
+based on the very first package, compiled with the old GCC, while the
+rest of the system is compiled with the newer GCC-&gcc-version; (which is
+known to be approximately 30 percent slower). SBUs are also not
+highly accurate for Symmetric Multi-Processor (SMP)-based machines.</para>
+
+<para>To view actual timings for a number of specific machines, we recommend
+<ulink url="&lfs-root;~bdubbs/"/>.</para>
+
+<para>In general, SBUs are not very accurate because they depend on many
+factors, not just the GCC version. They are provided
+here to give an estimate of how long it might take to
+install a package, but the numbers can vary by as much as dozens of
+minutes in some cases.</para>
 
 </sect1>
+
diff --git a/chapter04/abouttestsuites.xml b/chapter04/abouttestsuites.xml
index cfa1b9705..82ca9b062 100644
--- a/chapter04/abouttestsuites.xml
+++ b/chapter04/abouttestsuites.xml
@@ -7,6 +7,44 @@
 <title>About the Test Suites</title>
 <?dbhtml filename="abouttestsuites.html"?>
 
-<para>See testing</para>
+<para>Most packages provide a test suite. Running the test suite for a
+newly built package is a good idea because it can provide a <quote>sanity
+check</quote> indicating that everything compiled correctly. A test suite
+that passes its set of checks usually proves that the package is
+functioning as the developer intended. It does not, however, guarantee
+that the package is totally bug free.</para>
+
+<para>Some test suites are more important than others. For example,
+the test suites for the core toolchain packages&mdash;GCC, Binutils, and
+Glibc&mdash;are of the utmost importance due to their central role in a
+properly functioning system. The test suites for GCC and Glibc can
+take a very long time to complete, especially on slower hardware, but
+are strongly recommended.</para>
+
+<note><para>Experience has shown that there is little to be gained
+from running the test suites in <xref
+linkend="chapter-temporary-tools"/>. There can be no escaping the fact
+that the host system always exerts some influence on the tests in that
+chapter, often causing inexplicable failures. Because the tools built
+in <xref linkend="chapter-temporary-tools"/> are temporary and
+eventually discarded, we do not recommend running the test suites in
+<xref linkend="chapter-temporary-tools"/> for the average reader. The
+instructions for running those test suites are provided for the
+benefit of testers and developers, but they are strictly
+optional.</para></note>
+
+<para>A common issue with running the test suites for Binutils and GCC
+is running out of pseudo terminals (PTYs). This can result in a high
+number of failing tests. This may happen for several reasons, but the
+most likely cause is that the host system does not have the
+<systemitem class="filesystem">devpts</systemitem> file system set up 
+correctly. This issue is discussed in greater detail in <xref
+linkend="chapter-temporary-tools"/>.</para>
+
+<para>Sometimes package test suites will give false failures. Consult
+the LFS Wiki at <ulink url="&wiki-root;"/> to verify that these
+failures are expected. This site is valid for all tests throughout this
+book.</para>
 
 </sect1>
+
diff --git a/chapter04/addinguser.xml b/chapter04/addinguser.xml
index 5073eac68..d701566ba 100644
--- a/chapter04/addinguser.xml
+++ b/chapter04/addinguser.xml
@@ -7,17 +7,85 @@
 <title>Adding the LFS User</title>
 <?dbhtml filename="addinguser.html"?>
 
-<para>Issue the following commands to add the new user:</para>
+<para>When logged in as user <emphasis>root</emphasis>, making a
+single mistake can damage or destroy a system. Therefore, we recommend
+building the packages in this chapter as an unprivileged user. You
+could use your own user name, but to make it easier to set up a clean
+work environment, create a new user called <emphasis>lfs</emphasis> as
+a member of a new group (also named <emphasis>lfs</emphasis>) and use
+this user during the installation process. As
+<emphasis>root</emphasis>, issue the following commands to add the new
+user:</para>
 
 <screen><userinput>groupadd lfs
 useradd -s /bin/bash -g lfs -m -k /dev/null lfs</userinput></screen>
 
+<para>The meaning of the command line options:</para>
+
+<variablelist>
+<varlistentry>
+<term><parameter>-s /bin/bash</parameter></term>
+<listitem><para>This makes
+<command>bash</command> the default shell for user
+<emphasis>lfs</emphasis>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>-g lfs</parameter></term>
+<listitem><para>This option adds user <emphasis>lfs</emphasis> to group
+<emphasis>lfs</emphasis>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>-m</parameter></term>
+<listitem><para>This creates a home
+directory for <emphasis>lfs</emphasis>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>-k /dev/null</parameter></term>
+<listitem><para>This parameter
+prevents possible copying of files from a skeleton directory (default
+is <filename class="directory">/etc/skel</filename>) by changing the input location to
+the special null device.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><parameter>lfs</parameter></term>
+<listitem><para>This is the actual name for the created group and
+user.</para></listitem>
+</varlistentry>
+</variablelist>
+
+<para>To log in as <emphasis>lfs</emphasis> (as opposed to switching
+to user <emphasis>lfs</emphasis> when
+logged in as <emphasis>root</emphasis>, which does not require the
+<emphasis>lfs</emphasis> user to have a
+password), give <emphasis>lfs</emphasis> a password:</para>
+
 <screen><userinput>passwd lfs</userinput></screen>
 
+<para>Grant <emphasis>lfs</emphasis> full access to
+<filename class="directory">$LFS/tools</filename> by making
+<emphasis>lfs</emphasis> the directory owner:</para>
+
 <screen><userinput>chown lfs $LFS/tools</userinput></screen>
 
+<para>If a separate working directory was created as suggested, give
+user <emphasis>lfs</emphasis> ownership of this directory:</para>
+
 <screen><userinput>chown lfs $LFS/sources</userinput></screen>
 
+<para>Next, login as user <emphasis>lfs</emphasis>. This can be done
+via a virtual console, through a display manager, or with the
+following substitute user command:</para>
+
 <screen><userinput>su - lfs</userinput></screen>
 
+<para>The <quote><parameter>-</parameter></quote> instructs
+<command>su</command> to start a login shell as opposed to a non-login
+shell. The difference between these two types of shells can be found
+in detail in the Bash man and info pages.</para>
+
 </sect1>
+
diff --git a/chapter04/creatingtoolsdir.xml b/chapter04/creatingtoolsdir.xml
index 36e4fe7a4..8ab7fde3a 100644
--- a/chapter04/creatingtoolsdir.xml
+++ b/chapter04/creatingtoolsdir.xml
@@ -7,8 +7,40 @@
 <title>Creating the $LFS/tools Directory</title>
 <?dbhtml filename="creatingtoolsdir.html"?>
 
+<para>All programs compiled in <xref
+linkend="chapter-temporary-tools"/> will be installed under <filename
+class="directory">$LFS/tools</filename> to keep them separate from the
+programs compiled in <xref linkend="chapter-building-system"/>. The
+programs compiled here are temporary tools and will not be a part of
+the final LFS system.  By keeping these programs in a separate
+directory, they can easily be discarded later after their use. This
+also prevents these programs from ending up in the host production
+directories (easy to do by accident in <xref
+linkend="chapter-temporary-tools"/>).</para>
+
+<para>Create the required directory by running the following as
+<emphasis>root</emphasis>:</para>
+
 <screen><userinput>mkdir $LFS/tools</userinput></screen>
 
+<para>The next step is to create a <filename class="symlink">/tools</filename> 
+symlink on the host system.  This will point to the newly-created directory on
+the LFS partition. Run this command as <emphasis>root</emphasis> as
+well:</para>
+
 <screen><userinput>ln -s $LFS/tools /</userinput></screen>
 
+<note><para>The above command is correct. The <command>ln</command>
+command has a few syntactic variations, so be sure to check the info
+and man pages before reporting what you may think is an
+error.</para></note>
+
+<para>The created symlink enables the toolchain to be compiled so that
+it always refers to <filename class="directory">/tools</filename>,
+meaning that the compiler, assembler, and linker will work both in
+this chapter (when we are still using some tools from the host) and in
+the next (when we are <quote>chrooted</quote> to the LFS
+partition).</para>
+
 </sect1>
+
diff --git a/chapter04/settingenviron.xml b/chapter04/settingenviron.xml
index ea2672707..247b55e96 100644
--- a/chapter04/settingenviron.xml
+++ b/chapter04/settingenviron.xml
@@ -7,10 +7,35 @@
 <title>Setting Up the Environment</title>
 <?dbhtml filename="settingenvironment.html"?>
 
+<para>Set up a good working environment by creating two new startup
+files for the <command>bash</command> shell. While logged in as user
+<emphasis>lfs</emphasis>, issue the
+following command to create a new <filename>.bash_profile</filename>:</para>
+
 <screen><userinput>cat &gt; ~/.bash_profile &lt;&lt; "EOF"
 <literal>exec env -i HOME=$HOME TERM=$TERM PS1='\u:\w\$ ' /bin/bash</literal>
 EOF</userinput></screen>
 
+<para>When logged on as user <emphasis>lfs</emphasis>, the
+initial shell is usually a <emphasis>login</emphasis> shell which reads the
+<filename>/etc/profile</filename> of the host (probably containing
+some settings and environment variables) and then
+<filename>.bash_profile</filename>. The <command>exec env
+-i.../bin/bash</command> command in the
+<filename>.bash_profile</filename> file replaces the running shell
+with a new one with a completely empty environment, except for the
+<envar>HOME</envar>, <envar>TERM</envar>, and
+<envar>PS1</envar> variables. This ensures that no unwanted and
+potentially hazardous environment variables from the host system leak
+into the build environment. The technique used here achieves the goal
+of ensuring a clean environment.</para>
+
+<para>The new instance of the shell is a <emphasis>non-login</emphasis>
+shell, which does not read the <filename>/etc/profile</filename> or
+<filename>.bash_profile</filename> files, but rather reads the
+<filename>.bashrc</filename> file instead. Create the
+<filename>.bashrc</filename> file now:</para>
+
 <screen><userinput>cat &gt; ~/.bashrc &lt;&lt; "EOF"
 <literal>set +h
 umask 022
@@ -20,6 +45,49 @@ PATH=/tools/bin:/bin:/usr/bin
 export LFS LC_ALL PATH</literal>
 EOF</userinput></screen>
 
+<para>The <command>set +h</command> command turns off
+<command>bash</command>'s hash function. Hashing is ordinarily a useful 
+feature&mdash;<command>bash</command> uses a hash table to remember the
+full path of executable files to avoid searching the <envar>PATH</envar> time
+and again to find the same executable. However, the new tools
+should be used as soon as they are installed. By switching off the
+hash function, the shell will always search the <envar>PATH</envar> when a program is
+to be run. As such, the shell will find the newly compiled
+tools in <filename class="directory">$LFS/tools</filename> as soon as
+they are available without remembering a previous version of the same
+program in a different location.</para>
+
+<para>Setting the user file-creation mask (umask) to 022 ensures that newly
+created files and directories are only writable by their owner, but
+are readable and executable by anyone (assuming default modes are used
+by the open(2) system call, new files will end up with permission mode
+644 and directories with mode 755).</para>
+
+<para>The <envar>LFS</envar> variable should be set to the
+chosen mount point.</para>
+
+<para>The <envar>LC_ALL</envar> variable controls the
+localization of certain programs, making their messages follow the
+conventions of a specified country.  If the host system uses a version
+of Glibc older than 2.2.4, having <envar>LC_ALL</envar> set to something other than
+<quote>POSIX</quote> or <quote>C</quote> (during this chapter) may
+cause issues if you exit the chroot environment and wish to return
+later. Setting <envar>LC_ALL</envar> to <quote>POSIX</quote>
+or <quote>C</quote> (the two are equivalent) ensures that
+everything will work as expected in the chroot environment.</para>
+
+<para>By putting <filename class="directory">/tools/bin</filename>
+ahead of the standard <envar>PATH</envar>, all the programs installed in <xref
+linkend="chapter-temporary-tools"/> are picked up by the shell
+immediately after their installation. This, combined with turning off 
+hashing, limits the risk that old programs from
+the host are being used when they should not be used any
+longer.</para>
+
+<para>Finally, to have the environment fully prepared for building the
+temporary tools, source the just-created user profile:</para>
+
 <screen><userinput>source ~/.bash_profile</userinput></screen>
 
 </sect1>
+