1: <html> 2: 3: <head> 4: <title>GCC Frequently Asked Questions</title> 5: </head> 6: 7: <body> 8: 9: <h1>GCC Frequently Asked Questions</h1> 10: 11: <p>The latest version of this document is always available at 12: <a href="http://gcc.gnu.org/faq.html">http://gcc.gnu.org/faq.html</a>.</p> 13: 14: <p>This FAQ tries to answer specific questions concerning GCC. For 15: general information regarding C, C++, resp. Fortran please check the 16: <a href="http://c-faq.com/">comp.lang.c FAQ</a>, 17: <a href="http://www.comeaucomputing.com/csc/faq.html">comp.std.c++ 18: FAQ</a>, 19: and the <a href="http://www.fortran.com/fortran/info.html">Fortran 20: Information page</a>.</p> 21: 22: <p>Other GCC-related FAQs: 23: <a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html"> 24: libstdc++-v3</a>, and 25: <a href="http://gcc.gnu.org/java/faq.html">GCJ</a>.</p> 26: 27: <hr /> 28: <h1>Questions</h1> 29: <ol> 30: <li><a href="#general">General information</a> 31: <ol> 32: <li><a href="#support">How do I get a bug fixed or a feature added?</a></li> 33: <li><a href="#platforms">Does GCC work on my platform?</a></li> 34: </ol></li> 35: 36: <li><a href="#installation">Installation</a> 37: <ol> 38: <li><a href="#multiple">How to install multiple versions of GCC</a></li> 39: <li><a href="#rpath">Dynamic linker is unable to find GCC libraries</a></li> 40: <li><a href="#rpath">libstdc++/libio tests fail badly with --enable-shared</a></li> 41: <li><a href="#gas">GCC can not find GNU as/GNU ld</a></li> 42: <li><a href="#environ">cpp: Usage:... Error</a></li> 43: <li><a href="#optimizing">Optimizing the compiler itself</a></li> 44: <li><a href="#iconv">Why does <code>libiconv</code> get linked into <code>jc1</code> on Solaris?</a></li> 45: </ol></li> 46: 47: <li><a href="#testsuite">Testsuite problems</a> 48: <ol> 49: <li><a href="#testoptions">How do I pass flags like 50: <code>-fnew-abi</code> to the testsuite?</a></li> 51: <li><a href="#multipletests">How can I run the test suite with multiple options?</a></li> 52: </ol></li> 53: 54: <li><a href="#misc">Miscellaneous</a> 55: <ol> 56: <li><a href="#friend">Friend Templates</a></li> 57: <li><a href="#dso"><code>dynamic_cast</code>, <code>throw</code>, <code>typeid</code> don't work with shared libraries</a></li> 58: <li><a href="#generated_files">Why do I need autoconf, bison, xgettext, automake, etc?</a></li> 59: <li><a href="#picflag-needed">Why can't I build a shared library?</a></li> 60: <li><a href="#vtables">When building C++, the linker says my constructors, destructors or virtual tables are undefined, but I defined them</a></li> 61: </ol></li> 62: </ol> 63: 64: 65: <hr /> 66: <a name="general"></a> 67: <h1>General information</h1> 68: 69: <!-- The "bugreport" anchor was used in ICE messages of GCC < 2.95.3. --> 70: <h2 id="bugreport"><a name="support">How do I get a bug fixed or 71: a feature added?</a></h2> 72: 73: <p>There are lots of ways to get something fixed. The list below may be 74: incomplete, but it covers many of the common cases. These are listed 75: roughly in order of decreasing difficulty for the average GCC user, 76: meaning someone who is not skilled in the internals of GCC, and where 77: difficulty is measured in terms of the time required to fix the bug. 78: No alternative is better than any other; each has its benefits and 79: disadvantages.</p> 80: 81: <ul> 82: <li>Fix it yourself. This alternative will probably bring results, 83: if you work hard enough, but will probably take a lot of time, 84: and, depending on the quality of your work and the perceived 85: benefits of your changes, your code may or may not ever make it 86: into an official release of GCC.</li> 87: 88: <li><a href="bugs.html">Report the problem to the GCC bug tracking system</a> 89: and hope that someone will be kind 90: enough to fix it for you. While this is certainly possible, and 91: often happens, there is no guarantee that it will. You should 92: not expect the same response from this method that you would see 93: from a commercial support organization since the people who read 94: GCC bug reports, if they choose to help you, will be volunteering their 95: time.</li> 96: 97: <li>Hire someone to fix it for you. There are various companies and 98: individuals providing support for GCC. This alternative costs 99: money, but is relatively likely to get results.</li> 100: </ul> 101: 102: <hr /> 103: <h2><a name="platforms">Does GCC work on my platform?</a></h2> 104: 105: <p>The host/target specific installation notes for GCC include information 106: about known problems with installing or using GCC on particular platforms. 107: These are included in the sources for a release in INSTALL/specific.html, 108: and the <a href="http://gcc.gnu.org/install/specific.html">latest version</a> 109: is always available at the GCC web site. 110: Reports of <a href="http://gcc.gnu.org/buildstat.html">successful builds</a> 111: for several versions of GCC are also available at the web site.</p> 112: 113: <hr /> 114: <a name="installation"></a> 115: <h1>Installation</h1> 116: 117: <h2><a name="multiple">How to install multiple versions of GCC</a></h2> 118: 119: <p>It may be desirable to install multiple versions of the compiler on 120: the same system. This can be done by using different prefix paths at 121: configure time and a few symlinks.</p> 122: 123: <p>Basically, configure the two compilers with different --prefix options, 124: then build and install each compiler. Assume you want "gcc" to be the latest 125: compiler and available in /usr/local/bin; also assume that you want "gcc2" 126: to be the older gcc2 compiler and also available in /usr/local/bin.</p> 127: 128: <p>The easiest way to do this is to configure the new GCC with 129: <code>--prefix=/usr/local/gcc</code> and the older gcc2 with 130: <code>--prefix=/usr/local/gcc2</code>. Build and install both 131: compilers. Then make a symlink from <code>/usr/local/bin/gcc</code> 132: to <code>/usr/local/gcc/bin/gcc</code> and from 133: <code>/usr/local/bin/gcc2</code> to 134: <code>/usr/local/gcc2/bin/gcc</code>. Create similar links for the 135: "g++", "c++" and "g77" compiler drivers.</p> 136: 137: <p>An alternative to using symlinks is to configure with a 138: <code>--program-transform-name</code> option. This option specifies a 139: sed command to process installed program names with. Using it you can, 140: for instance, have all the new GCC programs installed as "new-gcc" and 141: the like. You will still have to specify different 142: <code>--prefix</code> options for new GCC and old GCC, because it is 143: only the executable program names that are transformed. The difference 144: is that you (as administrator) do not have to set up symlinks, but 145: must specify additional directories in your (as a user) PATH. A 146: complication with <code>--program-transform-name</code> is that the 147: sed command invariably contains characters significant to the shell, 148: and these have to be escaped correctly, also it is not possible to use 149: "^" or "$" in the command. Here is the option to prefix "new-" to the 150: new GCC installed programs:</p> 151: <blockquote><code> 152: --program-transform-name='s,\\\\(.*\\\\),new-\\\\1,' 153: </code></blockquote> 154: <p>With the above <code>--prefix</code> option, that will install the new 155: GCC programs into <code>/usr/local/gcc/bin</code> with names prefixed 156: by "new-". You can use <code>--program-transform-name</code> if you 157: have multiple versions of GCC, and wish to be sure about which version 158: you are invoking.</p> 159: 160: <p>If you use <code>--prefix</code>, GCC may have difficulty locating a GNU 161: assembler or linker on your system, <a href="#gas">GCC can not find GNU 162: as/GNU ld</a> explains how to deal with this.</p> 163: 164: <p>Another option that may be easier is to use the 165: <code>--program-prefix=</code> or <code>--program-suffix=</code> 166: options to configure. So if you're installing GCC 2.95.2 and don't 167: want to disturb the current version of GCC in 168: <code>/usr/local/bin/</code>, you could do</p> 169: <blockquote><code> 170: configure --program-suffix=-2.95.2 <other configure options> 171: </code></blockquote> 172: <p>This should result in GCC being installed as 173: <code>/usr/local/bin/gcc-2.95.2</code> instead of 174: <code>/usr/local/bin/gcc</code>.</p> 175: 176: <hr /> 177: <h2><a name="rpath">Dynamic linker is unable to find GCC libraries</a></h2> 178: 179: <p>This problem manifests itself by programs not finding shared 180: libraries they depend on when the programs are started. Note this 181: problem often manifests itself with failures in the libio/libstdc++ 182: tests after configuring with <code>--enable-shared</code> and building GCC.</p> 183: 184: <p>GCC does not specify a runpath so that the dynamic linker can find 185: dynamic libraries at runtime.</p> 186: 187: <p>The short explanation is that if you always pass a -R option to the 188: linker, then your programs become dependent on directories which 189: may be NFS mounted, and programs may hang unnecessarily when an 190: NFS server goes down.</p> 191: 192: <p>The problem is not programs that do require the directories; those 193: programs are going to hang no matter what you do. The problem is 194: programs that do not require the directories.</p> 195: 196: <p>SunOS effectively always passed a <code>-R</code> option for every 197: <code>-L</code> option; this was a bad idea, and so it was removed for 198: Solaris. We should not recreate it.</p> 199: 200: <p>However, if you feel you really need such an option to be passed 201: automatically to the linker, you may add it to the GCC specs file. 202: This file can be found in the same directory that contains cc1 (run 203: <code>gcc -print-prog-name=cc1</code> to find it). You may add linker 204: flags such as <code>-R</code> or <code>-rpath</code>, depending on 205: platform and linker, to the <code>*link</code> or <code>*lib</code> 206: specs.</p> 207: 208: <p>Another alternative is to install a wrapper script around gcc, g++ 209: or ld that adds the appropriate directory to the environment variable 210: <code>LD_RUN_PATH</code> or equivalent (again, it's 211: platform-dependent).</p> 212: 213: <p>Yet another option, that works on a few platforms, is to hard-code 214: the full pathname of the library into its soname. This can only be 215: accomplished by modifying the appropriate <tt>.ml</tt> file within 216: <tt>libstdc++/config</tt> (and also <tt>libg++/config</tt>, if you are 217: building libg++), so that <code>$(libdir)/</code> appears just before 218: the library name in <code>-soname</code> or <code>-h</code> options.</p> 219: 220: <hr /> 221: <h2><a name="gas">GCC can not find GNU as/GNU ld</a></h2> 222: <p>GCC searches the PATH for an assembler and a loader, but it only 223: does so after searching a directory list hard-coded in the GCC 224: executables. Since, on most platforms, the hard-coded list includes 225: directories in which the system assembler and loader can be found, you 226: may have to take one of the following actions to arrange that GCC uses 227: the GNU versions of those programs.</p> 228: 229: <p>To ensure that GCC finds the GNU assembler (the GNU loader), which 230: are required by <a href="http://gcc.gnu.org/install/specific.html">some 231: configurations</a>, 232: you should configure these with the same --prefix option as you used 233: for GCC. Then build & install GNU as (GNU ld) and proceed with 234: building GCC.</p> 235: 236: <p>Another alternative is to create links to GNU as and ld in any of 237: the directories printed by the command `<tt>gcc -print-search-dirs | 238: grep '^programs:'</tt>'. The link to `<tt>ld</tt>' should be named 239: `<tt>real-ld</tt>' if `<tt>ld</tt>' already exists. If such links do 240: not exist while you're compiling GCC, you may have to create them in 241: the build directories too, within the <tt>gcc</tt> directory 242: <em>and</em> in all the <tt>gcc/stage*</tt> subdirectories.</p> 243: 244: <p>GCC 2.95 allows you to specify the full pathname of the assembler 245: and the linker to use. The configure flags are 246: `<tt>--with-as=/path/to/as</tt>' and `<tt>--with-ld=/path/to/ld</tt>'. 247: GCC will try to use these pathnames before looking for `<tt>as</tt>' 248: or `<tt>(real-)ld</tt>' in the standard search dirs. If, at 249: configure-time, the specified programs are found to be GNU utilities, 250: `<tt>--with-gnu-as</tt>' and `<tt>--with-gnu-ld</tt>' need not be 251: used; these flags will be auto-detected. One drawback of this option 252: is that it won't allow you to override the search path for assembler 253: and linker with command-line options <tt>-B/path/</tt> if the 254: specified filenames exist.</p> 255: 256: <hr /> 257: <h2><a name="environ">cpp: Usage:... Error</a></h2> 258: 259: <p>If you get an error like this when building GCC (particularly when building 260: __mulsi3), then you likely have a problem with your environment variables.</p> 261: <pre> 262: cpp: Usage: /usr/lib/gcc-lib/i586-unknown-linux-gnulibc1/2.7.2.3/cpp 263: [switches] input output 264: </pre> 265: <p>First look for an explicit '.' in either LIBRARY_PATH or GCC_EXEC_PREFIX 266: from your environment. If you do not find an explicit '.', look for 267: an empty pathname in those variables. Note that ':' at either the start 268: or end of these variables is an implicit '.' and will cause problems.</p> 269: 270: <p>Also note '::' in these paths will also cause similar problems.</p> 271: 272: 273: <hr /> 274: <h2><a name="optimizing">Optimizing the compiler itself</a></h2> 275: 276: <p>If you want to test a particular optimization option, it's useful to try 277: bootstrapping the compiler with that option turned on. For example, to 278: test the <code>-fssa</code> option, you could bootstrap like this:</p> 279: 280: <pre>make BOOT_CFLAGS="-O2 -fssa" bootstrap</pre> 281: 282: <hr /> 283: <h2><a name="iconv">Why does <code>libiconv</code> get linked into <code>jc1</code> on Solaris?</a></h2> 284: 285: <p>The Java front end requires <code>iconv</code>. If the compiler 286: used to bootstrap GCC finds <code>libiconv</code> (because the GNU 287: version of <code>libiconv</code> has been installed in the same prefix 288: as the bootstrap compiler), but the newly built GCC does not find the 289: library (because it will be installed with a different prefix), then a 290: link-time error will occur when building <code>jc1</code>. This 291: problem does not show up so often on platforms that have 292: <code>libiconv</code> in a default location (like 293: <code>/usr/lib</code>) because then both compilers can find a library 294: named <code>libiconv</code>, even though it is a different 295: library.</p> 296: 297: <p>Using <code>--disable-nls</code> at configure-time does not 298: prevent this problem because <code>jc1</code> uses 299: <code>iconv</code> even in that case. Solutions include temporarily 300: removing the GNU <code>libiconv</code>, copying it to a default 301: location such as <code>/usr/lib/</code>, and using 302: <code>--enable-languages</code> at configure-time to disable Java.</p> 303: 304: <hr /> 305: <a name="testsuite"></a> 306: <h1>Testsuite problems</h1> 307: 308: <h2><a name="testoptions">How do I pass flags like 309: <code>-fnew-abi</code> to the testsuite?</a></h2> 310: 311: <p>If you invoke <code>runtest</code> directly, you can use the 312: <code>--tool_opts</code> option, e.g:</p> 313: <pre> 314: runtest --tool_opts "-fnew-abi -fno-honor-std" <other options> 315: </pre> 316: <p>Or, if you use <code>make check</code> you can use the 317: <code>make</code> variable <code>RUNTESTFLAGS</code>, e.g:</p> 318: <pre> 319: make RUNTESTFLAGS="--tool_opts '-fnew-abi -fno-honor-std'" check-g++ 320: </pre> 321: 322: <hr /> 323: <h2><a name="multipletests"> How can I run the test suite with multiple options? </a></h2> 324: 325: <p>If you invoke <code>runtest</code> directly, you can use the 326: <code>--target_board</code> option, e.g:</p> 327: <pre> 328: runtest --target_board "unix{-fPIC,-fpic,}" <other options> 329: </pre> 330: <p>Or, if you use <code>make check</code> you can use the 331: <code>make</code> variable <code>RUNTESTFLAGS</code>, e.g:</p> 332: <pre> 333: make RUNTESTFLAGS="--target_board 'unix{-fPIC,-fpic,}'" check-gcc 334: </pre> 335: <p>Either of these examples will run the tests three times. Once 336: with <code>-fPIC</code>, once with <code>-fpic</code>, and once with 337: no additional flags.</p> 338: 339: <p>This technique is particularly useful on multilibbed targets.</p> 340: 341: 342: <hr /> 343: <a name="misc"></a> 344: <h1>Miscellaneous</h1> 345: 346: 347: <h2><a name="friend">Friend Templates</a></h2> 348: 349: <p>In order to make a specialization of a template function a friend 350: of a (possibly template) class, you must explicitly state that the 351: friend function is a template, by appending angle brackets to its 352: name, and this template function must have been declared already. 353: Here's an example:</p> 354: <pre> 355: template <typename T> class foo { 356: friend void bar(foo<T>); 357: } 358: </pre> 359: <p>The above declaration declares a non-template function named 360: <code>bar</code>, so it must be explicitly defined for <b>each</b> 361: specialization of <code>foo</code>. A template definition of <code>bar</code> 362: won't do, because it is unrelated with the non-template declaration 363: above. So you'd have to end up writing:</p> 364: <pre> 365: void bar(foo<int>) { /* ... */ } 366: void bar(foo<void>) { /* ... */ } 367: </pre> 368: <p>If you meant <code>bar</code> to be a template function, you should 369: have forward-declared it as follows. Note that, since the template 370: function declaration refers to the template class, the template class 371: must be forward-declared too:</p> 372: <pre> 373: template <typename T> 374: class foo; 375: 376: template <typename T> 377: void bar(foo<T>); 378: 379: template <typename T> 380: class foo { 381: friend void bar<>(foo<T>); 382: }; 383: 384: template <typename T> 385: void bar(foo<T>) { /* ... */ } 386: </pre> 387: <p>In this case, the template argument list could be left empty, 388: because it can be implicitly deduced from the function arguments, but 389: the angle brackets must be present, otherwise the declaration will be 390: taken as a non-template function. Furthermore, in some cases, you may 391: have to explicitly specify the template arguments, to remove 392: ambiguity.</p> 393: 394: <p>An error in the last public comment draft of the ANSI/ISO C++ 395: Standard and the fact that previous releases of GCC would accept such 396: friend declarations as template declarations has led people to believe 397: that the forward declaration was not necessary, but, according to the 398: final version of the Standard, it is.</p> 399: 400: 401: <hr /> 402: <h2><a name="dso"><code>dynamic_cast</code>, <code>throw</code>, <code>typeid</code> don't work with shared libraries</a></h2> 403: 404: <p>The new C++ ABI in the GCC 3.0 series uses address comparisons, 405: rather than string compares, to determine type equality. This leads 406: to better performance. Like other objects that have to be present in the 407: final executable, these <code>std::type_info</code> objects have what 408: is called vague linkage because they are not tightly bound to any one 409: particular translation unit (object file). The compiler has to emit 410: them in any translation unit that requires their presence, and then 411: rely on the linking and loading process to make sure that only one of 412: them is active in the final executable. With static linking all of 413: these symbols are resolved at link time, but with dynamic linking, 414: further resolution occurs at load time. You have to ensure that 415: objects within a shared library are resolved against objects in the 416: executable and other shared libraries.</p> 417: 418: <ul> 419: <li>For a program which is linked against a shared library, no additional 420: precautions are needed.</li> 421: 422: <li>You cannot create a shared library with the "<code>-Bsymbolic</code>" 423: option, as that prevents the resolution described above.</li> 424: 425: <li>If you use <code>dlopen</code> to explicitly load code from a shared 426: library, you must do several things. First, export global symbols from 427: the executable by linking it with the "<code>-E</code>" flag (you will 428: have to specify this as "<code>-Wl,-E</code>" if you are invoking 429: the linker in the usual manner from the compiler driver, <code>g++</code>). 430: You must also make the external symbols in the loaded library 431: available for subsequent libraries by providing the <code>RTLD_GLOBAL</code> 432: flag to <code>dlopen</code>. The symbol resolution can be immediate or 433: lazy.</li> 434: 435: </ul> 436: 437: <p>Template instantiations are another, user visible, case of objects 438: with vague linkage, which needs similar resolution. If you do not take 439: the above precautions, you may discover that a template instantiation 440: with the same argument list, but instantiated in multiple translation 441: units, has several addresses, depending in which translation unit the 442: address is taken. (This is <em>not</em> an exhaustive list of the kind 443: of objects which have vague linkage and are expected to be resolved 444: during linking & loading.)</p> 445: 446: <p>If you are worried about different objects with the same name 447: colliding during the linking or loading process, then you should use 448: namespaces to disambiguate them. Giving distinct objects with global 449: linkage the same name is a violation of the One Definition Rule (ODR) 450: [basic.def.odr].</p> 451: 452: <p>For more details about the way that GCC implements these and other 453: C++ features, please read the <a 454: href="http://www.codesourcery.com/cxx-abi/">ABI specification</a>. 455: Note the <code>std::type_info</code> objects which <i>must</i> be 456: resolved all begin with "_ZTS". Refer to <code>ld</code>'s 457: documentation for a description of the "<code>-E</code>" & 458: "<code>-Bsymbolic</code>" flags.</p> 459: 460: <hr /> 461: <h2><a name="generated_files">Why do I need autoconf, bison, xgettext, automake, etc?</a></h2> 462: 463: <p>If you're using diffs up dated from one snapshot to the next, or 464: if you're using the SVN repository, you may need several additional programs 465: to build GCC.</p> 466: 467: <p>These include, but are not necessarily limited to autoconf, automake, 468: bison, and xgettext.</p> 469: 470: <p>This is necessary because neither diff nor cvs keep timestamps 471: correct. This causes problems for generated files as "make" may think 472: those generated files are out of date and try to regenerate them.</p> 473: 474: <p>An easy way to work around this problem is to use the <code>gcc_update 475: </code> script in the contrib subdirectory of GCC, which handles this 476: transparently without requiring installation of any additional tools.</p> 477: 478: 479: <p>When building from diffs or SVN or if you modified some sources, 480: you may also need to obtain development versions of some GNU tools, as 481: the production versions do not necessarily handle all features needed 482: to rebuild GCC.</p> 483: 484: <p>In general, the current versions of these tools from <a 485: href="ftp://ftp.gnu.org/gnu/">ftp://ftp.gnu.org/gnu/</a> will work. 486: At present, Autoconf 2.50 is not supported, and you will need to use 487: Autoconf 2.13; work is in progress to fix this problem. Also look at 488: <a href="ftp://gcc.gnu.org/pub/gcc/infrastructure/"> 489: ftp://gcc.gnu.org/pub/gcc/infrastructure/</a> for any special versions 490: of packages.</p> 491: 492: 493: <hr /> 494: <h2><a name="picflag-needed">Why can't I build a shared library?</a></h2> 495: 496: <p>When building a shared library you may get an error message from the 497: linker like `assert pure-text failed:' or `DP relative code in file'.</p> 498: 499: <p>This kind of error occurs when you've failed to provide proper flags 500: to gcc when linking the shared library. </p> 501: 502: <p>You can get this error even if all the .o files for the shared library were 503: compiled with the proper PIC option. When building a shared library, gcc will 504: compile additional code to be included in the library. That additional code 505: must also be compiled with the proper PIC option.</p> 506: 507: <p>Adding the proper PIC option (<tt>-fpic</tt> or <tt>-fPIC</tt>) to the link 508: line which creates the shared library will fix this problem on targets that 509: support PIC in this manner. For example:</p> 510: <pre> 511: gcc -c -fPIC myfile.c 512: gcc -shared -o libmyfile.so -fPIC myfile.o 513: </pre> 514: 515: 516: <hr /> 517: <h2><a name="vtables">When building C++, the linker says my constructors, destructors or virtual tables are undefined, but I defined them</a></h2> 518: 519: <p>The ISO C++ Standard specifies that all virtual methods of a class 520: that are not pure-virtual must be defined, but does not require any 521: diagnostic for violations of this rule [class.virtual]/8. Based on 522: this assumption, GCC will only emit the implicitly defined 523: constructors, the assignment operator, the destructor and the virtual 524: table of a class in the translation unit that defines its first such 525: non-inline method.</p> 526: 527: <p>Therefore, if you fail to define this particular method, the linker 528: may complain about the lack of definitions for apparently unrelated 529: symbols. Unfortunately, in order to improve this error message, it 530: might be necessary to change the linker, and this can't always be 531: done.</p> 532: 533: <p>The solution is to ensure that all virtual methods that are not 534: pure are defined. Note that a destructor must be defined even if it 535: is declared pure-virtual [class.dtor]/7.</p> 536: 537: 538: </body> 539: </html>