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="https://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, six 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="https://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 <!--  This appears to be obsolete
 223
 224     <note><para>As of version 4.3.0, GCC now unconditionally installs the
 225     <filename>limits.h</filename> file into the private
 226     <filename class="directory">include-fixed</filename> directory, and that
 227     directory is required to be in place.</para></note>
 228 -->
 229
 230     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 231     href="adjusting.xml"
 232     xpointer="xpointer(//*[@os='i'])"/>
 233
 234     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 235     href="adjusting.xml"
 236     xpointer="xpointer(//*[@os='j'])"/>
 237
 238     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 239     href="adjusting.xml"
 240     xpointer="xpointer(//*[@os='k'])"/>
 241
 242 <screen><computeroutput>SEARCH_DIR("/usr/x86_64-pc-linux-gnu/lib64")
 243 SEARCH_DIR("/usr/local/lib64")
 244 SEARCH_DIR("/lib64")
 245 SEARCH_DIR("/usr/lib64")
 246 SEARCH_DIR("/usr/x86_64-pc-linux-gnu/lib")
 247 SEARCH_DIR("/usr/local/lib")
 248 SEARCH_DIR("/lib")
 249 SEARCH_DIR("/usr/lib");</computeroutput></screen>
 250
 251    <para>A 32-bit system may see a few different directories. For example, here
 252    is the output from an i686 machine:</para>
 253
 254 <screen><computeroutput>SEARCH_DIR("/usr/i686-pc-linux-gnu/lib32")
 255 SEARCH_DIR("/usr/local/lib32")
 256 SEARCH_DIR("/lib32")
 257 SEARCH_DIR("/usr/lib32")
 258 SEARCH_DIR("/usr/i686-pc-linux-gnu/lib")
 259 SEARCH_DIR("/usr/local/lib")
 260 SEARCH_DIR("/lib")
 261 SEARCH_DIR("/usr/lib");</computeroutput></screen>
 262
 263     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 264     href="adjusting.xml"
 265     xpointer="xpointer(//*[@os='l'])"/>
 266
 267     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 268     href="adjusting.xml"
 269     xpointer="xpointer(//*[@os='m'])"/>
 270
 271     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 272     href="adjusting.xml"
 273     xpointer="xpointer(//*[@os='n'])"/>
 274
 275     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 276     href="adjusting.xml"
 277     xpointer="xpointer(//*[@os='o'])"/>
 278
 279     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 280     href="adjusting.xml"
 281     xpointer="xpointer(//*[@os='p'])"/>
 282
 283     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 284     href="adjusting.xml"
 285     xpointer="xpointer(//*[@os='q'])"/>
 286
 287     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 288     href="adjusting.xml"
 289     xpointer="xpointer(//*[@os='r'])"/>
 290
 291     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 292     href="adjusting.xml"
 293     xpointer="xpointer(//*[@os='s'])"/>
 294
 295     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 296     href="adjusting.xml"
 297     xpointer="xpointer(//*[@os='t'])"/>
 298
 299     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 300     href="adjusting.xml"
 301     xpointer="xpointer(//*[@os='u'])"/>
 302
 303     <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 304     href="adjusting.xml"
 305     xpointer="xpointer(//*[@os='v'])"/>
 306
 307     <para>Finally, move a misplaced file:</para>
 308
 309 <screen><userinput remap="install">mkdir -pv /usr/share/gdb/auto-load/usr/lib
 310 mv -v /usr/lib/*gdb.py /usr/share/gdb/auto-load/usr/lib</userinput></screen>
 311
 312   </sect2>
 313
 314   <sect2 id="contents-gcc" role="content">
 315     <title>Contents of GCC</title>
 316
 317     <segmentedlist>
 318       <segtitle>Installed programs</segtitle>
 319       <segtitle>Installed libraries</segtitle>
 320       <segtitle>Installed directories</segtitle>
 321
 322       <seglistitem>
 323         <seg>c++, cc (link to gcc), cpp, g++, gcc,
 324         gcc-ar, gcc-nm, gcc-ranlib, and gcov</seg>
 325
 326         <seg>libasan.{a,so}, libatomic.{a,so}, libgcc.a, libgcc_eh.a,
 327         libgcc_s.so, libgcov.a, libgomp.{a,so}, libiberty.a, libitm.{a,so},
 328         liblto_plugin.so,
 329         libquadmath.{a,so}, libssp.{a,so},
 330         libssp_nonshared.a, libstdc++.{a,so}, libsupc++.a, and libtsan.{a,so}</seg>
 331
 332         <seg>/usr/include/c++, /usr/lib/gcc, /usr/libexec/gcc, and
 333         /usr/share/gcc-&gcc-version;</seg>
 334       </seglistitem>
 335     </segmentedlist>
 336
 337     <variablelist>
 338       <bridgehead renderas="sect3">Short Descriptions</bridgehead>
 339       <?dbfo list-presentation="list"?>
 340       <?dbhtml list-presentation="table"?>
 341
 342       <varlistentry id="c">
 343         <term><command>c++</command></term>
 344         <listitem>
 345           <para>The C++ compiler</para>
 346           <indexterm zone="ch-system-gcc c">
 347             <primary sortas="b-c++">c++</primary>
 348           </indexterm>
 349         </listitem>
 350       </varlistentry>
 351
 352       <varlistentry id="cc">
 353         <term><command>cc</command></term>
 354         <listitem>
 355           <para>The C compiler</para>
 356           <indexterm zone="ch-system-gcc cc">
 357             <primary sortas="b-cc">cc</primary>
 358           </indexterm>
 359         </listitem>
 360       </varlistentry>
 361
 362       <varlistentry id="cpp">
 363         <term><command>cpp</command></term>
 364         <listitem>
 365           <para>The C preprocessor; it is used by the compiler to expand the
 366           #include, #define, and similar statements in the source files</para>
 367           <indexterm zone="ch-system-gcc cpp">
 368             <primary sortas="b-cpp">cpp</primary>
 369           </indexterm>
 370         </listitem>
 371       </varlistentry>
 372
 373       <varlistentry id="g">
 374         <term><command>g++</command></term>
 375         <listitem>
 376           <para>The C++ compiler</para>
 377           <indexterm zone="ch-system-gcc g">
 378             <primary sortas="b-g++">g++</primary>
 379           </indexterm>
 380         </listitem>
 381       </varlistentry>
 382
 383       <varlistentry id="gcc">
 384         <term><command>gcc</command></term>
 385         <listitem>
 386           <para>The C compiler</para>
 387           <indexterm zone="ch-system-gcc gcc">
 388             <primary sortas="b-gcc">gcc</primary>
 389           </indexterm>
 390         </listitem>
 391       </varlistentry>
 392
 393       <varlistentry id="gcc-ar">
 394         <term><command>gcc-ar</command></term>
 395         <listitem>
 396           <para>A wrapper around <command>ar</command> that adds a
 397           plugin to the command line. This program is only used
 398           to add "link time optimization" and is not useful with the
 399           default build options</para>
 400           <indexterm zone="ch-system-gcc gcc-ar">
 401             <primary sortas="b-gcc-ar">gc-ar</primary>
 402           </indexterm>
 403         </listitem>
 404       </varlistentry>
 405
 406       <varlistentry id="gcc-nm">
 407         <term><command>gcc-nm</command></term>
 408         <listitem>
 409           <para>A wrapper around <command>nm</command> that adds a
 410           plugin to the command line. This program is only used
 411           to add "link time optimization" and is not useful with the
 412           default build options</para>
 413           <indexterm zone="ch-system-gcc gcc-nm">
 414             <primary sortas="b-gcc-nm">gc-nm</primary>
 415           </indexterm>
 416         </listitem>
 417       </varlistentry>
 418
 419       <varlistentry id="gcc-ranlib">
 420         <term><command>gcc-ranlib</command></term>
 421         <listitem>
 422           <para>A wrapper around <command>ranlib</command> that adds a
 423           plugin to the command line. This program is only used
 424           to add "link time optimization" and is not useful with the
 425           default build options</para>
 426           <indexterm zone="ch-system-gcc gcc-ranlib">
 427             <primary sortas="b-gcc-ranlib">gc-ranlib</primary>
 428           </indexterm>
 429         </listitem>
 430       </varlistentry>
 431
 432       <varlistentry id="gcov">
 433         <term><command>gcov</command></term>
 434         <listitem>
 435           <para>A coverage testing tool; it is used to analyze programs to
 436           determine where optimizations will have the most effect</para>
 437           <indexterm zone="ch-system-gcc gcov">
 438             <primary sortas="b-gcov">gcov</primary>
 439           </indexterm>
 440         </listitem>
 441       </varlistentry>
 442
 443       <varlistentry id="libasan">
 444         <term><command>libasan</command></term>
 445         <listitem>
 446           <para>The Address Sanitizer runtime library</para>
 447           <indexterm zone="ch-system-gcc libasan">
 448             <primary sortas="b-libasan">libasan</primary>
 449           </indexterm>
 450         </listitem>
 451       </varlistentry>
 452
 453       <varlistentry id="libgcc">
 454         <term><filename class="libraryfile">libgcc</filename></term>
 455         <listitem>
 456           <para>Contains run-time support for <command>gcc</command></para>
 457           <indexterm zone="ch-system-gcc libgcc">
 458             <primary sortas="c-libgcc">libgcc</primary>
 459           </indexterm>
 460         </listitem>
 461       </varlistentry>
 462
 463       <varlistentry id="libgcov">
 464         <term><filename class="libraryfile">libgcov</filename></term>
 465         <listitem>
 466           <para>This library is linked in to a program when GCC is instructed
 467           to enable profiling</para>
 468           <indexterm zone="ch-system-gcc libgcov">
 469             <primary sortas="c-libgcov">libgcov</primary>
 470           </indexterm>
 471         </listitem>
 472       </varlistentry>
 473
 474       <varlistentry id="libgomp">
 475         <term><filename class="libraryfile">libgomp</filename></term>
 476         <listitem>
 477           <para>GNU implementation of the OpenMP API for multi-platform
 478           shared-memory parallel programming in C/C++ and Fortran</para>
 479           <indexterm zone="ch-system-gcc libgomp">
 480             <primary sortas="c-libgomp">libgomp</primary>
 481           </indexterm>
 482         </listitem>
 483       </varlistentry>
 484
 485       <varlistentry id="libiberty">
 486         <term><filename class="libraryfile">libiberty</filename></term>
 487         <listitem>
 488           <para>Contains routines used by various GNU programs, including
 489           <command>getopt</command>, <command>obstack</command>,
 490           <command>strerror</command>, <command>strtol</command>, and
 491           <command>strtoul</command></para>
 492           <indexterm zone="ch-system-gcc libiberty">
 493             <primary sortas="c-libiberty">libiberty</primary>
 494           </indexterm>
 495         </listitem>
 496       </varlistentry>
 497
 498       <varlistentry id="liblto_plugin">
 499         <term><filename class="libraryfile">liblto_plugin</filename></term>
 500         <listitem>
 501           <para>GCC's Link Time Optimization (LTO) plugin allows GCC to perform
 502           optimizations across compilation units</para>
 503           <indexterm zone="ch-system-gcc liblto_plugin">
 504             <primary sortas="c-liblto_plugin">liblto_plugin</primary>
 505           </indexterm>
 506         </listitem>
 507       </varlistentry>
 508
 509       <varlistentry id="libquadmath">
 510         <term><filename class="libraryfile">libquadmath</filename></term>
 511         <listitem>
 512           <para>GCC Quad Precision Math Library API</para>
 513           <indexterm zone="ch-system-gcc libquadmath">
 514             <primary sortas="c-libquadmath">libquadmath</primary>
 515           </indexterm>
 516         </listitem>
 517       </varlistentry>
 518
 519       <varlistentry id="libssp">
 520         <term><filename class="libraryfile">libssp</filename></term>
 521         <listitem>
 522           <para>Contains routines supporting GCC's stack-smashing protection
 523           functionality</para>
 524           <indexterm zone="ch-system-gcc libssp">
 525             <primary sortas="c-libssp">libssp</primary>
 526           </indexterm>
 527         </listitem>
 528       </varlistentry>
 529
 530       <varlistentry id="libstdc">
 531         <term><filename class="libraryfile">libstdc++</filename></term>
 532         <listitem>
 533           <para>The standard C++ library</para>
 534           <indexterm zone="ch-system-gcc libstdc">
 535             <primary sortas="c-libstdc++">libstdc++</primary>
 536           </indexterm>
 537         </listitem>
 538       </varlistentry>
 539
 540       <varlistentry id="libsupc">
 541         <term><filename class="libraryfile">libsupc++</filename></term>
 542         <listitem>
 543           <para>Provides supporting routines for the C++ programming
 544           language</para>
 545           <indexterm zone="ch-system-gcc libsupc">
 546             <primary sortas="c-libsupc++">libsupc++</primary>
 547           </indexterm>
 548         </listitem>
 549       </varlistentry>
 550
 551       <varlistentry id="libtsan">
 552         <term><filename class="libraryfile">libtsan</filename></term>
 553         <listitem>
 554           <para>The Thread Sanitizer runtime library</para>
 555           <indexterm zone="ch-system-gcc libtsan">
 556             <primary sortas="c-libtsan">libtsan</primary>
 557           </indexterm>
 558         </listitem>
 559       </varlistentry>
 560
 561     </variablelist>
 562
 563   </sect2>
 564
 565 </sect1>