source: general/prog/gcc.xml@ 907a269

<?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;

  <!ENTITY gcc-download-http  "&gnu-http;/gcc/gcc-&gcc-version;/gcc-&gcc-version;.tar.xz">
  <!ENTITY gcc-download-ftp   "&gnu-ftp;/gcc/gcc-&gcc-version;/gcc-&gcc-version;.tar.xz">
  <!-- Update this also on the grub-uefi page -->
  <!ENTITY gcc-md5sum         "43e4de77f2218c83ca675257ea1af9ef">
  <!ENTITY gcc-size           "83 MB">
  <!ENTITY gcc-buildsize      "9.6 GB (2.4 GB installed with all listed languages; add 1.4 GB for tests)">
  <!ENTITY gcc-time           "32 SBU (add 55 SBU for tests; both with parallelism=4)">
]>

<sect1 id="gcc" xreflabel="GCC-&gcc-version;">
  <?dbhtml filename="gcc.html" ?>


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

  <indexterm zone="gcc">
    <primary sortas="a-gcc-5-0">GCC-&gcc-version;</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to GCC</title>

    <para>
      The <application>GCC</application> package contains the GNU Compiler
      Collection. This page describes the installation of compilers for the
      following languages: C, C++, Fortran, Objective C, Objective C++, Go, and Modula2.
      Since C and C++ are installed in LFS, this page is either for upgrading
      C and C++, or for installing additional compilers.
    </para>

    <note>
      <para>
        Additional languages, among which D and Ada, are available in the
        collection. D and Ada have a binary bootstrap requirement for the first
        installation, so their installation is not described here. To install
        them, you can proceed along the same lines as below after installing
        the corresponding compiler from a binary package, adding
        <option>ada</option> or <option>d</option> to the
        <parameter>--enable-languages</parameter> line.
      </para>
    </note>

    &lfs113_checked;

    <caution>
      <para>
        If you are upgrading <application>GCC</application> from any other
        version prior to &gcc-version;, then you must be careful compiling 3rd
        party kernel modules. You should ensure that the kernel and all its
        native modules are also compiled using the same version of
        <application>GCC</application> that you use to build the 3rd party module.
        This issue does not affect native kernel (and kernel modules) updates,
        as the instructions below are a complete reinstallation of
        <application>GCC</application>. If you have existing 3rd party modules
        installed, ensure they are recompiled using the updated version of
        <application>GCC</application>. As always, never update the kernel
        headers from the ones used when <application>Glibc</application> was
        compiled during LFS.
      </para>
<!--
      <para>
        Some system headers need to be fixed to be used with GCC. This is done
        during the installation of GCC, and the <quote>fixed</quote> headers
        are installed in <filename class="directory">
        /usr/lib/gcc/&lt;machine triplet&gt;/&lt;GCC version&gt;/include-fixed
        </filename>. This is harmless if GCC is built during the LFS stage. But
        if you reinstall GCC in BLFS, some of the BLFS packages may be
        <quote>fixed</quote>. If one of those packages is reinstalled
        afterwards, the <quote>fixed</quote> headers are not updated, which may
        lead to version mismatches. In case that happens, the
        <quote>fixed</quote> headers must be updated by running (as
        <systemitem class="username">root</systemitem>):
        <command>
         /usr/libexec/gcc/x86_64-pc-linux-gnu/&gcc-version;/install-tools/mkheaders
        </command>. The machine triplet may be different on a 32-bit system.
      </para>
-->
    </caution>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&gcc-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&gcc-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &gcc-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &gcc-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &gcc-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &gcc-time;
        </para>
      </listitem>
    </itemizedlist>
<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Optional patch when adding Go to the desired language list:
          <ulink url="&patch-root;/gcc-&gcc-version;-fix_go_version-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <bridgehead renderas="sect3">GCC Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gdb"/>,
      <xref linkend="valgrind"/> (for tests), and
      <ulink url="https://repo.or.cz/isl.git">ISL</ulink> (to enable graphite optimization)
    </para>

    <para condition="html" role="usernotes">
      Editor Notes: <ulink url="&blfs-wiki;/gcc"/>
    </para>

  </sect2>

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

    <important>
      <para>
        Even if you specify only languages other than C and C++ to the
        <command>./configure</command> command below, the
        installation process will overwrite your existing
        <application>GCC</application> C and C++ compilers and libraries.
        Running the full suite of tests is recommended.
      </para>

      <para>
        Do not continue with the <command>make install</command> command
        until you are confident the build was successful. You can compare your
        test results with those found at <ulink
        url="https://gcc.gnu.org/ml/gcc-testresults/"/>. You may also want to
        refer to the information found in the <application>GCC</application>
        section of Chapter 8 in the LFS book (<ulink
        url="&lfs-root;/chapter08/gcc.html"/>).
      </para>
    </important>

    <para>
      The instructions below are intentionally performing a
      <quote>bootstrap</quote> process. Bootstrapping is needed for robustness
      and is highly recommended when upgrading the compilers version. To disable
      bootstrap anyway, add <parameter>--disable-bootstrap</parameter> to the
      <command>./configure</command> options below.
    </para>
<!--
    <para>
      Some packages checks on the phrase <literal>gccgo</literal> in the output
      of <command>go version</command> to see which kind of Go compiler is
      installed (gcc-go or golang). The absence of <literal>gccgo</literal> in
      that string makes them to assume the compiler is the golang which is wrong.
      If Go isn't in the list of desired languages, this patch can be skipped
      while it does not harm if applied anyway. Fix the Go part of gcc to show
      a valid version string when calling <command>go version</command> by
      applying a patch:
    </para>

<screen><userinput>patch -Np1 -i ../gcc-&gcc-version;-fix_go_version-1.patch</userinput></screen>
-->
    <para>
      Install <application>GCC</application> by running the following commands:
    </para>

<screen><userinput>case $(uname -m) in
  x86_64)
    sed -i.orig '/m64=/s/lib64/lib/' gcc/config/i386/t-linux64
  ;;
esac

mkdir build               &amp;&amp;
cd    build               &amp;&amp;

../configure              \
    --prefix=/usr         \
    --disable-multilib    \
    --with-system-zlib    \
    --enable-default-pie  \
    --enable-default-ssp  \
    --disable-fixincludes \
    --enable-languages=c,c++,fortran,go,objc,obj-c++,m2 &amp;&amp;
make</userinput></screen>

    <para>
      If you have installed additional packages such as
      <application>valgrind</application> and <application>gdb</application>,
      the <application>gcc</application> part of the test suite will run more
      tests than in LFS. Some of those will report FAIL and others XPASS
      (pass when expected to FAIL). As of gcc-13.1.0, about 60 FAIL occur
      in the <quote>guality</quote> suite, as well as miscellaneous failures
      throughout the rest of the test suite.
      If all the compilers above are built, there will be a little over 80 
      unexpected failures out of over 478,000 tests. To run the tests, issue:
    </para>

<screen><userinput>ulimit -s 32768 &amp;&amp;
make -k check</userinput></screen>
<!-- The command above may error out, so using && may prevent the summary
to be run. -->

    <para>
      The tests are very long, and the results may be hard to find in the
      logs, specially if you use parallel jobs with make. You can get a summary
      of the tests with:
    </para>

<screen><userinput>../contrib/test_summary</userinput></screen>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;

mkdir -pv /usr/share/gdb/auto-load/usr/lib              &amp;&amp;
mv -v /usr/lib/*gdb.py /usr/share/gdb/auto-load/usr/lib &amp;&amp;

chown -v -R root:root \
    /usr/lib/gcc/*linux-gnu/&gcc-version;/include{,-fixed}</userinput></screen>

    <para>
      Some packages expect to find the C preprocessor in
      <filename class="directory">/lib</filename> or may refer to the C compiler
      under the name <command>cc</command>. The following symbolic links are not
      needed if you have followed the LFS instructions, since they
      have been already created. If you do not have them on your system, issue
      as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>ln -v -sf ../usr/bin/cpp /lib          &amp;&amp;
ln -v -sf gcc /usr/bin/cc              &amp;&amp;
install -v -dm755 /usr/lib/bfd-plugins &amp;&amp;
ln -sfv ../../libexec/gcc/$(gcc -dumpmachine)/&gcc-version;/liblto_plugin.so /usr/lib/bfd-plugins/</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>mkdir build; cd build</command>: The
      <application>GCC</application> documentation recommends
      building the package in a dedicated build directory.
    </para>

    <para>
      <parameter>--disable-multilib</parameter>: This parameter ensures
      that files are created for the specific architecture of your computer.
    </para>

    <para>
      <parameter>--with-system-zlib</parameter>: Uses the system
      <application>zlib</application> instead of the bundled one.
      <application>zlib</application> is used for compressing
      and decompressing <application>GCC</application>'s intermediate
      language in LTO (Link Time Optimization) object files.
    </para>

    <para>
      <parameter>--enable-default-pie</parameter>: Makes the
      <option>-fpie</option> option the default when compiling programs.
      Together with the <xref linkend="gASLR"/> feature enabled in the kernel,
      this defeats some kind of attacks based on known memory layouts.
    </para>

    <para>
      <parameter>--enable-default-ssp</parameter>: Makes the
      <option>-fstack-protector-strong</option> option the default when
      compiling programs. <xref linkend="gSSP"/> is a technique preventing
      alteration of the program flow by corrupting the parameter stack.
    </para>

    <para>
      <parameter>--enable-languages=c,c++,fortran,go,objc,obj-c++,m2</parameter>:
      This command identifies which languages to build. You may modify
      this command to remove undesired languages.  GCC also supports Ada
      and D, but building GCC with Ada (or D) support needs an existing
      Ada (or D) compiler.  So they are not enabled here.
    </para>

    <para>
      <command>ulimit -s 32768</command>: This command prevents several
      tests from running out of stack space.
    </para>

    <para>
      <command>make -k check</command>: This command runs the test suite
      without stopping if any errors are encountered.
    </para>

    <para>
      <command>../contrib/test_summary</command>: This command will produce
      a summary of the test suite results. You can append <command>| grep
      -A7 Summ</command> to the command to produce an even more condensed
      version of the summary. You may also wish to redirect the output
      to a file for review and comparison later on.
    </para>

    <para>
      <command>mv -v /usr/lib/*gdb.py ...</command>: The installation
      stage puts some files used by <application>gdb</application> under the
      <filename class="directory">/usr/lib</filename> directory. This generates
      spurious error messages when performing <command>ldconfig</command>. This
      command moves the files to another location.
    </para>

    <para>
      <command>chown -v -R root:root /usr/lib/gcc/*linux-gnu/...</command>:
      If the package is built by a user other than root, the ownership of the
      installed <filename class="directory">include</filename> directory (and
      its content) will be incorrect. This command changes the ownership to the
      <systemitem class="username">root</systemitem> user and group.
    </para>

    <para>
      <option>--enable-host-shared --enable-languages=jit</option>:
      Build <systemitem class="library">libgccjit</systemitem>, a library
      for embedding GCC inside programs and libraries for generating machine
      code.  Despite <quote>JIT</quote> (just-in-time) in the name, the
      library can be used for AOT (ahead-of-time) compilation as well.
      <option>--enable-host-shared</option> is needed for building
      <systemitem class="library">libgccjit</systemitem>, but it
      significantly slows down GCC.  So
      <systemitem class="library">libgccjit</systemitem> should be built and
      installed separately, not as a part of the <quote>main</quote> GCC
      installation.  If you need this library, configure GCC with
      these two options and install the library by running
      <!-- from Arch, not tested -->
      <command>make -C gcc jit.install-common jit.install-info</command>
      as the &root; user.  This library is not used by any BLFS package,
      nor tested by the BLFS developers.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <para>
      Some program and library names and descriptions are not listed here,
      but can be found at
      <ulink url="&lfs-root;/chapter08/gcc.html#contents-gcc">LFS section
      for GCC</ulink> as they were
      initially installed during the building of LFS.
    </para>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          gccgo, gfortran, gm2, go, and gofmt, hard-linked to architecture
          specific names
        </seg>
        <seg>
          libgfortran.{so,a}, libgm2.{so,a}
          libgo.{so,a}, libgobegin.a, libgolibbegin.a,
          libobjc.{so,a}, and numerous other run-time libraries and executables
        </seg>
        <seg>
          /usr/lib/go
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="gccgo">
        <term><command>gccgo</command></term>
        <listitem>
          <para>
            is a GCC-based compiler for the <application>Go</application>
            language
          </para>
          <indexterm zone="gcc gccgo">
            <primary sortas="b-gccgo">gccgo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gm2">
        <term><command>gm2</command></term>
        <listitem>
          <para>
            is a GCC-based compiler for the
            <application>Modula-2</application> language
          </para>
          <indexterm zone="gcc gm2">
            <primary sortas="b-gm2">gm2</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="go">
        <term><command>go</command></term>
        <listitem>
          <para>
            is a tool for managing <application>Go</application> source code
          </para>
          <indexterm zone="gcc go">
            <primary sortas="b-go">go</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gofmt">
        <term><command>gofmt</command></term>
        <listitem>
          <para>
            is a tool for formatting <application>Go</application> source code
          </para>
          <indexterm zone="gcc gofmt">
            <primary sortas="b-gofmt">gofmt</primary>
          </indexterm>
        </listitem>
      </varlistentry>
      <!--
      <varlistentry id="gdc">
        <term><command>gdc</command></term>
        <listitem>
          <para>
            is a GCC-based compiler for the <application>D</application>
            language
          </para>
          <indexterm zone="gcc gdc">
            <primary sortas="b-gdc">gdc</primary>
          </indexterm>
        </listitem>
      </varlistentry>
      -->
      <varlistentry id="gfortran">
        <term><command>gfortran</command></term>
        <listitem>
          <para>
            is a GCC-based compiler for the <application>Fortran</application>
            language
          </para>
          <indexterm zone="gcc gfortran">
            <primary sortas="b-gfortran">gfortran</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>