Changeset 5620622


Ignore:
Timestamp:
09/28/2022 07:56:52 PM (19 months ago)
Author:
David Bryant <davidbryant@…>
Branches:
11.3, 11.3-rc1, 12.0, 12.0-rc1, 12.1, 12.1-rc1, bdubbs/gcc13, multilib, renodr/libudev-from-systemd, trunk, xry111/arm64, xry111/arm64-12.0, xry111/clfs-ng, xry111/loongarch, xry111/loongarch-12.0, xry111/loongarch-12.1, xry111/mips64el, xry111/pip3, xry111/rust-wip-20221008, xry111/update-glibc
Children:
199d14c
Parents:
dd7f9df
Message:

Polish up the prose in "Toolchain Technical Notes". Fix capitalization.
Rough edges remain. For instance, $LFS_TGT-ld is referenced, but not
clearly defined. Will need to discuss wirh other editors to resolve.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • part3intro/toolchaintechnotes.xml

    rdd7f9df r5620622  
    1212
    1313  <para>This section explains some of the rationale and technical details
    14   behind the overall build method. It is not essential to immediately
     14  behind the overall build method. Don't try to immediately
    1515  understand everything in this section. Most of this information will be
    16   clearer after performing an actual build. This section can be referred
    17   to at any time during the process.</para>
     16  clearer after performing an actual build. Come back and re-read this chapter
     17  at any time during the build process.</para>
    1818
    1919  <para>The overall goal of <xref linkend="chapter-cross-tools"/> and <xref
    20   linkend="chapter-temporary-tools"/> is to produce a temporary area that
    21   contains a known-good set of tools that can be isolated from the host system.
    22   By using <command>chroot</command>, the commands in the remaining chapters
    23   will be contained within that environment, ensuring a clean, trouble-free
     20  linkend="chapter-temporary-tools"/> is to produce a temporary area
     21  containing a set of tools that are known to be good, and that are isolated from the host system.
     22  By using the <command>chroot</command> command, the compilations in the remaining chapters
     23  will be isolated within that environment, ensuring a clean, trouble-free
    2424  build of the target LFS system. The build process has been designed to
    25   minimize the risks for new readers and to provide the most educational value
     25  minimize the risks for new readers, and to provide the most educational value
    2626  at the same time.</para>
    2727
    28   <para>The build process is based on the process of
     28  <para>This build process is based on
    2929  <emphasis>cross-compilation</emphasis>. Cross-compilation is normally used
    30   for building a compiler and its toolchain for a machine different from
    31   the one that is used for the build. This is not strictly needed for LFS,
     30  to build a compiler and its associated toolchain for a machine different from
     31  the one that is used for the build. This is not strictly necessary for LFS,
    3232  since the machine where the new system will run is the same as the one
    33   used for the build. But cross-compilation has the great advantage that
     33  used for the build. But cross-compilation has one great advantage:
    3434  anything that is cross-compiled cannot depend on the host environment.</para>
    3535
    … …  
    4040    <note>
    4141      <para>
    42         The LFS book is not, and does not contain a general tutorial to
    43         build a cross (or native) toolchain. Don't use the command in the
    44         book for a cross toolchain which will be used for some purpose other
     42        The LFS book is not (and does not contain) a general tutorial to
     43        build a cross (or native) toolchain. Don't use the commands in the
     44        book for a cross toolchain for some purpose other
    4545        than building LFS, unless you really understand what you are doing.
    4646      </para>
    4747    </note>
    4848
    49     <para>Cross-compilation involves some concepts that deserve a section on
    50     their own. Although this section may be omitted in a first reading,
    51     coming back to it later will be beneficial to your full understanding of
     49    <para>Cross-compilation involves some concepts that deserve a section of
     50    their own. Although this section may be omitted on a first reading,
     51    coming back to it later will help you gain a fuller understanding of
    5252    the process.</para>
    5353
    54     <para>Let us first define some terms used in this context:</para>
     54    <para>Let us first define some terms used in this context.</para>
    5555
    5656    <variablelist>
    57       <varlistentry><term>build</term><listitem>
     57      <varlistentry><term>The build</term><listitem>
    5858        <para>is the machine where we build programs. Note that this machine
    59         is referred to as the <quote>host</quote> in other
    60         sections.</para></listitem>
     59        is also referred to as the <quote>host</quote>.</para></listitem>
    6160      </varlistentry>
    6261
    63       <varlistentry><term>host</term><listitem>
     62      <varlistentry><term>The host</term><listitem>
    6463        <para>is the machine/system where the built programs will run. Note
    6564        that this use of <quote>host</quote> is not the same as in other
    … …  
    6766      </varlistentry>
    6867
    69       <varlistentry><term>target</term><listitem>
     68      <varlistentry><term>The target</term><listitem>
    7069        <para>is only used for compilers. It is the machine the compiler
    71         produces code for. It may be different from both build and
    72         host.</para></listitem>
     70        produces code for. It may be different from both the build and
     71        the host.</para></listitem>
    7372      </varlistentry>
    7473
    … …  
    7675
    7776    <para>As an example, let us imagine the following scenario (sometimes
    78     referred to as <quote>Canadian Cross</quote>): we may have a
     77    referred to as <quote>Canadian Cross</quote>): we have a
    7978    compiler on a slow machine only, let's call it machine A, and the compiler
    80     ccA. We may have also a fast machine (B), but with no compiler, and we may
    81     want to produce code for another slow machine (C). To build a
    82     compiler for machine C, we would have three stages:</para>
     79    ccA. We also have a fast machine (B), but no compiler for (B), and we
     80    want to produce code for a third, slow machine (C). We will build a
     81    compiler for machine C in three stages.</para>
    8382
    8483    <informaltable align="center">
    … …  
    9695          <row>
    9796            <entry>1</entry><entry>A</entry><entry>A</entry><entry>B</entry>
    98             <entry>build cross-compiler cc1 using ccA on machine A</entry>
     97            <entry>Build cross-compiler cc1 using ccA on machine A.</entry>
    9998          </row>
    10099          <row>
    101100            <entry>2</entry><entry>A</entry><entry>B</entry><entry>C</entry>
    102             <entry>build cross-compiler cc2 using cc1 on machine A</entry>
     101            <entry>Build cross-compiler cc2 using cc1 on machine A.</entry>
    103102          </row>
    104103          <row>
    105104            <entry>3</entry><entry>B</entry><entry>C</entry><entry>C</entry>
    106             <entry>build compiler ccC using cc2 on machine B</entry>
     105            <entry>Build compiler ccC using cc2 on machine B.</entry>
    107106          </row>
    108107        </tbody>
    … …  
    110109    </informaltable>
    111110
    112     <para>Then, all the other programs needed by machine C can be compiled
     111    <para>Then, all the programs needed by machine C can be compiled
    113112    using cc2 on the fast machine B. Note that unless B can run programs
    114     produced for C, there is no way to test the built programs until machine
    115     C itself is running. For example, for testing ccC, we may want to add a
     113    produced for C, there is no way to test the newly built programs until machine
     114    C itself is running. For example, to run a test suite on ccC, we may want to add a
    116115    fourth stage:</para>
    117116
    … …  
    130129          <row>
    131130            <entry>4</entry><entry>C</entry><entry>C</entry><entry>C</entry>
    132             <entry>rebuild  and test ccC using itself on machine C</entry>
     131            <entry>Rebuild and test ccC using ccC on machine C.</entry>
    133132          </row>
    134133        </tbody>
    … …  
    148147    <note>
    149148      <para>Almost all the build systems use names of the form
    150       cpu-vendor-kernel-os referred to as the machine triplet. An astute
     149      cpu-vendor-kernel-os, referred to as the machine triplet. An astute
    151150      reader may wonder why a <quote>triplet</quote> refers to a four component
    152       name. The reason is history: initially, three component names were enough
    153       to designate a machine unambiguously, but with new machines and systems
    154       appearing, that proved insufficient. The word <quote>triplet</quote>
     151      name. The reason is historical: initially, three component names were enough
     152      to designate a machine unambiguously, but as new machines and systems
     153      proliferated, that proved insufficient. The word <quote>triplet</quote>
    155154      remained. A simple way to determine your machine triplet is to run
    156155      the <command>config.guess</command>
    … …  
    159158      the output. For example, for a 32-bit Intel processor the
    160159      output will be <emphasis>i686-pc-linux-gnu</emphasis>. On a 64-bit
    161       system it will be <emphasis>x86_64-pc-linux-gnu</emphasis>.</para>
    162 
    163       <para>Also be aware of the name of the platform's dynamic linker, often
     160      system it will be <emphasis>x86_64-pc-linux-gnu</emphasis>. On most
     161      Linux systems the even simpler <command>gcc -dumpmachine</command> command
     162      will give you the same information.</para>
     163
     164      <para>You should also be aware of the name of the platform's dynamic linker, often
    164165      referred to as the dynamic loader (not to be confused with the standard
    165166      linker <command>ld</command> that is part of binutils). The dynamic linker
    166       provided by Glibc finds and loads the shared libraries needed by a
     167      provided by package glibc finds and loads the shared libraries needed by a
    167168      program, prepares the program to run, and then runs it. The name of the
    168169      dynamic linker for a 32-bit Intel machine is <filename
    169       class="libraryfile">ld-linux.so.2</filename> and is <filename
    170       class="libraryfile">ld-linux-x86-64.so.2</filename> for 64-bit systems. A
     170      class="libraryfile">ld-linux.so.2</filename>; it's <filename
     171      class="libraryfile">ld-linux-x86-64.so.2</filename> on 64-bit systems. A
    171172      sure-fire way to determine the name of the dynamic linker is to inspect a
    172173      random binary from the host system by running: <userinput>readelf -l
    173174      &lt;name of binary&gt; | grep interpreter</userinput> and noting the
    174175      output. The authoritative reference covering all platforms is in the
    175       <filename>shlib-versions</filename> file in the root of the Glibc source
     176      <filename>shlib-versions</filename> file in the root of the glibc source
    176177      tree.</para>
    177178    </note>
    … …  
    179180    <para>In order to fake a cross compilation in LFS, the name of the host triplet
    180181    is slightly adjusted by changing the &quot;vendor&quot; field in the
    181     <envar>LFS_TGT</envar> variable. We also use the
     182    <envar>LFS_TGT</envar> variable so it says &quot;lfs&quot;. We also use the
    182183    <parameter>--with-sysroot</parameter> option when building the cross linker and
    183184    cross compiler to tell them where to find the needed host files. This
    184185    ensures that none of the other programs built in <xref
    185186    linkend="chapter-temporary-tools"/> can link to libraries on the build
    186     machine. Only two stages are mandatory, and one more for tests:</para>
     187    machine. Only two stages are mandatory, plus one more for tests.</para>
    187188
    188189    <informaltable align="center">
    … …  
    200201          <row>
    201202            <entry>1</entry><entry>pc</entry><entry>pc</entry><entry>lfs</entry>
    202             <entry>build cross-compiler cc1 using cc-pc on pc</entry>
     203            <entry>Build cross-compiler cc1 using cc-pc on pc.</entry>
    203204          </row>
    204205          <row>
    205206            <entry>2</entry><entry>pc</entry><entry>lfs</entry><entry>lfs</entry>
    206             <entry>build compiler cc-lfs using cc1 on pc</entry>
     207            <entry>Build compiler cc-lfs using cc1 on pc.</entry>
    207208          </row>
    208209          <row>
    209210            <entry>3</entry><entry>lfs</entry><entry>lfs</entry><entry>lfs</entry>
    210             <entry>rebuild and test cc-lfs using itself on lfs</entry>
     211            <entry>Rebuild and test cc-lfs using cc-lfs on lfs.</entry>
    211212          </row>
    212213        </tbody>
    … …  
    214215    </informaltable>
    215216
    216     <para>In the above table, <quote>on pc</quote> means the commands are run
     217    <para>In the preceding table, <quote>on pc</quote> means the commands are run
    217218    on a machine using the already installed distribution. <quote>On
    218219    lfs</quote> means the commands are run in a chrooted environment.</para>
    … …  
    220221    <para>Now, there is more about cross-compiling: the C language is not
    221222    just a compiler, but also defines a standard library. In this book, the
    222     GNU C library, named glibc, is used. This library must
    223     be compiled for the lfs machine, that is, using the cross compiler cc1.
     223    GNU C library, named glibc, is used (there is an alternative, &quot;musl&quot;). This library must
     224    be compiled for the LFS machine; that is, using the cross compiler cc1.
    224225    But the compiler itself uses an internal library implementing complex
    225     instructions not available in the assembler instruction set. This
    226     internal library is named libgcc, and must be linked to the glibc
     226    subroutines for functions not available in the assembler instruction set. This
     227    internal library is named libgcc, and it must be linked to the glibc
    227228    library to be fully functional! Furthermore, the standard library for
    228     C++ (libstdc++) also needs being linked to glibc. The solution to this
    229     chicken and egg problem is to first build a degraded cc1 based libgcc,
    230     lacking some functionalities such as threads and exception handling, then
    231     build glibc using this degraded compiler (glibc itself is not
    232     degraded), then build libstdc++. But this last library will lack the
    233     same functionalities as libgcc.</para>
    234 
    235     <para>This is not the end of the story: the conclusion of the preceding
     229    C++ (libstdc++) must also be linked with glibc. The solution to this
     230    chicken and egg problem is first to build a degraded cc1-based libgcc,
     231    lacking some functionalities such as threads and exception handling, and then
     232    to build glibc using this degraded compiler (glibc itself is not
     233    degraded), and also to build libstdc++. This last library will lack some of the
     234    functionality of libgcc.</para>
     235
     236    <para>This is not the end of the story: the upshot of the preceding
    236237    paragraph is that cc1 is unable to build a fully functional libstdc++, but
    237238    this is the only compiler available for building the C/C++ libraries
    238239    during stage 2! Of course, the compiler built during stage 2, cc-lfs,
    239240    would be able to build those libraries, but (1) the build system of
    240     GCC does not know that it is usable on pc, and (2) using it on pc
    241     would be at risk of linking to the pc libraries, since cc-lfs is a native
    242     compiler. So we have to build libstdc++ later, in chroot.</para>
     241    gcc does not know that it is usable on pc, and (2) using it on pc
     242    would create a risk of linking to the pc libraries, since cc-lfs is a native
     243    compiler. So we have to re-build libstdc++ later, in the chroot environment.</para>
    243244
    244245  </sect2>
    … …  
    253254
    254255    <para>Binutils is installed first because the <command>configure</command>
    255     runs of both GCC and Glibc perform various feature tests on the assembler
     256    runs of both gcc and glibc perform various feature tests on the assembler
    256257    and linker to determine which software features to enable or disable. This
    257     is more important than one might first realize. An incorrectly configured
    258     GCC or Glibc can result in a subtly broken toolchain, where the impact of
     258    is more important than one might realize at first. An incorrectly configured
     259    gcc or glibc can result in a subtly broken toolchain, where the impact of
    259260    such breakage might not show up until near the end of the build of an
    260261    entire distribution. A test suite failure will usually highlight this error
    … …  
    275276    will show all the files successfully opened during the linking.</para>
    276277
    277     <para>The next package installed is GCC. An example of what can be
     278    <para>The next package installed is gcc. An example of what can be
    278279    seen during its run of <command>configure</command> is:</para>
    279280
    … …  
    282283
    283284    <para>This is important for the reasons mentioned above. It also
    284     demonstrates that GCC's configure script does not search the PATH
     285    demonstrates that gcc's configure script does not search the PATH
    285286    directories to find which tools to use. However, during the actual
    286287    operation of <command>gcc</command> itself, the same search paths are not
    … …  
    296297
    297298    <para>Next installed are sanitized Linux API headers. These allow the
    298     standard C library (Glibc) to interface with features that the Linux
     299    standard C library (glibc) to interface with features that the Linux
    299300    kernel will provide.</para>
    300301
    301     <para>The next package installed is Glibc. The most important
    302     considerations for building Glibc are the compiler, binary tools, and
    303     kernel headers. The compiler is generally not an issue since Glibc will
     302    <para>The next package installed is glibc. The most important
     303    considerations for building glibc are the compiler, binary tools, and
     304    kernel headers. The compiler is generally not an issue since glibc will
    304305    always use the compiler relating to the <parameter>--host</parameter>
    305306    parameter passed to its configure script; e.g. in our case, the compiler
    … …  
    314315    and the use of the <parameter>-nostdinc</parameter> and
    315316    <parameter>-isystem</parameter> flags to control the compiler's include
    316     search path. These items highlight an important aspect of the Glibc
     317    search path. These items highlight an important aspect of the glibc
    317318    package&mdash;it is very self-sufficient in terms of its build machinery
    318319    and generally does not rely on toolchain defaults.</para>
    319320
    320     <para>As said above, the standard C++ library is compiled next, followed in
    321     <xref linkend="chapter-temporary-tools"/> by all the programs that need
    322     themselves to be built. The install step of all those packages uses the
    323     <envar>DESTDIR</envar> variable to have the
    324     programs land into the LFS filesystem.</para>
     321    <para>As mentioned above, the standard C++ library is compiled next, followed in
     322    <xref linkend="chapter-temporary-tools"/> by all the remaining programs that need
     323    to be cross compiled. The install step of all those packages uses the
     324    <envar>DESTDIR</envar> variable to force installation
     325    in the LFS filesystem.</para>
    325326
    326327    <para>At the end of <xref linkend="chapter-temporary-tools"/> the native
    327     lfs compiler is installed. First binutils-pass2 is built,
    328     with the same <envar>DESTDIR</envar> install as the other programs,
    329     then the second pass of GCC is constructed, omitting libstdc++
    330     and other non-important libraries.  Due to some weird logic in GCC's
     328    LFS compiler is installed. First binutils-pass2 is built,
     329    in the same <envar>DESTDIR</envar> directory as the other programs,
     330    then the second version of gcc is constructed, omitting libstdc++
     331    and other non-critical libraries.  Due to some weird logic in gcc's
    331332    configure script, <envar>CC_FOR_TARGET</envar> ends up as
    332     <command>cc</command> when the host is the same as the target, but is
     333    <command>cc</command> when the host is the same as the target, but
    333334    different from the build system. This is why
    334     <parameter>CC_FOR_TARGET=$LFS_TGT-gcc</parameter> is put explicitly into
    335     the configure options.</para>
     335    <parameter>CC_FOR_TARGET=$LFS_TGT-gcc</parameter> is declared explicitly
     336    as one of the configuration options.</para>
    336337
    337338    <para>Upon entering the chroot environment in <xref
Note: See TracChangeset for help on using the changeset viewer.