+++ /dev/null
-This is doc/gcc.info, produced by makeinfo version 4.5 from
-doc/gcc.texi.
-
-INFO-DIR-SECTION Programming
-START-INFO-DIR-ENTRY
-* gcc: (gcc). The GNU Compiler Collection.
-END-INFO-DIR-ENTRY
- This file documents the use of the GNU compilers.
-
- Published by the Free Software Foundation
-59 Temple Place - Suite 330
-Boston, MA 02111-1307 USA
-
- Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-1999, 2000, 2001, 2002 Free Software Foundation, Inc.
-
- Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being "GNU General Public License" and "Funding Free
-Software", the Front-Cover texts being (a) (see below), and with the
-Back-Cover Texts being (b) (see below). A copy of the license is
-included in the section entitled "GNU Free Documentation License".
-
- (a) The FSF's Front-Cover Text is:
-
- A GNU Manual
-
- (b) The FSF's Back-Cover Text is:
-
- You have freedom to copy and modify this GNU Manual, like GNU
-software. Copies published by the Free Software Foundation raise
-funds for GNU development.
-
-\1f
-File: gcc.info, Node: Constant string objects, Next: compatibility_alias, Prev: Garbage Collection, Up: Objective-C
-
-Constant string objects
-=======================
-
- GNU Objective-C provides constant string objects that are generated
-directly by the compiler. You declare a constant string object by
-prefixing a C constant string with the character `@':
-
- id myString = @"this is a constant string object";
-
- The constant string objects are usually instances of the
-`NXConstantString' class which is provided by the GNU Objective-C
-runtime. To get the definition of this class you must include the
-`objc/NXConstStr.h' header file.
-
- User defined libraries may want to implement their own constant
-string class. To be able to support them, the GNU Objective-C compiler
-provides a new command line options
-`-fconstant-string-class=CLASS-NAME'. The provided class should adhere
-to a strict structure, the same as `NXConstantString''s structure:
-
-
- @interface NXConstantString : Object
- {
- char *c_string;
- unsigned int len;
- }
- @end
-
- User class libraries may choose to inherit the customized constant
-string class from a different class than `Object'. There is no
-requirement in the methods the constant string class has to implement.
-
- When a file is compiled with the `-fconstant-string-class' option,
-all the constant string objects will be instances of the class specified
-as argument to this option. It is possible to have multiple compilation
-units referring to different constant string classes, neither the
-compiler nor the linker impose any restrictions in doing this.
-
-\1f
-File: gcc.info, Node: compatibility_alias, Prev: Constant string objects, Up: Objective-C
-
-compatibility_alias
-===================
-
- This is a feature of the Objective-C compiler rather than of the
-runtime, anyway since it is documented nowhere and its existence was
-forgotten, we are documenting it here.
-
- The keyword `@compatibility_alias' allows you to define a class name
-as equivalent to another class name. For example:
-
- @compatibility_alias WOApplication GSWApplication;
-
- tells the compiler that each time it encounters `WOApplication' as a
-class name, it should replace it with `GSWApplication' (that is,
-`WOApplication' is just an alias for `GSWApplication').
-
- There are some constraints on how this can be used--
-
- * `WOApplication' (the alias) must not be an existing class;
-
- * `GSWApplication' (the real class) must be an existing class.
-
-
-\1f
-File: gcc.info, Node: Compatibility, Next: Gcov, Prev: Objective-C, Up: Top
-
-Binary Compatibility
-********************
-
- Binary compatibility encompasses several related concepts:
-
-"application binary interface (ABI)"
- The set of runtime conventions followed by all of the tools that
- deal with binary representations of a program, including
- compilers, assemblers, linkers, and language runtime support.
- Some ABIs are formal with a written specification, possibly
- designed by multiple interested parties. Others are simply the
- way things are actually done by a particular set of tools.
-
-"ABI conformance"
- A compiler conforms to an ABI if it generates code that follows
- all of the specifications enumerated by that ABI. A library
- conforms to an ABI if it is implemented according to that ABI. An
- application conforms to an ABI if it is built using tools that
- conform to that ABI and does not contain source code that
- specifically changes behavior specified by the ABI.
-
-"calling conventions"
- Calling conventions are a subset of an ABI that specify of how
- arguments are passed and function results are returned.
-
-"interoperability"
- Different sets of tools are interoperable if they generate files
- that can be used in the same program. The set of tools includes
- compilers, assemblers, linkers, libraries, header files, startup
- files, and debuggers. Binaries produced by different sets of
- tools are not interoperable unless they implement the same ABI.
- This applies to different versions of the same tools as well as
- tools from different vendors.
-
-"intercallability"
- Whether a function in a binary built by one set of tools can call a
- function in a binary built by a different set of tools is a subset
- of interoperability.
-
-"implementation-defined features"
- Language standards include lists of implementation-defined
- features whose behavior can vary from one implementation to
- another. Some of these features are normally covered by a
- platform's ABI and others are not. The features that are not
- covered by an ABI generally affect how a program behaves, but not
- intercallability.
-
-"compatibility"
- Conformance to the same ABI and the same behavior of
- implementation-defined features are both relevant for
- compatibility.
-
- The application binary interface implemented by a C or C++ compiler
-affects code generation and runtime support for:
-
- * size and alignment of data types
-
- * layout of structured types
-
- * calling conventions
-
- * register usage conventions
-
- * interfaces for runtime arithmetic support
-
- * object file formats
-
- In addition, the application binary interface implemented by a C++
-compiler affects code generation and runtime support for:
- * name mangling
-
- * exception handling
-
- * invoking constructors and destructors
-
- * layout, alignment, and padding of classes
-
- * layout and alignment of virtual tables
-
- Some GCC compilation options cause the compiler to generate code that
-does not conform to the platform's default ABI. Other options cause
-different program behavior for implementation-defined features that are
-not covered by an ABI. These options are provided for consistency with
-other compilers that do not follow the platform's default ABI or the
-usual behavior of implementation-defined features for the platform. Be
-very careful about using such options.
-
- Most platforms have a well-defined ABI that covers C code, but ABIs
-that cover C++ functionality are not yet common.
-
- Starting with GCC 3.2, GCC binary conventions for C++ are based on a
-written, vendor-neutral C++ ABI that was designed to be specific to
-64-bit Itanium but also includes generic specifications that apply to
-any platform. This C++ ABI is also implemented by other compiler
-vendors on some platforms, notably GNU/Linux and BSD systems. We have
-tried hard to provide a stable ABI that will be compatible with future
-GCC releases, but it is possible that we will encounter problems that
-make this difficult. Such problems could include different
-interpretations of the C++ ABI by different vendors, bugs in the ABI, or
-bugs in the implementation of the ABI in different compilers. GCC's
-`-Wabi' switch warns when G++ generates code that is probably not
-compatible with the C++ ABI.
-
- The C++ library used with a C++ compiler includes the Standard C++
-Library, with functionality defined in the C++ Standard, plus language
-runtime support. The runtime support is included in a C++ ABI, but
-there is no formal ABI for the Standard C++ Library. Two
-implementations of that library are interoperable if one follows the
-de-facto ABI of the other and if they are both built with the same
-compiler, or with compilers that conform to the same ABI for C++
-compiler and runtime support.
-
- When G++ and another C++ compiler conform to the same C++ ABI, but
-the implementations of the Standard C++ Library that they normally use
-do not follow the same ABI for the Standard C++ Library, object files
-built with those compilers can be used in the same program only if they
-use the same C++ library. This requires specifying the location of the
-C++ library header files when invoking the compiler whose usual library
-is not being used. The location of GCC's C++ header files depends on
-how the GCC build was configured, but can be seen by using the G++ `-v'
-option. With default configuration options for G++ 3.2 the compile
-line for a different C++ compiler needs to include
-
- -IGCC_INSTALL_DIRECTORY/include/c++/3.2
-
- Similarly, compiling code with G++ that must use a C++ library other
-than the GNU C++ library requires specifying the location of the header
-files for that other library.
-
- The most straightforward way to link a program to use a particular
-C++ library is to use a C++ driver that specifies that C++ library by
-default. The `g++' driver, for example, tells the linker where to find
-GCC's C++ library (`libstdc++') plus the other libraries and startup
-files it needs, in the proper order.
-
- If a program must use a different C++ library and it's not possible
-to do the final link using a C++ driver that uses that library by
-default, it is necessary to tell `g++' the location and name of that
-library. It might also be necessary to specify different startup files
-and other runtime support libraries, and to suppress the use of GCC's
-support libraries with one or more of the options `-nostdlib',
-`-nostartfiles', and `-nodefaultlibs'.
-
-\1f
-File: gcc.info, Node: Gcov, Next: Trouble, Prev: Compatibility, Up: Top
-
-`gcov'--a Test Coverage Program
-*******************************
-
- `gcov' is a tool you can use in conjunction with GCC to test code
-coverage in your programs.
-
-* Menu:
-
-* Gcov Intro:: Introduction to gcov.
-* Invoking Gcov:: How to use gcov.
-* Gcov and Optimization:: Using gcov with GCC optimization.
-* Gcov Data Files:: The files used by gcov.
-
-\1f
-File: gcc.info, Node: Gcov Intro, Next: Invoking Gcov, Up: Gcov
-
-Introduction to `gcov'
-======================
-
- `gcov' is a test coverage program. Use it in concert with GCC to
-analyze your programs to help create more efficient, faster running
-code. You can use `gcov' as a profiling tool to help discover where
-your optimization efforts will best affect your code. You can also use
-`gcov' along with the other profiling tool, `gprof', to assess which
-parts of your code use the greatest amount of computing time.
-
- Profiling tools help you analyze your code's performance. Using a
-profiler such as `gcov' or `gprof', you can find out some basic
-performance statistics, such as:
-
- * how often each line of code executes
-
- * what lines of code are actually executed
-
- * how much computing time each section of code uses
-
- Once you know these things about how your code works when compiled,
-you can look at each module to see which modules should be optimized.
-`gcov' helps you determine where to work on optimization.
-
- Software developers also use coverage testing in concert with
-testsuites, to make sure software is actually good enough for a release.
-Testsuites can verify that a program works as expected; a coverage
-program tests to see how much of the program is exercised by the
-testsuite. Developers can then determine what kinds of test cases need
-to be added to the testsuites to create both better testing and a better
-final product.
-
- You should compile your code without optimization if you plan to use
-`gcov' because the optimization, by combining some lines of code into
-one function, may not give you as much information as you need to look
-for `hot spots' where the code is using a great deal of computer time.
-Likewise, because `gcov' accumulates statistics by line (at the lowest
-resolution), it works best with a programming style that places only
-one statement on each line. If you use complicated macros that expand
-to loops or to other control structures, the statistics are less
-helpful--they only report on the line where the macro call appears. If
-your complex macros behave like functions, you can replace them with
-inline functions to solve this problem.
-
- `gcov' creates a logfile called `SOURCEFILE.gcov' which indicates
-how many times each line of a source file `SOURCEFILE.c' has executed.
-You can use these logfiles along with `gprof' to aid in fine-tuning the
-performance of your programs. `gprof' gives timing information you can
-use along with the information you get from `gcov'.
-
- `gcov' works only on code compiled with GCC. It is not compatible
-with any other profiling or test coverage mechanism.
-
-\1f
-File: gcc.info, Node: Invoking Gcov, Next: Gcov and Optimization, Prev: Gcov Intro, Up: Gcov
-
-Invoking gcov
-=============
-
- gcov [OPTIONS] SOURCEFILE
-
- `gcov' accepts the following options:
-
-`-h'
-`--help'
- Display help about using `gcov' (on the standard output), and exit
- without doing any further processing.
-
-`-v'
-`--version'
- Display the `gcov' version number (on the standard output), and
- exit without doing any further processing.
-
-`-b'
-`--branch-probabilities'
- Write branch frequencies to the output file, and write branch
- summary info to the standard output. This option allows you to
- see how often each branch in your program was taken.
-
-`-c'
-`--branch-counts'
- Write branch frequencies as the number of branches taken, rather
- than the percentage of branches taken.
-
-`-n'
-`--no-output'
- Do not create the `gcov' output file.
-
-`-l'
-`--long-file-names'
- Create long file names for included source files. For example, if
- the header file `x.h' contains code, and was included in the file
- `a.c', then running `gcov' on the file `a.c' will produce an
- output file called `a.c.x.h.gcov' instead of `x.h.gcov'. This can
- be useful if `x.h' is included in multiple source files.
-
-`-f'
-`--function-summaries'
- Output summaries for each function in addition to the file level
- summary.
-
-`-o DIRECTORY'
-`--object-directory DIRECTORY'
- The directory where the object files live. Gcov will search for
- `.bb', `.bbg', and `.da' files in this directory.
-
- When using `gcov', you must first compile your program with two
-special GCC options: `-fprofile-arcs -ftest-coverage'. This tells the
-compiler to generate additional information needed by gcov (basically a
-flow graph of the program) and also includes additional code in the
-object files for generating the extra profiling information needed by
-gcov. These additional files are placed in the directory where the
-source code is located.
-
- Running the program will cause profile output to be generated. For
-each source file compiled with `-fprofile-arcs', an accompanying `.da'
-file will be placed in the source directory.
-
- Running `gcov' with your program's source file names as arguments
-will now produce a listing of the code along with frequency of execution
-for each line. For example, if your program is called `tmp.c', this is
-what you see when you use the basic `gcov' facility:
-
- $ gcc -fprofile-arcs -ftest-coverage tmp.c
- $ a.out
- $ gcov tmp.c
- 87.50% of 8 source lines executed in file tmp.c
- Creating tmp.c.gcov.
-
- The file `tmp.c.gcov' contains output from `gcov'. Here is a sample:
-
- main()
- {
- 1 int i, total;
-
- 1 total = 0;
-
- 11 for (i = 0; i < 10; i++)
- 10 total += i;
-
- 1 if (total != 45)
- ###### printf ("Failure\n");
- else
- 1 printf ("Success\n");
- 1 }
-
- When you use the `-b' option, your output looks like this:
-
- $ gcov -b tmp.c
- 87.50% of 8 source lines executed in file tmp.c
- 80.00% of 5 branches executed in file tmp.c
- 80.00% of 5 branches taken at least once in file tmp.c
- 50.00% of 2 calls executed in file tmp.c
- Creating tmp.c.gcov.
-
- Here is a sample of a resulting `tmp.c.gcov' file:
-
- main()
- {
- 1 int i, total;
-
- 1 total = 0;
-
- 11 for (i = 0; i < 10; i++)
- branch 0 taken = 91%
- branch 1 taken = 100%
- branch 2 taken = 100%
- 10 total += i;
-
- 1 if (total != 45)
- branch 0 taken = 100%
- ###### printf ("Failure\n");
- call 0 never executed
- branch 1 never executed
- else
- 1 printf ("Success\n");
- call 0 returns = 100%
- 1 }
-
- For each basic block, a line is printed after the last line of the
-basic block describing the branch or call that ends the basic block.
-There can be multiple branches and calls listed for a single source
-line if there are multiple basic blocks that end on that line. In this
-case, the branches and calls are each given a number. There is no
-simple way to map these branches and calls back to source constructs.
-In general, though, the lowest numbered branch or call will correspond
-to the leftmost construct on the source line.
-
- For a branch, if it was executed at least once, then a percentage
-indicating the number of times the branch was taken divided by the
-number of times the branch was executed will be printed. Otherwise, the
-message "never executed" is printed.
-
- For a call, if it was executed at least once, then a percentage
-indicating the number of times the call returned divided by the number
-of times the call was executed will be printed. This will usually be
-100%, but may be less for functions call `exit' or `longjmp', and thus
-may not return every time they are called.
-
- The execution counts are cumulative. If the example program were
-executed again without removing the `.da' file, the count for the
-number of times each line in the source was executed would be added to
-the results of the previous run(s). This is potentially useful in
-several ways. For example, it could be used to accumulate data over a
-number of program runs as part of a test verification suite, or to
-provide more accurate long-term information over a large number of
-program runs.
-
- The data in the `.da' files is saved immediately before the program
-exits. For each source file compiled with `-fprofile-arcs', the
-profiling code first attempts to read in an existing `.da' file; if the
-file doesn't match the executable (differing number of basic block
-counts) it will ignore the contents of the file. It then adds in the
-new execution counts and finally writes the data to the file.
-
-\1f
-File: gcc.info, Node: Gcov and Optimization, Next: Gcov Data Files, Prev: Invoking Gcov, Up: Gcov
-
-Using `gcov' with GCC Optimization
-==================================
-
- If you plan to use `gcov' to help optimize your code, you must first
-compile your program with two special GCC options: `-fprofile-arcs
--ftest-coverage'. Aside from that, you can use any other GCC options;
-but if you want to prove that every single line in your program was
-executed, you should not compile with optimization at the same time.
-On some machines the optimizer can eliminate some simple code lines by
-combining them with other lines. For example, code like this:
-
- if (a != b)
- c = 1;
- else
- c = 0;
-
-can be compiled into one instruction on some machines. In this case,
-there is no way for `gcov' to calculate separate execution counts for
-each line because there isn't separate code for each line. Hence the
-`gcov' output looks like this if you compiled the program with
-optimization:
-
- 100 if (a != b)
- 100 c = 1;
- 100 else
- 100 c = 0;
-
- The output shows that this block of code, combined by optimization,
-executed 100 times. In one sense this result is correct, because there
-was only one instruction representing all four of these lines. However,
-the output does not indicate how many times the result was 0 and how
-many times the result was 1.
-
-\1f
-File: gcc.info, Node: Gcov Data Files, Prev: Gcov and Optimization, Up: Gcov
-
-Brief description of `gcov' data files
-======================================
-
- `gcov' uses three files for doing profiling. The names of these
-files are derived from the original _source_ file by substituting the
-file suffix with either `.bb', `.bbg', or `.da'. All of these files
-are placed in the same directory as the source file, and contain data
-stored in a platform-independent method.
-
- The `.bb' and `.bbg' files are generated when the source file is
-compiled with the GCC `-ftest-coverage' option. The `.bb' file
-contains a list of source files (including headers), functions within
-those files, and line numbers corresponding to each basic block in the
-source file.
-
- The `.bb' file format consists of several lists of 4-byte integers
-which correspond to the line numbers of each basic block in the file.
-Each list is terminated by a line number of 0. A line number of -1 is
-used to designate that the source file name (padded to a 4-byte
-boundary and followed by another -1) follows. In addition, a line
-number of -2 is used to designate that the name of a function (also
-padded to a 4-byte boundary and followed by a -2) follows.
-
- The `.bbg' file is used to reconstruct the program flow graph for
-the source file. It contains a list of the program flow arcs (possible
-branches taken from one basic block to another) for each function which,
-in combination with the `.bb' file, enables gcov to reconstruct the
-program flow.
-
- In the `.bbg' file, the format is:
- number of basic blocks for function #0 (4-byte number)
- total number of arcs for function #0 (4-byte number)
- count of arcs in basic block #0 (4-byte number)
- destination basic block of arc #0 (4-byte number)
- flag bits (4-byte number)
- destination basic block of arc #1 (4-byte number)
- flag bits (4-byte number)
- ...
- destination basic block of arc #N (4-byte number)
- flag bits (4-byte number)
- count of arcs in basic block #1 (4-byte number)
- destination basic block of arc #0 (4-byte number)
- flag bits (4-byte number)
- ...
-
- A -1 (stored as a 4-byte number) is used to separate each function's
-list of basic blocks, and to verify that the file has been read
-correctly.
-
- The `.da' file is generated when a program containing object files
-built with the GCC `-fprofile-arcs' option is executed. A separate
-`.da' file is created for each source file compiled with this option,
-and the name of the `.da' file is stored as an absolute pathname in the
-resulting object file. This path name is derived from the source file
-name by substituting a `.da' suffix.
-
- The format of the `.da' file is fairly simple. The first 8-byte
-number is the number of counts in the file, followed by the counts
-(stored as 8-byte numbers). Each count corresponds to the number of
-times each arc in the program is executed. The counts are cumulative;
-each time the program is executed, it attempts to combine the existing
-`.da' files with the new counts for this invocation of the program. It
-ignores the contents of any `.da' files whose number of arcs doesn't
-correspond to the current program, and merely overwrites them instead.
-
- All three of these files use the functions in `gcov-io.h' to store
-integers; the functions in this header provide a machine-independent
-mechanism for storing and retrieving data from a stream.
-
-\1f
-File: gcc.info, Node: Trouble, Next: Bugs, Prev: Gcov, Up: Top
-
-Known Causes of Trouble with GCC
-********************************
-
- This section describes known problems that affect users of GCC. Most
-of these are not GCC bugs per se--if they were, we would fix them. But
-the result for a user may be like the result of a bug.
-
- Some of these problems are due to bugs in other software, some are
-missing features that are too much work to add, and some are places
-where people's opinions differ as to what is best.
-
-* Menu:
-
-* Actual Bugs:: Bugs we will fix later.
-* Cross-Compiler Problems:: Common problems of cross compiling with GCC.
-* Interoperation:: Problems using GCC with other compilers,
- and with certain linkers, assemblers and debuggers.
-* External Bugs:: Problems compiling certain programs.
-* Incompatibilities:: GCC is incompatible with traditional C.
-* Fixed Headers:: GCC uses corrected versions of system header files.
- This is necessary, but doesn't always work smoothly.
-* Standard Libraries:: GCC uses the system C library, which might not be
- compliant with the ISO C standard.
-* Disappointments:: Regrettable things we can't change, but not quite bugs.
-* C++ Misunderstandings:: Common misunderstandings with GNU C++.
-* Protoize Caveats:: Things to watch out for when using `protoize'.
-* Non-bugs:: Things we think are right, but some others disagree.
-* Warnings and Errors:: Which problems in your code get warnings,
- and which get errors.
-
-\1f
-File: gcc.info, Node: Actual Bugs, Next: Cross-Compiler Problems, Up: Trouble
-
-Actual Bugs We Haven't Fixed Yet
-================================
-
- * The `fixincludes' script interacts badly with automounters; if the
- directory of system header files is automounted, it tends to be
- unmounted while `fixincludes' is running. This would seem to be a
- bug in the automounter. We don't know any good way to work around
- it.
-
- * The `fixproto' script will sometimes add prototypes for the
- `sigsetjmp' and `siglongjmp' functions that reference the
- `jmp_buf' type before that type is defined. To work around this,
- edit the offending file and place the typedef in front of the
- prototypes.
-
- * When `-pedantic-errors' is specified, GCC will incorrectly give an
- error message when a function name is specified in an expression
- involving the comma operator.
-
-\1f
-File: gcc.info, Node: Cross-Compiler Problems, Next: Interoperation, Prev: Actual Bugs, Up: Trouble
-
-Cross-Compiler Problems
-=======================
-
- You may run into problems with cross compilation on certain machines,
-for several reasons.
-
- * Cross compilation can run into trouble for certain machines because
- some target machines' assemblers require floating point numbers to
- be written as _integer_ constants in certain contexts.
-
- The compiler writes these integer constants by examining the
- floating point value as an integer and printing that integer,
- because this is simple to write and independent of the details of
- the floating point representation. But this does not work if the
- compiler is running on a different machine with an incompatible
- floating point format, or even a different byte-ordering.
-
- In addition, correct constant folding of floating point values
- requires representing them in the target machine's format. (The C
- standard does not quite require this, but in practice it is the
- only way to win.)
-
- It is now possible to overcome these problems by defining macros
- such as `REAL_VALUE_TYPE'. But doing so is a substantial amount of
- work for each target machine. *Note Cross Compilation and
- Floating Point: (gccint)Cross-compilation.
-
- * At present, the program `mips-tfile' which adds debug support to
- object files on MIPS systems does not work in a cross compile
- environment.
-
-\1f
-File: gcc.info, Node: Interoperation, Next: External Bugs, Prev: Cross-Compiler Problems, Up: Trouble
-
-Interoperation
-==============
-
- This section lists various difficulties encountered in using GCC
-together with other compilers or with the assemblers, linkers,
-libraries and debuggers on certain systems.
-
- * On many platforms, GCC supports a different ABI for C++ than do
- other compilers, so the object files compiled by GCC cannot be
- used with object files generated by another C++ compiler.
-
- An area where the difference is most apparent is name mangling.
- The use of different name mangling is intentional, to protect you
- from more subtle problems. Compilers differ as to many internal
- details of C++ implementation, including: how class instances are
- laid out, how multiple inheritance is implemented, and how virtual
- function calls are handled. If the name encoding were made the
- same, your programs would link against libraries provided from
- other compilers--but the programs would then crash when run.
- Incompatible libraries are then detected at link time, rather than
- at run time.
-
- * Older GDB versions sometimes fail to read the output of GCC version
- 2. If you have trouble, get GDB version 4.4 or later.
-
- * DBX rejects some files produced by GCC, though it accepts similar
- constructs in output from PCC. Until someone can supply a coherent
- description of what is valid DBX input and what is not, there is
- nothing I can do about these problems. You are on your own.
-
- * The GNU assembler (GAS) does not support PIC. To generate PIC
- code, you must use some other assembler, such as `/bin/as'.
-
- * On some BSD systems, including some versions of Ultrix, use of
- profiling causes static variable destructors (currently used only
- in C++) not to be run.
-
- * On some SGI systems, when you use `-lgl_s' as an option, it gets
- translated magically to `-lgl_s -lX11_s -lc_s'. Naturally, this
- does not happen when you use GCC. You must specify all three
- options explicitly.
-
- * On a Sparc, GCC aligns all values of type `double' on an 8-byte
- boundary, and it expects every `double' to be so aligned. The Sun
- compiler usually gives `double' values 8-byte alignment, with one
- exception: function arguments of type `double' may not be aligned.
-
- As a result, if a function compiled with Sun CC takes the address
- of an argument of type `double' and passes this pointer of type
- `double *' to a function compiled with GCC, dereferencing the
- pointer may cause a fatal signal.
-
- One way to solve this problem is to compile your entire program
- with GCC. Another solution is to modify the function that is
- compiled with Sun CC to copy the argument into a local variable;
- local variables are always properly aligned. A third solution is
- to modify the function that uses the pointer to dereference it via
- the following function `access_double' instead of directly with
- `*':
-
- inline double
- access_double (double *unaligned_ptr)
- {
- union d2i { double d; int i[2]; };
-
- union d2i *p = (union d2i *) unaligned_ptr;
- union d2i u;
-
- u.i[0] = p->i[0];
- u.i[1] = p->i[1];
-
- return u.d;
- }
-
- Storing into the pointer can be done likewise with the same union.
-
- * On Solaris, the `malloc' function in the `libmalloc.a' library may
- allocate memory that is only 4 byte aligned. Since GCC on the
- Sparc assumes that doubles are 8 byte aligned, this may result in a
- fatal signal if doubles are stored in memory allocated by the
- `libmalloc.a' library.
-
- The solution is to not use the `libmalloc.a' library. Use instead
- `malloc' and related functions from `libc.a'; they do not have
- this problem.
-
- * Sun forgot to include a static version of `libdl.a' with some
- versions of SunOS (mainly 4.1). This results in undefined symbols
- when linking static binaries (that is, if you use `-static'). If
- you see undefined symbols `_dlclose', `_dlsym' or `_dlopen' when
- linking, compile and link against the file `mit/util/misc/dlsym.c'
- from the MIT version of X windows.
-
- * The 128-bit long double format that the Sparc port supports
- currently works by using the architecturally defined quad-word
- floating point instructions. Since there is no hardware that
- supports these instructions they must be emulated by the operating
- system. Long doubles do not work in Sun OS versions 4.0.3 and
- earlier, because the kernel emulator uses an obsolete and
- incompatible format. Long doubles do not work in Sun OS version
- 4.1.1 due to a problem in a Sun library. Long doubles do work on
- Sun OS versions 4.1.2 and higher, but GCC does not enable them by
- default. Long doubles appear to work in Sun OS 5.x (Solaris 2.x).
-
- * On HP-UX version 9.01 on the HP PA, the HP compiler `cc' does not
- compile GCC correctly. We do not yet know why. However, GCC
- compiled on earlier HP-UX versions works properly on HP-UX 9.01
- and can compile itself properly on 9.01.
-
- * On the HP PA machine, ADB sometimes fails to work on functions
- compiled with GCC. Specifically, it fails to work on functions
- that use `alloca' or variable-size arrays. This is because GCC
- doesn't generate HP-UX unwind descriptors for such functions. It
- may even be impossible to generate them.
-
- * Debugging (`-g') is not supported on the HP PA machine, unless you
- use the preliminary GNU tools.
-
- * Taking the address of a label may generate errors from the HP-UX
- PA assembler. GAS for the PA does not have this problem.
-
- * Using floating point parameters for indirect calls to static
- functions will not work when using the HP assembler. There simply
- is no way for GCC to specify what registers hold arguments for
- static functions when using the HP assembler. GAS for the PA does
- not have this problem.
-
- * In extremely rare cases involving some very large functions you may
- receive errors from the HP linker complaining about an out of
- bounds unconditional branch offset. This used to occur more often
- in previous versions of GCC, but is now exceptionally rare. If
- you should run into it, you can work around by making your
- function smaller.
-
- * GCC compiled code sometimes emits warnings from the HP-UX
- assembler of the form:
-
- (warning) Use of GR3 when
- frame >= 8192 may cause conflict.
-
- These warnings are harmless and can be safely ignored.
-
- * On the IBM RS/6000, compiling code of the form
-
- extern int foo;
-
- ... foo ...
-
- static int foo;
-
- will cause the linker to report an undefined symbol `foo'.
- Although this behavior differs from most other systems, it is not a
- bug because redefining an `extern' variable as `static' is
- undefined in ISO C.
-
- * In extremely rare cases involving some very large functions you may
- receive errors from the AIX Assembler complaining about a
- displacement that is too large. If you should run into it, you
- can work around by making your function smaller.
-
- * The `libstdc++.a' library in GCC relies on the SVR4 dynamic linker
- semantics which merges global symbols between libraries and
- applications, especially necessary for C++ streams functionality.
- This is not the default behavior of AIX shared libraries and
- dynamic linking. `libstdc++.a' is built on AIX with
- "runtime-linking" enabled so that symbol merging can occur. To
- utilize this feature, the application linked with `libstdc++.a'
- must include the `-Wl,-brtl' flag on the link line. G++ cannot
- impose this because this option may interfere with the semantics
- of the user program and users may not always use `g++' to link his
- or her application. Applications are not required to use the
- `-Wl,-brtl' flag on the link line--the rest of the `libstdc++.a'
- library which is not dependent on the symbol merging semantics
- will continue to function correctly.
-
- * An application can interpose its own definition of functions for
- functions invoked by `libstdc++.a' with "runtime-linking" enabled
- on AIX. To accomplish this the application must be linked with
- "runtime-linking" option and the functions explicitly must be
- exported by the application (`-Wl,-brtl,-bE:exportfile').
-
- * AIX on the RS/6000 provides support (NLS) for environments outside
- of the United States. Compilers and assemblers use NLS to support
- locale-specific representations of various objects including
- floating-point numbers (`.' vs `,' for separating decimal
- fractions). There have been problems reported where the library
- linked with GCC does not produce the same floating-point formats
- that the assembler accepts. If you have this problem, set the
- `LANG' environment variable to `C' or `En_US'.
-
- * Even if you specify `-fdollars-in-identifiers', you cannot
- successfully use `$' in identifiers on the RS/6000 due to a
- restriction in the IBM assembler. GAS supports these identifiers.
-
- * There is an assembler bug in versions of DG/UX prior to 5.4.2.01
- that occurs when the `fldcr' instruction is used. GCC uses
- `fldcr' on the 88100 to serialize volatile memory references. Use
- the option `-mno-serialize-volatile' if your version of the
- assembler has this bug.
-
- * On VMS, GAS versions 1.38.1 and earlier may cause spurious warning
- messages from the linker. These warning messages complain of
- mismatched psect attributes. You can ignore them.
-
- * On NewsOS version 3, if you include both of the files `stddef.h'
- and `sys/types.h', you get an error because there are two typedefs
- of `size_t'. You should change `sys/types.h' by adding these
- lines around the definition of `size_t':
-
- #ifndef _SIZE_T
- #define _SIZE_T
- ACTUAL-TYPEDEF-HERE
- #endif
-
- * On the Alliant, the system's own convention for returning
- structures and unions is unusual, and is not compatible with GCC
- no matter what options are used.
-
- * On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different
- convention for structure and union returning. Use the option
- `-mhc-struct-return' to tell GCC to use a convention compatible
- with it.
-
- * On Ultrix, the Fortran compiler expects registers 2 through 5 to
- be saved by function calls. However, the C compiler uses
- conventions compatible with BSD Unix: registers 2 through 5 may be
- clobbered by function calls.
-
- GCC uses the same convention as the Ultrix C compiler. You can use
- these options to produce code compatible with the Fortran compiler:
-
- -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
-
- * On the WE32k, you may find that programs compiled with GCC do not
- work with the standard shared C library. You may need to link with
- the ordinary C compiler. If you do so, you must specify the
- following options:
-
- -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.8.1 -lgcc -lc_s
-
- The first specifies where to find the library `libgcc.a' specified
- with the `-lgcc' option.
-
- GCC does linking by invoking `ld', just as `cc' does, and there is
- no reason why it _should_ matter which compilation program you use
- to invoke `ld'. If someone tracks this problem down, it can
- probably be fixed easily.
-
- * On the Alpha, you may get assembler errors about invalid syntax as
- a result of floating point constants. This is due to a bug in the
- C library functions `ecvt', `fcvt' and `gcvt'. Given valid
- floating point numbers, they sometimes print `NaN'.
-
- * On Irix 4.0.5F (and perhaps in some other versions), an assembler
- bug sometimes reorders instructions incorrectly when optimization
- is turned on. If you think this may be happening to you, try
- using the GNU assembler; GAS version 2.1 supports ECOFF on Irix.
-
- Or use the `-noasmopt' option when you compile GCC with itself,
- and then again when you compile your program. (This is a temporary
- kludge to turn off assembler optimization on Irix.) If this
- proves to be what you need, edit the assembler spec in the file
- `specs' so that it unconditionally passes `-O0' to the assembler,
- and never passes `-O2' or `-O3'.
-
-\1f
-File: gcc.info, Node: External Bugs, Next: Incompatibilities, Prev: Interoperation, Up: Trouble
-
-Problems Compiling Certain Programs
-===================================
-
- Certain programs have problems compiling.
-
- * Parse errors may occur compiling X11 on a Decstation running
- Ultrix 4.2 because of problems in DEC's versions of the X11 header
- files `X11/Xlib.h' and `X11/Xutil.h'. People recommend adding
- `-I/usr/include/mit' to use the MIT versions of the header files,
- using the `-traditional' switch to turn off ISO C, or fixing the
- header files by adding this:
-
- #ifdef __STDC__
- #define NeedFunctionPrototypes 0
- #endif
-
- * On various 386 Unix systems derived from System V, including SCO,
- ISC, and ESIX, you may get error messages about running out of
- virtual memory while compiling certain programs.
-
- You can prevent this problem by linking GCC with the GNU malloc
- (which thus replaces the malloc that comes with the system). GNU
- malloc is available as a separate package, and also in the file
- `src/gmalloc.c' in the GNU Emacs 19 distribution.
-
- If you have installed GNU malloc as a separate library package,
- use this option when you relink GCC:
-
- MALLOC=/usr/local/lib/libgmalloc.a
-
- Alternatively, if you have compiled `gmalloc.c' from Emacs 19, copy
- the object file to `gmalloc.o' and use this option when you relink
- GCC:
-
- MALLOC=gmalloc.o
-