chapter06/gcc.xml

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
   4   <!ENTITY % general-entities SYSTEM "../general.ent">
   5   %general-entities;
   6 ]>
   7
   8 <sect1 id="ch-system-gcc" role="wrap">
   9   <?dbhtml filename="gcc.html"?>
  10
  11   <sect1info condition="script">
  12     <productname>gcc</productname>
  13     <productnumber>&gcc-version;</productnumber>
  14     <address>&gcc-url;</address>
  15   </sect1info>
  16
  17   <title>GCC-&gcc-version;</title>
  18
  19   <indexterm zone="ch-system-gcc">
  20     <primary sortas="a-GCC">GCC</primary>
  21   </indexterm>
  22
  23   <sect2 role="package">
  24     <title/>
  25
  26     <para>The GCC package contains the GNU compiler collection, which includes
  27     the C and C++ compilers.</para>
  28
  29     <segmentedlist>
  30       <segtitle>&buildtime;</segtitle>
  31       <segtitle>&diskspace;</segtitle>
  32
  33       <seglistitem>
  34         <seg>&gcc-ch6-sbu;</seg>
  35         <seg>&gcc-ch6-du;</seg>
  36       </seglistitem>
  37     </segmentedlist>
  38
  39   </sect2>
  40
  41   <sect2 role="installation">
  42     <title>Installation of GCC</title>
  43
  44     <para>If building on x86_64, change the default directory name for 64-bit
  45     libraries to <quote>lib</quote>:</para>
  46
  47 <screen><userinput remap="pre">case $(uname -m) in
  48   x86_64)
  49     sed -e '/m64=/s/lib64/lib/' \
  50         -i.orig gcc/config/i386/t-linux64
  51   ;;
  52 esac</userinput></screen>
  53
  54     <para>Remove the symlink created earlier as the final gcc includes will be
  55     installed here:</para>
  56
  57 <screen><userinput remap="pre">rm -f /usr/lib/gcc</userinput></screen>
  58
  59     <para>The GCC documentation recommends building GCC in a dedicated build directory:</para>
  60
  61 <screen><userinput remap="pre">mkdir -v build
  62 cd       build</userinput></screen>
  63
  64     <para>Prepare GCC for compilation:</para>
  65
  66 <screen><userinput remap="configure">SED=sed                               \
  67 ../configure --prefix=/usr            \
  68              --enable-languages=c,c++ \
  69              --disable-multilib       \
  70              --disable-bootstrap      \
  71              --with-system-zlib</userinput></screen>
  72
  73     <para>Note that for other languages, there are some prerequisites that
  74     are not yet available. See the
  75     <ulink url="&blfs-book;general/gcc.html">BLFS Book</ulink>
  76     for instructions on how to build all of GCC's supported languages.</para>
  77
  78     <variablelist>
  79       <title>The meaning of the new configure parameters:</title>
  80
  81       <varlistentry>
  82         <term><envar>SED=sed</envar></term>
  83         <listitem>
  84           <para>Setting this environment variable prevents a hard-coded
  85           path to /tools/bin/sed.</para>
  86         </listitem>
  87       </varlistentry>
  88
  89       <varlistentry>
  90         <term><parameter>--with-system-zlib</parameter></term>
  91         <listitem>
  92           <para>This switch tells GCC to link to the system installed copy of
  93           the Zlib library, rather than its own internal copy.</para>
  94         </listitem>
  95       </varlistentry>
  96     </variablelist>
  97
  98     <para>Compile the package:</para>
  99
 100 <screen><userinput remap="make">make</userinput></screen>
 101
 102     <important>
 103       <para>In this section, the test suite for GCC is considered
 104       critical. Do not skip it under any circumstance.</para>
 105     </important>
 106
 107    <para>One set of tests in the GCC test suite is known to exhaust the stack,
 108    so increase the stack size prior to running the tests:</para>
 109
 110 <screen><userinput remap="test">ulimit -s 32768</userinput></screen>
 111
 112     <para>Test the results, but do not stop at errors:</para>
 113
 114 <screen><userinput remap="test">make -k check</userinput></screen>
 115
 116     <para>To receive a summary of the test suite results, run:</para>
 117
 118 <screen><userinput remap="test">../contrib/test_summary</userinput></screen>
 119
 120     <para>For only the summaries, pipe the output through
 121     <userinput>grep -A7 Summ</userinput>.</para>
 122
 123     <para>Results can be compared with those located at <ulink
 124     url="&test-results;"/> and
 125     <ulink url="http://gcc.gnu.org/ml/gcc-testresults/"/>.</para>
 126
 127     <para>A few unexpected failures cannot always be avoided. The GCC developers
 128     are usually aware of these issues, but have not resolved them yet.
 129     In particular, five tests in the libstdc++ test suite are known to fail
 130     when running as the root user as we do here.
 131     Unless the test results are vastly different from those at the above URL,
 132     it is safe to continue.</para>
 133
 134     <note><para>
 135       On some combinations of kernel configuration and AMD processors
 136       there may be more than 1100 failures in the gcc.target/i386/mpx
 137       tests (which are designed to test the MPX option on recent
 138       Intel processors). These can safely be ignored on AMD
 139       processors.
 140     </para></note>
 141
 142     <para>Install the package:</para>
 143
 144 <screen><userinput remap="install">make install</userinput></screen>
 145
 146     <para>Create a symlink required by the <ulink
 147     url="http://refspecs.linuxfoundation.org/FHS_3.0/fhs/ch03s09.html">FHS</ulink>
 148     for "historical" reasons.</para>
 149
 150 <screen><userinput remap="install">ln -sv ../usr/bin/cpp /lib</userinput></screen>
 151
 152     <para>Many packages use the name <command>cc</command> to call the C
 153     compiler. To satisfy those packages, create a symlink:</para>
 154
 155 <screen><userinput remap="install">ln -sv gcc /usr/bin/cc</userinput></screen>
 156
 157     <para>Add a compatibility symlink to enable building programs with
 158     Link Time Optimization (LTO):</para>
 159
 160 <screen><userinput remap="install">install -v -dm755 /usr/lib/bfd-plugins
 161 ln -sfv ../../libexec/gcc/$(gcc -dumpmachine)/&gcc-version;/liblto_plugin.so \
 162         /usr/lib/bfd-plugins/</userinput></screen>
 163
 164     <para>Now that our final toolchain is in place, it is important to again ensure
 165     that compiling and linking will work as expected. We do this by performing
 166     the same sanity checks as we did earlier in the chapter:</para>
 167
 168     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 169     href="adjusting.xml"
 170     xpointer="xpointer(//*[@os='a'])"/>
 171
 172     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 173     href="adjusting.xml"
 174     xpointer="xpointer(//*[@os='b'])"/>
 175
 176     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 177     href="adjusting.xml"
 178     xpointer="xpointer(//*[@os='c'])"/>
 179
 180     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 181     href="adjusting.xml"
 182     xpointer="xpointer(//*[@os='d'])"/>
 183
 184     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 185     href="adjusting.xml"
 186     xpointer="xpointer(//*[@os='e'])"/>
 187
 188     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 189     href="adjusting.xml"
 190     xpointer="xpointer(//*[@os='f'])"/>
 191
 192 <screen><computeroutput>/usr/lib/gcc/x86_64-pc-linux-gnu/&gcc-version;/../../../../lib/crt1.o succeeded
 193 /usr/lib/gcc/x86_64-pc-linux-gnu/&gcc-version;/../../../../lib/crti.o succeeded
 194 /usr/lib/gcc/x86_64-pc-linux-gnu/&gcc-version;/../../../../lib/crtn.o succeeded</computeroutput></screen>
 195
 196   <para>Depending on your machine architecture, the above may differ slightly,
 197   the difference usually being the name of the directory
 198   after <filename class="directory">/usr/lib/gcc</filename>. The important
 199   thing to look for here is that <command>gcc</command> has found all three
 200   <filename>crt*.o</filename> files under the
 201   <filename class="directory">/usr/lib</filename> directory.</para>
 202
 203     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 204     href="adjusting.xml"
 205     xpointer="xpointer(//*[@os='g'])"/>
 206
 207 <screen><userinput>grep -B4 '^ /usr/include' dummy.log</userinput></screen>
 208
 209     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 210     href="adjusting.xml"
 211     xpointer="xpointer(//*[@os='h'])"/>
 212
 213 <screen><computeroutput>#include &lt;...&gt; search starts here:
 214  /usr/lib/gcc/x86_64-pc-linux-gnu/&gcc-version;/include
 215  /usr/local/include
 216  /usr/lib/gcc/x86_64-pc-linux-gnu/&gcc-version;/include-fixed
 217  /usr/include</computeroutput></screen>
 218
 219    <para>Again, note that the directory named after your target triplet may be
 220    different than the above, depending on your architecture.</para>
 221
 222     <note><para>As of version 4.3.0, GCC now unconditionally installs the
 223     <filename>limits.h</filename> file into the private
 224     <filename class="directory">include-fixed</filename> directory, and that
 225     directory is required to be in place.</para></note>
 226
 227     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 228     href="adjusting.xml"
 229     xpointer="xpointer(//*[@os='i'])"/>
 230
 231     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 232     href="adjusting.xml"
 233     xpointer="xpointer(//*[@os='j'])"/>
 234
 235     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 236     href="adjusting.xml"
 237     xpointer="xpointer(//*[@os='k'])"/>
 238
 239 <screen><computeroutput>SEARCH_DIR("/usr/x86_64-pc-linux-gnu/lib64")
 240 SEARCH_DIR("/usr/local/lib64")
 241 SEARCH_DIR("/lib64")
 242 SEARCH_DIR("/usr/lib64")
 243 SEARCH_DIR("/usr/x86_64-pc-linux-gnu/lib")
 244 SEARCH_DIR("/usr/local/lib")
 245 SEARCH_DIR("/lib")
 246 SEARCH_DIR("/usr/lib");</computeroutput></screen>
 247
 248    <para>A 32-bit system may see a few different directories. For example, here
 249    is the output from an i686 machine:</para>
 250
 251 <screen><computeroutput>SEARCH_DIR("/usr/i686-pc-linux-gnu/lib32")
 252 SEARCH_DIR("/usr/local/lib32")
 253 SEARCH_DIR("/lib32")
 254 SEARCH_DIR("/usr/lib32")
 255 SEARCH_DIR("/usr/i686-pc-linux-gnu/lib")
 256 SEARCH_DIR("/usr/local/lib")
 257 SEARCH_DIR("/lib")
 258 SEARCH_DIR("/usr/lib");</computeroutput></screen>
 259
 260     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 261     href="adjusting.xml"
 262     xpointer="xpointer(//*[@os='l'])"/>
 263
 264     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 265     href="adjusting.xml"
 266     xpointer="xpointer(//*[@os='m'])"/>
 267
 268     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 269     href="adjusting.xml"
 270     xpointer="xpointer(//*[@os='n'])"/>
 271
 272     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 273     href="adjusting.xml"
 274     xpointer="xpointer(//*[@os='o'])"/>
 275
 276     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 277     href="adjusting.xml"
 278     xpointer="xpointer(//*[@os='p'])"/>
 279
 280     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 281     href="adjusting.xml"
 282     xpointer="xpointer(//*[@os='q'])"/>
 283
 284     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 285     href="adjusting.xml"
 286     xpointer="xpointer(//*[@os='r'])"/>
 287
 288     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 289     href="adjusting.xml"
 290     xpointer="xpointer(//*[@os='s'])"/>
 291
 292     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 293     href="adjusting.xml"
 294     xpointer="xpointer(//*[@os='t'])"/>
 295
 296     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 297     href="adjusting.xml"
 298     xpointer="xpointer(//*[@os='u'])"/>
 299
 300     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 301     href="adjusting.xml"
 302     xpointer="xpointer(//*[@os='v'])"/>
 303
 304     <para>Finally, move a misplaced file:</para>
 305
 306 <screen><userinput remap="install">mkdir -pv /usr/share/gdb/auto-load/usr/lib
 307 mv -v /usr/lib/*gdb.py /usr/share/gdb/auto-load/usr/lib</userinput></screen>
 308
 309   </sect2>
 310
 311   <sect2 id="contents-gcc" role="content">
 312     <title>Contents of GCC</title>
 313
 314     <segmentedlist>
 315       <segtitle>Installed programs</segtitle>
 316       <segtitle>Installed libraries</segtitle>
 317       <segtitle>Installed directories</segtitle>
 318
 319       <seglistitem>
 320         <seg>c++, cc (link to gcc), cpp, g++, gcc,
 321         gcc-ar, gcc-nm, gcc-ranlib, and gcov</seg>
 322
 323         <seg>libasan.{a,so}, libatomic.{a,so}, libgcc.a, libgcc_eh.a,
 324         libgcc_s.so, libgcov.a, libgomp.{a,so}, libiberty.a, libitm.{a,so},
 325         liblto_plugin.so,
 326         libquadmath.{a,so}, libssp.{a,so},
 327         libssp_nonshared.a, libstdc++.{a,so}, libsupc++.a, and libtsan.{a,so}</seg>
 328
 329         <seg>/usr/include/c++, /usr/lib/gcc, /usr/libexec/gcc, and
 330         /usr/share/gcc-&gcc-version;</seg>
 331       </seglistitem>
 332     </segmentedlist>
 333
 334     <variablelist>
 335       <bridgehead renderas="sect3">Short Descriptions</bridgehead>
 336       <?dbfo list-presentation="list"?>
 337       <?dbhtml list-presentation="table"?>
 338
 339       <varlistentry id="c">
 340         <term><command>c++</command></term>
 341         <listitem>
 342           <para>The C++ compiler</para>
 343           <indexterm zone="ch-system-gcc c">
 344             <primary sortas="b-c++">c++</primary>
 345           </indexterm>
 346         </listitem>
 347       </varlistentry>
 348
 349       <varlistentry id="cc">
 350         <term><command>cc</command></term>
 351         <listitem>
 352           <para>The C compiler</para>
 353           <indexterm zone="ch-system-gcc cc">
 354             <primary sortas="b-cc">cc</primary>
 355           </indexterm>
 356         </listitem>
 357       </varlistentry>
 358
 359       <varlistentry id="cpp">
 360         <term><command>cpp</command></term>
 361         <listitem>
 362           <para>The C preprocessor; it is used by the compiler to expand the
 363           #include, #define, and similar statements in the source files</para>
 364           <indexterm zone="ch-system-gcc cpp">
 365             <primary sortas="b-cpp">cpp</primary>
 366           </indexterm>
 367         </listitem>
 368       </varlistentry>
 369
 370       <varlistentry id="g">
 371         <term><command>g++</command></term>
 372         <listitem>
 373           <para>The C++ compiler</para>
 374           <indexterm zone="ch-system-gcc g">
 375             <primary sortas="b-g++">g++</primary>
 376           </indexterm>
 377         </listitem>
 378       </varlistentry>
 379
 380       <varlistentry id="gcc">
 381         <term><command>gcc</command></term>
 382         <listitem>
 383           <para>The C compiler</para>
 384           <indexterm zone="ch-system-gcc gcc">
 385             <primary sortas="b-gcc">gcc</primary>
 386           </indexterm>
 387         </listitem>
 388       </varlistentry>
 389
 390       <varlistentry id="gcc-ar">
 391         <term><command>gcc-ar</command></term>
 392         <listitem>
 393           <para>A wrapper around <command>ar</command> that adds a
 394           plugin to the command line. This program is only used
 395           to add "link time optimization" and is not useful with the
 396           default build options</para>
 397           <indexterm zone="ch-system-gcc gcc-ar">
 398             <primary sortas="b-gcc-ar">gc-ar</primary>
 399           </indexterm>
 400         </listitem>
 401       </varlistentry>
 402
 403       <varlistentry id="gcc-nm">
 404         <term><command>gcc-nm</command></term>
 405         <listitem>
 406           <para>A wrapper around <command>nm</command> that adds a
 407           plugin to the command line. This program is only used
 408           to add "link time optimization" and is not useful with the
 409           default build options</para>
 410           <indexterm zone="ch-system-gcc gcc-nm">
 411             <primary sortas="b-gcc-nm">gc-nm</primary>
 412           </indexterm>
 413         </listitem>
 414       </varlistentry>
 415
 416       <varlistentry id="gcc-ranlib">
 417         <term><command>gcc-ranlib</command></term>
 418         <listitem>
 419           <para>A wrapper around <command>ranlib</command> that adds a
 420           plugin to the command line. This program is only used
 421           to add "link time optimization" and is not useful with the
 422           default build options</para>
 423           <indexterm zone="ch-system-gcc gcc-ranlib">
 424             <primary sortas="b-gcc-ranlib">gc-ranlib</primary>
 425           </indexterm>
 426         </listitem>
 427       </varlistentry>
 428
 429       <varlistentry id="gcov">
 430         <term><command>gcov</command></term>
 431         <listitem>
 432           <para>A coverage testing tool; it is used to analyze programs to
 433           determine where optimizations will have the most effect</para>
 434           <indexterm zone="ch-system-gcc gcov">
 435             <primary sortas="b-gcov">gcov</primary>
 436           </indexterm>
 437         </listitem>
 438       </varlistentry>
 439
 440       <varlistentry id="libasan">
 441         <term><command>libasan</command></term>
 442         <listitem>
 443           <para>The Address Sanitizer runtime library</para>
 444           <indexterm zone="ch-system-gcc libasan">
 445             <primary sortas="b-libasan">libasan</primary>
 446           </indexterm>
 447         </listitem>
 448       </varlistentry>
 449
 450       <varlistentry id="libgcc">
 451         <term><filename class="libraryfile">libgcc</filename></term>
 452         <listitem>
 453           <para>Contains run-time support for <command>gcc</command></para>
 454           <indexterm zone="ch-system-gcc libgcc">
 455             <primary sortas="c-libgcc">libgcc</primary>
 456           </indexterm>
 457         </listitem>
 458       </varlistentry>
 459
 460       <varlistentry id="libgcov">
 461         <term><filename class="libraryfile">libgcov</filename></term>
 462         <listitem>
 463           <para>This library is linked in to a program when GCC is instructed
 464           to enable profiling</para>
 465           <indexterm zone="ch-system-gcc libgcov">
 466             <primary sortas="c-libgcov">libgcov</primary>
 467           </indexterm>
 468         </listitem>
 469       </varlistentry>
 470
 471       <varlistentry id="libgomp">
 472         <term><filename class="libraryfile">libgomp</filename></term>
 473         <listitem>
 474           <para>GNU implementation of the OpenMP API for multi-platform
 475           shared-memory parallel programming in C/C++ and Fortran</para>
 476           <indexterm zone="ch-system-gcc libgomp">
 477             <primary sortas="c-libgomp">libgomp</primary>
 478           </indexterm>
 479         </listitem>
 480       </varlistentry>
 481
 482       <varlistentry id="libiberty">
 483         <term><filename class="libraryfile">libiberty</filename></term>
 484         <listitem>
 485           <para>Contains routines used by various GNU programs, including
 486           <command>getopt</command>, <command>obstack</command>,
 487           <command>strerror</command>, <command>strtol</command>, and
 488           <command>strtoul</command></para>
 489           <indexterm zone="ch-system-gcc libiberty">
 490             <primary sortas="c-libiberty">libiberty</primary>
 491           </indexterm>
 492         </listitem>
 493       </varlistentry>
 494
 495       <varlistentry id="liblto_plugin">
 496         <term><filename class="libraryfile">liblto_plugin</filename></term>
 497         <listitem>
 498           <para>GCC's Link Time Optimization (LTO) plugin allows GCC to perform
 499           optimizations across compilation units</para>
 500           <indexterm zone="ch-system-gcc liblto_plugin">
 501             <primary sortas="c-liblto_plugin">liblto_plugin</primary>
 502           </indexterm>
 503         </listitem>
 504       </varlistentry>
 505
 506       <varlistentry id="libquadmath">
 507         <term><filename class="libraryfile">libquadmath</filename></term>
 508         <listitem>
 509           <para>GCC Quad Precision Math Library API</para>
 510           <indexterm zone="ch-system-gcc libquadmath">
 511             <primary sortas="c-libquadmath">libquadmath</primary>
 512           </indexterm>
 513         </listitem>
 514       </varlistentry>
 515
 516       <varlistentry id="libssp">
 517         <term><filename class="libraryfile">libssp</filename></term>
 518         <listitem>
 519           <para>Contains routines supporting GCC's stack-smashing protection
 520           functionality</para>
 521           <indexterm zone="ch-system-gcc libssp">
 522             <primary sortas="c-libssp">libssp</primary>
 523           </indexterm>
 524         </listitem>
 525       </varlistentry>
 526
 527       <varlistentry id="libstdc">
 528         <term><filename class="libraryfile">libstdc++</filename></term>
 529         <listitem>
 530           <para>The standard C++ library</para>
 531           <indexterm zone="ch-system-gcc libstdc">
 532             <primary sortas="c-libstdc++">libstdc++</primary>
 533           </indexterm>
 534         </listitem>
 535       </varlistentry>
 536
 537       <varlistentry id="libsupc">
 538         <term><filename class="libraryfile">libsupc++</filename></term>
 539         <listitem>
 540           <para>Provides supporting routines for the C++ programming
 541           language</para>
 542           <indexterm zone="ch-system-gcc libsupc">
 543             <primary sortas="c-libsupc++">libsupc++</primary>
 544           </indexterm>
 545         </listitem>
 546       </varlistentry>
 547
 548       <varlistentry id="libtsan">
 549         <term><filename class="libraryfile">libtsan</filename></term>
 550         <listitem>
 551           <para>The Thread Sanitizer runtime library</para>
 552           <indexterm zone="ch-system-gcc libtsan">
 553             <primary sortas="c-libtsan">libtsan</primary>
 554           </indexterm>
 555         </listitem>
 556       </varlistentry>
 557
 558     </variablelist>
 559
 560   </sect2>
 561
 562 </sect1>