source: chapter05/gcc-pass1.xml@ a3e320b9

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../general.ent">
  %general-entities;
]>

<sect1 id="ch-tools-gcc-pass1" role="wrap">
  <?dbhtml filename="gcc-pass1.html"?>

  <sect1info condition="script">
    <productname>gcc</productname>
    <productnumber>&gcc-version;</productnumber>
    <address>&gcc-url;</address>
  </sect1info>

  <title>GCC-&gcc-version; - Pass 1</title>

  <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>
      <segtitle>&diskspace;</segtitle>

      <seglistitem>
        <seg>&gcc-ch5p1-sbu;</seg>
        <seg>&gcc-ch5p1-du;</seg>
      </seglistitem>
    </segmentedlist>

  </sect2>

  <sect2 role="installation">
    <title>Installation of GCC</title>

    <para>The GCC documentation recommends building GCC outside of the
    source directory in a dedicated build directory:</para>

<screen><userinput>mkdir -v ../gcc-build
cd ../gcc-build</userinput></screen>

    <para>Set the --with-arch flag if the machine is x86:</para>

<screen><userinput>test $(uname -m | grep i?86) &amp;&amp; WITHARCH="--with-arch=i486"</userinput></screen>

    <para>Prepare GCC for compilation:</para>

<screen><userinput>CC="gcc -B/usr/bin/" ../gcc-&gcc-version;/configure --prefix=/tools \
    --with-local-prefix=/tools --disable-nls --disable-shared \
    --enable-languages=c --disable-multilib \
    $WITHARCH
unset WITHARCH</userinput></screen>

    <variablelist>
      <title>The meaning of the configure options:</title>

      <varlistentry>
        <term><envar>CC="gcc -B/usr/bin/"</envar></term>
        <listitem>
          <para>This forces <command>gcc</command> to prefer the linker from
          the host in <filename class="directory">/usr/bin</filename>. This
          is necessary on some hosts where the new <command>ld</command>
          built in the previous section is not compatible with the host's
          <command>gcc</command>.</para>
        </listitem>
      </varlistentry>

      <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>--disable-shared</parameter></term>
        <listitem>
          <para>This forces gcc to link its internal libraries statically. We do this
          to avoid possible issues with the host system.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--enable-languages=c</parameter></term>
        <listitem>
          <para>This option ensures that only the C compiler is built.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--disable-multilib</parameter></term>
        <listitem>
          <para>We currently only want to build support for 64-bit libraries.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><parameter>--with-arch=i486</parameter></term>
        <listitem>
          <para>On x86 machines Glibc-&glibc-version; needs to be built for a
          minimum architecture of <quote>i486</quote>. In fact, Glibc developers suggest
          setting the compiler flag <parameter>-march=i486</parameter> when compiling it.
          However, by using the above parameter for the GCC build, we can set a default
          value for <parameter>-march</parameter> at the compiler level, ensuring that
          the entire system is built consistently, i.e., for the same cpu-type.
          Of course, values greater or more specific than <quote>i486</quote> could be
          used. See <command>man gcc</command> for other acceptable cpu-types.
          Keep in mind that using an incompatible cpu-type for the machine will result
          in breakage. The advantage of <quote>i486</quote> is that it is a generic
          option and will work for all modern x86 machines.</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>The following command will compile GCC not once, but 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 is called
    <quote>bootstrapping</quote>. Building GCC in this way ensures that it was
    compiled correctly and is now the default configuration for the released
    package. Continue with compiling by running:</para>

<screen><userinput>make</userinput></screen>

    <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>Using <command>--disable-shared</command> means that the file
    <filename class="libraryfile">libgcc_eh.a</filename>
    isn't created and installed. The next package, Glibc, depends on this 
    library as it uses <command>-lgcc_eh</command> within its build system.
    We can satisfy that dependency by creating a symlink to
    <filename class="libraryfile">libgcc.a</filename>, since that file will
    end up containing the objects normally contained in
    <filename class="libraryfile">libgcc_eh.a</filename>.</para>

<screen><userinput>ln -vs libgcc.a `gcc -print-libgcc-file-name | \
    sed 's/libgcc/&amp;_eh/'`</userinput></screen>

    <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 -vs 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>