OSDN Git Service

* doc/trouble.texi: Remove obsolete information. Update
[pf3gnuchains/gcc-fork.git] / gcc / doc / trouble.texi
index b578536..e206041 100644 (file)
@@ -22,7 +22,6 @@ where people's opinions differ as to what is best.
 * 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.
@@ -52,12 +51,6 @@ The @code{fixproto} script will sometimes add prototypes for the
 @code{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.
-
-@item
-@opindex pedantic-errors
-When @option{-pedantic-errors} is specified, GCC will incorrectly give
-an error message when a function name is specified in an expression
-involving the comma operator.
 @end itemize
 
 @node Cross-Compiler Problems
@@ -68,29 +61,6 @@ for several reasons.
 
 @itemize @bullet
 @item
-Cross compilation can run into trouble for certain machines because
-some target machines' assemblers require floating point numbers to be
-written as @emph{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 @code{REAL_VALUE_TYPE}.  But doing so is a substantial amount of
-work for each target machine.
-@xref{Cross-compilation,,Cross Compilation and Floating Point,
-gccint, GNU Compiler Collection (GCC) Internals}.
-
-@item
 At present, the program @file{mips-tfile} which adds debug
 support to object files on MIPS systems does not work in a cross
 compile environment.
@@ -121,41 +91,10 @@ run.  Incompatible libraries are then detected at link time, rather than
 at run time.
 
 @item
-Older GDB versions sometimes fail to read the output of GCC version
-2.  If you have trouble, get GDB version 4.4 or later.
-
-@item
-@cindex DBX
-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.
-
-@item
-The GNU assembler (GAS) does not support PIC@.  To generate PIC code, you
-must use some other assembler, such as @file{/bin/as}.
-
-@item
 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.
 
-@ignore
-@cindex @code{vfork}, for the Sun-4
-@item
-There is a bug in @code{vfork} on the Sun-4 which causes the registers
-of the child process to clobber those of the parent.  Because of this,
-programs that call @code{vfork} are likely to lose when compiled
-optimized with GCC when the child code alters registers which contain
-C variables in the parent.  This affects variables which are live in the
-parent across the call to @code{vfork}.
-
-If you encounter this, you can work around the problem by declaring
-variables @code{volatile} in the function that calls @code{vfork}, until
-the problem goes away, or by not declaring them @code{register} and not
-using @option{-O} for those source files.
-@end ignore
-
 @item
 On some SGI systems, when you use @option{-lgl_s} as an option,
 it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}.
@@ -211,32 +150,6 @@ The solution is to not use the @file{libmalloc.a} library.  Use instead
 this problem.
 
 @item
-Sun forgot to include a static version of @file{libdl.a} with some
-versions of SunOS (mainly 4.1).  This results in undefined symbols when
-linking static binaries (that is, if you use @option{-static}).  If you
-see undefined symbols @code{_dlclose}, @code{_dlsym} or @code{_dlopen}
-when linking, compile and link against the file
-@file{mit/util/misc/dlsym.c} from the MIT version of X windows.
-
-@item
-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).
-
-@item
-On HP-UX version 9.01 on the HP PA, the HP compiler @code{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.
-
-@item
 On the HP PA machine, ADB sometimes fails to work on functions compiled
 with GCC@.  Specifically, it fails to work on functions that use
 @code{alloca} or variable-size arrays.  This is because GCC doesn't
@@ -276,23 +189,6 @@ the form:
 These warnings are harmless and can be safely ignored.
 
 @item
-On the IBM RS/6000, compiling code of the form
-
-@smallexample
-extern int foo;
-
-@dots{} foo @dots{}
-
-static int foo;
-@end smallexample
-
-@noindent
-will cause the linker to report an undefined symbol @code{foo}.
-Although this behavior differs from most other systems, it is not a
-bug because redefining an @code{extern} variable as @code{static}
-is undefined in ISO C@.
-
-@item
 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
@@ -352,58 +248,6 @@ these options to produce code compatible with the Fortran compiler:
 @smallexample
 -fcall-saved-r2 -fcall-saved-r3 -fcall-saved-r4 -fcall-saved-r5
 @end smallexample
-
-@item
-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 @code{ecvt}, @code{fcvt} and @code{gcvt}.  Given valid
-floating point numbers, they sometimes print @samp{NaN}.
-@end itemize
-
-@node External Bugs
-@section Problems Compiling Certain Programs
-
-@c prevent bad page break with this line
-Certain programs have problems compiling.
-
-@itemize @bullet
-@item
-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
-@file{X11/Xlib.h} and @file{X11/Xutil.h}.  People recommend adding
-@option{-I/usr/include/mit} to use the MIT versions of the header files,
-or fixing the header files by adding this:
-
-@smallexample
-#ifdef __STDC__
-#define NeedFunctionPrototypes 0
-#endif
-@end smallexample
-
-@item
-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
-@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:
-
-@smallexample
-MALLOC=/usr/local/lib/libgmalloc.a
-@end smallexample
-
-Alternatively, if you have compiled @file{gmalloc.c} from Emacs 19, copy
-the object file to @file{gmalloc.o} and use this option when you relink
-GCC:
-
-@smallexample
-MALLOC=gmalloc.o
-@end smallexample
 @end itemize
 
 @node Incompatibilities
@@ -509,8 +353,7 @@ ISO C does not permit such a construct.
 
 @item
 K&R compilers allow comments to cross over an inclusion boundary
-(i.e.@: started in an include file and ended in the including file).  I think
-this would be quite ugly and can't imagine it could be needed.
+(i.e.@: started in an include file and ended in the including file).
 
 @cindex external declaration scope
 @cindex scope of external declarations
@@ -663,8 +506,7 @@ incompatible with ISO C, and some depend on special features of other
 compilers.
 
 Installing GCC automatically creates and installs the fixed header
-files, by running a program called @code{fixincludes} (or for certain
-targets an alternative such as @code{fixinc.svr4}).  Normally, you
+files, by running a program called @code{fixincludes}.  Normally, you
 don't need to pay attention to this.  But there are cases where it
 doesn't do the right thing automatically.
 
@@ -672,35 +514,23 @@ doesn't do the right thing automatically.
 @item
 If you update the system's header files, such as by installing a new
 system version, the fixed header files of GCC are not automatically
-updated.  The easiest way to update them is to reinstall GCC@.  (If
-you want to be clever, look in the makefile and you can find a
-shortcut.)
+updated.  They can be updated using the @command{mkheaders} script
+installed in
+@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}.
 
 @item
-On some systems, in particular SunOS 4, header file directories contain
+On some systems, header file directories contain
 machine-specific symbolic links in certain places.  This makes it
 possible to share most of the header files among hosts running the
-same version of SunOS 4 on different machine models.
+same version of the system on different machine models.
 
 The programs that fix the header files do not understand this special
 way of using symbolic links; therefore, the directory of fixed header
 files is good only for the machine model used to build it.
 
-In SunOS 4, only programs that look inside the kernel will notice the
-difference between machine models.  Therefore, for most purposes, you
-need not be concerned about this.
-
 It is possible to make separate sets of fixed header files for the
 different machine models, and arrange a structure of symbolic links so
 as to use the proper set, but you'll have to do this by hand.
-
-@item
-On Lynxos, GCC by default does not fix the header files.  This is
-because bugs in the shell cause the @code{fixincludes} script to fail.
-
-This means you will encounter problems due to bugs in the system header
-files.  It may be no comfort that they aren't GCC's fault, but it
-does mean that there's nothing for us to do about them.
 @end itemize
 
 @node Standard Libraries
@@ -797,11 +627,9 @@ scripts adapt to various systems by searching all the system header
 files for the problem cases that we know about.
 
 If new system header files are installed, nothing automatically arranges
-to update the corrected header files.  You will have to reinstall GCC
-to fix the new header files.  More specifically, go to the build
-directory and delete the files @file{stmp-fixinc} and
-@file{stmp-headers}, and the subdirectory @code{include}; then do
-@samp{make install} again.
+to update the corrected header files.  They can be updated using the
+@command{mkheaders} script installed in
+@file{@var{libexecdir}/gcc/@var{target}/@var{version}/install-tools/}.
 
 @item
 @cindex floating point precision
@@ -911,11 +739,11 @@ of instantiation.  For example, consider
   struct A @{
     template <typename T>
     void f () @{
-      foo (1);        // 1
-      int i = N;      // 2
+      foo (1);        // @r{1}
+      int i = N;      // @r{2}
       T t;
-      t.bar();        // 3
-      foo (t);        // 4
+      t.bar();        // @r{3}
+      foo (t);        // @r{4}
     @}
 
     static const int N;
@@ -999,11 +827,11 @@ compiler will consequently produce the following error message:
 @end smallexample
 
 To make the code valid either use @code{this->f()}, or
-@code{Base<T>::f()}.  Using the @code{-fpermissive} flag will also let
+@code{Base<T>::f()}.  Using the @option{-fpermissive} flag will also let
 the compiler accept the code, by marking all function calls for which no
 declaration is visible at the time of definition of the template for
 later lookup at instantiation time, as if it were a dependent call.
-We do not recommend using @code{-fpermissive} to work around invalid
+We do not recommend using @option{-fpermissive} to work around invalid
 code, and it will also only catch cases where functions in base classes
 are called, not where variables in base classes are used (as in the
 example above).
@@ -1065,7 +893,7 @@ forces it to remain until the end of the scope of the name.  For
 example:
 
 @smallexample
-string& tmp = strfunc ();
+const string& tmp = strfunc ();
 charfunc (tmp.c_str ());
 @end smallexample
 
@@ -1242,11 +1070,16 @@ more annoyance than good.
 @item
 Warning when a non-void function value is ignored.
 
-Coming as I do from a Lisp background, I balk at the idea that there is
-something dangerous about discarding a value.  There are functions that
-return values which some callers may find useful; it makes no sense to
-clutter the program with a cast to @code{void} whenever the value isn't
-useful.
+C contains many standard functions that return a value that most
+programs choose to ignore.  One obvious example is @code{printf}.
+Warning about this practice only leads the defensive programmer to
+clutter programs with dozens of casts to @code{void}.  Such casts are
+required so frequently that they become visual noise.  Writing those
+casts becomes so automatic that they no longer convey useful
+information about the intentions of the programmer.  For functions
+where the return value should never be ignored, use the
+@code{warn_unused_result} function attribute (@pxref{Function
+Attributes}).
 
 @item
 @opindex fshort-enums
@@ -1414,14 +1247,6 @@ order.  Either increment might happen first.  @code{func} might get the
 arguments @samp{2, 3}, or it might get @samp{3, 2}, or even @samp{2, 2}.
 
 @item
-Not allowing structures with volatile fields in registers.
-
-Strictly speaking, there is no prohibition in the ISO C standard
-against allowing structures with volatile fields in registers, but
-it does not seem to make any sense and is probably not what you wanted
-to do.  So the compiler will give an error message in this case.
-
-@item
 Making certain warnings into errors by default.
 
 Some ISO C testsuites report failure when the compiler does not produce
@@ -1431,7 +1256,7 @@ an error message for a certain program.
 ISO C requires a ``diagnostic'' message for certain kinds of invalid
 programs, but a warning is defined by GCC to count as a diagnostic.  If
 GCC produces a warning but not an error, that is correct ISO C support.
-If test suites call this ``failure'', they should be run with the GCC
+If testsuites call this ``failure'', they should be run with the GCC
 option @option{-pedantic-errors}, which will turn these warnings into
 errors.