diff options
Diffstat (limited to 'chapter05')
36 files changed, 1585 insertions, 181 deletions
diff --git a/chapter05/adjusting.xml b/chapter05/adjusting.xml index ac342fe87..834ef166f 100644 --- a/chapter05/adjusting.xml +++ b/chapter05/adjusting.xml @@ -7,12 +7,34 @@ <title>Adjusting the Toolchain</title> <?dbhtml filename="adjusting.html"?> -<para>Run the following command from within -the <filename class="directory">binutils-build</filename> directory:</para> +<para>Now that the temporary C libraries have been installed, all +tools compiled in the rest of this chapter should be linked against +these libraries. In order to accomplish this, the linker and the +compiler's specs file need to be adjusted.</para> + +<para>The linker, adjusted at the end of the first pass of Binutils, +is installed by running the following command from within the +<filename class="directory">binutils-build</filename> directory:</para> <screen><userinput>make -C ld install</userinput></screen> -<para>Amend the GCC specs file:</para> +<para>From this point onwards, everything will link only +against the libraries in <filename class="directory">/tools/lib</filename>.</para> + +<note><para>If the earlier warning to retain the Binutils source and +build directories from the first pass was missed, ignore the above +command. This results in a small chance that the subsequent testing +programs will link against libraries on the host. This is not ideal, +but it is not a major problem. The situation is corrected when the +second pass of Binutils is installed later.</para></note> + +<para>Now that the adjusted linker is installed, the Binutils build and source +directories should be removed.</para> + +<para>The next task is to amend the GCC specs file so that it points +to the new dynamic linker. A simple sed script will accomplish this:</para> + +<!-- Ampersands are needed to allow copy and paste --> <screen><userinput>SPECFILE=`gcc --print-file specs` && sed 's@ /lib/ld-linux.so.2@ /tools/lib/ld-linux.so.2@g' \ @@ -20,24 +42,71 @@ sed 's@ /lib/ld-linux.so.2@ /tools/lib/ld-linux.so.2@g' \ mv -f tempspecfile $SPECFILE && unset SPECFILE</userinput></screen> -<para>Make clean-up:</para> +<para><phrase condition="html">It is recommended that the above +command be copy-and-pasted in order to ensure accuracy.</phrase> +Alternatively, the specs file can be edited by hand. This is done by +replacing every occurrence of <quote>/lib/ld-linux.so.2</quote> with +<quote>/tools/lib/ld-linux.so.2</quote></para> + +<para>Be sure to visually inspect the specs file in order to verify the +intended changes have been made.</para> + +<important><para>If working on a platform where the name of the +dynamic linker is something other than +<filename class="libraryfile">ld-linux.so.2</filename>, replace +<quote>ld-linux.so.2</quote> with the name of the platform's +dynamic linker in the above commands. Refer back to <xref +linkend="ch-tools-toolchaintechnotes" role=","/> if +necessary.</para></important> + +<para>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 as a result of GCC's <quote>fixincludes</quote> process, which runs as part +of the GCC build. This is explained in more detail later in this +chapter. Run the following command to eliminate this +possibility:</para> <screen><userinput>rm -f /tools/lib/gcc/*/*/include/{pthread.h,bits/sigthread.h}</userinput></screen> -<para>Test the tools:</para> +<caution><para>At this point, it is imperative to stop and ensure that +the basic functions (compiling and linking) of the new toolchain are +working as expected. To perform a sanity check, run the following +commands:</para> <screen><userinput>echo 'main(){}' > dummy.c cc dummy.c readelf -l a.out | grep ': /tools'</userinput></screen> -<para>The output of the last command will be of the form:</para> +<para>If everything is working correctly, there should be no errors, +and the output of the last command will be of the form:</para> <screen><computeroutput>[Requesting program interpreter: /tools/lib/ld-linux.so.2]</computeroutput></screen> -<para>Remove the test files:</para> +<para>Note that <filename class="directory">/tools/lib</filename> +appears as the prefix of the dynamic linker.</para> -<screen><userinput>rm dummy.c a.out</userinput></screen> +<para>If the output is not shown as above or there was no output at +all, then something is wrong. Investigate and retrace the steps to +find out where the problem is and correct it. This issue must be +resolved before continuing on. First, perform the sanity check again, +using <command>gcc</command> instead of <command>cc</command>. If this +works, then the <filename class="symlink">/tools/bin/cc</filename> symlink is missing. +Revisit <xref linkend="ch-tools-gcc-pass1" role=","/> and install the symlink. +Next, ensure that the <envar>PATH</envar> is correct. This can be checked by running +<command>echo $PATH</command> and verifying that <filename +class="directory">/tools/bin</filename> is at the head of the list. If +the <envar>PATH</envar> is wrong it could mean that you are not logged in as user +<emphasis>lfs</emphasis> or that something went wrong back in <xref +linkend="ch-tools-settingenviron" role="."/> Another option is that something +may have gone wrong with the specs file amendment above. In this case, +redo the specs file amendment<phrase condition="html">, being careful to copy-and-paste the +commands</phrase>.</para> +<para>Once all is well, clean up the test files:</para> + +<screen><userinput>rm dummy.c a.out</userinput></screen> +</caution> </sect1> + diff --git a/chapter05/bash.xml b/chapter05/bash.xml index 62feb7904..930bd964a 100644 --- a/chapter05/bash.xml +++ b/chapter05/bash.xml @@ -7,8 +7,12 @@ <title>Bash-&bash-version;</title> <?dbhtml filename="bash.html"?> +<indexterm zone="ch-tools-bash"> +<primary sortas="a-Bash">Bash</primary> +<secondary>tools</secondary></indexterm> <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bash.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -16,12 +20,16 @@ <seglistitem><seg>1.2 SBU</seg><seg>27 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bash.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Bash</title> -<para>Apply a patch:</para> +<!-- Edit Me --> +<para>Bash has a problem when compiled against newer versions of Glibc, causing +it to hang inappropriately. This patch fixes the problem:</para> <screen><userinput>patch -Np1 -i ../bash-&bash-version;-avoid_WCONTINUED-1.patch</userinput></screen> @@ -29,21 +37,39 @@ <screen><userinput>./configure --prefix=/tools --without-bash-malloc</userinput></screen> -<para>Compile the program:</para> +<para>The meaning of the configure option:</para> + +<variablelist> +<varlistentry> +<term><parameter>--without-bash-malloc</parameter></term> +<listitem><para>This options turns off the use of Bash's memory +allocation (malloc) function which is known to cause segmentation +faults. By turning this option off, Bash will use the malloc functions +from Glibc which are more stable.</para></listitem> +</varlistentry> +</variablelist> + +<para>Compile the package:</para> <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make test</userinput>.</para> +<para>To test the results, issue: <userinput>make +tests</userinput>.</para> -<para>Then install it :</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> -<para>Create a symlink:</para> +<para>Make a link for the programs that use <command>sh</command> for +a shell:</para> <screen><userinput>ln -s bash /tools/bin/sh</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref linkend="contents-bash" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/binutils-pass1.xml b/chapter05/binutils-pass1.xml index 4dc8b3e1a..9f35ae722 100644 --- a/chapter05/binutils-pass1.xml +++ b/chapter05/binutils-pass1.xml @@ -7,7 +7,12 @@ <title>Binutils-&binutils-version; - Pass 1</title> <?dbhtml filename="binutils-pass1.html"?> +<indexterm zone="ch-tools-binutils-pass1"> +<primary sortas="a-Binutils">Binutils</primary> +<secondary>tools, pass 1</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/binutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,44 +20,134 @@ <seglistitem><seg>1.0 SBU</seg><seg>194 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/binutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Binutils</title> -<para>Create a build dir:</para> +<para>It is important that Binutils be the first package compiled +because both Glibc and GCC perform various tests on the available +linker and assembler to determine which of their own features to +enable.</para> + +<para>This package is known to have issues when its default +optimization flags (including the <parameter>-march</parameter> and +<parameter>-mcpu</parameter> options) are changed. If any environment +variables that override default optimizations have been defined, such +as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>, +unset them when building Binutils.</para> + +<para>The Binutils documentation recommends building Binutils outside of the +source directory in a dedicated build directory:</para> <screen><userinput>mkdir ../binutils-build cd ../binutils-build</userinput></screen> -<note><para>If you want the SBU values you could wrap the four commands in a -<command>time</command> command like this: -<userinput>time { ./configure ... && ... && ... -&& make install; }</userinput>.</para></note> +<note><para>In order for the SBU values listed in the rest of the book +to be of any use, measure the time it takes to build this package from +the configuration, up to and including the first install. To achieve +this easily, wrap the four commands in a <command>time</command> +command like this: <userinput>time { ./configure ... && ... +&& ... && make install; }</userinput>.</para></note> <para>Now prepare Binutils for compilation:</para> <screen><userinput>../binutils-&binutils-version;/configure --prefix=/tools \ --disable-nls</userinput></screen> +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--prefix=/tools</parameter></term> +<listitem><para>This tells the configure script to prepare to install the Binutils +programs in the <filename class="directory">/tools</filename> directory.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--disable-nls</parameter></term> +<listitem><para>This disables internationalization. This is not needed +for the static programs, and NLS can cause problems when linking +statically.</para></listitem> +</varlistentry> +</variablelist> + <para>Continue with compiling the package:</para> <screen><userinput>make configure-host make LDFLAGS="-all-static"</userinput></screen> -<para>Now install the package:</para> +<para>The meaning of the make parameters:</para> + +<variablelist> +<varlistentry> +<term><parameter>configure-host</parameter></term> +<listitem><para>This forces all subdirectories to be configured +immediately. A statically-linked build will fail without it. Use this +option to work around the problem.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>LDFLAGS="-all-static"</parameter></term> +<listitem><para>This tells the linker that all Binutils programs +should be linked statically. However, strictly speaking, +<parameter>"-all-static"</parameter> is passed to the +<command>libtool</command> program, which then passes +<parameter>"-static"</parameter> to the linker.</para></listitem> +</varlistentry> +</variablelist> + +<para>Compilation is now complete. Ordinarily we would now run the +test suite, but at this early stage the test suite framework (Tcl, +Expect, and DejaGNU) is not yet in place. The benefits of running the +tests at this point are minimal since the programs from this +first pass will soon be replaced by those from the second.</para> + +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> -<para>Now prepare the linker for the <quote>Adjusting</quote> phase later on:</para> +<para>Next, prepare the linker for the <quote>Adjusting</quote> phase +later on:</para> <screen><userinput>make -C ld clean make -C ld LDFLAGS="-all-static" LIB_PATH=/tools/lib</userinput></screen> -<warning><para><emphasis>Do not yet remove</emphasis> the Binutils build and -source directories. You will need them again in their current state a bit -further on in this chapter.</para></warning> +<para>The meaning of the make parameters:</para> + +<variablelist> +<varlistentry> +<term><parameter>-C ld clean</parameter></term> +<listitem><para>This tells the make program to remove all compiled +files in the <filename class="directory">ld</filename> +subdirectory.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>-C ld LDFLAGS="-all-static" +LIB_PATH=/tools/lib</parameter></term> +<listitem><para>This option rebuilds everything in the +<filename class="directory">ld</filename> subdirectory. Specifying +the <envar>LIB_PATH</envar> Makefile variable on the command +line allows us to override the default value +and point it to the temporary tools location. The value of this variable +specifies the linker's default library search path. This preparation +is used later in the chapter.</para></listitem> +</varlistentry> +</variablelist> + +<warning><para><emphasis>Do not</emphasis> remove the Binutils +build and source directories yet. These will be needed again in their +current state later in this chapter.</para></warning> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-binutils" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/binutils-pass2.xml b/chapter05/binutils-pass2.xml index 0c28271f7..85a574309 100644 --- a/chapter05/binutils-pass2.xml +++ b/chapter05/binutils-pass2.xml @@ -7,7 +7,14 @@ <title>Binutils-&binutils-version; - Pass 2</title> <?dbhtml filename="binutils-pass2.html"?> +<indexterm zone="ch-tools-binutils-pass2"> +<primary sortas="a-Binutils">Binutils</primary> +<secondary>tools, pass 2</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" + href="../chapter06/binutils.xml" + xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,39 +22,57 @@ <seglistitem><seg>1.5 SBU</seg><seg>108 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" + href="../chapter06/binutils.xml" + xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Re-installation of Binutils</title> +<para>This package is known to have issues when its default +optimization flags (including the <parameter>-march</parameter> and +<parameter>-mcpu</parameter> options) are changed. If any environment +variables that override default optimizations have been defined, such +as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>, +unset them when building Binutils.</para> + <para>Create a separate build directory again:</para> <screen><userinput>mkdir ../binutils-build cd ../binutils-build</userinput></screen> -<para>Now prepare Binutils for compilation:</para> +<para>Prepare Binutils for compilation:</para> <screen><userinput>../binutils-&binutils-version;/configure --prefix=/tools \ --enable-shared --with-lib-path=/tools/lib</userinput></screen> -<para>Compile the package:</para> +<para>The meaning of the new configure option:</para> -<screen><userinput>make</userinput></screen> +<variablelist> +<varlistentry> +<term><parameter>--with-lib-path=/tools/lib</parameter></term> +<listitem><para>This tells the configure script to specify the library +search path during the compilation of Binutils, resulting in <filename +class="directory">/tools/lib</filename> being passed to the linker. +This prevents the linker from searching through library directories on +the host.</para></listitem> +</varlistentry> +</variablelist> -<para>Test the results:</para> +<para>Compile the package:</para> -<!-- NEW --> -<screen><userinput>make -k check</userinput></screen> +<screen><userinput>make</userinput></screen> -<para>Except for a few known failures, the binutils tests should all pass. The -exceptions to this rule are as follows:</para> +<para>Compilation is now complete. As discussed earlier, running the +test suite is not mandatory for the temporary tools here in this +chapter. To run the Binutils test suite anyway, issue the following +command:</para> -<screen><computeroutput>* 5 FAIL (unexpected failure) for visibility -* 1 FAIL for selective4 -* 1 FAIL for selective5</computeroutput></screen> -<!-- END NEW--> +<screen><userinput>make check</userinput></screen> -<para>And install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> @@ -58,10 +83,16 @@ chapter:</para> make -C ld LIB_PATH=/usr/lib:/lib</userinput></screen> -<warning><para><emphasis>Do not yet remove</emphasis> the Binutils source and -build directories. You will need these directories again in the next chapter -in the state they are in now.</para></warning> +<warning><para><emphasis>Do not</emphasis> remove the Binutils source and +build directories yet. These directories will be needed again in the next +chapter in their current state.</para></warning> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-binutils" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/bison.xml b/chapter05/bison.xml index e3572e99d..dc237997d 100644 --- a/chapter05/bison.xml +++ b/chapter05/bison.xml @@ -7,7 +7,12 @@ <title>Bison-&bison-version;</title> <?dbhtml filename="bison.html"?> +<indexterm zone="ch-tools-bison"> +<primary sortas="a-Bison">Bison</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bison.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.6 SBU</seg><seg>10.6 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bison.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,13 +35,19 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput>.</para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> -<para>Now install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-bison" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/bzip2.xml b/chapter05/bzip2.xml index fb2ae264e..a45dee979 100644 --- a/chapter05/bzip2.xml +++ b/chapter05/bzip2.xml @@ -7,7 +7,12 @@ <title>Bzip2-&bzip2-version;</title> <?dbhtml filename="bzip2.html"?> +<indexterm zone="ch-tools-bzip2"> +<primary sortas="a-Bzip2">Bzip2</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bzip2.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,20 +20,28 @@ <seglistitem><seg>0.1 SBU</seg><seg>2.5 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/bzip2.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Bzip2</title> -<para>The Bzip2 package doesn't contain a <command>configure</command> -script. Compile it with a straightforward:</para> +<para>The Bzip2 package does not contain a <command>configure</command> +script. Compile it with:</para> <screen><userinput>make</userinput></screen> -<para>And install it:</para> +<para>Install the package:</para> <screen><userinput>make PREFIX=/tools install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-bzip2" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/chapter05.xml b/chapter05/chapter05.xml index 353071c9d..9c567c530 100644 --- a/chapter05/chapter05.xml +++ b/chapter05/chapter05.xml @@ -14,9 +14,6 @@ <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="binutils-pass1.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="gcc-pass1.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="linux-libc-headers.xml"/> -<!-- -<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="kernel-headers.xml"/> ---> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="glibc.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="adjusting.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="tcl.xml"/> @@ -44,9 +41,6 @@ <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="flex.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="util-linux.xml"/> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="perl.xml"/> -<!-- -<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="udev.xml"/> ---> <xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="stripping.xml"/> </chapter> diff --git a/chapter05/coreutils.xml b/chapter05/coreutils.xml index f99768465..e7bf67d37 100644 --- a/chapter05/coreutils.xml +++ b/chapter05/coreutils.xml @@ -7,7 +7,12 @@ <title>Coreutils-&coreutils-version;</title> <?dbhtml filename="coreutils.html"?> +<indexterm zone="ch-tools-coreutils"> +<primary sortas="a-Coreutils">Coreutils</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/coreutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.9 SBU</seg><seg>69 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/coreutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -24,17 +31,44 @@ <screen><userinput>DEFAULT_POSIX2_VERSION=199209 ./configure --prefix=/tools</userinput></screen> +<para>This package has an issue when compiled against versions of +Glibc later than 2.3.2. Some of the Coreutils utilities (such as +<command>head</command>, <command>tail</command>, and +<command>sort</command>) will reject their traditional syntax, a +syntax that has been in use for approximately 30 years. This old +syntax is so pervasive that compatibility should be preserved until +the many places where it is used can be updated. Backwards +compatibility is achieved by setting the +<envar>DEFAULT_POSIX2_VERSION</envar> environment variable to +<quote>199209</quote> in the above command. If you do not want +Coreutils to be backwards compatible with the traditional syntax, then +omit setting the <envar>DEFAULT_POSIX2_VERSION</envar> +environment variable. It is important to remember that doing so will +have consequences, including the need to patch the many packages that +still use the old syntax. Therefore, it is recommended that the +instructions be followed exactly as given above.</para> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> -<para>To test the result, issue: -<userinput>make RUN_EXPENSIVE_TESTS=yes check</userinput></para> +<para>To test the results, issue: <userinput>make +RUN_EXPENSIVE_TESTS=yes check</userinput>. The +<parameter>RUN_EXPENSIVE_TESTS=yes</parameter> parameter tells the +test suite to run several additional tests that are considered +relatively expensive (in terms of CPU power and memory usage) on some +platforms, but generally are not a problem on Linux.</para> -<para>And install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-coreutils" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/dejagnu.xml b/chapter05/dejagnu.xml index 25e3e87b2..2b9703030 100644 --- a/chapter05/dejagnu.xml +++ b/chapter05/dejagnu.xml @@ -3,13 +3,14 @@ <!ENTITY % general-entities SYSTEM "../general.ent"> %general-entities; ]> -<sect1 id="ch-tools-dejagnu" xreflabel="DejaGNU" role="wrap"> +<sect1 id="ch-tools-dejagnu" role="wrap"> <title>DejaGNU-&dejagnu-version;</title> <?dbhtml filename="dejagnu.html"?> <indexterm zone="ch-tools-dejagnu"><primary sortas="a-DejaGNU">DejaGNU</primary></indexterm> <sect2 role="package"><title/> +<para>The DejaGNU package contains a framework for testing other programs.</para> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -17,6 +18,11 @@ <seglistitem><seg>0.1 SBU</seg><seg>8.6 MB</seg></seglistitem> </segmentedlist> +<segmentedlist> +<segtitle>DejaGNU installation depends on</segtitle> +<seglistitem><seg>Bash, Binutils, Coreutils, Diffutils, +GCC, Glibc, Grep, Make, and Sed</seg></seglistitem> +</segmentedlist> </sect2> <sect2 role="installation"> @@ -32,11 +38,28 @@ </sect2> + <sect2 id="contents-dejagnu" role="content"><title>Contents of DejaGNU</title> -<para>See testing</para> +<segmentedlist> +<segtitle>Installed program</segtitle> +<seglistitem><seg>runtest</seg></seglistitem> +</segmentedlist> -</sect2> +<variablelist><bridgehead renderas="sect3">Short Descriptions</bridgehead> +<?dbfo list-presentation="list"?> + +<varlistentry id="runtest"> +<term><command>runtest</command></term> +<listitem> +<para>A wrapper script that locates the proper +<command>expect</command> shell and then runs DejaGNU</para> +<indexterm zone="ch-tools-dejagnu runtest"><primary sortas="b-runtest">runtest</primary></indexterm> +</listitem> +</varlistentry> +</variablelist> +</sect2> </sect1> + diff --git a/chapter05/diffutils.xml b/chapter05/diffutils.xml index 7d9d49eb5..b3408d512 100644 --- a/chapter05/diffutils.xml +++ b/chapter05/diffutils.xml @@ -7,7 +7,12 @@ <title>Diffutils-&diffutils-version;</title> <?dbhtml filename="diffutils.html"?> +<indexterm zone="ch-tools-diffutils"> +<primary sortas="a-Diffutils">Diffutils</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/diffutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.1 SBU</seg><seg>7.5 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/diffutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,10 +35,18 @@ <screen><userinput>make</userinput></screen> -<para>And install it:</para> +<para>This package does not come with a test suite.</para> + +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-diffutils" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/expect.xml b/chapter05/expect.xml index 11887dfd2..5d99eaf4d 100644 --- a/chapter05/expect.xml +++ b/chapter05/expect.xml @@ -3,13 +3,15 @@ <!ENTITY % general-entities SYSTEM "../general.ent"> %general-entities; ]> -<sect1 id="ch-tools-expect" xreflabel="Expect" role="wrap"> +<sect1 id="ch-tools-expect" role="wrap"> <title>Expect-&expect-version;</title> <?dbhtml filename="expect.html"?> <indexterm zone="ch-tools-expect"><primary sortas="a-Expect">Expect</primary></indexterm> <sect2 role="package"><title/> +<para>The Expect package contains a program for carrying out scripted dialogues +with other interactive programs.</para> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -17,12 +19,18 @@ <seglistitem><seg>0.1 SBU</seg><seg>3.9 MB</seg></seglistitem> </segmentedlist> +<segmentedlist> +<segtitle>Expect installation depends on</segtitle> +<seglistitem><seg>Bash, Binutils, Coreutils, Diffutils, +GCC, Glibc, Grep, Make, Sed, and Tcl</seg></seglistitem> +</segmentedlist> </sect2> <sect2 role="installation"> <title>Installation of Expect</title> -<para>Apply a patch:</para> +<para>First, fix a bug that can result in false failures during the GCC test +suite run:</para> <screen><userinput>patch -Np1 -i ../expect-&expect-version;-spawn-1.patch</userinput></screen> @@ -30,26 +38,84 @@ <screen><userinput>./configure --prefix=/tools --with-tcl=/tools/lib --with-x=no</userinput></screen> +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--with-tcl=/tools/lib</parameter></term> +<listitem><para>This ensures that the configure script finds the Tcl installation in +the temporary tools location instead of possibly locating an existing +one on the host system.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--with-x=no</parameter></term> +<listitem><para>This tells the configure script not to search for Tk +(the Tcl GUI component) or the X Window System libraries, both of +which may reside on the host system.</para></listitem> +</varlistentry> +</variablelist> + <para>Build the package:</para> <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make test</userinput></para> +<para>To test the results, issue: <userinput>make test</userinput>. +Note that the Expect test suite is known to experience failures under +certain host conditions that are not within our control. Therefore, +test suite failures here are not surprising and are not considered +critical.</para> -<para>And install it:</para> +<para>Install the package:</para> <screen><userinput>make SCRIPTS="" install</userinput></screen> -<para>You can now remove the source directories of both Tcl and Expect.</para> +<para>The meaning of the make parameter:</para> + +<variablelist> +<varlistentry> +<term><parameter>SCRIPTS=""</parameter></term> +<listitem><para>This prevents installation of the supplementary expect +scripts, which are not needed.</para></listitem> +</varlistentry> +</variablelist> + +<para>The source directories of both Tcl and Expect can now be removed.</para> </sect2> <sect2 id="contents-expect" role="content"><title>Contents of Expect</title> -<para>See testing</para> +<segmentedlist> +<segtitle>Installed program</segtitle> +<segtitle>Installed library</segtitle> +<seglistitem><seg>expect</seg><seg>libexpect-5.42.a</seg></seglistitem> +</segmentedlist> + +<variablelist><bridgehead renderas="sect3">Short Descriptions</bridgehead> +<?dbfo list-presentation="list"?> + +<varlistentry id="expect"> +<term><command>expect</command></term> +<listitem> +<para>Communicates with other interactive +programs according to a script</para> +<indexterm zone="ch-tools-expect expect"><primary sortas="b-expect">expect</primary></indexterm> +</listitem> +</varlistentry> + +<varlistentry id="libexpect"> +<term><filename class="libraryfile">libexpect-5.42.a</filename></term> +<listitem> +<para>Contains functions that allow Expect to be used as a Tcl extension or to +be used directly from C or C++ (without Tcl)</para> +<indexterm zone="ch-tools-expect libexpect"><primary +sortas="c-libexpect-5.42">libexpect-5.42</primary></indexterm> +</listitem> +</varlistentry> +</variablelist> </sect2> - </sect1> + diff --git a/chapter05/findutils.xml b/chapter05/findutils.xml index 0da1b5bc0..d75f15b90 100644 --- a/chapter05/findutils.xml +++ b/chapter05/findutils.xml @@ -7,7 +7,12 @@ <title>Findutils-&findutils-version;</title> <?dbhtml filename="findutils.html"?> +<indexterm zone="ch-tools-findutils"> +<primary sortas="a-Findutils">Findutils</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/findutils.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.2 SBU</seg><seg>7.6 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/findutils.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,13 +35,19 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> -<para>And install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-findutils" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/flex.xml b/chapter05/flex.xml index d8f01a11e..c78a52ffc 100644 --- a/chapter05/flex.xml +++ b/chapter05/flex.xml @@ -3,11 +3,16 @@ <!ENTITY % general-entities SYSTEM "../general.ent"> %general-entities; ]> -<sect1 id="ch-tools-flex" xreflabel="Flex" role="wrap"> +<sect1 id="ch-tools-flex" role="wrap"> <title>Flex-&flex-version;</title> <?dbhtml filename="flex.html"?> +<indexterm zone="ch-tools-flex"> +<primary sortas="a-Flex">Flex</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/flex.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,16 +20,22 @@ <seglistitem><seg>0.6 SBU</seg><seg>10.6 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/flex.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Flex</title> -<para>Apply a patch:</para> +<para>Flex contains several known bugs. These can be fixed with the +following patch:</para> <screen><userinput>patch -Np1 -i ../flex-&flex-version;-debian_fixes-2.patch</userinput></screen> -<para>Touch the man-page:</para> +<para>The GNU autotools will detect that the Flex source code has been +modified by the previous patch and tries to update the manual page +accordingly. This does not work on many systems, and the default page is +fine, so make sure it does not get regenerated:</para> <screen><userinput>touch doc/flex.1</userinput></screen> @@ -39,10 +50,16 @@ <para>To test the results, issue: <userinput>make check</userinput>.</para> -<para>Now install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-flex" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/gawk.xml b/chapter05/gawk.xml index 62ad8768d..e72817f81 100644 --- a/chapter05/gawk.xml +++ b/chapter05/gawk.xml @@ -7,7 +7,12 @@ <title>Gawk-&gawk-version;</title> <?dbhtml filename="gawk.html"?> +<indexterm zone="ch-tools-gawk"> +<primary sortas="a-Gawk">Gawk</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gawk.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.2 SBU</seg><seg>17 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gawk.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,13 +35,19 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results (not necessary), issue: <userinput>make +check</userinput>.</para> -<para>And install it:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-gawk" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/gcc-pass1.xml b/chapter05/gcc-pass1.xml index 39b343a2e..503438558 100644 --- a/chapter05/gcc-pass1.xml +++ b/chapter05/gcc-pass1.xml @@ -7,7 +7,12 @@ <title>GCC-&gcc-version; - Pass 1</title> <?dbhtml filename="gcc-pass1.html"?> +<indexterm zone="ch-tools-gcc-pass1"> +<primary sortas="a-GCC">GCC</primary> +<secondary>tools, pass 1</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gcc.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,36 +20,117 @@ <seglistitem><seg>4.4 SBU</seg><seg>300 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gcc.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of GCC</title> -<para>Create a build dir:</para> +<para>Unpack only the gcc-core tarball because neither the C++ +compiler nor the test suite will be needed here.</para> + +<para>This package is known to have issues when its default +optimization flags (including the <parameter>-march</parameter> and +<parameter>-mcpu</parameter> options) are changed. If any environment +variables that override default optimizations have been defined, such +as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>, +unset them when building GCC.</para> + +<para>The GCC documentation recommends building GCC outside of the +source directory in a dedicated build directory:</para> <screen><userinput>mkdir ../gcc-build cd ../gcc-build</userinput></screen> <para>Prepare GCC for compilation:</para> -<!--NEW--> -<screen><userinput>CC="gcc -B/usr/bin" ../gcc-&gcc-version;/configure \ - --prefix=/tools --libexecdir=/tools/lib \ - --with-local-prefix=/tools --disable-nls \ - --enable-shared --enable-languages=c</userinput></screen> +<screen><userinput>../gcc-&gcc-version;/configure --prefix=/tools \ + --libexecdir=/tools/lib --with-local-prefix=/tools \ + --disable-nls --enable-shared --enable-languages=c</userinput></screen> + +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--with-local-prefix=/tools</parameter></term> +<listitem><para>The purpose of this switch is to remove <filename class="directory">/usr/local/include</filename> +from <command>gcc</command>'s include search path. This is not absolutely +essential, however, it helps to minimize the influence of the host +system.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-shared</parameter></term> +<listitem><para>This switch may seem counter-intuitive at first. +However, this switch allows the building of +<filename class="libraryfile">libgcc_s.so.1</filename> and +<filename class="libraryfile">libgcc_eh.a</filename>, and having +<filename class="libraryfile">libgcc_eh.a</filename> available ensures that the configure +script for Glibc (the next package we compile) produces the proper +results. Note that the GCC binaries will still be linked statically +because this is controlled by the <parameter>-static</parameter> value of +the <envar>BOOT_LDFLAGS</envar> variable in the next +step.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-languages=c</parameter></term> +<listitem><para>This option ensures that only the C compiler is built. +This option is only needed when you have downloaded and unpacked the +full GCC tarball, as opposed to just the gcc-core +tarball.</para></listitem> +</varlistentry> +</variablelist> <para>Continue with compiling the package:</para> <screen><userinput>make BOOT_LDFLAGS="-static" bootstrap</userinput></screen> -<para>Now install the package:</para> +<para>The meaning of the make parameters:</para> + +<variablelist> +<varlistentry> +<term><parameter>BOOT_LDFLAGS="-static"</parameter></term> +<listitem><para>This tells GCC to link its programs statically.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>bootstrap</parameter></term> +<listitem><para>This target does not just compile GCC, but compiles it +several times. It uses the programs compiled in a first round to +compile itself a second time, and then again a third time. It then +compares these second and third compiles to make sure it can reproduce +itself flawlessly. This also implies that it was compiled +correctly.</para></listitem> +</varlistentry> +</variablelist> + +<para>Compilation is now complete. At this point, the test suite would +normally be run, but, as mentioned before, the test suite framework is +not in place yet. The benefits of running the tests at this point +are minimal since the programs from this first pass will soon be +replaced.</para> + +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> -<para>Create a symlink:</para> +<para>As a finishing touch, create a symlink. Many programs and +scripts run <command>cc</command> instead of <command>gcc</command>, which is used to keep programs generic +and therefore usable on all kinds of UNIX systems where the GNU C compiler +is not always installed. Running <command>cc</command> leaves the system administrator +free to decide which C compiler to install.</para> <screen><userinput>ln -s gcc /tools/bin/cc</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-gcc" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/gcc-pass2.xml b/chapter05/gcc-pass2.xml index 9058c02ea..202f9a0d9 100644 --- a/chapter05/gcc-pass2.xml +++ b/chapter05/gcc-pass2.xml @@ -7,6 +7,10 @@ <title>GCC-&gcc-version; - Pass 2</title> <?dbhtml filename="gcc-pass2.html"?> +<indexterm zone="ch-tools-gcc-pass2"> +<primary sortas="a-GCC">GCC</primary> +<secondary>tools, pass 2</secondary></indexterm> + <sect2 role="package"><title/> <segmentedlist> @@ -15,25 +19,88 @@ <seglistitem><seg>11.0 SBU</seg><seg>274 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gcc.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Re-installation of GCC</title> -<para>Check if there is PTYs for the test suites:</para> +<para>This package is known to have issues when its default +optimization flags (including the <parameter>-march</parameter> and +<parameter>-mcpu</parameter> options) are changed. If any environment +variables that override default optimizations have been defined, such +as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>, +unset them when building GCC.</para> + +<para>The tools required to test GCC and Binutils—Tcl, Expect +and DejaGNU—are installed now. GCC and Binutils can now be +rebuilt, linking them against the new Glibc and testing them properly +(if running the test suites in this chapter). Please note that these +test suites are highly dependent on properly functioning PTYs which +are provided by the host. PTYs are most commonly implemented via the +<systemitem class="filesystem">devpts</systemitem> file system. Check +to see if the host system is set up correctly in this regard by +performing a quick test:</para> <screen><userinput>expect -c "spawn ls"</userinput></screen> -<para>Apply two patches:</para> +<para>The response might be:</para> + +<screen><computeroutput>The system has no more ptys. +Ask your system administrator to create more.</computeroutput></screen> + +<para>If the above message is received, the host does not have its +PTYs set up properly. In this case, there is no point in running the +test suites for GCC and Binutils until this issue is resolved. Please +consult the LFS Wiki at <ulink url="&wiki-root;"/> for more +information on how to get PTYs working.</para> + +<para>Because the C and the C++ compilers will be built, unpack both +the core and the g++ tarballs (as well as test suite, if you want to +run the tests). By unpacking them in the working directory, they will +all unfold into a single <filename +class="directory">gcc-&gcc-version;/</filename> subdirectory.</para> + +<para>First correct a known problem and make an essential adjustment:</para> <screen><userinput>patch -Np1 -i ../gcc-&gcc-version;-no_fixincludes-1.patch patch -Np1 -i ../gcc-&gcc-version;-specs-2.patch</userinput></screen> +<para>The first patch disables the GCC <command>fixincludes</command> +script. This was briefly mentioned earlier, but a more in-depth +explanation of the fixincludes process is warranted here. Under normal +circumstances, the GCC <command>fixincludes</command> script scans the +system for header files that need to be fixed. It might find that some +Glibc header files on the host system need to be fixed, and will fix +them and put them in the GCC private include directory. In <xref +linkend="chapter-building-system"/>, after the newer Glibc has been +installed, this private include directory will be searched before the +system include directory. This may result in GCC finding the fixed +headers from the host system, which most likely will not match the +Glibc version used for the LFS system.</para> + +<para>The second patch changes GCC's default location of the dynamic +linker (typically <filename class="libraryfile">ld-linux.so.2</filename>). It also removes +<filename class="directory">/usr/include</filename> from GCC's include +search path. Patching now rather than adjusting the specs file after +installation ensures that the new dynamic linker is used during the +actual build of GCC. That is, all of the final (and temporary) +binaries created during the build will link against the new +Glibc.</para> + +<important><para>The above patches are critical in ensuring a +successful overall build. Do not forget to apply +them.</para></important> + <para>Create a separate build directory again:</para> <screen><userinput>mkdir ../gcc-build cd ../gcc-build</userinput></screen> +<para>Before starting to build GCC, remember to unset any environment +variables that override the default optimization flags.</para> + <para>Now prepare GCC for compilation:</para> <screen><userinput>../gcc-&gcc-version;/configure --prefix=/tools \ @@ -42,36 +109,105 @@ cd ../gcc-build</userinput></screen> --enable-threads=posix --enable-__cxa_atexit \ --enable-languages=c,c++ --disable-libstdcxx-pch</userinput></screen> +<para>The meaning of the new configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--enable-clocale=gnu</parameter></term> +<listitem><para>This option ensures the correct locale model is +selected for the C++ libraries under all circumstances. If the +configure script finds the <emphasis>de_DE</emphasis> locale installed, it will select the +correct gnu locale model. However, if the <emphasis>de_DE</emphasis> locale is not +installed, there is the risk of building Application Binary Interface +(ABI)-incompatible C++ libraries because the incorrect generic locale +model may be selected.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-threads=posix</parameter></term> +<listitem><para>This enables C++ exception handling for multi-threaded +code.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-__cxa_atexit</parameter></term> +<listitem><para>This option allows use of +<emphasis>__cxa_atexit</emphasis>, rather than +<emphasis>atexit</emphasis>, to register C++ destructors for local +statics and global objects. This option is essential for fully +standards-compliant handling of destructors. It also effects the C++ +ABI, and therefore results in C++ shared libraries and C++ programs +that are interoperable with other Linux +distributions.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-languages=c,c++</parameter></term> +<listitem><para>This option +ensures that both the C and C++ compilers are built.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--disable-libstdcxx-pch</parameter></term> +<listitem><para>Do not build the pre-compiled header (PCH) for +<filename class="libraryfile">libstdc++</filename>. It takes up a lot of space, +and we have no use for it.</para></listitem> +</varlistentry> +</variablelist> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> -<para>Test the results</para> +<para>There is no need to use the <parameter>bootstrap</parameter> +target now because the compiler being used to compile this GCC was +built from the exact same version of the GCC sources used +earlier.</para> + +<para>Compilation is now complete. As previously mentioned, running +the test suites for the temporary tools compiled in this chapter is +not mandatory. To run the GCC test suite anyway, use the following +command:</para> <screen><userinput>make -k check</userinput></screen> -<para>To get a summary of the test suite results, run this:</para> +<para>The <parameter>-k</parameter> flag is used to make the test suite run +through to completion and not stop at the first failure. The GCC test +suite is very comprehensive and is almost guaranteed to generate a few +failures. To receive a summary of the test suite results, run:</para> <screen><userinput>../gcc-&gcc-version;/contrib/test_summary</userinput></screen> <para>For only the summaries, pipe the output through -<userinput>grep -A7 Summ</userinput></para> +<userinput>grep -A7 Summ</userinput>.</para> <para>Results can be compared to those posted to the gcc-testresults -mailing list to see similar configurations to the one being built. For an example of how -current GCC-&gcc-version; should look on i686-pc-linux-gnu, see -<ulink url="http://gcc.gnu.org/ml/gcc-testresults/2004-11/msg00569.html"/>.</para> +mailing list to see similar configurations to the one being built. For +an example of how current GCC-&gcc-version; should look on +i686-pc-linux-gnu, see <ulink +url="http://gcc.gnu.org/ml/gcc-testresults/2004-07/msg00179.html"/>.</para> + +<para>A few unexpected failures cannot always be avoided. The +GCC developers are usually aware of these issues, but have not +resolved them yet. Unless the test results are vastly different from +those at the above URL, it is safe to continue.</para> -<para>And finally install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> -<note><para>At this point it is strongly recommended to repeat the sanity check -we performed earlier in this chapter. Refer back to -<xref linkend="ch-tools-adjusting"/> and repeat the little test compilation. If -the result is wrong, then most likely you forgot to apply the above mentioned -GCC Specs patch.</para></note> +<note><para>At this point it is strongly recommended to repeat the +sanity check we performed earlier in this chapter. Refer back to <xref +linkend="ch-tools-adjusting" role=","/> and repeat the test compilation. If +the result is wrong, the most likely reason is that the GCC Specs +patch was not properly applied.</para></note> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-gcc" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/gettext.xml b/chapter05/gettext.xml index feb4c38ed..ceca963c1 100644 --- a/chapter05/gettext.xml +++ b/chapter05/gettext.xml @@ -7,7 +7,12 @@ <title>Gettext-&gettext-version;</title> <?dbhtml filename="gettext.html"?> +<indexterm zone="ch-tools-gettext"> +<primary sortas="a-Gettext">Gettext</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gettext.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.5 SBU</seg><seg>55 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gettext.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -25,17 +32,46 @@ <screen><userinput>./configure --prefix=/tools --disable-libasprintf \ --disable-csharp</userinput></screen> +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--disable-libasprintf</parameter></term> +<listitem><para>This flag tells Gettext not to build the +<filename class="libraryfile">asprintf</filename> library. Because nothing in this +chapter or the next requires this library and Gettext gets rebuilt later, +exclude it to save time and space.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--disable-csharp</parameter></term> +<listitem><para>This tells Gettext not to use a C# compiler, even if a +C# compiler is installed on the host. This needs to be done because +once we enter the chroot environment, C# will no longer be +available.</para></listitem> +</varlistentry> +</variablelist> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make check</userinput>. +This takes quite some time, around 7 SBUs. The Gettext test suite is +known to experience failures under certain host conditions, for +example when it finds a Java compiler on the host. An experimental +patch to disable Java is available from the LFS Patches project at +<ulink url="&lfs-root;patches/"/>.</para> -<para>And install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref linkend="contents-gettext" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/glibc.xml b/chapter05/glibc.xml index dcb468a56..1e3d4925b 100644 --- a/chapter05/glibc.xml +++ b/chapter05/glibc.xml @@ -7,7 +7,12 @@ <title>Glibc-&glibc-version;</title> <?dbhtml filename="glibc.html"?> +<indexterm zone="ch-tools-glibc"> +<primary sortas="a-Glibc">Glibc</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/glibc.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,12 +20,26 @@ <seglistitem><seg>11.8 SBU</seg><seg>800 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/glibc.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Glibc</title> -<para>Create a build dir:</para> +<para>This package is known to have issues when its default +optimization flags (including the <parameter>-march</parameter> and +<parameter>-mcpu</parameter> options) are changed. If any environment +variables that override default optimizations have been defined, such +as <envar>CFLAGS</envar> and <envar>CXXFLAGS</envar>, +unset them when building Glibc.</para> + +<para>It should be noted that compiling Glibc in any way other than +the method suggested in this book puts the stability of the system at +risk.</para> + +<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> @@ -33,32 +52,153 @@ cd ../glibc-build</userinput></screen> --without-gd --without-cvs --with-headers=/tools/include \ --disable-selinux</userinput></screen> +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--disable-profile</parameter></term> +<listitem><para>This builds the libraries without profiling +information. Omit this option if profiling on the temporary tools is +necessary.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-add-ons</parameter></term> +<listitem><para>This tells Glibc to use the NPTL add-on as its threading +library.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-kernel=2.6.0</parameter></term> +<listitem><para>This tells Glibc to compile the library with support +for 2.6.x Linux kernels.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--with-binutils=/tools/bin</parameter></term> +<listitem><para>While not required, this switch ensures that there are +no errors pertaining to which Binutils programs get used during the +Glibc build.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--without-gd</parameter></term> +<listitem><para>This prevents the build of the +<command>memusagestat</command> program, which insists on linking +against the host's libraries (libgd, libpng, libz, +etc.).</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--without-cvs</parameter></term> +<listitem><para>This prevents the Makefile files from +attempting automatic CVS checkouts when using a CVS snapshot. While +this command is not required, it is recommended because it suppresses +an annoying, but harmless, warning about a missing autoconf +program.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--with-headers=/tools/include</parameter></term> +<listitem><para>This tells Glibc to compile itself against the headers recently +installed to the tools directory, so that it knows exactly what features the +kernel has and can optimize itself accordingly.</para></listitem> +</varlistentry> + +<!-- Edit Me --> +<varlistentry> +<term><parameter>--disable-selinux</parameter></term> +<listitem><para>When building from hosts using SELinux functionality +(i.e. Fedora Core 3), glibc will try to integrate this functionality into +itself, but will fail, because we do not have this functionality in the LFS +tools enviornment. This option will disable this, allowing glibc to build +correctly, but will not otherwise affect the build.</para></listitem> +</varlistentry> +<!-- --> +</variablelist> + +<para>During this stage the following warning might appear:</para> + +<blockquote><screen><computeroutput>configure: WARNING: +*** These auxiliary programs are missing or +*** incompatible versions: msgfmt +*** some features will be disabled. +*** Check the INSTALL file for required versions.</computeroutput></screen></blockquote> + +<para>The missing or incompatible <command>msgfmt</command> program is +generally harmless, but it can sometimes cause issues when running the +test suite. This <command>msgfmt</command> program is part of the +Gettext package which the host distribution should provide. If +<command>msgfmt</command> is present but deemed incompatible, upgrade +the host system's Gettext package or continue without it and see if +the test suite runs without problems regardless.</para> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> -<para>Test the results:</para> +<para>Compilation is now complete. As mentioned earlier, running the +test suites for the temporary tools installed in this chapter is not +mandatory. To run the Glibc test suite (if desired), the following +command will do so:</para> <screen><userinput>make check</userinput></screen> <para>For a discussion of test failures that are of particular -importance, please see <xref linkend="ch-system-glibc"/>.</para> +importance, please see <xref linkend="ch-system-glibc" role="."/></para> + +<para>In this chapter, some tests can be adversely effected by +existing tools or environmental issues on the host system. Glibc test +suite failures in this chapter are typically not worrisome. The Glibc +installed in <xref linkend="chapter-building-system"/> is the one that +will ultimately end up being used, so that is the one that needs to pass +most tests (even in <xref linkend="chapter-building-system"/>, some +failures could still occur, for example, with the math tests).</para> + +<para>When experiencing a failure, make a note of it, then continue by +reissuing the <command>make check</command> command. The test suite should pick up where it left +off and continue. This stop-start sequence can be circumvented by +issuing a <command>make -k check</command> command. If using this option, be sure to log the +output so that the log file can be examined for failures later.</para> + +<para>The install stage of Glibc will issue a harmless warning at the +end about the absence of <filename>/tools/etc/ld.so.conf</filename>. +Prevent this warning with:</para> <screen><userinput>mkdir /tools/etc touch /tools/etc/ld.so.conf</userinput></screen> -<para>Now install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> -<para>To install the Glibc locales, use the following +<para>Different countries and cultures have varying conventions for +how to communicate. These conventions range from the format for +representing dates and times to more complex issues, such as the +language spoken. The <quote>internationalization</quote> of GNU +programs works by locale.</para> + +<note><para>If the test suites are not being run in this chapter (as +per the recommendation), there is no need to install the locales now. +The appropriate locales will be installed in the next +chapter.</para></note> + +<para>To install the Glibc locales anyway, use the following command:</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. The following instructions, instead of the -install-locales target above, will install the minimum set of locales necessary +<para>To save time, an alternative to running the +previous command (which generates and installs every locale Glibc is +aware of) is to install only those locales that are wanted and needed. +This can be achieved by using the <command>localedef</command> +command. Information on this command is located in the +<filename>INSTALL</filename> file in the Glibc source. However, there +are a number of locales that are essential in order for the tests of +future packages to pass, in particular, the +<emphasis>libstdc++</emphasis> tests from GCC. The following +instructions, instead of the <parameter>install-locales</parameter> +target used above, will install the minimum set of locales necessary for the tests to run successfully:</para> <screen><userinput>mkdir -p /tools/lib/locale @@ -76,4 +216,10 @@ localedef -i ja_JP -f EUC-JP ja_JP</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-glibc" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/grep.xml b/chapter05/grep.xml index 7af37c4b6..6cc9ce553 100644 --- a/chapter05/grep.xml +++ b/chapter05/grep.xml @@ -7,7 +7,12 @@ <title>Grep-&grep-version;</title> <?dbhtml filename="grep.html"?> +<indexterm zone="ch-tools-grep"> +<primary sortas="a-Grep">Grep</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/grep.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.1 SBU</seg><seg>5.8 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/grep.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -25,12 +32,32 @@ <screen><userinput>./configure --prefix=/tools \ --disable-perl-regexp --with-included-regex</userinput></screen> +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--disable-perl-regexp</parameter></term> +<listitem><para>This makes sure that the <command>grep</command> +program does not get linked against a Perl Compatible Regular +Expression (PCRE) library that may be present on the host and would +not be available once we enter the chroot +environment.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--with-included-regex</parameter></term> +<listitem><para>This ensures that Grep uses its internal regular +expression code. Without this switch, Grep will use the code from +Glibc, which is known to be buggy.</para></listitem> +</varlistentry> +</variablelist> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> <para>Install the package:</para> @@ -38,4 +65,10 @@ </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-grep" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/gzip.xml b/chapter05/gzip.xml index f8c86b663..3683d5ff9 100644 --- a/chapter05/gzip.xml +++ b/chapter05/gzip.xml @@ -7,7 +7,12 @@ <title>Gzip-&gzip-version;</title> <?dbhtml filename="gzip.html"?> +<indexterm zone="ch-tools-gzip"> +<primary sortas="a-Gzip">Gzip</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gzip.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.1 SBU</seg><seg>2.6 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/gzip.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,10 +35,18 @@ <screen><userinput>make</userinput></screen> -<para>And install it:</para> +<para>This package does not come with a test suite.</para> + +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-gzip" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/hostreqs.xml b/chapter05/hostreqs.xml index c4a216a24..310d450d1 100644 --- a/chapter05/hostreqs.xml +++ b/chapter05/hostreqs.xml @@ -7,6 +7,34 @@ <title>Host System Requirements</title> <?dbhtml filename="hostreqs.html"?> -<para>See testing.</para> +<para>The host must be running at least a 2.6.2 kernel compiled with +GCC-3.0 or higher. There are two main reasons for this high +requirement. First, the Native POSIX Threading Library (NPTL) +test suite will segfault if the host's kernel has not been compiled with +GCC-3.0 or a later version. Secondly, the 2.6.2 or later version of +the kernel is required for the use of Udev. Udev creates devices +dynamically by reading from the <systemitem +class="filesystem">sysfs</systemitem> file system. However, support +for this filesystem has only recently been implemented in most of +the kernel drivers. We must be sure that all critical system devices +get created properly.</para> + +<para>In order to determine whether the host kernel meets the +requirements outlined above, run the following command:</para> + +<screen><userinput>cat /proc/version</userinput></screen> + +<para>This will produce output similar to:</para> + +<screen><computeroutput>Linux version 2.6.2 (user@host) (gcc version 3.4.0) #1 + Tue Apr 20 21:22:18 GMT 2004</computeroutput></screen> + +<para>If the results of the above command state that the host kernel +was not compiled using a GCC-3.0 (or later) compiler, one will need to +be compiled. The host system will then need to be rebooted to use the +newly compiled kernel. Instructions for compiling the kernel and +configuring the boot loader (assuming the host uses GRUB) are located +in <xref linkend="chapter-bootable"/>.</para> </sect1> + diff --git a/chapter05/introduction.xml b/chapter05/introduction.xml index e16f460a8..4438bd7a6 100644 --- a/chapter05/introduction.xml +++ b/chapter05/introduction.xml @@ -7,6 +7,61 @@ <title>Introduction</title> <?dbhtml filename="introduction.html"?> -<para>See testing.</para> +<para>This chapter shows how to compile and install a minimal Linux +system. This system will contain just enough tools to start +constructing the final LFS system in <xref +linkend="chapter-building-system"/> and allow a working environment +with more user convenience than a minimum environment would.</para> + +<para>There are two steps in building this minimal system. The first +step is to build a new and host-independent toolchain (compiler, +assembler, linker, libraries, and a few useful utilities). The second +step uses this toolchain to build the other essential tools.</para> + +<para>The files compiled in this chapter will be installed under the +<filename class="directory">$LFS/tools</filename> directory to keep +them separate from the files installed in the next chapter and the +host production directories. Since the packages compiled here are +temporary, we do not want them to pollute the soon-to-be LFS +system.</para> + +<para>Before issuing the build instructions for a package, the package +should be unpacked as user <emphasis>lfs</emphasis>, and a +<command>cd</command> into the created directory should be performed. The build +instructions assume that the <command>bash</command> shell is in use.</para> + +<para>Several of the packages are patched before compilation, but only +when the patch is needed to circumvent a problem. A patch is often +needed in both this and the next chapter, but sometimes in only one or +the other. Therefore, do not be concerned if instructions for a downloaded +patch seem to be missing. Warning messages about +<emphasis>offset</emphasis> or <emphasis>fuzz</emphasis> may +also be encountered when applying a patch. Do not worry about these +warnings, as the patch was still successfully applied.</para> + +<para>During the compilation of most packages, there will be several +warnings that scroll by on the screen. These are normal and can safely +be ignored. These warnings are as they appear—warnings about +deprecated, but not invalid, use of the C or C++ syntax. C standards +change fairly often, and some packages still use the older standard. +This is not a problem, but does prompt the warning.</para> + +<para>After installing each package, delete its source and build +directories, unless specifically instructed otherwise. Deleting the +sources saves space and prevents mis-configuration when the same +package is reinstalled later. Only three of the packages need to +retain the source and build directories in order for their contents to +be used by later commands. Pay special attention to these +reminders.</para> + +<para>Check one last time that the <envar>LFS</envar> environment +variable is set up properly:</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>, using +our example.</para> </sect1> + diff --git a/chapter05/linux-libc-headers.xml b/chapter05/linux-libc-headers.xml index 167dceb57..4370bef9f 100644 --- a/chapter05/linux-libc-headers.xml +++ b/chapter05/linux-libc-headers.xml @@ -7,7 +7,14 @@ <title>Linux-Libc-Headers-&linux-libc-headers-version;</title> <?dbhtml filename="linux-libc-headers.html"?> +<indexterm zone="ch-tools-linux-libc-headers"> +<primary sortas="a-Linux-Libc-Headers">Linux-Libc-Headers</primary> +<secondary>tools, headers</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" + href="../chapter06/linux-libc-headers.xml" + xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,16 +22,38 @@ <seglistitem><seg>0.1 SBU</seg><seg>22 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" + href="../chapter06/linux-libc-headers.xml" + xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + + </sect2> <sect2 role="installation"> <title>Installation of Linux-Libc-Headers</title> +<para>For years it has been common practice to use <quote>raw</quote> kernel +headers (straight from a kernel tarball) in <filename +class="directory">/usr/include</filename>, but over the +last few years, the kernel developers have taken a strong stance that +this should not be done. This gave birth to the Linux-Libc-Headers +Project, which was designed to maintain an Application Programming +Interface (API) stable version of the Linux headers.</para> + <para>Install the header files:</para> <screen><userinput>cp -R include/asm-i386 /tools/include/asm cp -R include/linux /tools/include</userinput></screen> +<para>If your architecture is not i386 (compatible), adjust the first command +accordingly.</para> + +</sect2> + +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-linux-libc-headers" role="."/></para> </sect2> </sect1> + diff --git a/chapter05/m4.xml b/chapter05/m4.xml index bab2b6a18..c861f0593 100644 --- a/chapter05/m4.xml +++ b/chapter05/m4.xml @@ -3,11 +3,16 @@ <!ENTITY % general-entities SYSTEM "../general.ent"> %general-entities; ]> -<sect1 id="ch-tools-m4" xreflabel="M4" role="wrap"> +<sect1 id="ch-tools-m4" role="wrap"> <title>M4-&m4-version;</title> <?dbhtml filename="m4.html"?> +<indexterm zone="ch-tools-m4"> +<primary sortas="a-M4">M4</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/m4.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.1 SBU</seg><seg>3.0 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/m4.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,13 +35,19 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput>.</para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> -<para>Now install the package:</para> +<para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-m4" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/make.xml b/chapter05/make.xml index ea37ca105..d20b8ac0a 100644 --- a/chapter05/make.xml +++ b/chapter05/make.xml @@ -7,7 +7,12 @@ <title>Make-&make-version;</title> <?dbhtml filename="make.html"?> +<indexterm zone="ch-tools-make"> +<primary sortas="a-Make">Make</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/make.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.2 SBU</seg><seg>8.8 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/make.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,8 +35,8 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> <para>Install the package:</para> @@ -37,4 +44,10 @@ </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-make" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/ncurses.xml b/chapter05/ncurses.xml index 8227b03bb..72538b445 100644 --- a/chapter05/ncurses.xml +++ b/chapter05/ncurses.xml @@ -7,7 +7,12 @@ <title>Ncurses-&ncurses-version;</title> <?dbhtml filename="ncurses.html"?> +<indexterm zone="ch-tools-ncurses"> +<primary sortas="a-Ncurses">Ncurses</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/ncurses.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.7 SBU</seg><seg>26 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/ncurses.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -25,14 +32,43 @@ <screen><userinput>./configure --prefix=/tools --with-shared \ --without-debug --without-ada --enable-overwrite</userinput></screen> +<para>The meaning of the configure options:</para> + +<variablelist> +<varlistentry> +<term><parameter>--without-ada</parameter></term> +<listitem><para>This tells Ncurses not to build its Ada bindings, even +if an Ada compiler is installed on the host. This needs to be done +because once we enter the chroot environment, Ada will no longer be +available.</para></listitem> +</varlistentry> + +<varlistentry> +<term><parameter>--enable-overwrite</parameter></term> +<listitem><para>This tells Ncurses to install its header files into +<filename class="directory">/tools/include</filename>, instead of +<filename class="directory">/tools/include/ncurses</filename>, to +ensure that other packages can find the Ncurses headers +successfully.</para></listitem> +</varlistentry> +</variablelist> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> +<para>This package does not come with a test suite.</para> + <para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-ncurses" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/patch.xml b/chapter05/patch.xml index 0f8c62cb5..ec5bc8888 100644 --- a/chapter05/patch.xml +++ b/chapter05/patch.xml @@ -7,7 +7,12 @@ <title>Patch-&patch-version;</title> <?dbhtml filename="patch.html"?> +<indexterm zone="ch-tools-patch"> +<primary sortas="a-Patch">Patch</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/patch.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.1 SBU</seg><seg>1.9 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/patch.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -24,14 +31,26 @@ <screen><userinput>CPPFLAGS=-D_GNU_SOURCE ./configure --prefix=/tools</userinput></screen> +<para>The preprocessor flag <parameter>-D_GNU_SOURCE</parameter> is +only needed on the PowerPC platform. It can be left out on other +architectures.</para> + <para>Compile the package:</para> <screen><userinput>make</userinput></screen> +<para>This package does not come with a test suite.</para> + <para>Install the package:</para> <screen><userinput>make install</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-patch" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/perl.xml b/chapter05/perl.xml index d118bb56f..77d619441 100644 --- a/chapter05/perl.xml +++ b/chapter05/perl.xml @@ -7,7 +7,12 @@ <title>Perl-&perl-version;</title> <?dbhtml filename="perl.html"?> +<indexterm zone="ch-tools-perl"> +<primary sortas="a-Perl">Perl</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/perl.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,24 +20,45 @@ <seglistitem><seg>0.8 SBU</seg><seg>74 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/perl.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Perl</title> -<para>First adapt some hard-wired paths to the C library:</para> +<para>First adapt some hard-wired paths to the C library by applying +the following patch:</para> <screen><userinput>patch -Np1 -i ../perl-&perl-version;-libc-1.patch</userinput></screen> -<para>Now prepare Perl for compilation:</para> +<para>Prepare Perl for compilation (make sure to get the 'IO Fcntl POSIX' +part of the command correct—they are all letters):</para> <screen><userinput>./configure.gnu --prefix=/tools -Dstatic_ext='IO Fcntl POSIX'</userinput></screen> +<para>The meaning of the configure option:</para> + +<variablelist> +<varlistentry> +<term><parameter>-Dstatic_ext='IO Fcntl POSIX'</parameter></term> +<listitem><para>This tells Perl to build the minimum set of static +extensions needed for installing and testing the Coreutils package in +the next chapter.</para></listitem> +</varlistentry> +</variablelist> + <para>Compile only the required tools:</para> <screen><userinput>make perl utilities</userinput></screen> -<para>Then copy these tools and their libraries:</para> +<para>Although Perl comes with a test suite, it is not recommended to +run it at this point. Only part of Perl was built and running +<userinput>make test</userinput> now will cause the rest of Perl to be +built as well, which is unnecessary at this point. The test suite can +be run in the next chapter if desired.</para> + +<para>Copy these tools and their libraries:</para> <screen><userinput>cp perl pod/pod2man /tools/bin mkdir -p /tools/lib/perl5/&perl-version; @@ -40,4 +66,10 @@ cp -R lib/* /tools/lib/perl5/&perl-version;</userinput></screen> </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-perl" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/sed.xml b/chapter05/sed.xml index 271e01d4d..9bb1090e4 100644 --- a/chapter05/sed.xml +++ b/chapter05/sed.xml @@ -7,7 +7,12 @@ <title>Sed-&sed-version;</title> <?dbhtml filename="sed.html"?> +<indexterm zone="ch-tools-sed"> +<primary sortas="a-Sed">Sed</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/sed.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.2 SBU</seg><seg>5.2 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/sed.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,8 +35,8 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> <para>Install the package:</para> @@ -37,4 +44,10 @@ </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-sed" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/stripping.xml b/chapter05/stripping.xml index 5e7d7a00a..dcafa39da 100644 --- a/chapter05/stripping.xml +++ b/chapter05/stripping.xml @@ -7,13 +7,32 @@ <title>Stripping</title> <?dbhtml filename="stripping.html"?> -<para>Strip the programs and libraries:</para> +<para>The steps in this section are optional, but if the LFS partition +is rather small, it is beneficial to learn that unnecessary items can +be removed. The executables and libraries built so far contain about +130 MB of unneeded debugging symbols. Remove those symbols +with:</para> <screen><userinput>strip --strip-debug /tools/lib/* strip --strip-unneeded /tools/{,s}bin/*</userinput></screen> -<para>Remove the documentation:</para> +<para>The last of the above commands will skip some twenty files, +reporting that it does not recognize their file format. Most of these +are scripts instead of binaries.</para> + +<para>Take care <emphasis>not</emphasis> to use +<parameter>--strip-unneeded</parameter> on the libraries. The static +ones would be destroyed and the toolchain packages would need to be +built all over again.</para> + +<para>To save another 30 MB, remove the documentation:</para> <screen><userinput>rm -rf /tools/{doc,info,man}</userinput></screen> +<para>There will now be at least 850 MB of free space on the LFS file +system that can be used to build and install Glibc in the next phase. +If you can build and install Glibc, you can build and install the rest +too.</para> + </sect1> + diff --git a/chapter05/tar.xml b/chapter05/tar.xml index bd279bada..21e59b24c 100644 --- a/chapter05/tar.xml +++ b/chapter05/tar.xml @@ -7,7 +7,12 @@ <title>Tar-&tar-version;</title> <?dbhtml filename="tar.html"?> +<indexterm zone="ch-tools-tar"> +<primary sortas="a-Tar">Tar</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/tar.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.2 SBU</seg><seg>10 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/tar.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,8 +35,8 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> <para>Install the package:</para> @@ -37,4 +44,10 @@ </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-tar" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/tcl.xml b/chapter05/tcl.xml index 7f15832c2..69dcbdec3 100644 --- a/chapter05/tcl.xml +++ b/chapter05/tcl.xml @@ -3,13 +3,14 @@ <!ENTITY % general-entities SYSTEM "../general.ent"> %general-entities; ]> -<sect1 id="ch-tools-tcl" xreflabel="Tcl" role="wrap"> +<sect1 id="ch-tools-tcl" role="wrap"> <title>Tcl-&tcl-version;</title> <?dbhtml filename="tcl.html"?> <indexterm zone="ch-tools-tcl"><primary sortas="a-Tcl">Tcl</primary></indexterm> <sect2 role="package"><title/> +<para>The Tcl package contains the Tool Command Language.</para> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -17,11 +18,26 @@ <seglistitem><seg>0.9 SBU</seg><seg>23 MB</seg></seglistitem> </segmentedlist> +<segmentedlist> +<segtitle>Tcl installation depends on</segtitle> +<seglistitem><seg>Bash, Binutils, Coreutils, Diffutils, +GCC, Glibc, Grep, Make, and Sed</seg></seglistitem> +</segmentedlist> + </sect2> <sect2 role="installation"> <title>Installation of Tcl</title> +<para>This package and the next two (Expect and DejaGNU) are +installed to support running the test suites for GCC and Binutils. +Installing three packages for testing purposes may seem excessive, but +it is very reassuring, if not essential, to know that the most +important tools are working properly. Even if the test suites are not +run in this chapter (they are not mandatory), these packages +are required to run the test suites in <xref +linkend="chapter-building-system"/>.</para> + <para>Prepare Tcl for compilation:</para> <screen><userinput>cd unix @@ -31,14 +47,22 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>TZ=UTC make test</userinput>.</para> +<para>To test the results, issue: <userinput>TZ=UTC make +test</userinput>. The Tcl test suite is known to experience failures +under certain host conditions that are not fully understood. +Therefore, test suite failures here are not surprising, and are not +considered critical. The <parameter>TZ=UTC</parameter> parameter sets +the time zone to Coordinated Universal Time (UTC), also known as +Greenwich Mean Time (GMT), but only for the duration of the test suite +run. This ensures that the clock tests are exercised correctly. +Details on the <envar>TZ</envar> environment variable is provided in +<xref linkend="chapter-bootscripts"/>.</para> <para>Install the package:</para> <screen><userinput>make install</userinput></screen> -<warning><para><emphasis>Do not remove</emphasis> the +<warning><para><emphasis>Do not</emphasis> remove the <filename class="directory">tcl&tcl-version;</filename> source directory yet, as the next package will need its internal headers.</para></warning> @@ -50,8 +74,41 @@ will need its internal headers.</para></warning> <sect2 id="contents-tcl" role="content"><title>Contents of Tcl</title> -<para>See testing</para> +<segmentedlist> +<segtitle>Installed programs</segtitle> +<segtitle>Installed library</segtitle> +<seglistitem><seg>tclsh (link to tclsh8.4) and tclsh8.4</seg><seg>libtcl8.4.so</seg></seglistitem> +</segmentedlist> + +<variablelist><bridgehead renderas="sect3">Short Descriptions</bridgehead> +<?dbfo list-presentation="list"?> + +<varlistentry id="tclsh8.4"> +<term><command>tclsh8.4</command></term> +<listitem> +<para>The Tcl command shell</para> +<indexterm zone="ch-tools-tcl tclsh8.4"><primary sortas="b-tclsh8.4">tclsh8.4</primary></indexterm> +</listitem> +</varlistentry> + +<varlistentry id="tclsh"> +<term><command>tclsh</command></term> +<listitem> +<para>A link to tclsh8.4</para> +<indexterm zone="ch-tools-tcl tclsh"><primary sortas="b-tclsh">tclsh</primary></indexterm> +</listitem> +</varlistentry> + +<varlistentry id="libtcl8.4.so"> +<term><filename class="libraryfile">libtcl8.4.so</filename></term> +<listitem> +<para>The Tcl library</para> +<indexterm zone="ch-tools-tcl libtcl8.4.so"><primary sortas="c-libtcl8.4.so">libtcl8.4.so</primary></indexterm> +</listitem> +</varlistentry> +</variablelist> </sect2> </sect1> + diff --git a/chapter05/texinfo.xml b/chapter05/texinfo.xml index dce70c00b..3a7ddf4c6 100644 --- a/chapter05/texinfo.xml +++ b/chapter05/texinfo.xml @@ -7,7 +7,12 @@ <title>Texinfo-&texinfo-version;</title> <?dbhtml filename="texinfo.html"?> +<indexterm zone="ch-tools-texinfo"> +<primary sortas="a-Texinfo">Texinfo</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/texinfo.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,6 +20,8 @@ <seglistitem><seg>0.2 SBU</seg><seg>16 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/texinfo.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> @@ -28,8 +35,8 @@ <screen><userinput>make</userinput></screen> -<para>To test the results, issue: -<userinput>make check</userinput></para> +<para>To test the results, issue: <userinput>make +check</userinput>.</para> <para>Install the package:</para> @@ -37,4 +44,10 @@ </sect2> +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-texinfo" role="."/></para> +</sect2> + </sect1> + diff --git a/chapter05/toolchaintechnotes.xml b/chapter05/toolchaintechnotes.xml index afc621085..9c2951387 100644 --- a/chapter05/toolchaintechnotes.xml +++ b/chapter05/toolchaintechnotes.xml @@ -7,6 +7,218 @@ <title>Toolchain Technical Notes</title> <?dbhtml filename="toolchaintechnotes.html"?> -<para>See testing</para> +<para>This section explains some of the rationale and technical +details behind the overall build method. It is not essential to +immediately understand everything in this section. Most of this +information will be clearer after performing an actual build. This +section can be referred back to at any time during the process.</para> + +<para>The overall goal of <xref linkend="chapter-temporary-tools"/> is +to provide a temporary environment that can be chrooted into and from +which can be produced a clean, trouble-free build of the target LFS +system in <xref linkend="chapter-building-system"/>. Along the way, we +separate from the host system as much as possible, and in doing so, +build a self-contained and self-hosted toolchain. It should be noted +that the build process has been designed to minimize the risks for new +readers and provide maximum educational value at the same time. In +other words, more advanced techniques could be used to build the +system.</para> + +<important> +<para>Before continuing, be aware of the name of the working platform, +often referred to as the target triplet. Many times, the target +triplet will probably be <emphasis>i686-pc-linux-gnu</emphasis>. A +simple way to determine the name of the target triplet is to run the +<command>config.guess</command> script that comes with the source for +many packages. Unpack the Binutils sources and run the script: +<userinput>./config.guess</userinput> and note the output.</para> + +<para>Also be aware of the name of the platform's dynamic linker, +often referred to as the dynamic loader (not to be confused with the +standard linker <command>ld</command> that is part of Binutils). The +dynamic linker provided by Glibc finds and loads the shared libraries +needed by a program, prepares the program to run, and then runs it. +The name of the dynamic linker will usually be +<filename class="libraryfile">ld-linux.so.2</filename>. On platforms that are less +prevalent, the name might be <filename class="libraryfile">ld.so.1</filename>, +and newer 64 bit platforms might be named something else entirely. The name of +the platform's dynamic linker can be determined by looking in the +<filename class="directory">/lib</filename> directory on the host +system. A sure-fire way to determine the name is to inspect a random +binary from the host system by running: <userinput>readelf -l <name +of binary> | grep interpreter</userinput> and noting the output. +The authoritative reference covering all platforms is in the +<filename>shlib-versions</filename> file in the root of the Glibc +source tree.</para> +</important> + +<para>Some key technical points of how the <xref linkend="chapter-temporary-tools"/> build +method works:</para> + +<itemizedlist> +<listitem><para>The process is similar in principle to +cross-compiling, whereby tools installed in the same prefix work in +cooperation, and thus utilize a little GNU +<quote>magic</quote></para></listitem> + +<listitem><para>Careful manipulation of the standard linker's library +search path ensures programs are linked only against chosen +libraries</para></listitem> + +<listitem><para>Careful manipulation of <command>gcc</command>'s +<filename>specs</filename> file tell the compiler which target dynamic +linker will be used</para></listitem> +</itemizedlist> + +<para>Binutils is installed first because the +<command>./configure</command> runs of both GCC and Glibc perform +various feature tests on the assembler and linker to determine which +software features to enable or disable. This is more important than +one might first realize. An incorrectly configured GCC or Glibc can +result in a subtly broken toolchain, where the impact of such breakage +might not show up until near the end of the build of an entire +distribution. A test suite failure will usually alert this error +before too much additional work is performed.</para> + +<para>Binutils installs its assembler and linker in two locations, +<filename class="directory">/tools/bin</filename> and <filename +class="directory">/tools/$TARGET_TRIPLET/bin</filename>. The tools in +one location are hard linked to the other. An important facet of the +linker is its library search order. Detailed information can be +obtained from <command>ld</command> by passing it the +<parameter>--verbose</parameter> flag. For example, an <userinput>ld +--verbose | grep SEARCH</userinput> will illustrate the current search +paths and their order. It shows which files are linked by +<command>ld</command> by compiling a dummy program and passing the +<parameter>--verbose</parameter> switch to the linker. For example, +<userinput>gcc dummy.c -Wl,--verbose 2>&1 | grep +succeeded</userinput> will show all the files successfully opened +during the linking.</para> + +<para>The next package installed is GCC. An example of what can be +seen during its run of <command>./configure</command> is:</para> + +<screen><computeroutput>checking what assembler to use... + /tools/i686-pc-linux-gnu/bin/as +checking what linker to use... /tools/i686-pc-linux-gnu/bin/ld</computeroutput></screen> + +<para>This is important for the reasons mentioned above. It also +demonstrates that GCC's configure script does not search the PATH +directories to find which tools to use. However, during the actual +operation of <command>gcc</command> itself, the same +search paths are not necessarily used. To find out which standard +linker <command>gcc</command> will use, run: <userinput>gcc +-print-prog-name=ld</userinput>.</para> + +<para>Detailed information can be obtained from <command>gcc</command> +by passing it the <parameter>-v</parameter> command line option while +compiling a dummy program. For example, <userinput>gcc -v +dummy.c</userinput> will show detailed information about the +preprocessor, compilation, and assembly stages, including +<command>gcc</command>'s included search paths and their order.</para> + +<para>The next package installed is Glibc. The most important +considerations for building Glibc are the compiler, binary tools, and +kernel headers. The compiler is generally not an issue since Glibc +will always use the <command>gcc</command> found in a +<envar>PATH</envar> directory. +The binary tools and kernel headers can be a bit more complicated. +Therefore, take no risks and use the available configure switches to +enforce the correct selections. After the run of +<command>./configure</command>, check the contents of the +<filename>config.make</filename> file in the <filename +class="directory">glibc-build</filename> directory for all important +details. Note the use of <parameter>CC="gcc -B/tools/bin/"</parameter> +to control which binary tools are used and the use of the +<parameter>-nostdinc</parameter> and <parameter>-isystem</parameter> +flags to control the compiler's include search path. These items +highlight an important aspect of the Glibc package—it is very +self-sufficient in terms of its build machinery and generally does not +rely on toolchain defaults.</para> + +<para>After the Glibc installation, make some adjustments to ensure +that searching and linking take place only within the <filename +class="directory">/tools</filename> prefix. Install an adjusted +<command>ld</command>, which has a hard-wired search path limited to +<filename class="directory">/tools/lib</filename>. Then amend +<command>gcc</command>'s specs file to point to the new dynamic linker +in <filename class="directory">/tools/lib</filename>. This last step +is vital to the whole process. As mentioned above, a hard-wired path +to a dynamic linker is embedded into every Executable and Link Format +(ELF)-shared executable. This can be inspected by running: +<userinput>readelf -l <name of binary> | grep +interpreter</userinput>. Amending gcc's specs file +ensures that every program compiled from here through the end of this +chapter will use the new dynamic linker in <filename +class="directory">/tools/lib</filename>.</para> + +<para>The need to use the new dynamic linker is also the reason why +the Specs patch is applied for the second pass of GCC. Failure to do +so will result in the GCC programs themselves having the name of the +dynamic linker from the host system's <filename +class="directory">/lib</filename> directory embedded into them, which +would defeat the goal of getting away from the host.</para> + +<para>During the second pass of Binutils, we are able to utilize the +<parameter>--with-lib-path</parameter> configure switch to control +<command>ld</command>'s library search path. From this point onwards, +the core toolchain is self-contained and self-hosted. The remainder of +the <xref linkend="chapter-temporary-tools"/> packages all build +against the new Glibc in <filename +class="directory">/tools</filename>.</para> + +<para>Upon entering the chroot environment in <xref +linkend="chapter-building-system"/>, the first major package to be +installed is Glibc, due to its self-sufficient nature mentioned above. +Once this Glibc is installed into <filename +class="directory">/usr</filename>, perform a quick changeover of the +toolchain defaults, then proceed in building the rest of the target +LFS system.</para> + +<sect2> +<title>Notes on Static Linking</title> + +<para>Besides their specific task, most programs have to perform many +common and sometimes trivial operations. These include allocating +memory, searching directories, reading and writing files, string +handling, pattern matching, arithmetic, and other tasks. Instead of +obliging each program to reinvent the wheel, the GNU system provides +all these basic functions in ready-made libraries. The major library +on any Linux system is Glibc.</para> + +<para>There are two primary ways of linking the functions from a +library to a program that uses them—statically or dynamically. When +a program is linked statically, the code of the used functions is +included in the executable, resulting in a rather bulky program. When +a program is dynamically linked, it includes a reference to the +dynamic linker, the name of the library, and the name of the function, +resulting in a much smaller executable. A third option is to use the +programming interface of the dynamic linker (see the +<emphasis>dlopen</emphasis> man page for more information).</para> + +<para>Dynamic linking is the default on Linux and has three major +advantages over static linking. First, only one copy of the executable +library code is needed on the hard disk, instead of having multiple +copies of the same code included in several programs, thus saving +disk space. Second, when several programs use the same library +function at the same time, only one copy of the function's code is +required in core, thus saving memory space. Third, when a library +function gets a bug fixed or is otherwise improved, only the one +library needs to be recompiled instead of recompiling all programs +that make use of the improved function.</para> + +<para>If dynamic linking has several advantages, why then do we +statically link the first two packages in this chapter? The reasons +are threefold—historical, educational, and technical. The +historical reason is that earlier versions of LFS statically linked +every program in this chapter. Educationally, knowing the difference +between static and dynamic linking is useful. The technical benefit is +a gained element of independence from the host, meaning that those +programs can be used independently of the host system. However, it is +worth noting that an overall successful LFS build can still be +achieved when the first two packages are built dynamically.</para> + +</sect2> </sect1> + diff --git a/chapter05/udev.xml b/chapter05/udev.xml deleted file mode 100644 index 0809dfd53..000000000 --- a/chapter05/udev.xml +++ /dev/null @@ -1,40 +0,0 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> -<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ - <!ENTITY % general-entities SYSTEM "../general.ent"> - %general-entities; -]> -<sect1 id="ch-tools-udev" role="wrap"> -<title>Udev-&udev-version;</title> -<?dbhtml filename="udev.html"?> - -<sect2 role="package"><title/> - -<segmentedlist> -<segtitle>&buildtime;</segtitle> -<segtitle>&diskspace;</segtitle> -<seglistitem><seg>0.2 SBU</seg><seg>5.2 MB</seg></seglistitem> -</segmentedlist> - -</sect2> - -<sect2 role="installation"> -<title>Installation of Udev</title> - -<para>The following patch makes Udev respect the DESTDIR variable:</para> - -<screen><userinput>patch -Np1 -i ../udev-&udev-version;-DESTDIR-1.patch</userinput></screen> - -<para>Now compile Udev:</para> - -<screen><userinput>make prefix=/tools udevdir=/dev</userinput></screen> - -<para>Install the package:</para> - -<screen><userinput>make DESTDIR=/tools udevdir=/dev install</userinput></screen> - -<screen><userinput>cp ../udev-config-2.permissions /tools/etc/udev/permissions.d/00-lfs.permissions -cp ../udev-config-1.rules /tools/etc/udev/rules.d/00-lfs.rules</userinput></screen> - -</sect2> - -</sect1> diff --git a/chapter05/util-linux.xml b/chapter05/util-linux.xml index 4349f326f..1c0ae3c19 100644 --- a/chapter05/util-linux.xml +++ b/chapter05/util-linux.xml @@ -7,7 +7,12 @@ <title>Util-linux-&util-linux-version;</title> <?dbhtml filename="util-linux.html"?> +<indexterm zone="ch-tools-util-linux"> +<primary sortas="a-Util-linux">Util-linux</primary> +<secondary>tools</secondary></indexterm> + <sect2 role="package"><title/> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/util-linux.xml" xpointer="xpointer(/sect1/sect2[1]/para[1])"/> <segmentedlist> <segtitle>&buildtime;</segtitle> @@ -15,12 +20,16 @@ <seglistitem><seg>0.2 SBU</seg><seg>16 MB</seg></seglistitem> </segmentedlist> +<xi:include xmlns:xi="http://www.w3.org/2003/XInclude" href="../chapter06/util-linux.xml" xpointer="xpointer(/sect1/sect2[1]/segmentedlist[2])"/> + </sect2> <sect2 role="installation"> <title>Installation of Util-linux</title> -<para>Issue a sed sustitution:</para> +<para>Util-linux does not use the freshly installed headers and +libraries from the <filename class="directory">/tools</filename> +directory. This is fixed by altering the configure script:</para> <screen><userinput>sed -i 's@/usr/include@/tools/include@g' configure</userinput></screen> @@ -32,14 +41,23 @@ <screen><userinput>make -C lib</userinput></screen> -<para>Build the needed utilities:</para> +<para>Since only a couple of the utilities contained in this package +are needed, build only those:</para> <screen><userinput>make -C mount mount umount make -C text-utils more</userinput></screen> -<para>Now copy these programs to the temporary tools directory:</para> +<para>This package does not come with a test suite.</para> + +<para>Copy these programs to the temporary tools directory:</para> <screen><userinput>cp mount/{,u}mount text-utils/more /tools/bin</userinput></screen> </sect2> + +<sect2 role="content"><title/> +<para>Details on this package are located in <xref +linkend="contents-utillinux" role="."/></para> +</sect2> </sect1> + |