cross-ng: chapter 7: adjust introduction for cross build

chapter02/stages.xml

@@ -64,31 +64,16 @@
 
     <itemizedlist>
       <listitem>
-         <para>The /mnt/lfs partition must be mounted.</para>
+        <para>You must boot the temporary system on the target machine.</para>
       </listitem>
 
       <listitem>
-        <para>A few operations, from <quote>Changing Ownership</quote> to
+        <para>A few operations, from
-        <quote>Entering the Chroot Environment</quote> must be done as the
+        <quote>Preparing Virtual Kernel File Systems</quote> to
-        <systemitem class="username">root</systemitem> user, with the LFS
+        <quote>Setting up Environment</quote> must be done as the
-        environment variable set for the
+        <systemitem class="username">root</systemitem> user.</para>
-        <systemitem class="username">root</systemitem>user.</para>
       </listitem>
 
-      <listitem>
-         <para> When entering chroot, the LFS environment variable must be set
-         for <systemitem class="username">root</systemitem>. The LFS
-         variable is not used afterwards.</para>
-      </listitem>
-
-      <listitem>
-         <para> The virtual file systems must be mounted.  This can be done
-         before or after entering chroot by changing to a host virtual terminal
-         and, as <systemitem class="username">root</systemitem>, running the
-         commands in
-         <xref linkend='ch-tools-bindmount'/> and
-         <xref linkend='ch-tools-kernfsmount'/>.</para>
-      </listitem>
     </itemizedlist>
   </sect2>
 </sect1>

chapter07/chapter07.xml

@@ -9,10 +9,10 @@
   <?dbhtml dir="chapter07"?>
   <?dbhtml filename="chapter07.html"?>
 
-  <title>Entering Chroot and Building Additional Temporary Tools</title>
+  <title>Booting the Target System and Building Additional Temporary Tools</title>
 
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml"/>
-  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="changingowner.xml"/>
+  <!--xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="changingowner.xml"/-->
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="kernfs.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="chroot.xml"/>
   <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="creatingdirs.xml"/>

chapter07/chroot.xml

@@ -6,45 +6,58 @@
 ]>
 
 <sect1 id="ch-tools-chroot">
-  <?dbhtml filename="chroot.html"?>
+  <?dbhtml filename="env.html"?>
 
-  <title>Entering the Chroot Environment</title>
+  <title>Setting up the Environment</title>
 
-  <para>Now that all the packages which are required to build the rest of the
+    <para>The standard I/O streams of the initial shell process is connected
-  needed tools are on the system, it is time to enter the chroot environment to
+    with <filename>/dev/console</filename>.  However, the testsuite of some
-  finish installing the remaining temporary tools. This environment will be in
+    packages may expect the standard I/O streams to be connected with a
-  use also for installing the final system. As user <systemitem
+    <quote>real</quote> TTY device node.  Spawn a new shell process on the
-  class="username">root</systemitem>, run the following command to enter the
+    TTY device with <command>agetty</command>:</para>
-  environment that is, at the moment, populated with only the temporary
-  tools:</para>
 
-<screen role="nodump"><userinput>chroot "$LFS" /usr/bin/env -i   \
+<screen role="nodump"><userinput>agetty -n -l /bin/bash <replaceable>tty0</replaceable></userinput></screen>
+
+    <para>If you are working via a serial console, replace
+    <replaceable>tty0</replaceable> with the name of the serial console
+    device node, for example <literal>ttyS0</literal>.</para>
+
+    <para>The command above spawns a new shell process on the TTY device
+    specified in the command, and the initial shell process will run in
+    background as an init process with very limited functions. The new shell
+    process will output:</para>
+
+<screen role="nodump"><computeroutput>bash: cannot set terminal process group (-1): Inappropriate ioctl for device
+bash: no job control in this shell</computeroutput></screen>
+
+    <para>This is normal because the shell is not assigned with a
+    controlling terminal yet.  Now set up controlling terminal and
+    environment variables:</para>
+
+<screen><userinput>exec setsid -c /usr/bin/env -i  \
     HOME=/root                  \
     TERM="$TERM"                \
-    PS1='(lfs chroot) \u:\w\$ ' \
+    PS1='(lfs) \u:\w\$ '        \
     PATH=/usr/bin:/usr/sbin     \
     /bin/bash --login</userinput></screen>
 
+    <para>The command replace the current shell process with a new shell
+    process, with controlling terminal set up.</para>
+
   <para>The <parameter>-i</parameter> option given to the <command>env</command>
-  command will clear all variables of the chroot environment. After that, only
+  command will clear all variables of the environment. After that, only
   the <envar>HOME</envar>, <envar>TERM</envar>, <envar>PS1</envar>, and
   <envar>PATH</envar> variables are set again. The
   <parameter>TERM=$TERM</parameter> construct will set the <envar>TERM</envar>
-  variable inside chroot to the same value as outside chroot. This variable is
+  variable to the default value specified by <command>agetty</command>. This variable is
   needed for programs like <command>vim</command> and <command>less</command>
   to operate properly.  If other variables are desired, such as
   <envar>CFLAGS</envar> or <envar>CXXFLAGS</envar>, this is a good place to set
   them again.</para>
 
-  <para>From this point on, there is no need to use the
-  <envar>LFS</envar> variable anymore because all work will be restricted
-  to the LFS file system.  This is because the Bash shell is told that
-  <filename class="directory">$LFS</filename> is now the root
-  (<filename class="directory">/</filename>) directory.</para>
-
   <para>Notice that <filename class="directory">/tools/bin</filename> is not
   in the <envar>PATH</envar>. This means that the cross toolchain will no longer be
-  used in the chroot environment.</para>
+  used on the target machine.</para>
 
   <para>Note that the <command>bash</command> prompt will say
   <computeroutput>I have no name!</computeroutput> This is normal because the
@@ -52,12 +65,12 @@
 
   <note>
     <para>It is important that all the commands throughout the remainder of this
-    chapter and the following chapters are run from within the chroot
+    chapter and the following chapters are run from within the environment
-    environment. If you leave this environment for any reason (rebooting for
+    we've set. If you leave this environment for any reason (rebooting for
     example), ensure that the virtual kernel filesystems are mounted as
-    explained in <xref linkend="ch-tools-bindmount"/> and <xref
+    explained in <xref linkend="ch-tools-kernfsmount"/> and
-    linkend="ch-tools-kernfsmount"/> and enter chroot again before continuing
+    <xref linkend="ch-tools-devadjust"/> and set up the environment again before
-    with the installation.</para>
+    continuing with the installation.</para>
   </note>
 
 </sect1>

chapter07/introduction.xml

@@ -12,21 +12,21 @@
 
   <para>This chapter shows how to build the last missing bits of the temporary
   system: the tools needed by the build machinery of various packages.  Now
-  that all circular dependencies have been resolved, a <quote>chroot</quote>
+  that all circular dependencies have been resolved and the temporary system
-  environment, completely isolated from the host operating system (except for
+  is already bootable, we can boot it on the target machine and it would be
-  the running kernel), can be used for the build.</para>
+  completely isolated from the host operating system.  Then we can continue
+  to build on the target machine.</para>
 
-  <para>For proper operation of the isolated environment, some communication
+  <para>For proper operation of the temporary system, some communication
   with the running kernel must be established. This is done through the
   so-called <emphasis>Virtual Kernel File Systems</emphasis>, which must be
-  mounted when entering the chroot environment. You may want to check
+  mounted as soon as possible after boot. You may want to check
-  that they are mounted by issuing <command>findmnt</command>.</para>
+  that they are mounted by issuing <command>mount</command>.</para>
 
-  <para>Until <xref linkend="ch-tools-chroot"/>, the commands must be
+  <para>All commands in this and following chapters are run as root on the
-  run as <systemitem class="username">root</systemitem>, with the
+  target system, fortunately without access to the host system.
-  <envar>LFS</envar> variable set. After entering chroot, all commands
+  Be careful anyway, as if the storage devices of your target system already
-  are run as root, fortunately without access to the OS of the computer
+  contain some important data, it's possible to destroy them with badly
-  you built LFS on. Be careful anyway, as it is easy to destroy the whole
+  formed commands.</para>
-  LFS system with badly formed commands.</para>
 
 </sect1>

chapter07/kernfs.xml

@@ -22,58 +22,22 @@
     <para>Begin by creating directories onto which the file systems will be
     mounted:</para>
 
-<screen><userinput>mkdir -pv $LFS/{dev,proc,sys,run}</userinput></screen>
+<screen><userinput>mkdir -pv /{proc,sys,run}</userinput></screen>
-
-  <sect2>
-    <title>Creating Initial Device Nodes</title>
-
-    <para>When the kernel boots the system, it requires the presence of a few
-    device nodes, in particular the <filename
-    class="devicefile">console</filename> and <filename
-    class="devicefile">null</filename> devices. The device nodes must be
-    created on the hard disk so that they are available before the kernel
-    populates <systemitem class="filesystem">/dev</systemitem>), and
-    additionally when Linux is started with
-    <parameter>init=/bin/bash</parameter>. Create the devices by running the
-    following commands:</para>
-
-<screen><userinput>mknod -m 600 $LFS/dev/console c 5 1
-mknod -m 666 $LFS/dev/null c 1 3</userinput></screen>
-
-  </sect2>
-
-  <sect2 id="ch-tools-bindmount">
-    <title>Mounting and Populating /dev</title>
-
-      <para>The recommended method of populating the <filename
-      class="directory">/dev</filename> directory with devices is to mount a
-      virtual filesystem (such as <systemitem
-      class="filesystem">tmpfs</systemitem>) on the <filename
-      class="directory">/dev</filename> directory, and allow the devices to be
-      created dynamically on that virtual filesystem as they are detected or
-      accessed. Device creation is generally done during the boot process
-      by Udev. Since this new system does not yet have Udev and has not yet
-      been booted, it is necessary to mount and populate <filename
-      class="directory">/dev</filename> manually. This is accomplished by bind
-      mounting the host system's <filename class="directory">/dev</filename>
-      directory. A bind mount is a special type of mount that allows you to
-      create a mirror of a directory or mount point to some other location. Use
-      the following command to achieve this:</para>
-
-<screen><userinput>mount -v --bind /dev $LFS/dev</userinput></screen>
-
-  </sect2>
 
   <sect2 id="ch-tools-kernfsmount">
     <title>Mounting Virtual Kernel File Systems</title>
 
-      <para>Now mount the remaining virtual kernel filesystems:</para>
+    <para>The kernel has already mounted
+    <systemitem class="filesystem">devtmpfs</systemitem>.
+    Mount the remaining virtual kernel filesystems:</para>
+
+<screen><userinput>mkdir -pv /dev/{pts,shm}
+mount -vt devpts /dev/pts /dev/pts -o gid=5,mode=620
+mount -vt proc  proc  /proc
+mount -vt sysfs sysfs /sys
+mount -vt tmpfs tmpfs /run
+mount -vt tmpfs tmpfs /dev/shm</userinput></screen>
 
-<screen><userinput>mount -v --bind /dev/pts $LFS/dev/pts
-mount -vt proc proc $LFS/proc
-mount -vt sysfs sysfs $LFS/sys
-mount -vt tmpfs tmpfs $LFS/run</userinput></screen>
-<!--
     <variablelist>
       <title>The meaning of the mount options for devpts:</title>
 
@@ -101,15 +65,23 @@ mount -vt tmpfs tmpfs $LFS/run</userinput></screen>
       </varlistentry>
 
     </variablelist>
--->
-      <para>In some host systems, <filename>/dev/shm</filename> is a
-      symbolic link to <filename class="directory">/run/shm</filename>.
-      The /run tmpfs was mounted above so in this case only a
-      directory needs to be created.</para>
 
-<screen><userinput>if [ -h $LFS/dev/shm ]; then
+  </sect2>
-  mkdir -pv $LFS/$(readlink $LFS/dev/shm)
+
-fi</userinput></screen>
+  <sect2 id="ch-tools-devadjust">
+    <title>Adjusting devtmpfs</title>
+
+    <para>Now <systemitem class='filesystem'>proc</systemitem> filesystem
+    is mounted, we can replace the device nodes for standard I/O streams
+    with symlinks to pseudo files in
+    <filename class="directory">/proc/self/fd</filename> (which are symlinks
+    to the files connected to the standard I/O streams for the current
+    process).  This is necessary for I/O redirection in the building system
+    of some packages to function properly:</para>
+
+<screen><userinput>ln -sfv /proc/self/fd/0 /dev/stdin
+ln -sfv /proc/self/fd/1 /dev/stdout
+ln -sfv /proc/self/fd/2 /dev/stderr</userinput></screen>
 
   </sect2>