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