| >\input texinfo @c -*-texinfo-*- |
| @c %**start of header |
| @setfilename gcc.info |
| @c @setfilename usegcc.info |
| @c @setfilename portgcc.info |
| @c To produce the full manual, use the "gcc.info" setfilename, and |
| @c make sure the following do NOT begin with '@c' (and the @clear lines DO) |
| @set INTERNALS |
| @set USING |
| @c To produce a user-only manual, use the "usegcc.info" setfilename, and |
| @c make sure the following does NOT begin with '@c': |
| @c @clear INTERNALS |
| @c To produce a porter-only manual, use the "portgcc.info" setfilename, |
| @c and make sure the following does NOT begin with '@c': |
| @c @clear USING |
| |
| @c (For FSF printing, turn on smallbook, comment out finalout below; |
| @c that is all that is needed.) |
| |
| @c 6/27/96 FSF DO wants smallbook fmt for 1st bound edition. |
| @c @smallbook |
| |
| @c i also commented out the finalout command, so if there *are* any |
| @c overfulls, you'll (hopefully) see the rectangle in the right hand |
| @c margin. -mew 15june93 |
| @c @finalout |
| |
| @c NOTE: checks/things to do: |
| @c |
| @c -have bob do a search in all seven files for "mew" (ideally --mew, |
| @c but i may have forgotten the occasional "--"..). |
| @c Just checked... all have `--'! Bob 22Jul96 |
| @c Use this to search: grep -n '\-\-mew' *.texi |
| @c -item/itemx, text after all (sub/sub)section titles, etc.. |
| @c -consider putting the lists of options on pp 17--> etc in columns or |
| @c some such. |
| @c -spellcheck |
| @c -continuity of phrasing; ie, bit-field vs bitfield in rtl.texi |
| @c -overfulls. do a search for "mew" in the files, and you will see |
| @c overfulls that i noted but could not deal with. |
| @c -have to add text: beginning of chapter 8 |
| |
| @c |
| @c anything else? --mew 10feb93 |
| |
| |
| |
| @ifset INTERNALS |
| @ifset USING |
| @settitle Using and Porting GNU CC |
| @end ifset |
| @end ifset |
| @c seems reasonable to assume at least one of INTERNALS or USING is set... |
| @ifclear INTERNALS |
| @settitle Using GNU CC |
| @end ifclear |
| @ifclear USING |
| @settitle Porting GNU CC |
| @end ifclear |
| |
| @syncodeindex fn cp |
| @syncodeindex vr cp |
| @c %**end of header |
| |
| @c Use with @@smallbook. |
| |
| @c Cause even numbered pages to be printed on the left hand side of |
| @c the page and odd numbered pages to be printed on the right hand |
| @c side of the page. Using this, you can print on both sides of a |
| @c sheet of paper and have the text on the same part of the sheet. |
| |
| @c The text on right hand pages is pushed towards the right hand |
| @c margin and the text on left hand pages is pushed toward the left |
| @c hand margin. |
| @c (To provide the reverse effect, set bindingoffset to -0.75in.) |
| |
| @c @tex |
| @c \global\bindingoffset=0.75in |
| @c \global\normaloffset =0.75in |
| @c @end tex |
| |
| @ifinfo |
| @ifset INTERNALS |
| @ifset USING |
| This file documents the use and the internals of the GNU compiler. |
| @end ifset |
| @end ifset |
| @ifclear USING |
| This file documents the internals of the GNU compiler. |
| @end ifclear |
| @ifclear INTERNALS |
| This file documents the use of the GNU compiler. |
| @end ifclear |
| |
| 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 Free Software Foundation, Inc. |
| |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| @ignore |
| Permission is granted to process this file through Tex and print the |
| results, provided the printed document carries copying permission |
| notice identical to this one except for the removal of this paragraph |
| (this paragraph not being relevant to the printed manual). |
| |
| @end ignore |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that the |
| sections entitled ``GNU General Public License,'' ``Funding for Free |
| Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are |
| included exactly as in the original, and provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions, |
| except that the sections entitled ``GNU General Public License,'' |
| ``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look |
| And Feel'@w{}'', and this permission notice, may be included in |
| translations approved by the Free Software Foundation instead of in the |
| original English. |
| @end ifinfo |
| |
| @setchapternewpage odd |
| |
| @titlepage |
| @ifset INTERNALS |
| @ifset USING |
| @center @titlefont{Using and Porting GNU CC} |
| |
| @end ifset |
| @end ifset |
| @ifclear INTERNALS |
| @title Using GNU CC |
| @end ifclear |
| @ifclear USING |
| @title Porting GNU CC |
| @end ifclear |
| @sp 2 |
| @center Richard M. Stallman |
| @sp 3 |
| @center Last updated 26 November 1995 |
| @sp 1 |
| @c The version number appears twice more in this file. |
| |
| @center for egcs-1.0.3 |
| @page |
| @vskip 0pt plus 1filll |
| Copyright @copyright{} 1988, 89, 92, 93, 94, 95, 96 Free Software Foundation, Inc. |
| @sp 2 |
| For EGCS Version 1.0@* |
| @sp 1 |
| Published by the Free Software Foundation @* |
| 59 Temple Place - Suite 330@* |
| Boston, MA 02111-1307, USA@* |
| Last printed November, 1995.@* |
| Printed copies are available for $50 each.@* |
| ISBN 1-882114-36-1 |
| @sp 1 |
| Permission is granted to make and distribute verbatim copies of |
| this manual provided the copyright notice and this permission notice |
| are preserved on all copies. |
| |
| Permission is granted to copy and distribute modified versions of this |
| manual under the conditions for verbatim copying, provided also that the |
| sections entitled ``GNU General Public License,'' ``Funding for Free |
| Software,'' and ``Protect Your Freedom---Fight `Look And Feel'@w{}'' are |
| included exactly as in the original, and provided that the entire |
| resulting derived work is distributed under the terms of a permission |
| notice identical to this one. |
| |
| Permission is granted to copy and distribute translations of this manual |
| into another language, under the above conditions for modified versions, |
| except that the sections entitled ``GNU General Public License,'' |
| ``Funding for Free Software,'' and ``Protect Your Freedom---Fight `Look |
| And Feel'@w{}'', and this permission notice, may be included in |
| translations approved by the Free Software Foundation instead of in the |
| original English. |
| @end titlepage |
| @page |
| |
| @ifinfo |
| |
| @node Top, G++ and GCC,, (DIR) |
| @top Introduction |
| @cindex introduction |
| |
| @ifset INTERNALS |
| @ifset USING |
| This manual documents how to run, install and port the GNU |
| compiler, as well as its new features and incompatibilities, and how to |
| report bugs. It corresponds to EGCS version 1.0. |
| @end ifset |
| @end ifset |
| |
| @ifclear INTERNALS |
| This manual documents how to run and install the GNU compiler, |
| as well as its new features and incompatibilities, and how to report |
| bugs. It corresponds to EGCS version 1.0. |
| @end ifclear |
| @ifclear USING |
| This manual documents how to port the GNU compiler, |
| as well as its new features and incompatibilities, and how to report |
| bugs. It corresponds to EGCS version 1.0. |
| @end ifclear |
| |
| @end ifinfo |
| @menu |
| @ifset USING |
| * G++ and GCC:: You can compile C or C++ programs. |
| * Invoking GCC:: Command options supported by @samp{gcc}. |
| * Installation:: How to configure, compile and install GNU CC. |
| * C Extensions:: GNU extensions to the C language family. |
| * C++ Extensions:: GNU extensions to the C++ language. |
| * Gcov:: gcov: a GNU CC test coverage program. |
| * Trouble:: If you have trouble installing GNU CC. |
| * Bugs:: How, why and where to report bugs. |
| * Service:: How to find suppliers of support for GNU CC. |
| * Contributing:: How to contribute to testing and developing GNU CC. |
| * VMS:: Using GNU CC on VMS. |
| @end ifset |
| @ifset INTERNALS |
| * Portability:: Goals of GNU CC's portability features. |
| * Interface:: Function-call interface of GNU CC output. |
| * Passes:: Order of passes, what they do, and what each file is for. |
| * RTL:: The intermediate representation that most passes work on. |
| * Machine Desc:: How to write machine description instruction patterns. |
| * Target Macros:: How to write the machine description C macros. |
| * Config:: Writing the @file{xm-@var{machine}.h} file. |
| * Fragments:: Writing the @file{t-@var{target}} and @file{x-@var{host}} files. |
| @end ifset |
| |
| * Funding:: How to help assure funding for free software. |
| * Look and Feel:: Protect your freedom---fight ``look and feel''. |
| |
| * Copying:: GNU General Public License says |
| how you can copy and share GNU CC. |
| * Contributors:: People who have contributed to GNU CC. |
| |
| * Index:: Index of concepts and symbol names. |
| @end menu |
| |
| @ifset USING |
| @node G++ and GCC |
| @chapter Compile C, C++, or Objective C |
| |
| @cindex Objective C |
| The C, C++, and Objective C versions of the compiler are integrated; the |
| GNU C compiler can compile programs written in C, C++, or Objective C. |
| |
| @cindex GCC |
| ``GCC'' is a common shorthand term for the GNU C compiler. This is both |
| the most general name for the compiler, and the name used when the |
| emphasis is on compiling C programs. |
| |
| @cindex C++ |
| @cindex G++ |
| When referring to C++ compilation, it is usual to call the compiler |
| ``G++''. Since there is only one compiler, it is also accurate to call |
| it ``GCC'' no matter what the language context; however, the term |
| ``G++'' is more useful when the emphasis is on compiling C++ programs. |
| |
| We use the name ``GNU CC'' to refer to the compilation system as a |
| whole, and more specifically to the language-independent part of the |
| compiler. For example, we refer to the optimization options as |
| affecting the behavior of ``GNU CC'' or sometimes just ``the compiler''. |
| |
| Front ends for other languages, such as Ada 9X, Fortran, Modula-3, and |
| Pascal, are under development. These front-ends, like that for C++, are |
| built in subdirectories of GNU CC and link to it. The result is an |
| integrated compiler that can compile programs written in C, C++, |
| Objective C, or any of the languages for which you have installed front |
| ends. |
| |
| In this manual, we only discuss the options for the C, Objective-C, and |
| C++ compilers and those of the GNU CC core. Consult the documentation |
| of the other front ends for the options to use when compiling programs |
| written in other languages. |
| |
| @cindex compiler compared to C++ preprocessor |
| @cindex intermediate C version, nonexistent |
| @cindex C intermediate output, nonexistent |
| G++ is a @emph{compiler}, not merely a preprocessor. G++ builds object |
| code directly from your C++ program source. There is no intermediate C |
| version of the program. (By contrast, for example, some other |
| implementations use a program that generates a C program from your C++ |
| source.) Avoiding an intermediate C representation of the program means |
| that you get better object code, and better debugging information. The |
| GNU debugger, GDB, works with this information in the object code to |
| give you comprehensive C++ source-level editing capabilities |
| (@pxref{C,,C and C++,gdb.info, Debugging with GDB}). |
| |
| @c FIXME! Someone who knows something about Objective C ought to put in |
| @c a paragraph or two about it here, and move the index entry down when |
| @c there is more to point to than the general mention in the 1st par. |
| |
| @include invoke.texi |
| |
| @include install.texi |
| |
| @include extend.texi |
| |
| @include gcov.texi |
| |
| @node Trouble |
| @chapter Known Causes of Trouble with GNU CC |
| @cindex bugs, known |
| @cindex installation trouble |
| @cindex known causes of trouble |
| |
| This section describes known problems that affect users of GNU CC. Most |
| of these are not GNU CC 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. |
| * Installation Problems:: Problems that manifest when you install GNU CC. |
| * Cross-Compiler Problems:: Common problems of cross compiling with GNU CC. |
| * Interoperation:: Problems using GNU CC with other compilers, |
| and with certain linkers, assemblers and debuggers. |
| * External Bugs:: Problems compiling certain programs. |
| * Incompatibilities:: GNU CC is incompatible with traditional C. |
| * Fixed Headers:: GNU C uses corrected versions of system header files. |
| This is necessary, but doesn't always work smoothly. |
| * Standard Libraries:: GNU C uses the system C library, which might not be |
| compliant with the ISO/ANSI 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 @code{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. |
| @end menu |
| |
| @node Actual Bugs |
| @section Actual Bugs We Haven't Fixed Yet |
| |
| @itemize @bullet |
| @item |
| The @code{fixincludes} script interacts badly with automounters; if the |
| directory of system header files is automounted, it tends to be |
| unmounted while @code{fixincludes} is running. This would seem to be a |
| bug in the automounter. We don't know any good way to work around it. |
| |
| @item |
| The @code{fixproto} script will sometimes add prototypes for the |
| @code{sigsetjmp} and @code{siglongjmp} functions that reference 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 |
| There are several obscure case of mis-using struct, union, and |
| enum tags that are not detected as errors by the compiler. |
| |
| @item |
| When @samp{-pedantic-errors} is specified, GNU C will incorrectly give |
| an error message when a function name is specified in an expression |
| involving the comma operator. |
| |
| @item |
| Loop unrolling doesn't work properly for certain C++ programs. This is |
| a bug in the C++ front end. It sometimes emits incorrect debug info, and |
| the loop unrolling code is unable to recover from this error. |
| @end itemize |
| |
| @node Installation Problems |
| @section Installation Problems |
| |
| This is a list of problems (and some apparent problems which don't |
| really mean anything is wrong) that show up during installation of GNU |
| CC. |
| |
| @itemize @bullet |
| @item |
| On certain systems, defining certain environment variables such as |
| @code{CC} can interfere with the functioning of @code{make}. |
| |
| @item |
| If you encounter seemingly strange errors when trying to build the |
| compiler in a directory other than the source directory, it could be |
| because you have previously configured the compiler in the source |
| directory. Make sure you have done all the necessary preparations. |
| @xref{Other Dir}. |
| |
| @item |
| If you build GNU CC on a BSD system using a directory stored in a System |
| V file system, problems may occur in running @code{fixincludes} if the |
| System V file system doesn't support symbolic links. These problems |
| result in a failure to fix the declaration of @code{size_t} in |
| @file{sys/types.h}. If you find that @code{size_t} is a signed type and |
| that type mismatches occur, this could be the cause. |
| |
| The solution is not to use such a directory for building GNU CC. |
| |
| @item |
| In previous versions of GNU CC, the @code{gcc} driver program looked for |
| @code{as} and @code{ld} in various places; for example, in files |
| beginning with @file{/usr/local/lib/gcc-}. GNU CC version 2 looks for |
| them in the directory |
| @file{/usr/local/lib/gcc-lib/@var{target}/@var{version}}. |
| |
| Thus, to use a version of @code{as} or @code{ld} that is not the system |
| default, for example @code{gas} or GNU @code{ld}, you must put them in |
| that directory (or make links to them from that directory). |
| |
| @item |
| Some commands executed when making the compiler may fail (return a |
| non-zero status) and be ignored by @code{make}. These failures, which |
| are often due to files that were not found, are expected, and can safely |
| be ignored. |
| |
| @item |
| It is normal to have warnings in compiling certain files about |
| unreachable code and about enumeration type clashes. These files' names |
| begin with @samp{insn-}. Also, @file{real.c} may get some warnings that |
| you can ignore. |
| |
| @item |
| Sometimes @code{make} recompiles parts of the compiler when installing |
| the compiler. In one case, this was traced down to a bug in |
| @code{make}. Either ignore the problem or switch to GNU Make. |
| |
| @item |
| If you have installed a program known as purify, you may find that it |
| causes errors while linking @code{enquire}, which is part of building |
| GNU CC. The fix is to get rid of the file @code{real-ld} which purify |
| installs---so that GNU CC won't try to use it. |
| |
| @item |
| On Linux SLS 1.01, there is a problem with @file{libc.a}: it does not |
| contain the obstack functions. However, GNU CC assumes that the obstack |
| functions are in @file{libc.a} when it is the GNU C library. To work |
| around this problem, change the @code{__GNU_LIBRARY__} conditional |
| around line 31 to @samp{#if 1}. |
| |
| @item |
| On some 386 systems, building the compiler never finishes because |
| @code{enquire} hangs due to a hardware problem in the motherboard---it |
| reports floating point exceptions to the kernel incorrectly. You can |
| install GNU CC except for @file{float.h} by patching out the command to |
| run @code{enquire}. You may also be able to fix the problem for real by |
| getting a replacement motherboard. This problem was observed in |
| Revision E of the Micronics motherboard, and is fixed in Revision F. |
| It has also been observed in the MYLEX MXA-33 motherboard. |
| |
| If you encounter this problem, you may also want to consider removing |
| the FPU from the socket during the compilation. Alternatively, if you |
| are running SCO Unix, you can reboot and force the FPU to be ignored. |
| To do this, type @samp{hd(40)unix auto ignorefpu}. |
| |
| @item |
| On some 386 systems, GNU CC crashes trying to compile @file{enquire.c}. |
| This happens on machines that don't have a 387 FPU chip. On 386 |
| machines, the system kernel is supposed to emulate the 387 when you |
| don't have one. The crash is due to a bug in the emulator. |
| |
| One of these systems is the Unix from Interactive Systems: 386/ix. |
| On this system, an alternate emulator is provided, and it does work. |
| To use it, execute this command as super-user: |
| |
| @example |
| ln /etc/emulator.rel1 /etc/emulator |
| @end example |
| |
| @noindent |
| and then reboot the system. (The default emulator file remains present |
| under the name @file{emulator.dflt}.) |
| |
| Try using @file{/etc/emulator.att}, if you have such a problem on the |
| SCO system. |
| |
| Another system which has this problem is Esix. We don't know whether it |
| has an alternate emulator that works. |
| |
| On NetBSD 0.8, a similar problem manifests itself as these error messages: |
| |
| @example |
| enquire.c: In function `fprop': |
| enquire.c:2328: floating overflow |
| @end example |
| |
| @item |
| On SCO systems, when compiling GNU CC with the system's compiler, |
| do not use @samp{-O}. Some versions of the system's compiler miscompile |
| GNU CC with @samp{-O}. |
| |
| @cindex @code{genflags}, crash on Sun 4 |
| @item |
| Sometimes on a Sun 4 you may observe a crash in the program |
| @code{genflags} or @code{genoutput} while building GNU CC. This is said to |
| be due to a bug in @code{sh}. You can probably get around it by running |
| @code{genflags} or @code{genoutput} manually and then retrying the |
| @code{make}. |
| |
| @item |
| On Solaris 2, executables of GNU CC version 2.0.2 are commonly |
| available, but they have a bug that shows up when compiling current |
| versions of GNU CC: undefined symbol errors occur during assembly if you |
| use @samp{-g}. |
| |
| The solution is to compile the current version of GNU CC without |
| @samp{-g}. That makes a working compiler which you can use to recompile |
| with @samp{-g}. |
| |
| @item |
| Solaris 2 comes with a number of optional OS packages. Some of these |
| packages are needed to use GNU CC fully. If you did not install all |
| optional packages when installing Solaris, you will need to verify that |
| the packages that GNU CC needs are installed. |
| |
| To check whether an optional package is installed, use |
| the @code{pkginfo} command. To add an optional package, use the |
| @code{pkgadd} command. For further details, see the Solaris |
| documentation. |
| |
| For Solaris 2.0 and 2.1, GNU CC needs six packages: @samp{SUNWarc}, |
| @samp{SUNWbtool}, @samp{SUNWesu}, @samp{SUNWhea}, @samp{SUNWlibm}, and |
| @samp{SUNWtoo}. |
| |
| For Solaris 2.2, GNU CC needs an additional seventh package: @samp{SUNWsprot}. |
| |
| @item |
| On Solaris 2, trying to use the linker and other tools in |
| @file{/usr/ucb} to install GNU CC has been observed to cause trouble. |
| For example, the linker may hang indefinitely. The fix is to remove |
| @file{/usr/ucb} from your @code{PATH}. |
| |
| @item |
| If you use the 1.31 version of the MIPS assembler (such as was shipped |
| with Ultrix 3.1), you will need to use the -fno-delayed-branch switch |
| when optimizing floating point code. Otherwise, the assembler will |
| complain when the GCC compiler fills a branch delay slot with a |
| floating point instruction, such as @code{add.d}. |
| |
| @item |
| If on a MIPS system you get an error message saying ``does not have gp |
| sections for all it's [sic] sectons [sic]'', don't worry about it. This |
| happens whenever you use GAS with the MIPS linker, but there is not |
| really anything wrong, and it is okay to use the output file. You can |
| stop such warnings by installing the GNU linker. |
| |
| It would be nice to extend GAS to produce the gp tables, but they are |
| optional, and there should not be a warning about their absence. |
| |
| @item |
| In Ultrix 4.0 on the MIPS machine, @file{stdio.h} does not work with GNU |
| CC at all unless it has been fixed with @code{fixincludes}. This causes |
| problems in building GNU CC. Once GNU CC is installed, the problems go |
| away. |
| |
| To work around this problem, when making the stage 1 compiler, specify |
| this option to Make: |
| |
| @example |
| GCC_FOR_TARGET="./xgcc -B./ -I./include" |
| @end example |
| |
| When making stage 2 and stage 3, specify this option: |
| |
| @example |
| CFLAGS="-g -I./include" |
| @end example |
| |
| @item |
| Users have reported some problems with version 2.0 of the MIPS |
| compiler tools that were shipped with Ultrix 4.1. Version 2.10 |
| which came with Ultrix 4.2 seems to work fine. |
| |
| Users have also reported some problems with version 2.20 of the |
| MIPS compiler tools that were shipped with RISC/os 4.x. The earlier |
| version 2.11 seems to work fine. |
| |
| @item |
| Some versions of the MIPS linker will issue an assertion failure |
| when linking code that uses @code{alloca} against shared |
| libraries on RISC-OS 5.0, and DEC's OSF/1 systems. This is a bug |
| in the linker, that is supposed to be fixed in future revisions. |
| To protect against this, GNU CC passes @samp{-non_shared} to the |
| linker unless you pass an explicit @samp{-shared} or |
| @samp{-call_shared} switch. |
| |
| @item |
| On System V release 3, you may get this error message |
| while linking: |
| |
| @smallexample |
| ld fatal: failed to write symbol name @var{something} |
| in strings table for file @var{whatever} |
| @end smallexample |
| |
| This probably indicates that the disk is full or your ULIMIT won't allow |
| the file to be as large as it needs to be. |
| |
| This problem can also result because the kernel parameter @code{MAXUMEM} |
| is too small. If so, you must regenerate the kernel and make the value |
| much larger. The default value is reported to be 1024; a value of 32768 |
| is said to work. Smaller values may also work. |
| |
| @item |
| On System V, if you get an error like this, |
| |
| @example |
| /usr/local/lib/bison.simple: In function `yyparse': |
| /usr/local/lib/bison.simple:625: virtual memory exhausted |
| @end example |
| |
| @noindent |
| that too indicates a problem with disk space, ULIMIT, or @code{MAXUMEM}. |
| |
| @item |
| Current GNU CC versions probably do not work on version 2 of the NeXT |
| operating system. |
| |
| @item |
| On NeXTStep 3.0, the Objective C compiler does not work, due, |
| apparently, to a kernel bug that it happens to trigger. This problem |
| does not happen on 3.1. |
| |
| @item |
| On the Tower models 4@var{n}0 and 6@var{n}0, by default a process is not |
| allowed to have more than one megabyte of memory. GNU CC cannot compile |
| itself (or many other programs) with @samp{-O} in that much memory. |
| |
| To solve this problem, reconfigure the kernel adding the following line |
| to the configuration file: |
| |
| @smallexample |
| MAXUMEM = 4096 |
| @end smallexample |
| |
| @item |
| On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a bug |
| in the assembler that must be fixed before GNU CC can be built. This |
| bug manifests itself during the first stage of compilation, while |
| building @file{libgcc2.a}: |
| |
| @smallexample |
| _floatdisf |
| cc1: warning: `-g' option not supported on this version of GCC |
| cc1: warning: `-g1' option not supported on this version of GCC |
| ./xgcc: Internal compiler error: program as got fatal signal 11 |
| @end smallexample |
| |
| A patched version of the assembler is available by anonymous ftp from |
| @code{altdorf.ai.mit.edu} as the file |
| @file{archive/cph/hpux-8.0-assembler}. If you have HP software support, |
| the patch can also be obtained directly from HP, as described in the |
| following note: |
| |
| @quotation |
| This is the patched assembler, to patch SR#1653-010439, where the |
| assembler aborts on floating point constants. |
| |
| The bug is not really in the assembler, but in the shared library |
| version of the function ``cvtnum(3c)''. The bug on ``cvtnum(3c)'' is |
| SR#4701-078451. Anyway, the attached assembler uses the archive |
| library version of ``cvtnum(3c)'' and thus does not exhibit the bug. |
| @end quotation |
| |
| This patch is also known as PHCO_4484. |
| |
| @item |
| On HP-UX version 8.05, but not on 8.07 or more recent versions, |
| the @code{fixproto} shell script triggers a bug in the system shell. |
| If you encounter this problem, upgrade your operating system or |
| use BASH (the GNU shell) to run @code{fixproto}. |
| |
| @item |
| Some versions of the Pyramid C compiler are reported to be unable to |
| compile GNU CC. You must use an older version of GNU CC for |
| bootstrapping. One indication of this problem is if you get a crash |
| when GNU CC compiles the function @code{muldi3} in file @file{libgcc2.c}. |
| |
| You may be able to succeed by getting GNU CC version 1, installing it, |
| and using it to compile GNU CC version 2. The bug in the Pyramid C |
| compiler does not seem to affect GNU CC version 1. |
| |
| @item |
| There may be similar problems on System V Release 3.1 on 386 systems. |
| |
| @item |
| On the Intel Paragon (an i860 machine), if you are using operating |
| system version 1.0, you will get warnings or errors about redefinition |
| of @code{va_arg} when you build GNU CC. |
| |
| If this happens, then you need to link most programs with the library |
| @file{iclib.a}. You must also modify @file{stdio.h} as follows: before |
| the lines |
| |
| @example |
| #if defined(__i860__) && !defined(_VA_LIST) |
| #include <va_list.h> |
| @end example |
| |
| @noindent |
| insert the line |
| |
| @example |
| #if __PGC__ |
| @end example |
| |
| @noindent |
| and after the lines |
| |
| @example |
| extern int vprintf(const char *, va_list ); |
| extern int vsprintf(char *, const char *, va_list ); |
| #endif |
| @end example |
| |
| @noindent |
| insert the line |
| |
| @example |
| #endif /* __PGC__ */ |
| @end example |
| |
| These problems don't exist in operating system version 1.1. |
| |
| @item |
| On the Altos 3068, programs compiled with GNU CC won't work unless you |
| fix a kernel bug. This happens using system versions V.2.2 1.0gT1 and |
| V.2.2 1.0e and perhaps later versions as well. See the file |
| @file{README.ALTOS}. |
| |
| @item |
| You will get several sorts of compilation and linking errors on the |
| we32k if you don't follow the special instructions. @xref{Configurations}. |
| |
| @item |
| A bug in the HP-UX 8.05 (and earlier) shell will cause the fixproto |
| program to report an error of the form: |
| |
| @example |
| ./fixproto: sh internal 1K buffer overflow |
| @end example |
| |
| To fix this, change the first line of the fixproto script to look like: |
| |
| @example |
| #!/bin/ksh |
| @end example |
| @end itemize |
| |
| @node Cross-Compiler Problems |
| @section Cross-Compiler Problems |
| |
| You may run into problems with cross compilation on certain machines, |
| 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. |
| @ifset INTERNALS |
| @xref{Cross-compilation}. |
| @end ifset |
| @ifclear INTERNALS |
| @xref{Cross-compilation,,Cross Compilation and Floating Point Format, |
| gcc.info, Using and Porting GCC}. |
| @end ifclear |
| |
| @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. |
| @end itemize |
| |
| @node Interoperation |
| @section Interoperation |
| |
| This section lists various difficulties encountered in using GNU C or |
| GNU C++ together with other compilers or with the assemblers, linkers, |
| libraries and debuggers on certain systems. |
| |
| @itemize @bullet |
| @item |
| Objective C does not work on the RS/6000. |
| |
| @item |
| GNU C++ does not do name mangling in the same way as other C++ |
| compilers. This means that object files compiled with one compiler |
| cannot be used with another. |
| |
| This effect 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. |
| |
| @item |
| Older GDB versions sometimes fail to read the output of GNU CC version |
| 2. If you have trouble, get GDB version 4.4 or later. |
| |
| @item |
| @cindex DBX |
| DBX rejects some files produced by GNU CC, 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. |
| |
| @item |
| Use of @samp{-I/usr/include} may cause trouble. |
| |
| Many systems come with header files that won't work with GNU CC unless |
| corrected by @code{fixincludes}. The corrected header files go in a new |
| directory; GNU CC searches this directory before @file{/usr/include}. |
| If you use @samp{-I/usr/include}, this tells GNU CC to search |
| @file{/usr/include} earlier on, before the corrected headers. The |
| result is that you get the uncorrected header files. |
| |
| Instead, you should use these options (when compiling C programs): |
| |
| @smallexample |
| -I/usr/local/lib/gcc-lib/@var{target}/@var{version}/include -I/usr/include |
| @end smallexample |
| |
| For C++ programs, GNU CC also uses a special directory that defines C++ |
| interfaces to standard C subroutines. This directory is meant to be |
| searched @emph{before} other standard include directories, so that it |
| takes precedence. If you are compiling C++ programs and specifying |
| include directories explicitly, use this option first, then the two |
| options above: |
| |
| @example |
| -I/usr/local/lib/g++-include |
| @end example |
| |
| @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 GNU CC 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 @samp{-O} for those source files. |
| @end ignore |
| |
| @item |
| On some SGI systems, when you use @samp{-lgl_s} as an option, |
| it gets translated magically to @samp{-lgl_s -lX11_s -lc_s}. |
| Naturally, this does not happen when you use GNU CC. |
| You must specify all three options explicitly. |
| |
| @item |
| On a Sparc, GNU CC aligns all values of type @code{double} on an 8-byte |
| boundary, and it expects every @code{double} to be so aligned. The Sun |
| compiler usually gives @code{double} values 8-byte alignment, with one |
| exception: function arguments of type @code{double} may not be aligned. |
| |
| As a result, if a function compiled with Sun CC takes the address of an |
| argument of type @code{double} and passes this pointer of type |
| @code{double *} to a function compiled with GNU CC, dereferencing the |
| pointer may cause a fatal signal. |
| |
| One way to solve this problem is to compile your entire program with GNU |
| CC. 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 |
| @code{access_double} instead of directly with @samp{*}: |
| |
| @smallexample |
| 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; |
| @} |
| @end smallexample |
| |
| @noindent |
| Storing into the pointer can be done likewise with the same union. |
| |
| @item |
| On Solaris, the @code{malloc} function in the @file{libmalloc.a} library |
| may allocate memory that is only 4 byte aligned. Since GNU CC 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 |
| @file{libmalloc.a} library. |
| |
| The solution is to not use the @file{libmalloc.a} library. Use instead |
| @code{malloc} and related functions from @file{libc.a}; they do not have |
| 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 @samp{-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 GNU CC |
| 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 GNU CC correctly. We do not yet know why. However, GNU CC |
| 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 GNU CC. Specifically, it fails to work on functions that use |
| @code{alloca} or variable-size arrays. This is because GNU CC doesn't |
| generate HP-UX unwind descriptors for such functions. It may even be |
| impossible to generate them. |
| |
| @item |
| Debugging (@samp{-g}) is not supported on the HP PA machine, unless you use |
| the preliminary GNU tools (@pxref{Installation}). |
| |
| @item |
| Taking the address of a label may generate errors from the HP-UX |
| PA assembler. GAS for the PA does not have this problem. |
| |
| @item |
| 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. |
| |
| @item |
| 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 GNU CC, but is now exceptionally rare. If you should run |
| into it, you can work around by making your function smaller. |
| |
| @item |
| GNU CC compiled code sometimes emits warnings from the HP-UX assembler of |
| the form: |
| |
| @smallexample |
| (warning) Use of GR3 when |
| frame >= 8192 may cause conflict. |
| @end smallexample |
| |
| These warnings are harmless and can be safely ignored. |
| |
| @item |
| The current version of the assembler (@file{/bin/as}) for the RS/6000 |
| has certain problems that prevent the @samp{-g} option in GCC from |
| working. Note that @file{Makefile.in} uses @samp{-g} by default when |
| compiling @file{libgcc2.c}. |
| |
| IBM has produced a fixed version of the assembler. The upgraded |
| assembler unfortunately was not included in any of the AIX 3.2 update |
| PTF releases (3.2.2, 3.2.3, or 3.2.3e). Users of AIX 3.1 should request |
| PTF U403044 from IBM and users of AIX 3.2 should request PTF U416277. |
| See the file @file{README.RS6000} for more details on these updates. |
| |
| You can test for the presense of a fixed assembler by using the |
| command |
| |
| @smallexample |
| as -u < /dev/null |
| @end smallexample |
| |
| @noindent |
| If the command exits normally, the assembler fix already is installed. |
| If the assembler complains that "-u" is an unknown flag, you need to |
| order the fix. |
| |
| @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 ANSI C. |
| |
| @item |
| 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". |
| |
| @item |
| Even if you specify @samp{-fdollars-in-identifiers}, |
| you cannot successfully use @samp{$} in identifiers on the RS/6000 due |
| to a restriction in the IBM assembler. GAS supports these |
| identifiers. |
| |
| @item |
| On the RS/6000, XLC version 1.3.0.0 will miscompile @file{jump.c}. XLC |
| version 1.3.0.1 or later fixes this problem. You can obtain XLC-1.3.0.2 |
| by requesting PTF 421749 from IBM. |
| |
| @item |
| There is an assembler bug in versions of DG/UX prior to 5.4.2.01 that |
| occurs when the @samp{fldcr} instruction is used. GNU CC uses |
| @samp{fldcr} on the 88100 to serialize volatile memory references. Use |
| the option @samp{-mno-serialize-volatile} if your version of the |
| assembler has this bug. |
| |
| @item |
| 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. @xref{VMS Install}. |
| |
| @item |
| On NewsOS version 3, if you include both of the files @file{stddef.h} |
| and @file{sys/types.h}, you get an error because there are two typedefs |
| of @code{size_t}. You should change @file{sys/types.h} by adding these |
| lines around the definition of @code{size_t}: |
| |
| @smallexample |
| #ifndef _SIZE_T |
| #define _SIZE_T |
| @var{actual typedef here} |
| #endif |
| @end smallexample |
| |
| @cindex Alliant |
| @item |
| On the Alliant, the system's own convention for returning structures |
| and unions is unusual, and is not compatible with GNU CC no matter |
| what options are used. |
| |
| @cindex RT PC |
| @cindex IBM RT PC |
| @item |
| On the IBM RT PC, the MetaWare HighC compiler (hc) uses a different |
| convention for structure and union returning. Use the option |
| @samp{-mhc-struct-return} to tell GNU CC to use a convention compatible |
| with it. |
| |
| @cindex Vax calling convention |
| @cindex Ultrix calling convention |
| @item |
| 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. |
| |
| GNU CC uses the same convention as the Ultrix C compiler. You can use |
| 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 WE32k, you may find that programs compiled with GNU CC 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: |
| |
| @smallexample |
| -L/usr/local/lib/gcc-lib/we32k-att-sysv/2.7.1 -lgcc -lc_s |
| @end smallexample |
| |
| The first specifies where to find the library @file{libgcc.a} |
| specified with the @samp{-lgcc} option. |
| |
| GNU CC does linking by invoking @code{ld}, just as @code{cc} does, and |
| there is no reason why it @emph{should} matter which compilation program |
| you use to invoke @code{ld}. If someone tracks this problem down, |
| it can probably be fixed easily. |
| |
| @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}. |
| |
| @item |
| 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 @samp{-noasmopt} option when you compile GNU CC 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 @file{specs} so |
| that it unconditionally passes @samp{-O0} to the assembler, and never |
| passes @samp{-O2} or @samp{-O3}. |
| @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 |
| @samp{-I/usr/include/mit} to use the MIT versions of the header files, |
| using the @samp{-traditional} switch to turn off ANSI C, or fixing the |
| header files by adding this: |
| |
| @example |
| #ifdef __STDC__ |
| #define NeedFunctionPrototypes 0 |
| #endif |
| @end example |
| |
| @item |
| If you have trouble compiling Perl on a SunOS 4 system, it may be |
| because Perl specifies @samp{-I/usr/ucbinclude}. This accesses the |
| unfixed header files. Perl specifies the options |
| |
| @example |
| -traditional -Dvolatile=__volatile__ |
| -I/usr/include/sun -I/usr/ucbinclude |
| -fpcc-struct-return |
| @end example |
| |
| @noindent |
| most of which are unnecessary with GCC 2.4.5 and newer versions. You |
| can make a properly working Perl by setting @code{ccflags} to |
| @samp{-fwritable-strings} (implied by the @samp{-traditional} in the |
| original options) and @code{cppflags} to empty in @file{config.sh}, then |
| typing @samp{./doSH; make depend; make}. |
| |
| @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 GNU CC 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 GNU CC: |
| |
| @example |
| MALLOC=/usr/local/lib/libgmalloc.a |
| @end example |
| |
| 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 |
| GNU CC: |
| |
| @example |
| MALLOC=gmalloc.o |
| @end example |
| @end itemize |
| |
| @node Incompatibilities |
| @section Incompatibilities of GNU CC |
| @cindex incompatibilities of GNU CC |
| |
| There are several noteworthy incompatibilities between GNU C and most |
| existing (non-ANSI) versions of C. The @samp{-traditional} option |
| eliminates many of these incompatibilities, @emph{but not all}, by |
| telling GNU C to behave like the other C compilers. |
| |
| @itemize @bullet |
| @cindex string constants |
| @cindex read-only strings |
| @cindex shared strings |
| @item |
| GNU CC normally makes string constants read-only. If several |
| identical-looking string constants are used, GNU CC stores only one |
| copy of the string. |
| |
| @cindex @code{mktemp}, and constant strings |
| One consequence is that you cannot call @code{mktemp} with a string |
| constant argument. The function @code{mktemp} always alters the |
| string its argument points to. |
| |
| @cindex @code{sscanf}, and constant strings |
| @cindex @code{fscanf}, and constant strings |
| @cindex @code{scanf}, and constant strings |
| Another consequence is that @code{sscanf} does not work on some systems |
| when passed a string constant as its format control string or input. |
| This is because @code{sscanf} incorrectly tries to write into the string |
| constant. Likewise @code{fscanf} and @code{scanf}. |
| |
| The best solution to these problems is to change the program to use |
| @code{char}-array variables with initialization strings for these |
| purposes instead of string constants. But if this is not possible, |
| you can use the @samp{-fwritable-strings} flag, which directs GNU CC |
| to handle string constants the same way most C compilers do. |
| @samp{-traditional} also has this effect, among others. |
| |
| @item |
| @code{-2147483648} is positive. |
| |
| This is because 2147483648 cannot fit in the type @code{int}, so |
| (following the ANSI C rules) its data type is @code{unsigned long int}. |
| Negating this value yields 2147483648 again. |
| |
| @item |
| GNU CC does not substitute macro arguments when they appear inside of |
| string constants. For example, the following macro in GNU CC |
| |
| @example |
| #define foo(a) "a" |
| @end example |
| |
| @noindent |
| will produce output @code{"a"} regardless of what the argument @var{a} is. |
| |
| The @samp{-traditional} option directs GNU CC to handle such cases |
| (among others) in the old-fashioned (non-ANSI) fashion. |
| |
| @cindex @code{setjmp} incompatibilities |
| @cindex @code{longjmp} incompatibilities |
| @item |
| When you use @code{setjmp} and @code{longjmp}, the only automatic |
| variables guaranteed to remain valid are those declared |
| @code{volatile}. This is a consequence of automatic register |
| allocation. Consider this function: |
| |
| @example |
| jmp_buf j; |
| |
| foo () |
| @{ |
| int a, b; |
| |
| a = fun1 (); |
| if (setjmp (j)) |
| return a; |
| |
| a = fun2 (); |
| /* @r{@code{longjmp (j)} may occur in @code{fun3}.} */ |
| return a + fun3 (); |
| @} |
| @end example |
| |
| Here @code{a} may or may not be restored to its first value when the |
| @code{longjmp} occurs. If @code{a} is allocated in a register, then |
| its first value is restored; otherwise, it keeps the last value stored |
| in it. |
| |
| If you use the @samp{-W} option with the @samp{-O} option, you will |
| get a warning when GNU CC thinks such a problem might be possible. |
| |
| The @samp{-traditional} option directs GNU C to put variables in |
| the stack by default, rather than in registers, in functions that |
| call @code{setjmp}. This results in the behavior found in |
| traditional C compilers. |
| |
| @item |
| Programs that use preprocessing directives in the middle of macro |
| arguments do not work with GNU CC. For example, a program like this |
| will not work: |
| |
| @example |
| foobar ( |
| #define luser |
| hack) |
| @end example |
| |
| ANSI C does not permit such a construct. It would make sense to support |
| it when @samp{-traditional} is used, but it is too much work to |
| implement. |
| |
| @cindex external declaration scope |
| @cindex scope of external declarations |
| @cindex declaration scope |
| @item |
| Declarations of external variables and functions within a block apply |
| only to the block containing the declaration. In other words, they |
| have the same scope as any other declaration in the same place. |
| |
| In some other C compilers, a @code{extern} declaration affects all the |
| rest of the file even if it happens within a block. |
| |
| The @samp{-traditional} option directs GNU C to treat all @code{extern} |
| declarations as global, like traditional compilers. |
| |
| @item |
| In traditional C, you can combine @code{long}, etc., with a typedef name, |
| as shown here: |
| |
| @example |
| typedef int foo; |
| typedef long foo bar; |
| @end example |
| |
| In ANSI C, this is not allowed: @code{long} and other type modifiers |
| require an explicit @code{int}. Because this criterion is expressed |
| by Bison grammar rules rather than C code, the @samp{-traditional} |
| flag cannot alter it. |
| |
| @cindex typedef names as function parameters |
| @item |
| PCC allows typedef names to be used as function parameters. The |
| difficulty described immediately above applies here too. |
| |
| @cindex whitespace |
| @item |
| PCC allows whitespace in the middle of compound assignment operators |
| such as @samp{+=}. GNU CC, following the ANSI standard, does not |
| allow this. The difficulty described immediately above applies here |
| too. |
| |
| @cindex apostrophes |
| @cindex ' |
| @item |
| GNU CC complains about unterminated character constants inside of |
| preprocessing conditionals that fail. Some programs have English |
| comments enclosed in conditionals that are guaranteed to fail; if these |
| comments contain apostrophes, GNU CC will probably report an error. For |
| example, this code would produce an error: |
| |
| @example |
| #if 0 |
| You can't expect this to work. |
| #endif |
| @end example |
| |
| The best solution to such a problem is to put the text into an actual |
| C comment delimited by @samp{/*@dots{}*/}. However, |
| @samp{-traditional} suppresses these error messages. |
| |
| @item |
| Many user programs contain the declaration @samp{long time ();}. In the |
| past, the system header files on many systems did not actually declare |
| @code{time}, so it did not matter what type your program declared it to |
| return. But in systems with ANSI C headers, @code{time} is declared to |
| return @code{time_t}, and if that is not the same as @code{long}, then |
| @samp{long time ();} is erroneous. |
| |
| The solution is to change your program to use @code{time_t} as the return |
| type of @code{time}. |
| |
| @cindex @code{float} as function value type |
| @item |
| When compiling functions that return @code{float}, PCC converts it to |
| a double. GNU CC actually returns a @code{float}. If you are concerned |
| with PCC compatibility, you should declare your functions to return |
| @code{double}; you might as well say what you mean. |
| |
| @cindex structures |
| @cindex unions |
| @item |
| When compiling functions that return structures or unions, GNU CC |
| output code normally uses a method different from that used on most |
| versions of Unix. As a result, code compiled with GNU CC cannot call |
| a structure-returning function compiled with PCC, and vice versa. |
| |
| The method used by GNU CC is as follows: a structure or union which is |
| 1, 2, 4 or 8 bytes long is returned like a scalar. A structure or union |
| with any other size is stored into an address supplied by the caller |
| (usually in a special, fixed register, but on some machines it is passed |
| on the stack). The machine-description macros @code{STRUCT_VALUE} and |
| @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. |
| |
| By contrast, PCC on most target machines returns structures and unions |
| of any size by copying the data into an area of static storage, and then |
| returning the address of that storage as if it were a pointer value. |
| The caller must copy the data from that memory area to the place where |
| the value is wanted. GNU CC does not use this method because it is |
| slower and nonreentrant. |
| |
| On some newer machines, PCC uses a reentrant convention for all |
| structure and union returning. GNU CC on most of these machines uses a |
| compatible convention when returning structures and unions in memory, |
| but still returns small structures and unions in registers. |
| |
| You can tell GNU CC to use a compatible convention for all structure and |
| union returning with the option @samp{-fpcc-struct-return}. |
| |
| @cindex preprocessing tokens |
| @cindex preprocessing numbers |
| @item |
| GNU C complains about program fragments such as @samp{0x74ae-0x4000} |
| which appear to be two hexadecimal constants separated by the minus |
| operator. Actually, this string is a single @dfn{preprocessing token}. |
| Each such token must correspond to one token in C. Since this does not, |
| GNU C prints an error message. Although it may appear obvious that what |
| is meant is an operator and two values, the ANSI C standard specifically |
| requires that this be treated as erroneous. |
| |
| A @dfn{preprocessing token} is a @dfn{preprocessing number} if it |
| begins with a digit and is followed by letters, underscores, digits, |
| periods and @samp{e+}, @samp{e-}, @samp{E+}, or @samp{E-} character |
| sequences. |
| |
| To make the above program fragment valid, place whitespace in front of |
| the minus sign. This whitespace will end the preprocessing number. |
| @end itemize |
| |
| @node Fixed Headers |
| @section Fixed Header Files |
| |
| GNU CC needs to install corrected versions of some system header files. |
| This is because most target systems have some header files that won't |
| work with GNU CC unless they are changed. Some have bugs, some are |
| incompatible with ANSI C, and some depend on special features of other |
| compilers. |
| |
| Installing GNU CC 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 |
| don't need to pay attention to this. But there are cases where it |
| doesn't do the right thing automatically. |
| |
| @itemize @bullet |
| @item |
| If you update the system's header files, such as by installing a new |
| system version, the fixed header files of GNU CC are not automatically |
| updated. The easiest way to update them is to reinstall GNU CC. (If |
| you want to be clever, look in the makefile and you can find a |
| shortcut.) |
| |
| @item |
| On some systems, in particular SunOS 4, 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. |
| |
| 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, GNU CC 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 GNU CC's fault, but it |
| does mean that there's nothing for us to do about them. |
| @end itemize |
| |
| @node Standard Libraries |
| @section Standard Libraries |
| |
| GNU CC by itself attempts to be what the ISO/ANSI C standard calls a |
| @dfn{conforming freestanding implementation}. This means all ANSI |
| C language features are available, as well as the contents of |
| @file{float.h}, @file{limits.h}, @file{stdarg.h}, and |
| @file{stddef.h}. The rest of the C library is supplied by the |
| vendor of the operating system. If that C library doesn't conform to |
| the C standards, then your programs might get warnings (especially when |
| using @samp{-Wall}) that you don't expect. |
| |
| For example, the @code{sprintf} function on SunOS 4.1.3 returns |
| @code{char *} while the C standard says that @code{sprintf} returns an |
| @code{int}. The @code{fixincludes} program could make the prototype for |
| this function match the Standard, but that would be wrong, since the |
| function will still return @code{char *}. |
| |
| If you need a Standard compliant library, then you need to find one, as |
| GNU CC does not provide one. The GNU C library (called @code{glibc}) |
| has been ported to a number of operating systems, and provides ANSI/ISO, |
| POSIX, BSD and SystemV compatibility. You could also ask your operating |
| system vendor if newer libraries are available. |
| |
| @node Disappointments |
| @section Disappointments and Misunderstandings |
| |
| These problems are perhaps regrettable, but we don't know any practical |
| way around them. |
| |
| @itemize @bullet |
| @item |
| Certain local variables aren't recognized by debuggers when you compile |
| with optimization. |
| |
| This occurs because sometimes GNU CC optimizes the variable out of |
| existence. There is no way to tell the debugger how to compute the |
| value such a variable ``would have had'', and it is not clear that would |
| be desirable anyway. So GNU CC simply does not mention the eliminated |
| variable when it writes debugging information. |
| |
| You have to expect a certain amount of disagreement between the |
| executable and your source code, when you use optimization. |
| |
| @cindex conflicting types |
| @cindex scope of declaration |
| @item |
| Users often think it is a bug when GNU CC reports an error for code |
| like this: |
| |
| @example |
| int foo (struct mumble *); |
| |
| struct mumble @{ @dots{} @}; |
| |
| int foo (struct mumble *x) |
| @{ @dots{} @} |
| @end example |
| |
| This code really is erroneous, because the scope of @code{struct |
| mumble} in the prototype is limited to the argument list containing it. |
| It does not refer to the @code{struct mumble} defined with file scope |
| immediately below---they are two unrelated types with similar names in |
| different scopes. |
| |
| But in the definition of @code{foo}, the file-scope type is used |
| because that is available to be inherited. Thus, the definition and |
| the prototype do not match, and you get an error. |
| |
| This behavior may seem silly, but it's what the ANSI standard specifies. |
| It is easy enough for you to make your code work by moving the |
| definition of @code{struct mumble} above the prototype. It's not worth |
| being incompatible with ANSI C just to avoid an error for the example |
| shown above. |
| |
| @item |
| Accesses to bitfields even in volatile objects works by accessing larger |
| objects, such as a byte or a word. You cannot rely on what size of |
| object is accessed in order to read or write the bitfield; it may even |
| vary for a given bitfield according to the precise usage. |
| |
| If you care about controlling the amount of memory that is accessed, use |
| volatile but do not use bitfields. |
| |
| @item |
| GNU CC comes with shell scripts to fix certain known problems in system |
| header files. They install corrected copies of various header files in |
| a special directory where only GNU CC will normally look for them. The |
| 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 GNU CC |
| 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. |
| |
| @item |
| @cindex floating point precision |
| On 68000 and x86 systems, for instance, you can get paradoxical results |
| if you test the precise values of floating point numbers. For example, |
| you can find that a floating point value which is not a NaN is not equal |
| to itself. This results from the fact that the floating point registers |
| hold a few more bits of precision than fit in a @code{double} in memory. |
| Compiled code moves values between memory and floating point registers |
| at its convenience, and moving them into memory truncates them. |
| |
| You can partially avoid this problem by using the @samp{-ffloat-store} |
| option (@pxref{Optimize Options}). |
| |
| @item |
| On the MIPS, variable argument functions using @file{varargs.h} |
| cannot have a floating point value for the first argument. The |
| reason for this is that in the absence of a prototype in scope, |
| if the first argument is a floating point, it is passed in a |
| floating point register, rather than an integer register. |
| |
| If the code is rewritten to use the ANSI standard @file{stdarg.h} |
| method of variable arguments, and the prototype is in scope at |
| the time of the call, everything will work fine. |
| |
| @item |
| On the H8/300 and H8/300H, variable argument functions must be |
| implemented using the ANSI standard @file{stdarg.h} method of |
| variable arguments. Furthermore, calls to functions using @file{stdarg.h} |
| variable arguments must have a prototype for the called function |
| in scope at the time of the call. |
| @end itemize |
| |
| @node C++ Misunderstandings |
| @section Common Misunderstandings with GNU C++ |
| |
| @cindex misunderstandings in C++ |
| @cindex surprises in C++ |
| @cindex C++ misunderstandings |
| C++ is a complex language and an evolving one, and its standard definition |
| (the ANSI C++ draft standard) is also evolving. As a result, |
| your C++ compiler may occasionally surprise you, even when its behavior is |
| correct. This section discusses some areas that frequently give rise to |
| questions of this sort. |
| |
| @menu |
| * Static Definitions:: Static member declarations are not definitions |
| * Temporaries:: Temporaries may vanish before you expect |
| @end menu |
| |
| @node Static Definitions |
| @subsection Declare @emph{and} Define Static Members |
| |
| @cindex C++ static data, declaring and defining |
| @cindex static data in C++, declaring and defining |
| @cindex declaring static data in C++ |
| @cindex defining static data in C++ |
| When a class has static data members, it is not enough to @emph{declare} |
| the static member; you must also @emph{define} it. For example: |
| |
| @example |
| class Foo |
| @{ |
| @dots{} |
| void method(); |
| static int bar; |
| @}; |
| @end example |
| |
| This declaration only establishes that the class @code{Foo} has an |
| @code{int} named @code{Foo::bar}, and a member function named |
| @code{Foo::method}. But you still need to define @emph{both} |
| @code{method} and @code{bar} elsewhere. According to the draft ANSI |
| standard, you must supply an initializer in one (and only one) source |
| file, such as: |
| |
| @example |
| int Foo::bar = 0; |
| @end example |
| |
| Other C++ compilers may not correctly implement the standard behavior. |
| As a result, when you switch to @code{g++} from one of these compilers, |
| you may discover that a program that appeared to work correctly in fact |
| does not conform to the standard: @code{g++} reports as undefined |
| symbols any static data members that lack definitions. |
| |
| @node Temporaries |
| @subsection Temporaries May Vanish Before You Expect |
| |
| @cindex temporaries, lifetime of |
| @cindex portions of temporary objects, pointers to |
| It is dangerous to use pointers or references to @emph{portions} of a |
| temporary object. The compiler may very well delete the object before |
| you expect it to, leaving a pointer to garbage. The most common place |
| where this problem crops up is in classes like the libg++ |
| @code{String} class, that define a conversion function to type |
| @code{char *} or @code{const char *}. However, any class that returns |
| a pointer to some internal structure is potentially subject to this |
| problem. |
| |
| For example, a program may use a function @code{strfunc} that returns |
| @code{String} objects, and another function @code{charfunc} that |
| operates on pointers to @code{char}: |
| |
| @example |
| String strfunc (); |
| void charfunc (const char *); |
| @end example |
| |
| @noindent |
| In this situation, it may seem natural to write @w{@samp{charfunc |
| (strfunc ());}} based on the knowledge that class @code{String} has an |
| explicit conversion to @code{char} pointers. However, what really |
| happens is akin to @samp{charfunc (@w{strfunc ()}.@w{convert ()});}, |
| where the @code{convert} method is a function to do the same data |
| conversion normally performed by a cast. Since the last use of the |
| temporary @code{String} object is the call to the conversion function, |
| the compiler may delete that object before actually calling |
| @code{charfunc}. The compiler has no way of knowing that deleting the |
| @code{String} object will invalidate the pointer. The pointer then |
| points to garbage, so that by the time @code{charfunc} is called, it |
| gets an invalid argument. |
| |
| Code like this may run successfully under some other compilers, |
| especially those that delete temporaries relatively late. However, the |
| GNU C++ behavior is also standard-conforming, so if your program depends |
| on late destruction of temporaries it is not portable. |
| |
| If you think this is surprising, you should be aware that the ANSI C++ |
| committee continues to debate the lifetime-of-temporaries problem. |
| |
| For now, at least, the safe way to write such code is to give the |
| temporary a name, which forces it to remain until the end of the scope of |
| the name. For example: |
| |
| @example |
| String& tmp = strfunc (); |
| charfunc (tmp); |
| @end example |
| |
| @node Protoize Caveats |
| @section Caveats of using @code{protoize} |
| |
| The conversion programs @code{protoize} and @code{unprotoize} can |
| sometimes change a source file in a way that won't work unless you |
| rearrange it. |
| |
| @itemize @bullet |
| @item |
| @code{protoize} can insert references to a type name or type tag before |
| the definition, or in a file where they are not defined. |
| |
| If this happens, compiler error messages should show you where the new |
| references are, so fixing the file by hand is straightforward. |
| |
| @item |
| There are some C constructs which @code{protoize} cannot figure out. |
| For example, it can't determine argument types for declaring a |
| pointer-to-function variable; this you must do by hand. @code{protoize} |
| inserts a comment containing @samp{???} each time it finds such a |
| variable; so you can find all such variables by searching for this |
| string. ANSI C does not require declaring the argument types of |
| pointer-to-function types. |
| |
| @item |
| Using @code{unprotoize} can easily introduce bugs. If the program |
| relied on prototypes to bring about conversion of arguments, these |
| conversions will not take place in the program without prototypes. |
| One case in which you can be sure @code{unprotoize} is safe is when |
| you are removing prototypes that were made with @code{protoize}; if |
| the program worked before without any prototypes, it will work again |
| without them. |
| |
| You can find all the places where this problem might occur by compiling |
| the program with the @samp{-Wconversion} option. It prints a warning |
| whenever an argument is converted. |
| |
| @item |
| Both conversion programs can be confused if there are macro calls in and |
| around the text to be converted. In other words, the standard syntax |
| for a declaration or definition must not result from expanding a macro. |
| This problem is inherent in the design of C and cannot be fixed. If |
| only a few functions have confusing macro calls, you can easily convert |
| them manually. |
| |
| @item |
| @code{protoize} cannot get the argument types for a function whose |
| definition was not actually compiled due to preprocessing conditionals. |
| When this happens, @code{protoize} changes nothing in regard to such |
| a function. @code{protoize} tries to detect such instances and warn |
| about them. |
| |
| You can generally work around this problem by using @code{protoize} step |
| by step, each time specifying a different set of @samp{-D} options for |
| compilation, until all of the functions have been converted. There is |
| no automatic way to verify that you have got them all, however. |
| |
| @item |
| Confusion may result if there is an occasion to convert a function |
| declaration or definition in a region of source code where there is more |
| than one formal parameter list present. Thus, attempts to convert code |
| containing multiple (conditionally compiled) versions of a single |
| function header (in the same vicinity) may not produce the desired (or |
| expected) results. |
| |
| If you plan on converting source files which contain such code, it is |
| recommended that you first make sure that each conditionally compiled |
| region of source code which contains an alternative function header also |
| contains at least one additional follower token (past the final right |
| parenthesis of the function header). This should circumvent the |
| problem. |
| |
| @item |
| @code{unprotoize} can become confused when trying to convert a function |
| definition or declaration which contains a declaration for a |
| pointer-to-function formal argument which has the same name as the |
| function being defined or declared. We recommand you avoid such choices |
| of formal parameter names. |
| |
| @item |
| You might also want to correct some of the indentation by hand and break |
| long lines. (The conversion programs don't write lines longer than |
| eighty characters in any case.) |
| @end itemize |
| |
| @node Non-bugs |
| @section Certain Changes We Don't Want to Make |
| |
| This section lists changes that people frequently request, but which |
| we do not make because we think GNU CC is better without them. |
| |
| @itemize @bullet |
| @item |
| Checking the number and type of arguments to a function which has an |
| old-fashioned definition and no prototype. |
| |
| Such a feature would work only occasionally---only for calls that appear |
| in the same file as the called function, following the definition. The |
| only way to check all calls reliably is to add a prototype for the |
| function. But adding a prototype eliminates the motivation for this |
| feature. So the feature is not worthwhile. |
| |
| @item |
| Warning about using an expression whose type is signed as a shift count. |
| |
| Shift count operands are probably signed more often than unsigned. |
| Warning about this would cause far more annoyance than good. |
| |
| @item |
| Warning about assigning a signed value to an unsigned variable. |
| |
| Such assignments must be very common; warning about them would cause |
| more annoyance than good. |
| |
| @item |
| Warning about unreachable code. |
| |
| It's very common to have unreachable code in machine-generated |
| programs. For example, this happens normally in some files of GNU C |
| itself. |
| |
| @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. |
| |
| @item |
| Assuming (for optimization) that the address of an external symbol is |
| never zero. |
| |
| This assumption is false on certain systems when @samp{#pragma weak} is |
| used. |
| |
| @item |
| Making @samp{-fshort-enums} the default. |
| |
| This would cause storage layout to be incompatible with most other C |
| compilers. And it doesn't seem very important, given that you can get |
| the same result in other ways. The case where it matters most is when |
| the enumeration-valued object is inside a structure, and in that case |
| you can specify a field width explicitly. |
| |
| @item |
| Making bitfields unsigned by default on particular machines where ``the |
| ABI standard'' says to do so. |
| |
| The ANSI C standard leaves it up to the implementation whether a bitfield |
| declared plain @code{int} is signed or not. This in effect creates two |
| alternative dialects of C. |
| |
| The GNU C compiler supports both dialects; you can specify the signed |
| dialect with @samp{-fsigned-bitfields} and the unsigned dialect with |
| @samp{-funsigned-bitfields}. However, this leaves open the question of |
| which dialect to use by default. |
| |
| Currently, the preferred dialect makes plain bitfields signed, because |
| this is simplest. Since @code{int} is the same as @code{signed int} in |
| every other context, it is cleanest for them to be the same in bitfields |
| as well. |
| |
| Some computer manufacturers have published Application Binary Interface |
| standards which specify that plain bitfields should be unsigned. It is |
| a mistake, however, to say anything about this issue in an ABI. This is |
| because the handling of plain bitfields distinguishes two dialects of C. |
| Both dialects are meaningful on every type of machine. Whether a |
| particular object file was compiled using signed bitfields or unsigned |
| is of no concern to other object files, even if they access the same |
| bitfields in the same data structures. |
| |
| A given program is written in one or the other of these two dialects. |
| The program stands a chance to work on most any machine if it is |
| compiled with the proper dialect. It is unlikely to work at all if |
| compiled with the wrong dialect. |
| |
| Many users appreciate the GNU C compiler because it provides an |
| environment that is uniform across machines. These users would be |
| inconvenienced if the compiler treated plain bitfields differently on |
| certain machines. |
| |
| Occasionally users write programs intended only for a particular machine |
| type. On these occasions, the users would benefit if the GNU C compiler |
| were to support by default the same dialect as the other compilers on |
| that machine. But such applications are rare. And users writing a |
| program to run on more than one type of machine cannot possibly benefit |
| from this kind of compatibility. |
| |
| This is why GNU CC does and will treat plain bitfields in the same |
| fashion on all types of machines (by default). |
| |
| There are some arguments for making bitfields unsigned by default on all |
| machines. If, for example, this becomes a universal de facto standard, |
| it would make sense for GNU CC to go along with it. This is something |
| to be considered in the future. |
| |
| (Of course, users strongly concerned about portability should indicate |
| explicitly in each bitfield whether it is signed or not. In this way, |
| they write programs which have the same meaning in both C dialects.) |
| |
| @item |
| Undefining @code{__STDC__} when @samp{-ansi} is not used. |
| |
| Currently, GNU CC defines @code{__STDC__} as long as you don't use |
| @samp{-traditional}. This provides good results in practice. |
| |
| Programmers normally use conditionals on @code{__STDC__} to ask whether |
| it is safe to use certain features of ANSI C, such as function |
| prototypes or ANSI token concatenation. Since plain @samp{gcc} supports |
| all the features of ANSI C, the correct answer to these questions is |
| ``yes''. |
| |
| Some users try to use @code{__STDC__} to check for the availability of |
| certain library facilities. This is actually incorrect usage in an ANSI |
| C program, because the ANSI C standard says that a conforming |
| freestanding implementation should define @code{__STDC__} even though it |
| does not have the library facilities. @samp{gcc -ansi -pedantic} is a |
| conforming freestanding implementation, and it is therefore required to |
| define @code{__STDC__}, even though it does not come with an ANSI C |
| library. |
| |
| Sometimes people say that defining @code{__STDC__} in a compiler that |
| does not completely conform to the ANSI C standard somehow violates the |
| standard. This is illogical. The standard is a standard for compilers |
| that claim to support ANSI C, such as @samp{gcc -ansi}---not for other |
| compilers such as plain @samp{gcc}. Whatever the ANSI C standard says |
| is relevant to the design of plain @samp{gcc} without @samp{-ansi} only |
| for pragmatic reasons, not as a requirement. |
| |
| @item |
| Undefining @code{__STDC__} in C++. |
| |
| Programs written to compile with C++-to-C translators get the |
| value of @code{__STDC__} that goes with the C compiler that is |
| subsequently used. These programs must test @code{__STDC__} |
| to determine what kind of C preprocessor that compiler uses: |
| whether they should concatenate tokens in the ANSI C fashion |
| or in the traditional fashion. |
| |
| These programs work properly with GNU C++ if @code{__STDC__} is defined. |
| They would not work otherwise. |
| |
| In addition, many header files are written to provide prototypes in ANSI |
| C but not in traditional C. Many of these header files can work without |
| change in C++ provided @code{__STDC__} is defined. If @code{__STDC__} |
| is not defined, they will all fail, and will all need to be changed to |
| test explicitly for C++ as well. |
| |
| @item |
| Deleting ``empty'' loops. |
| |
| GNU CC does not delete ``empty'' loops because the most likely reason |
| you would put one in a program is to have a delay. Deleting them will |
| not make real programs run any faster, so it would be pointless. |
| |
| It would be different if optimization of a nonempty loop could produce |
| an empty one. But this generally can't happen. |
| |
| @item |
| Making side effects happen in the same order as in some other compiler. |
| |
| @cindex side effects, order of evaluation |
| @cindex order of evaluation, side effects |
| It is never safe to depend on the order of evaluation of side effects. |
| For example, a function call like this may very well behave differently |
| from one compiler to another: |
| |
| @example |
| void func (int, int); |
| |
| int i = 2; |
| func (i++, i++); |
| @end example |
| |
| There is no guarantee (in either the C or the C++ standard language |
| definitions) that the increments will be evaluated in any particular |
| 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 ANSI 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. |
| @end itemize |
| |
| @node Warnings and Errors |
| @section Warning Messages and Error Messages |
| |
| @cindex error messages |
| @cindex warnings vs errors |
| @cindex messages, warning and error |
| The GNU compiler can produce two kinds of diagnostics: errors and |
| warnings. Each kind has a different purpose: |
| |
| @itemize @w{} |
| @item |
| @emph{Errors} report problems that make it impossible to compile your |
| program. GNU CC reports errors with the source file name and line |
| number where the problem is apparent. |
| |
| @item |
| @emph{Warnings} report other unusual conditions in your code that |
| @emph{may} indicate a problem, although compilation can (and does) |
| proceed. Warning messages also report the source file name and line |
| number, but include the text @samp{warning:} to distinguish them |
| from error messages. |
| @end itemize |
| |
| Warnings may indicate danger points where you should check to make sure |
| that your program really does what you intend; or the use of obsolete |
| features; or the use of nonstandard features of GNU C or C++. Many |
| warnings are issued only if you ask for them, with one of the @samp{-W} |
| options (for instance, @samp{-Wall} requests a variety of useful |
| warnings). |
| |
| GNU CC always tries to compile your program if possible; it never |
| gratuitously rejects a program whose meaning is clear merely because |
| (for instance) it fails to conform to a standard. In some cases, |
| however, the C and C++ standards specify that certain extensions are |
| forbidden, and a diagnostic @emph{must} be issued by a conforming |
| compiler. The @samp{-pedantic} option tells GNU CC to issue warnings in |
| such cases; @samp{-pedantic-errors} says to make them errors instead. |
| This does not mean that @emph{all} non-ANSI constructs get warnings |
| or errors. |
| |
| @xref{Warning Options,,Options to Request or Suppress Warnings}, for |
| more detail on these and related command-line options. |
| |
| @node Bugs |
| @chapter Reporting Bugs |
| @cindex bugs |
| @cindex reporting bugs |
| |
| Your bug reports play an essential role in making GNU CC reliable. |
| |
| When you encounter a problem, the first thing to do is to see if it is |
| already known. @xref{Trouble}. If it isn't known, then you should |
| report the problem. |
| |
| Reporting a bug may help you by bringing a solution to your problem, or |
| it may not. (If it does not, look in the service directory; see |
| @ref{Service}.) In any case, the principal function of a bug report is |
| to help the entire community by making the next version of GNU CC work |
| better. Bug reports are your contribution to the maintenance of GNU CC. |
| |
| Since the maintainers are very overloaded, we cannot respond to every |
| bug report. However, if the bug has not been fixed, we are likely to |
| send you a patch and ask you to tell us whether it works. |
| |
| In order for a bug report to serve its purpose, you must include the |
| information that makes for fixing the bug. |
| |
| @menu |
| * Criteria: Bug Criteria. Have you really found a bug? |
| * Where: Bug Lists. Where to send your bug report. |
| * Reporting: Bug Reporting. How to report a bug effectively. |
| * Patches: Sending Patches. How to send a patch for GNU CC. |
| * Known: Trouble. Known problems. |
| * Help: Service. Where to ask for help. |
| @end menu |
| |
| @node Bug Criteria |
| @section Have You Found a Bug? |
| @cindex bug criteria |
| |
| If you are not sure whether you have found a bug, here are some guidelines: |
| |
| @itemize @bullet |
| @cindex fatal signal |
| @cindex core dump |
| @item |
| If the compiler gets a fatal signal, for any input whatever, that is a |
| compiler bug. Reliable compilers never crash. |
| |
| @cindex invalid assembly code |
| @cindex assembly code, invalid |
| @item |
| If the compiler produces invalid assembly code, for any input whatever |
| (except an @code{asm} statement), that is a compiler bug, unless the |
| compiler reports errors (not just warnings) which would ordinarily |
| prevent the assembler from being run. |
| |
| @cindex undefined behavior |
| @cindex undefined function value |
| @cindex increment operators |
| @item |
| If the compiler produces valid assembly code that does not correctly |
| execute the input source code, that is a compiler bug. |
| |
| However, you must double-check to make sure, because you may have run |
| into an incompatibility between GNU C and traditional C |
| (@pxref{Incompatibilities}). These incompatibilities might be considered |
| bugs, but they are inescapable consequences of valuable features. |
| |
| Or you may have a program whose behavior is undefined, which happened |
| by chance to give the desired results with another C or C++ compiler. |
| |
| For example, in many nonoptimizing compilers, you can write @samp{x;} |
| at the end of a function instead of @samp{return x;}, with the same |
| results. But the value of the function is undefined if @code{return} |
| is omitted; it is not a bug when GNU CC produces different results. |
| |
| Problems often result from expressions with two increment operators, |
| as in @code{f (*p++, *p++)}. Your previous compiler might have |
| interpreted that expression the way you intended; GNU CC might |
| interpret it another way. Neither compiler is wrong. The bug is |
| in your code. |
| |
| After you have localized the error to a single source line, it should |
| be easy to check for these things. If your program is correct and |
| well defined, you have found a compiler bug. |
| |
| @item |
| If the compiler produces an error message for valid input, that is a |
| compiler bug. |
| |
| @cindex invalid input |
| @item |
| If the compiler does not produce an error message for invalid input, |
| that is a compiler bug. However, you should note that your idea of |
| ``invalid input'' might be my idea of ``an extension'' or ``support |
| for traditional practice''. |
| |
| @item |
| If you are an experienced user of C or C++ compilers, your suggestions |
| for improvement of GNU CC or GNU C++ are welcome in any case. |
| @end itemize |
| |
| @node Bug Lists |
| @section Where to Report Bugs |
| @cindex bug report mailing lists |
| @kindex egcs-bugs@@cygnus.com |
| Send bug reports for GNU C to @samp{egcs-bugs@@cygnus.com}. |
| |
| @kindex egcs-bugs@@cygnus.com |
| @kindex egcs-bugs@@cygnus.com |
| Send bug reports for GNU C++ and the C++ runtime libraries to |
| @samp{egcs-bugs@@cygnus.com}. |
| |
| Often people think of posting bug reports to the newsgroup instead of |
| mailing them. This appears to work, but it has one problem which can be |
| crucial: a newsgroup posting does not contain a mail path back to the |
| sender. Thus, if maintainers need more information, they may be unable |
| to reach you. For this reason, you should always send bug reports by |
| mail to the proper mailing list. |
| |
| As a last resort, send bug reports on paper to: |
| |
| @example |
| GNU Compiler Bugs |
| Free Software Foundation |
| 59 Temple Place - Suite 330 |
| Boston, MA 02111-1307, USA |
| @end example |
| |
| @node Bug Reporting |
| @section How to Report Bugs |
| @cindex compiler bugs, reporting |
| |
| The fundamental principle of reporting bugs usefully is this: |
| @strong{report all the facts}. If you are not sure whether to state a |
| fact or leave it out, state it! |
| |
| Often people omit facts because they think they know what causes the |
| problem and they conclude that some details don't matter. Thus, you might |
| assume that the name of the variable you use in an example does not matter. |
| Well, probably it doesn't, but one cannot be sure. Perhaps the bug is a |
| stray memory reference which happens to fetch from the location where that |
| name is stored in memory; perhaps, if the name were different, the contents |
| of that location would fool the compiler into doing the right thing despite |
| the bug. Play it safe and give a specific, complete example. That is the |
| easiest thing for you to do, and the most helpful. |
| |
| Keep in mind that the purpose of a bug report is to enable someone to |
| fix the bug if it is not known. It isn't very important what happens if |
| the bug is already known. Therefore, always write your bug reports on |
| the assumption that the bug is not known. |
| |
| Sometimes people give a few sketchy facts and ask, ``Does this ring a |
| bell?'' This cannot help us fix a bug, so it is basically useless. We |
| respond by asking for enough details to enable us to investigate. |
| You might as well expedite matters by sending them to begin with. |
| |
| Try to make your bug report self-contained. If we have to ask you for |
| more information, it is best if you include all the previous information |
| in your response, as well as the information that was missing. |
| |
| Please report each bug in a separate message. This makes it easier for |
| us to track which bugs have been fixed and to forward your bugs reports |
| to the appropriate maintainer. |
| |
| Do not compress and encode any part of your bug report using programs |
| such as @file{uuencode}. If you do so it will slow down the processing |
| of your bug. If you must submit multiple large files, use @file{shar}, |
| which allows us to read your message without having to run any |
| decompression programs. |
| |
| To enable someone to investigate the bug, you should include all these |
| things: |
| |
| @itemize @bullet |
| @item |
| The version of GNU CC. You can get this by running it with the |
| @samp{-v} option. |
| |
| Without this, we won't know whether there is any point in looking for |
| the bug in the current version of GNU CC. |
| |
| @item |
| A complete input file that will reproduce the bug. If the bug is in the |
| C preprocessor, send a source file and any header files that it |
| requires. If the bug is in the compiler proper (@file{cc1}), run your |
| source file through the C preprocessor by doing @samp{gcc -E |
| @var{sourcefile} > @var{outfile}}, then include the contents of |
| @var{outfile} in the bug report. (When you do this, use the same |
| @samp{-I}, @samp{-D} or @samp{-U} options that you used in actual |
| compilation.) |
| |
| A single statement is not enough of an example. In order to compile it, |
| it must be embedded in a complete file of compiler input; and the bug |
| might depend on the details of how this is done. |
| |
| Without a real example one can compile, all anyone can do about your bug |
| report is wish you luck. It would be futile to try to guess how to |
| provoke the bug. For example, bugs in register allocation and reloading |
| frequently depend on every little detail of the function they happen in. |
| |
| Even if the input file that fails comes from a GNU program, you should |
| still send the complete test case. Don't ask the GNU CC maintainers to |
| do the extra work of obtaining the program in question---they are all |
| overworked as it is. Also, the problem may depend on what is in the |
| header files on your system; it is unreliable for the GNU CC maintainers |
| to try the problem with the header files available to them. By sending |
| CPP output, you can eliminate this source of uncertainty and save us |
| a certain percentage of wild goose chases. |
| |
| @item |
| The command arguments you gave GNU CC or GNU C++ to compile that example |
| and observe the bug. For example, did you use @samp{-O}? To guarantee |
| you won't omit something important, list all the options. |
| |
| If we were to try to guess the arguments, we would probably guess wrong |
| and then we would not encounter the bug. |
| |
| @item |
| The type of machine you are using, and the operating system name and |
| version number. |
| |
| @item |
| The operands you gave to the @code{configure} command when you installed |
| the compiler. |
| |
| @item |
| A complete list of any modifications you have made to the compiler |
| source. (We don't promise to investigate the bug unless it happens in |
| an unmodified compiler. But if you've made modifications and don't tell |
| us, then you are sending us on a wild goose chase.) |
| |
| Be precise about these changes. A description in English is not |
| enough---send a context diff for them. |
| |
| Adding files of your own (such as a machine description for a machine we |
| don't support) is a modification of the compiler source. |
| |
| @item |
| Details of any other deviations from the standard procedure for installing |
| GNU CC. |
| |
| @item |
| A description of what behavior you observe that you believe is |
| incorrect. For example, ``The compiler gets a fatal signal,'' or, |
| ``The assembler instruction at line 208 in the output is incorrect.'' |
| |
| Of course, if the bug is that the compiler gets a fatal signal, then one |
| can't miss it. But if the bug is incorrect output, the maintainer might |
| not notice unless it is glaringly wrong. None of us has time to study |
| all the assembler code from a 50-line C program just on the chance that |
| one instruction might be wrong. We need @emph{you} to do this part! |
| |
| Even if the problem you experience is a fatal signal, you should still |
| say so explicitly. Suppose something strange is going on, such as, your |
| copy of the compiler is out of synch, or you have encountered a bug in |
| the C library on your system. (This has happened!) Your copy might |
| crash and the copy here would not. If you @i{said} to expect a crash, |
| then when the compiler here fails to crash, we would know that the bug |
| was not happening. If you don't say to expect a crash, then we would |
| not know whether the bug was happening. We would not be able to draw |
| any conclusion from our observations. |
| |
| If the problem is a diagnostic when compiling GNU CC with some other |
| compiler, say whether it is a warning or an error. |
| |
| Often the observed symptom is incorrect output when your program is run. |
| Sad to say, this is not enough information unless the program is short |
| and simple. None of us has time to study a large program to figure out |
| how it would work if compiled correctly, much less which line of it was |
| compiled wrong. So you will have to do that. Tell us which source line |
| it is, and what incorrect result happens when that line is executed. A |
| person who understands the program can find this as easily as finding a |
| bug in the program itself. |
| |
| @item |
| If you send examples of assembler code output from GNU CC or GNU C++, |
| please use @samp{-g} when you make them. The debugging information |
| includes source line numbers which are essential for correlating the |
| output with the input. |
| |
| @item |
| If you wish to mention something in the GNU CC source, refer to it by |
| context, not by line number. |
| |
| The line numbers in the development sources don't match those in your |
| sources. Your line numbers would convey no useful information to the |
| maintainers. |
| |
| @item |
| Additional information from a debugger might enable someone to find a |
| problem on a machine which he does not have available. However, you |
| need to think when you collect this information if you want it to have |
| any chance of being useful. |
| |
| @cindex backtrace for bug reports |
| For example, many people send just a backtrace, but that is never |
| useful by itself. A simple backtrace with arguments conveys little |
| about GNU CC because the compiler is largely data-driven; the same |
| functions are called over and over for different RTL insns, doing |
| different things depending on the details of the insn. |
| |
| Most of the arguments listed in the backtrace are useless because they |
| are pointers to RTL list structure. The numeric values of the |
| pointers, which the debugger prints in the backtrace, have no |
| significance whatever; all that matters is the contents of the objects |
| they point to (and most of the contents are other such pointers). |
| |
| In addition, most compiler passes consist of one or more loops that |
| scan the RTL insn sequence. The most vital piece of information about |
| such a loop---which insn it has reached---is usually in a local variable, |
| not in an argument. |
| |
| @findex debug_rtx |
| What you need to provide in addition to a backtrace are the values of |
| the local variables for several stack frames up. When a local |
| variable or an argument is an RTX, first print its value and then use |
| the GDB command @code{pr} to print the RTL expression that it points |
| to. (If GDB doesn't run on your machine, use your debugger to call |
| the function @code{debug_rtx} with the RTX as an argument.) In |
| general, whenever a variable is a pointer, its value is no use |
| without the data it points to. |
| @end itemize |
| |
| Here are some things that are not necessary: |
| |
| @itemize @bullet |
| @item |
| A description of the envelope of the bug. |
| |
| Often people who encounter a bug spend a lot of time investigating |
| which changes to the input file will make the bug go away and which |
| changes will not affect it. |
| |
| This is often time consuming and not very useful, because the way we |
| will find the bug is by running a single example under the debugger with |
| breakpoints, not by pure deduction from a series of examples. You might |
| as well save your time for something else. |
| |
| Of course, if you can find a simpler example to report @emph{instead} of |
| the original one, that is a convenience. Errors in the output will be |
| easier to spot, running under the debugger will take less time, etc. |
| Most GNU CC bugs involve just one function, so the most straightforward |
| way to simplify an example is to delete all the function definitions |
| except the one where the bug occurs. Those earlier in the file may be |
| replaced by external declarations if the crucial function depends on |
| them. (Exception: inline functions may affect compilation of functions |
| defined later in the file.) |
| |
| However, simplification is not vital; if you don't want to do this, |
| report the bug anyway and send the entire test case you used. |
| |
| @item |
| In particular, some people insert conditionals @samp{#ifdef BUG} around |
| a statement which, if removed, makes the bug not happen. These are just |
| clutter; we won't pay any attention to them anyway. Besides, you should |
| send us cpp output, and that can't have conditionals. |
| |
| @item |
| A patch for the bug. |
| |
| A patch for the bug is useful if it is a good one. But don't omit the |
| necessary information, such as the test case, on the assumption that a |
| patch is all we need. We might see problems with your patch and decide |
| to fix the problem another way, or we might not understand it at all. |
| |
| Sometimes with a program as complicated as GNU CC it is very hard to |
| construct an example that will make the program follow a certain path |
| through the code. If you don't send the example, we won't be able to |
| construct one, so we won't be able to verify that the bug is fixed. |
| |
| And if we can't understand what bug you are trying to fix, or why your |
| patch should be an improvement, we won't install it. A test case will |
| help us to understand. |
| |
| @xref{Sending Patches}, for guidelines on how to make it easy for us to |
| understand and install your patches. |
| |
| @item |
| A guess about what the bug is or what it depends on. |
| |
| Such guesses are usually wrong. Even I can't guess right about such |
| things without first using the debugger to find the facts. |
| |
| @item |
| A core dump file. |
| |
| We have no way of examining a core dump for your type of machine |
| unless we have an identical system---and if we do have one, |
| we should be able to reproduce the crash ourselves. |
| @end itemize |
| |
| @node Sending Patches,, Bug Reporting, Bugs |
| @section Sending Patches for GNU CC |
| |
| If you would like to write bug fixes or improvements for the GNU C |
| compiler, that is very helpful. Send suggested fixes to the bug report |
| mailing list, @code{egcs-bugs@@cygnus.com}. |
| |
| Please follow these guidelines so we can study your patches efficiently. |
| If you don't follow these guidelines, your information might still be |
| useful, but using it will take extra work. Maintaining GNU C is a lot |
| of work in the best of circumstances, and we can't keep up unless you do |
| your best to help. |
| |
| @itemize @bullet |
| @item |
| Send an explanation with your changes of what problem they fix or what |
| improvement they bring about. For a bug fix, just include a copy of the |
| bug report, and explain why the change fixes the bug. |
| |
| (Referring to a bug report is not as good as including it, because then |
| we will have to look it up, and we have probably already deleted it if |
| we've already fixed the bug.) |
| |
| @item |
| Always include a proper bug report for the problem you think you have |
| fixed. We need to convince ourselves that the change is right before |
| installing it. Even if it is right, we might have trouble judging it if |
| we don't have a way to reproduce the problem. |
| |
| @item |
| Include all the comments that are appropriate to help people reading the |
| source in the future understand why this change was needed. |
| |
| @item |
| Don't mix together changes made for different reasons. |
| Send them @emph{individually}. |
| |
| If you make two changes for separate reasons, then we might not want to |
| install them both. We might want to install just one. If you send them |
| all jumbled together in a single set of diffs, we have to do extra work |
| to disentangle them---to figure out which parts of the change serve |
| which purpose. If we don't have time for this, we might have to ignore |
| your changes entirely. |
| |
| If you send each change as soon as you have written it, with its own |
| explanation, then the two changes never get tangled up, and we can |
| consider each one properly without any extra work to disentangle them. |
| |
| Ideally, each change you send should be impossible to subdivide into |
| parts that we might want to consider separately, because each of its |
| parts gets its motivation from the other parts. |
| |
| @item |
| Send each change as soon as that change is finished. Sometimes people |
| think they are helping us by accumulating many changes to send them all |
| together. As explained above, this is absolutely the worst thing you |
| could do. |
| |
| Since you should send each change separately, you might as well send it |
| right away. That gives us the option of installing it immediately if it |
| is important. |
| |
| @item |
| Use @samp{diff -c} to make your diffs. Diffs without context are hard |
| for us to install reliably. More than that, they make it hard for us to |
| study the diffs to decide whether we want to install them. Unidiff |
| format is better than contextless diffs, but not as easy to read as |
| @samp{-c} format. |
| |
| If you have GNU diff, use @samp{diff -cp}, which shows the name of the |
| function that each change occurs in. |
| |
| @item |
| Write the change log entries for your changes. We get lots of changes, |
| and we don't have time to do all the change log writing ourselves. |
| |
| Read the @file{ChangeLog} file to see what sorts of information to put |
| in, and to learn the style that we use. The purpose of the change log |
| is to show people where to find what was changed. So you need to be |
| specific about what functions you changed; in large functions, it's |
| often helpful to indicate where within the function the change was. |
| |
| On the other hand, once you have shown people where to find the change, |
| you need not explain its purpose. Thus, if you add a new function, all |
| you need to say about it is that it is new. If you feel that the |
| purpose needs explaining, it probably does---but the explanation will be |
| much more useful if you put it in comments in the code. |
| |
| If you would like your name to appear in the header line for who made |
| the change, send us the header line. |
| |
| @item |
| When you write the fix, keep in mind that we can't install a change that |
| would break other systems. |
| |
| People often suggest fixing a problem by changing machine-independent |
| files such as @file{toplev.c} to do something special that a particular |
| system needs. Sometimes it is totally obvious that such changes would |
| break GNU CC for almost all users. We can't possibly make a change like |
| that. At best it might tell us how to write another patch that would |
| solve the problem acceptably. |
| |
| Sometimes people send fixes that @emph{might} be an improvement in |
| general---but it is hard to be sure of this. It's hard to install |
| such changes because we have to study them very carefully. Of course, |
| a good explanation of the reasoning by which you concluded the change |
| was correct can help convince us. |
| |
| The safest changes are changes to the configuration files for a |
| particular machine. These are safe because they can't create new bugs |
| on other machines. |
| |
| Please help us keep up with the workload by designing the patch in a |
| form that is good to install. |
| @end itemize |
| |
| @node Service |
| @chapter How To Get Help with GNU CC |
| |
| If you need help installing, using or changing GNU CC, there are two |
| ways to find it: |
| |
| @itemize @bullet |
| @item |
| Send a message to a suitable network mailing list. First try |
| @code{egcs-bugs@@cygnus.com}, and if that brings no response, try |
| @code{egcs@@cygnus.com}. |
| |
| @item |
| Look in the service directory for someone who might help you for a fee. |
| The service directory is found in the file named @file{SERVICE} in the |
| GNU CC distribution. |
| @end itemize |
| |
| @node Contributing |
| @chapter Contributing to GNU CC Development |
| |
| If you would like to help pretest GNU CC releases to assure they work |
| well, or if you would like to work on improving GNU CC, please contact |
| the maintainers at @code{egcs@@cygnus.com}. A pretester should |
| be willing to try to investigate bugs as well as report them. |
| |
| If you'd like to work on improvements, please ask for suggested projects |
| or suggest your own ideas. If you have already written an improvement, |
| please tell us about it. If you have not yet started work, it is useful |
| to contact @code{egcs@@cygnus.com} before you start; the |
| maintainers may be able to suggest ways to make your extension fit in |
| better with the rest of GNU CC and with other development plans. |
| |
| @node VMS |
| @chapter Using GNU CC on VMS |
| |
| @c prevent bad page break with this line |
| Here is how to use GNU CC on VMS. |
| |
| @menu |
| * Include Files and VMS:: Where the preprocessor looks for the include files. |
| * Global Declarations:: How to do globaldef, globalref and globalvalue with |
| GNU CC. |
| * VMS Misc:: Misc information. |
| @end menu |
| |
| @node Include Files and VMS |
| @section Include Files and VMS |
| |
| @cindex include files and VMS |
| @cindex VMS and include files |
| @cindex header files and VMS |
| Due to the differences between the filesystems of Unix and VMS, GNU CC |
| attempts to translate file names in @samp{#include} into names that VMS |
| will understand. The basic strategy is to prepend a prefix to the |
| specification of the include file, convert the whole filename to a VMS |
| filename, and then try to open the file. GNU CC tries various prefixes |
| one by one until one of them succeeds: |
| |
| @enumerate |
| @item |
| The first prefix is the @samp{GNU_CC_INCLUDE:} logical name: this is |
| where GNU C header files are traditionally stored. If you wish to store |
| header files in non-standard locations, then you can assign the logical |
| @samp{GNU_CC_INCLUDE} to be a search list, where each element of the |
| list is suitable for use with a rooted logical. |
| |
| @item |
| The next prefix tried is @samp{SYS$SYSROOT:[SYSLIB.]}. This is where |
| VAX-C header files are traditionally stored. |
| |
| @item |
| If the include file specification by itself is a valid VMS filename, the |
| preprocessor then uses this name with no prefix in an attempt to open |
| the include file. |
| |
| @item |
| If the file specification is not a valid VMS filename (i.e. does not |
| contain a device or a directory specifier, and contains a @samp{/} |
| character), the preprocessor tries to convert it from Unix syntax to |
| VMS syntax. |
| |
| Conversion works like this: the first directory name becomes a device, |
| and the rest of the directories are converted into VMS-format directory |
| names. For example, the name @file{X11/foobar.h} is |
| translated to @file{X11:[000000]foobar.h} or @file{X11:foobar.h}, |
| whichever one can be opened. This strategy allows you to assign a |
| logical name to point to the actual location of the header files. |
| |
| @item |
| If none of these strategies succeeds, the @samp{#include} fails. |
| @end enumerate |
| |
| Include directives of the form: |
| |
| @example |
| #include foobar |
| @end example |
| |
| @noindent |
| are a common source of incompatibility between VAX-C and GNU CC. VAX-C |
| treats this much like a standard @code{#include <foobar.h>} directive. |
| That is incompatible with the ANSI C behavior implemented by GNU CC: to |
| expand the name @code{foobar} as a macro. Macro expansion should |
| eventually yield one of the two standard formats for @code{#include}: |
| |
| @example |
| #include "@var{file}" |
| #include <@var{file}> |
| @end example |
| |
| If you have this problem, the best solution is to modify the source to |
| convert the @code{#include} directives to one of the two standard forms. |
| That will work with either compiler. If you want a quick and dirty fix, |
| define the file names as macros with the proper expansion, like this: |
| |
| @example |
| #define stdio <stdio.h> |
| @end example |
| |
| @noindent |
| This will work, as long as the name doesn't conflict with anything else |
| in the program. |
| |
| Another source of incompatibility is that VAX-C assumes that: |
| |
| @example |
| #include "foobar" |
| @end example |
| |
| @noindent |
| is actually asking for the file @file{foobar.h}. GNU CC does not |
| make this assumption, and instead takes what you ask for literally; |
| it tries to read the file @file{foobar}. The best way to avoid this |
| problem is to always specify the desired file extension in your include |
| directives. |
| |
| GNU CC for VMS is distributed with a set of include files that is |
| sufficient to compile most general purpose programs. Even though the |
| GNU CC distribution does not contain header files to define constants |
| and structures for some VMS system-specific functions, there is no |
| reason why you cannot use GNU CC with any of these functions. You first |
| may have to generate or create header files, either by using the public |
| domain utility @code{UNSDL} (which can be found on a DECUS tape), or by |
| extracting the relevant modules from one of the system macro libraries, |
| and using an editor to construct a C header file. |
| |
| A @code{#include} file name cannot contain a DECNET node name. The |
| preprocessor reports an I/O error if you attempt to use a node name, |
| whether explicitly, or implicitly via a logical name. |
| |
| @node Global Declarations |
| @section Global Declarations and VMS |
| |
| @findex GLOBALREF |
| @findex GLOBALDEF |
| @findex GLOBALVALUEDEF |
| @findex GLOBALVALUEREF |
| GNU CC does not provide the @code{globalref}, @code{globaldef} and |
| @code{globalvalue} keywords of VAX-C. You can get the same effect with |
| an obscure feature of GAS, the GNU assembler. (This requires GAS |
| version 1.39 or later.) The following macros allow you to use this |
| feature in a fairly natural way: |
| |
| @smallexample |
| #ifdef __GNUC__ |
| #define GLOBALREF(TYPE,NAME) \ |
| TYPE NAME \ |
| asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) |
| #define GLOBALDEF(TYPE,NAME,VALUE) \ |
| TYPE NAME \ |
| asm ("_$$PsectAttributes_GLOBALSYMBOL$$" #NAME) \ |
| = VALUE |
| #define GLOBALVALUEREF(TYPE,NAME) \ |
| const TYPE NAME[1] \ |
| asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) |
| #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ |
| const TYPE NAME[1] \ |
| asm ("_$$PsectAttributes_GLOBALVALUE$$" #NAME) \ |
| = @{VALUE@} |
| #else |
| #define GLOBALREF(TYPE,NAME) \ |
| globalref TYPE NAME |
| #define GLOBALDEF(TYPE,NAME,VALUE) \ |
| globaldef TYPE NAME = VALUE |
| #define GLOBALVALUEDEF(TYPE,NAME,VALUE) \ |
| globalvalue TYPE NAME = VALUE |
| #define GLOBALVALUEREF(TYPE,NAME) \ |
| globalvalue TYPE NAME |
| #endif |
| @end smallexample |
| |
| @noindent |
| (The @code{_$$PsectAttributes_GLOBALSYMBOL} prefix at the start of the |
| name is removed by the assembler, after it has modified the attributes |
| of the symbol). These macros are provided in the VMS binaries |
| distribution in a header file @file{GNU_HACKS.H}. An example of the |
| usage is: |
| |
| @example |
| GLOBALREF (int, ijk); |
| GLOBALDEF (int, jkl, 0); |
| @end example |
| |
| The macros @code{GLOBALREF} and @code{GLOBALDEF} cannot be used |
| straightforwardly for arrays, since there is no way to insert the array |
| dimension into the declaration at the right place. However, you can |
| declare an array with these macros if you first define a typedef for the |
| array type, like this: |
| |
| @example |
| typedef int intvector[10]; |
| GLOBALREF (intvector, foo); |
| @end example |
| |
| Array and structure initializers will also break the macros; you can |
| define the initializer to be a macro of its own, or you can expand the |
| @code{GLOBALDEF} macro by hand. You may find a case where you wish to |
| use the @code{GLOBALDEF} macro with a large array, but you are not |
| interested in explicitly initializing each element of the array. In |
| such cases you can use an initializer like: @code{@{0,@}}, which will |
| initialize the entire array to @code{0}. |
| |
| A shortcoming of this implementation is that a variable declared with |
| @code{GLOBALVALUEREF} or @code{GLOBALVALUEDEF} is always an array. For |
| example, the declaration: |
| |
| @example |
| GLOBALVALUEREF(int, ijk); |
| @end example |
| |
| @noindent |
| declares the variable @code{ijk} as an array of type @code{int [1]}. |
| This is done because a globalvalue is actually a constant; its ``value'' |
| is what the linker would normally consider an address. That is not how |
| an integer value works in C, but it is how an array works. So treating |
| the symbol as an array name gives consistent results---with the |
| exception that the value seems to have the wrong type. @strong{Don't |
| try to access an element of the array.} It doesn't have any elements. |
| The array ``address'' may not be the address of actual storage. |
| |
| The fact that the symbol is an array may lead to warnings where the |
| variable is used. Insert type casts to avoid the warnings. Here is an |
| example; it takes advantage of the ANSI C feature allowing macros that |
| expand to use the same name as the macro itself. |
| |
| @example |
| GLOBALVALUEREF (int, ss$_normal); |
| GLOBALVALUEDEF (int, xyzzy,123); |
| #ifdef __GNUC__ |
| #define ss$_normal ((int) ss$_normal) |
| #define xyzzy ((int) xyzzy) |
| #endif |
| @end example |
| |
| Don't use @code{globaldef} or @code{globalref} with a variable whose |
| type is an enumeration type; this is not implemented. Instead, make the |
| variable an integer, and use a @code{globalvaluedef} for each of the |
| enumeration values. An example of this would be: |
| |
| @example |
| #ifdef __GNUC__ |
| GLOBALDEF (int, color, 0); |
| GLOBALVALUEDEF (int, RED, 0); |
| GLOBALVALUEDEF (int, BLUE, 1); |
| GLOBALVALUEDEF (int, GREEN, 3); |
| #else |
| enum globaldef color @{RED, BLUE, GREEN = 3@}; |
| #endif |
| @end example |
| |
| @node VMS Misc |
| @section Other VMS Issues |
| |
| @cindex exit status and VMS |
| @cindex return value of @code{main} |
| @cindex @code{main} and the exit status |
| GNU CC automatically arranges for @code{main} to return 1 by default if |
| you fail to specify an explicit return value. This will be interpreted |
| by VMS as a status code indicating a normal successful completion. |
| Version 1 of GNU CC did not provide this default. |
| |
| GNU CC on VMS works only with the GNU assembler, GAS. You need version |
| 1.37 or later of GAS in order to produce value debugging information for |
| the VMS debugger. Use the ordinary VMS linker with the object files |
| produced by GAS. |
| |
| @cindex shared VMS run time system |
| @cindex @file{VAXCRTL} |
| Under previous versions of GNU CC, the generated code would occasionally |
| give strange results when linked to the sharable @file{VAXCRTL} library. |
| Now this should work. |
| |
| A caveat for use of @code{const} global variables: the @code{const} |
| modifier must be specified in every external declaration of the variable |
| in all of the source files that use that variable. Otherwise the linker |
| will issue warnings about conflicting attributes for the variable. Your |
| program will still work despite the warnings, but the variable will be |
| placed in writable storage. |
| |
| @cindex name augmentation |
| @cindex case sensitivity and VMS |
| @cindex VMS and case sensitivity |
| Although the VMS linker does distinguish between upper and lower case |
| letters in global symbols, most VMS compilers convert all such symbols |
| into upper case and most run-time library routines also have upper case |
| names. To be able to reliably call such routines, GNU CC (by means of |
| the assembler GAS) converts global symbols into upper case like other |
| VMS compilers. However, since the usual practice in C is to distinguish |
| case, GNU CC (via GAS) tries to preserve usual C behavior by augmenting |
| each name that is not all lower case. This means truncating the name |
| to at most 23 characters and then adding more characters at the end |
| which encode the case pattern of those 23. Names which contain at |
| least one dollar sign are an exception; they are converted directly into |
| upper case without augmentation. |
| |
| Name augmentation yields bad results for programs that use precompiled |
| libraries (such as Xlib) which were generated by another compiler. You |
| can use the compiler option @samp{/NOCASE_HACK} to inhibit augmentation; |
| it makes external C functions and variables case-independent as is usual |
| on VMS. Alternatively, you could write all references to the functions |
| and variables in such libraries using lower case; this will work on VMS, |
| but is not portable to other systems. The compiler option @samp{/NAMES} |
| also provides control over global name handling. |
| |
| Function and variable names are handled somewhat differently with GNU |
| C++. The GNU C++ compiler performs @dfn{name mangling} on function |
| names, which means that it adds information to the function name to |
| describe the data types of the arguments that the function takes. One |
| result of this is that the name of a function can become very long. |
| Since the VMS linker only recognizes the first 31 characters in a name, |
| special action is taken to ensure that each function and variable has a |
| unique name that can be represented in 31 characters. |
| |
| If the name (plus a name augmentation, if required) is less than 32 |
| characters in length, then no special action is performed. If the name |
| is longer than 31 characters, the assembler (GAS) will generate a |
| hash string based upon the function name, truncate the function name to |
| 23 characters, and append the hash string to the truncated name. If the |
| @samp{/VERBOSE} compiler option is used, the assembler will print both |
| the full and truncated names of each symbol that is truncated. |
| |
| The @samp{/NOCASE_HACK} compiler option should not be used when you are |
| compiling programs that use libg++. libg++ has several instances of |
| objects (i.e. @code{Filebuf} and @code{filebuf}) which become |
| indistinguishable in a case-insensitive environment. This leads to |
| cases where you need to inhibit augmentation selectively (if you were |
| using libg++ and Xlib in the same program, for example). There is no |
| special feature for doing this, but you can get the result by defining a |
| macro for each mixed case symbol for which you wish to inhibit |
| augmentation. The macro should expand into the lower case equivalent of |
| itself. For example: |
| |
| @example |
| #define StuDlyCapS studlycaps |
| @end example |
| |
| These macro definitions can be placed in a header file to minimize the |
| number of changes to your source code. |
| @end ifset |
| |
| @ifset INTERNALS |
| @node Portability |
| @chapter GNU CC and Portability |
| @cindex portability |
| @cindex GNU CC and portability |
| |
| The main goal of GNU CC was to make a good, fast compiler for machines in |
| the class that the GNU system aims to run on: 32-bit machines that address |
| 8-bit bytes and have several general registers. Elegance, theoretical |
| power and simplicity are only secondary. |
| |
| GNU CC gets most of the information about the target machine from a machine |
| description which gives an algebraic formula for each of the machine's |
| instructions. This is a very clean way to describe the target. But when |
| the compiler needs information that is difficult to express in this |
| fashion, I have not hesitated to define an ad-hoc parameter to the machine |
| description. The purpose of portability is to reduce the total work needed |
| on the compiler; it was not of interest for its own sake. |
| |
| @cindex endianness |
| @cindex autoincrement addressing, availability |
| @findex abort |
| GNU CC does not contain machine dependent code, but it does contain code |
| that depends on machine parameters such as endianness (whether the most |
| significant byte has the highest or lowest address of the bytes in a word) |
| and the availability of autoincrement addressing. In the RTL-generation |
| pass, it is often necessary to have multiple strategies for generating code |
| for a particular kind of syntax tree, strategies that are usable for different |
| combinations of parameters. Often I have not tried to address all possible |
| cases, but only the common ones or only the ones that I have encountered. |
| As a result, a new target may require additional strategies. You will know |
| if this happens because the compiler will call @code{abort}. Fortunately, |
| the new strategies can be added in a machine-independent fashion, and will |
| affect only the target machines that need them. |
| @end ifset |
| |
| @ifset INTERNALS |
| @node Interface |
| @chapter Interfacing to GNU CC Output |
| @cindex interfacing to GNU CC output |
| @cindex run-time conventions |
| @cindex function call conventions |
| @cindex conventions, run-time |
| |
| GNU CC is normally configured to use the same function calling convention |
| normally in use on the target system. This is done with the |
| machine-description macros described (@pxref{Target Macros}). |
| |
| @cindex unions, returning |
| @cindex structures, returning |
| @cindex returning structures and unions |
| However, returning of structure and union values is done differently on |
| some target machines. As a result, functions compiled with PCC |
| returning such types cannot be called from code compiled with GNU CC, |
| and vice versa. This does not cause trouble often because few Unix |
| library routines return structures or unions. |
| |
| GNU CC code returns structures and unions that are 1, 2, 4 or 8 bytes |
| long in the same registers used for @code{int} or @code{double} return |
| values. (GNU CC typically allocates variables of such types in |
| registers also.) Structures and unions of other sizes are returned by |
| storing them into an address passed by the caller (usually in a |
| register). The machine-description macros @code{STRUCT_VALUE} and |
| @code{STRUCT_INCOMING_VALUE} tell GNU CC where to pass this address. |
| |
| By contrast, PCC on most target machines returns structures and unions |
| of any size by copying the data into an area of static storage, and then |
| returning the address of that storage as if it were a pointer value. |
| The caller must copy the data from that memory area to the place where |
| the value is wanted. This is slower than the method used by GNU CC, and |
| fails to be reentrant. |
| |
| On some target machines, such as RISC machines and the 80386, the |
| standard system convention is to pass to the subroutine the address of |
| where to return the value. On these machines, GNU CC has been |
| configured to be compatible with the standard compiler, when this method |
| is used. It may not be compatible for structures of 1, 2, 4 or 8 bytes. |
| |
| @cindex argument passing |
| @cindex passing arguments |
| GNU CC uses the system's standard convention for passing arguments. On |
| some machines, the first few arguments are passed in registers; in |
| others, all are passed on the stack. It would be possible to use |
| registers for argument passing on any machine, and this would probably |
| result in a significant speedup. But the result would be complete |
| incompatibility with code that follows the standard convention. So this |
| change is practical only if you are switching to GNU CC as the sole C |
| compiler for the system. We may implement register argument passing on |
| certain machines once we have a complete GNU system so that we can |
| compile the libraries with GNU CC. |
| |
| On some machines (particularly the Sparc), certain types of arguments |
| are passed ``by invisible reference''. This means that the value is |
| stored in memory, and the address of the memory location is passed to |
| the subroutine. |
| |
| @cindex @code{longjmp} and automatic variables |
| If you use @code{longjmp}, beware of automatic variables. ANSI C says that |
| automatic variables that are not declared @code{volatile} have undefined |
| values after a @code{longjmp}. And this is all GNU CC promises to do, |
| because it is very difficult to restore register variables correctly, and |
| one of GNU CC's features is that it can put variables in registers without |
| your asking it to. |
| |
| If you want a variable to be unaltered by @code{longjmp}, and you don't |
| want to write @code{volatile} because old C compilers don't accept it, |
| just take the address of the variable. If a variable's address is ever |
| taken, even if just to compute it and ignore it, then the variable cannot |
| go in a register: |
| |
| @example |
| @{ |
| int careful; |
| &careful; |
| @dots{} |
| @} |
| @end example |
| |
| @cindex arithmetic libraries |
| @cindex math libraries |
| Code compiled with GNU CC may call certain library routines. Most of |
| them handle arithmetic for which there are no instructions. This |
| includes multiply and divide on some machines, and floating point |
| operations on any machine for which floating point support is disabled |
| with @samp{-msoft-float}. Some standard parts of the C library, such as |
| @code{bcopy} or @code{memcpy}, are also called automatically. The usual |
| function call interface is used for calling the library routines. |
| |
| These library routines should be defined in the library @file{libgcc.a}, |
| which GNU CC automatically searches whenever it links a program. On |
| machines that have multiply and divide instructions, if hardware |
| floating point is in use, normally @file{libgcc.a} is not needed, but it |
| is searched just in case. |
| |
| Each arithmetic function is defined in @file{libgcc1.c} to use the |
| corresponding C arithmetic operator. As long as the file is compiled |
| with another C compiler, which supports all the C arithmetic operators, |
| this file will work portably. However, @file{libgcc1.c} does not work if |
| compiled with GNU CC, because each arithmetic function would compile |
| into a call to itself! |
| @end ifset |
| |
| @ifset INTERNALS |
| @node Passes |
| @chapter Passes and Files of the Compiler |
| @cindex passes and files of the compiler |
| @cindex files and passes of the compiler |
| @cindex compiler passes and files |
| |
| @cindex top level of compiler |
| The overall control structure of the compiler is in @file{toplev.c}. This |
| file is responsible for initialization, decoding arguments, opening and |
| closing files, and sequencing the passes. |
| |
| @cindex parsing pass |
| The parsing pass is invoked only once, to parse the entire input. The RTL |
| intermediate code for a function is generated as the function is parsed, a |
| statement at a time. Each statement is read in as a syntax tree and then |
| converted to RTL; then the storage for the tree for the statement is |
| reclaimed. Storage for types (and the expressions for their sizes), |
| declarations, and a representation of the binding contours and how they nest, |
| remain until the function is finished being compiled; these are all needed |
| to output the debugging information. |
| |
| @findex rest_of_compilation |
| @findex rest_of_decl_compilation |
| Each time the parsing pass reads a complete function definition or |
| top-level declaration, it calls either the function |
| @code{rest_of_compilation}, or the function |
| @code{rest_of_decl_compilation} in @file{toplev.c}, which are |
| responsible for all further processing necessary, ending with output of |
| the assembler language. All other compiler passes run, in sequence, |
| within @code{rest_of_compilation}. When that function returns from |
| compiling a function definition, the storage used for that function |
| definition's compilation is entirely freed, unless it is an inline |
| function |
| @ifset USING |
| (@pxref{Inline,,An Inline Function is As Fast As a Macro}). |
| @end ifset |
| @ifclear USING |
| (@pxref{Inline,,An Inline Function is As Fast As a Macro,gcc.texi,Using GCC}). |
| @end ifclear |
| |
| Here is a list of all the passes of the compiler and their source files. |
| Also included is a description of where debugging dumps can be requested |
| with @samp{-d} options. |
| |
| @itemize @bullet |
| @item |
| Parsing. This pass reads the entire text of a function definition, |
| constructing partial syntax trees. This and RTL generation are no longer |
| truly separate passes (formerly they were), but it is easier to think |
| of them as separate. |
| |
| The tree representation does not entirely follow C syntax, because it is |
| intended to support other languages as well. |
| |
| Language-specific data type analysis is also done in this pass, and every |
| tree node that represents an expression has a data type attached. |
| Variables are represented as declaration nodes. |
| |
| @cindex constant folding |
| @cindex arithmetic simplifications |
| @cindex simplifications, arithmetic |
| Constant folding and some arithmetic simplifications are also done |
| during this pass. |
| |
| The language-independent source files for parsing are |
| @file{stor-layout.c}, @file{fold-const.c}, and @file{tree.c}. |
| There are also header files @file{tree.h} and @file{tree.def} |
| which define the format of the tree representation.@refill |
| |
| @c Avoiding overfull is tricky here. |
| The source files to parse C are |
| @file{c-parse.in}, |
| @file{c-decl.c}, |
| @file{c-typeck.c}, |
| @file{c-aux-info.c}, |
| @file{c-convert.c}, |
| and @file{c-lang.c} |
| along with header files |
| @file{c-lex.h}, and |
| @file{c-tree.h}. |
| |
| The source files for parsing C++ are @file{cp-parse.y}, |
| @file{cp-class.c},@* |
| @file{cp-cvt.c}, @file{cp-decl.c}, @file{cp-decl2.c}, |
| @file{cp-dem.c}, @file{cp-except.c},@* |
| @file{cp-expr.c}, @file{cp-init.c}, @file{cp-lex.c}, |
| @file{cp-method.c}, @file{cp-ptree.c},@* |
| @file{cp-search.c}, @file{cp-tree.c}, @file{cp-type2.c}, and |
| @file{cp-typeck.c}, along with header files @file{cp-tree.def}, |
| @file{cp-tree.h}, and @file{cp-decl.h}. |
| |
| The special source files for parsing Objective C are |
| @file{objc-parse.y}, @file{objc-actions.c}, @file{objc-tree.def}, and |
| @file{objc-actions.h}. Certain C-specific files are used for this as |
| well. |
| |
| The file @file{c-common.c} is also used for all of the above languages. |
| |
| @cindex RTL generation |
| @item |
| RTL generation. This is the conversion of syntax tree into RTL code. |
| It is actually done statement-by-statement during parsing, but for |
| most purposes it can be thought of as a separate pass. |
| |
| @cindex target-parameter-dependent code |
| This is where the bulk of target-parameter-dependent code is found, |
| since often it is necessary for strategies to apply only when certain |
| standard kinds of instructions are available. The purpose of named |
| instruction patterns is to provide this information to the RTL |
| generation pass. |
| |
| @cindex tail recursion optimization |
| Optimization is done in this pass for @code{if}-conditions that are |
| comparisons, boolean operations or conditional expressions. Tail |
| recursion is detected at this time also. Decisions are made about how |
| best to arrange loops and how to output @code{switch} statements. |
| |
| @c Avoiding overfull is tricky here. |
| The source files for RTL generation include |
| @file{stmt.c}, |
| @file{calls.c}, |
| @file{expr.c}, |
| @file{explow.c}, |
| @file{expmed.c}, |
| @file{function.c}, |
| @file{optabs.c} |
| and @file{emit-rtl.c}. |
| Also, the file |
| @file{insn-emit.c}, generated from the machine description by the |
| program @code{genemit}, is used in this pass. The header file |
| @file{expr.h} is used for communication within this pass.@refill |
| |
| @findex genflags |
| @findex gencodes |
| The header files @file{insn-flags.h} and @file{insn-codes.h}, |
| generated from the machine description by the programs @code{genflags} |
| and @code{gencodes}, tell this pass which standard names are available |
| for use and which patterns correspond to them.@refill |
| |
| Aside from debugging information output, none of the following passes |
| refers to the tree structure representation of the function (only |
| part of which is saved). |
| |
| @cindex inline, automatic |
| The decision of whether the function can and should be expanded inline |
| in its subsequent callers is made at the end of rtl generation. The |
| function must meet certain criteria, currently related to the size of |
| the function and the types and number of parameters it has. Note that |
| this function may contain loops, recursive calls to itself |
| (tail-recursive functions can be inlined!), gotos, in short, all |
| constructs supported by GNU CC. The file @file{integrate.c} contains |
| the code to save a function's rtl for later inlining and to inline that |
| rtl when the function is called. The header file @file{integrate.h} |
| is also used for this purpose. |
| |
| The option @samp{-dr} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.rtl} to |
| the input file name. |
| |
| @cindex jump optimization |
| @cindex unreachable code |
| @cindex dead code |
| @item |
| Jump optimization. This pass simplifies jumps to the following |
| instruction, jumps across jumps, and jumps to jumps. It deletes |
| unreferenced labels and unreachable code, except that unreachable code |
| that contains a loop is not recognized as unreachable in this pass. |
| (Such loops are deleted later in the basic block analysis.) It also |
| converts some code originally written with jumps into sequences of |
| instructions that directly set values from the results of comparisons, |
| if the machine has such instructions. |
| |
| Jump optimization is performed two or three times. The first time is |
| immediately following RTL generation. The second time is after CSE, |
| but only if CSE says repeated jump optimization is needed. The |
| last time is right before the final pass. That time, cross-jumping |
| and deletion of no-op move instructions are done together with the |
| optimizations described above. |
| |
| The source file of this pass is @file{jump.c}. |
| |
| The option @samp{-dj} causes a debugging dump of the RTL code after |
| this pass is run for the first time. This dump file's name is made by |
| appending @samp{.jump} to the input file name. |
| |
| @cindex register use analysis |
| @item |
| Register scan. This pass finds the first and last use of each |
| register, as a guide for common subexpression elimination. Its source |
| is in @file{regclass.c}. |
| |
| @cindex jump threading |
| @item |
| Jump threading. This pass detects a condition jump that branches to an |
| identical or inverse test. Such jumps can be @samp{threaded} through |
| the second conditional test. The source code for this pass is in |
| @file{jump.c}. This optimization is only performed if |
| @samp{-fthread-jumps} is enabled. |
| |
| @cindex common subexpression elimination |
| @cindex constant propagation |
| @item |
| Common subexpression elimination. This pass also does constant |
| propagation. Its source file is @file{cse.c}. If constant |
| propagation causes conditional jumps to become unconditional or to |
| become no-ops, jump optimization is run again when CSE is finished. |
| |
| The option @samp{-ds} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.cse} to |
| the input file name. |
| |
| @cindex loop optimization |
| @cindex code motion |
| @cindex strength-reduction |
| @item |
| Loop optimization. This pass moves constant expressions out of loops, |
| and optionally does strength-reduction and loop unrolling as well. |
| Its source files are @file{loop.c} and @file{unroll.c}, plus the header |
| @file{loop.h} used for communication between them. Loop unrolling uses |
| some functions in @file{integrate.c} and the header @file{integrate.h}. |
| |
| The option @samp{-dL} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.loop} to |
| the input file name. |
| |
| @item |
| If @samp{-frerun-cse-after-loop} was enabled, a second common |
| subexpression elimination pass is performed after the loop optimization |
| pass. Jump threading is also done again at this time if it was specified. |
| |
| The option @samp{-dt} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.cse2} to |
| the input file name. |
| |
| @cindex register allocation, stupid |
| @cindex stupid register allocation |
| @item |
| Stupid register allocation is performed at this point in a |
| nonoptimizing compilation. It does a little data flow analysis as |
| well. When stupid register allocation is in use, the next pass |
| executed is the reloading pass; the others in between are skipped. |
| The source file is @file{stupid.c}. |
| |
| @cindex data flow analysis |
| @cindex analysis, data flow |
| @cindex basic blocks |
| @item |
| Data flow analysis (@file{flow.c}). This pass divides the program |
| into basic blocks (and in the process deletes unreachable loops); then |
| it computes which pseudo-registers are live at each point in the |
| program, and makes the first instruction that uses a value point at |
| the instruction that computed the value. |
| |
| @cindex autoincrement/decrement analysis |
| This pass also deletes computations whose results are never used, and |
| combines memory references with add or subtract instructions to make |
| autoincrement or autodecrement addressing. |
| |
| The option @samp{-df} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.flow} to |
| the input file name. If stupid register allocation is in use, this |
| dump file reflects the full results of such allocation. |
| |
| @cindex instruction combination |
| @item |
| Instruction combination (@file{combine.c}). This pass attempts to |
| combine groups of two or three instructions that are related by data |
| flow into single instructions. It combines the RTL expressions for |
| the instructions by substitution, simplifies the result using algebra, |
| and then attempts to match the result against the machine description. |
| |
| The option @samp{-dc} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.combine} |
| to the input file name. |
| |
| @cindex instruction scheduling |
| @cindex scheduling, instruction |
| @item |
| Instruction scheduling (@file{sched.c}). This pass looks for |
| instructions whose output will not be available by the time that it is |
| used in subsequent instructions. (Memory loads and floating point |
| instructions often have this behavior on RISC machines). It re-orders |
| instructions within a basic block to try to separate the definition and |
| use of items that otherwise would cause pipeline stalls. |
| |
| Instruction scheduling is performed twice. The first time is immediately |
| after instruction combination and the second is immediately after reload. |
| |
| The option @samp{-dS} causes a debugging dump of the RTL code after this |
| pass is run for the first time. The dump file's name is made by |
| appending @samp{.sched} to the input file name. |
| |
| @cindex register class preference pass |
| @item |
| Register class preferencing. The RTL code is scanned to find out |
| which register class is best for each pseudo register. The source |
| file is @file{regclass.c}. |
| |
| @cindex register allocation |
| @cindex local register allocation |
| @item |
| Local register allocation (@file{local-alloc.c}). This pass allocates |
| hard registers to pseudo registers that are used only within one basic |
| block. Because the basic block is linear, it can use fast and |
| powerful techniques to do a very good job. |
| |
| The option @samp{-dl} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.lreg} to |
| the input file name. |
| |
| @cindex global register allocation |
| @item |
| Global register allocation (@file{global.c}). This pass |
| allocates hard registers for the remaining pseudo registers (those |
| whose life spans are not contained in one basic block). |
| |
| @cindex reloading |
| @item |
| Reloading. This pass renumbers pseudo registers with the hardware |
| registers numbers they were allocated. Pseudo registers that did not |
| get hard registers are replaced with stack slots. Then it finds |
| instructions that are invalid because a value has failed to end up in |
| a register, or has ended up in a register of the wrong kind. It fixes |
| up these instructions by reloading the problematical values |
| temporarily into registers. Additional instructions are generated to |
| do the copying. |
| |
| The reload pass also optionally eliminates the frame pointer and inserts |
| instructions to save and restore call-clobbered registers around calls. |
| |
| Source files are @file{reload.c} and @file{reload1.c}, plus the header |
| @file{reload.h} used for communication between them. |
| |
| The option @samp{-dg} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.greg} to |
| the input file name. |
| |
| @cindex instruction scheduling |
| @cindex scheduling, instruction |
| @item |
| Instruction scheduling is repeated here to try to avoid pipeline stalls |
| due to memory loads generated for spilled pseudo registers. |
| |
| The option @samp{-dR} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.sched2} |
| to the input file name. |
| |
| @cindex cross-jumping |
| @cindex no-op move instructions |
| @item |
| Jump optimization is repeated, this time including cross-jumping |
| and deletion of no-op move instructions. |
| |
| The option @samp{-dJ} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.jump2} |
| to the input file name. |
| |
| @cindex delayed branch scheduling |
| @cindex scheduling, delayed branch |
| @item |
| Delayed branch scheduling. This optional pass attempts to find |
| instructions that can go into the delay slots of other instructions, |
| usually jumps and calls. The source file name is @file{reorg.c}. |
| |
| The option @samp{-dd} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.dbr} |
| to the input file name. |
| |
| @cindex register-to-stack conversion |
| @item |
| Conversion from usage of some hard registers to usage of a register |
| stack may be done at this point. Currently, this is supported only |
| for the floating-point registers of the Intel 80387 coprocessor. The |
| source file name is @file{reg-stack.c}. |
| |
| The options @samp{-dk} causes a debugging dump of the RTL code after |
| this pass. This dump file's name is made by appending @samp{.stack} |
| to the input file name. |
| |
| @cindex final pass |
| @cindex peephole optimization |
| @item |
| Final. This pass outputs the assembler code for the function. It is |
| also responsible for identifying spurious test and compare |
| instructions. Machine-specific peephole optimizations are performed |
| at the same time. The function entry and exit sequences are generated |
| directly as assembler code in this pass; they never exist as RTL. |
| |
| The source files are @file{final.c} plus @file{insn-output.c}; the |
| latter is generated automatically from the machine description by the |
| tool @file{genoutput}. The header file @file{conditions.h} is used |
| for communication between these files. |
| |
| @cindex debugging information generation |
| @item |
| Debugging information output. This is run after final because it must |
| output the stack slot offsets for pseudo registers that did not get |
| hard registers. Source files are @file{dbxout.c} for DBX symbol table |
| format, @file{sdbout.c} for SDB symbol table format, and |
| @file{dwarfout.c} for DWARF symbol table format. |
| @end itemize |
| |
| Some additional files are used by all or many passes: |
| |
| @itemize @bullet |
| @item |
| Every pass uses @file{machmode.def} and @file{machmode.h} which define |
| the machine modes. |
| |
| @item |
| Several passes use @file{real.h}, which defines the default |
| representation of floating point constants and how to operate on them. |
| |
| @item |
| All the passes that work with RTL use the header files @file{rtl.h} |
| and @file{rtl.def}, and subroutines in file @file{rtl.c}. The tools |
| @code{gen*} also use these files to read and work with the machine |
| description RTL. |
| |
| @findex genconfig |
| @item |
| Several passes refer to the header file @file{insn-config.h} which |
| contains a few parameters (C macro definitions) generated |
| automatically from the machine description RTL by the tool |
| @code{genconfig}. |
| |
| @cindex instruction recognizer |
| @item |
| Several passes use the instruction recognizer, which consists of |
| @file{recog.c} and @file{recog.h}, plus the files @file{insn-recog.c} |
| and @file{insn-extract.c} that are generated automatically from the |
| machine description by the tools @file{genrecog} and |
| @file{genextract}.@refill |
| |
| @item |
| Several passes use the header files @file{regs.h} which defines the |
| information recorded about pseudo register usage, and @file{basic-block.h} |
| which defines the information recorded about basic blocks. |
| |
| @item |
| @file{hard-reg-set.h} defines the type @code{HARD_REG_SET}, a bit-vector |
| with a bit for each hard register, and some macros to manipulate it. |
| This type is just @code{int} if the machine has few enough hard registers; |
| otherwise it is an array of @code{int} and some of the macros expand |
| into loops. |
| |
| @item |
| Several passes use instruction attributes. A definition of the |
| attributes defined for a particular machine is in file |
| @file{insn-attr.h}, which is generated from the machine description by |
| the program @file{genattr}. The file @file{insn-attrtab.c} contains |
| subroutines to obtain the attribute values for insns. It is generated |
| from the machine description by the program @file{genattrtab}.@refill |
| @end itemize |
| @end ifset |
| |
| @ifset INTERNALS |
| @include rtl.texi |
| @include md.texi |
| @include tm.texi |
| @end ifset |
| |
| @ifset INTERNALS |
| @node Config |
| @chapter The Configuration File |
| @cindex configuration file |
| @cindex @file{xm-@var{machine}.h} |
| |
| The configuration file @file{xm-@var{machine}.h} contains macro |
| definitions that describe the machine and system on which the compiler |
| is running, unlike the definitions in @file{@var{machine}.h}, which |
| describe the machine for which the compiler is producing output. Most |
| of the values in @file{xm-@var{machine}.h} are actually the same on all |
| machines that GNU CC runs on, so large parts of all configuration files |
| are identical. But there are some macros that vary: |
| |
| @table @code |
| @findex USG |
| @item USG |
| Define this macro if the host system is System V. |
| |
| @findex VMS |
| @item VMS |
| Define this macro if the host system is VMS. |
| |
| @findex FATAL_EXIT_CODE |
| @item FATAL_EXIT_CODE |
| A C expression for the status code to be returned when the compiler |
| exits after serious errors. |
| |
| @findex SUCCESS_EXIT_CODE |
| @item SUCCESS_EXIT_CODE |
| A C expression for the status code to be returned when the compiler |
| exits without serious errors. |
| |
| @findex HOST_WORDS_BIG_ENDIAN |
| @item HOST_WORDS_BIG_ENDIAN |
| Defined if the host machine stores words of multi-word values in |
| big-endian order. (GNU CC does not depend on the host byte ordering |
| within a word.) |
| |
| @findex HOST_FLOAT_WORDS_BIG_ENDIAN |
| @item HOST_FLOAT_WORDS_BIG_ENDIAN |
| Define this macro to be 1 if the host machine stores @code{DFmode}, |
| @code{XFmode} or @code{TFmode} floating point numbers in memory with the |
| word containing the sign bit at the lowest address; otherwise, define it |
| to be zero. |
| |
| This macro need not be defined if the ordering is the same as for |
| multi-word integers. |
| |
| @findex HOST_FLOAT_FORMAT |
| @item HOST_FLOAT_FORMAT |
| A numeric code distinguishing the floating point format for the host |
| machine. See @code{TARGET_FLOAT_FORMAT} in @ref{Storage Layout} for the |
| alternatives and default. |
| |
| @findex HOST_BITS_PER_CHAR |
| @item HOST_BITS_PER_CHAR |
| A C expression for the number of bits in @code{char} on the host |
| machine. |
| |
| @findex HOST_BITS_PER_SHORT |
| @item HOST_BITS_PER_SHORT |
| A C expression for the number of bits in @code{short} on the host |
| machine. |
| |
| @findex HOST_BITS_PER_INT |
| @item HOST_BITS_PER_INT |
| A C expression for the number of bits in @code{int} on the host |
| machine. |
| |
| @findex HOST_BITS_PER_LONG |
| @item HOST_BITS_PER_LONG |
| A C expression for the number of bits in @code{long} on the host |
| machine. |
| |
| @findex ONLY_INT_FIELDS |
| @item ONLY_INT_FIELDS |
| Define this macro to indicate that the host compiler only supports |
| @code{int} bit fields, rather than other integral types, including |
| @code{enum}, as do most C compilers. |
| |
| @findex OBSTACK_CHUNK_SIZE |
| @item OBSTACK_CHUNK_SIZE |
| A C expression for the size of ordinary obstack chunks. |
| If you don't define this, a usually-reasonable default is used. |
| |
| @findex OBSTACK_CHUNK_ALLOC |
| @item OBSTACK_CHUNK_ALLOC |
| The function used to allocate obstack chunks. |
| If you don't define this, @code{xmalloc} is used. |
| |
| @findex OBSTACK_CHUNK_FREE |
| @item OBSTACK_CHUNK_FREE |
| The function used to free obstack chunks. |
| If you don't define this, @code{free} is used. |
| |
| @findex USE_C_ALLOCA |
| @item USE_C_ALLOCA |
| Define this macro to indicate that the compiler is running with the |
| @code{alloca} implemented in C. This version of @code{alloca} can be |
| found in the file @file{alloca.c}; to use it, you must also alter the |
| @file{Makefile} variable @code{ALLOCA}. (This is done automatically |
| for the systems on which we know it is needed.) |
| |
| If you do define this macro, you should probably do it as follows: |
| |
| @example |
| #ifndef __GNUC__ |
| #define USE_C_ALLOCA |
| #else |
| #define alloca __builtin_alloca |
| #endif |
| @end example |
| |
| @noindent |
| so that when the compiler is compiled with GNU CC it uses the more |
| efficient built-in @code{alloca} function. |
| |
| @item FUNCTION_CONVERSION_BUG |
| @findex FUNCTION_CONVERSION_BUG |
| Define this macro to indicate that the host compiler does not properly |
| handle converting a function value to a pointer-to-function when it is |
| used in an expression. |
| |
| @findex HAVE_VPRINTF |
| @findex vprintf |
| @item HAVE_VPRINTF |
| Define this if the library function @code{vprintf} is available on your |
| system. |
| |
| @findex MULTIBYTE_CHARS |
| @item MULTIBYTE_CHARS |
| Define this macro to enable support for multibyte characters in the |
| input to GNU CC. This requires that the host system support the ANSI C |
| library functions for converting multibyte characters to wide |
| characters. |
| |
| @findex HAVE_PUTENV |
| @findex putenv |
| @item HAVE_PUTENV |
| Define this if the library function @code{putenv} is available on your |
| system. |
| |
| @findex POSIX |
| @item POSIX |
| Define this if your system is POSIX.1 compliant. |
| |
| @findex HAVE_POPEN |
| @findex popen |
| @item HAVE_POPEN |
| Define this if the library function @code{popen} is available on your |
| system. |
| |
| @findex NO_SYS_SIGLIST |
| @item NO_SYS_SIGLIST |
| Define this if your system @emph{does not} provide the variable |
| @code{sys_siglist}. |
| |
| @findex USE_PROTOTYPES |
| @item USE_PROTOTYPES |
| Define this to be 1 if you know that the host compiler supports |
| prototypes, even if it doesn't define __STDC__, or define |
| it to be 0 if you do not want any prototypes used in compiling |
| GNU CC. If @samp{USE_PROTOTYPES} is not defined, it will be |
| determined automatically whether your compiler supports |
| prototypes by checking if @samp{__STDC__} is defined. |
| |
| @findex NO_MD_PROTOTYPES |
| @item NO_MD_PROTOTYPES |
| Define this if you wish suppression of prototypes generated from |
| the machine description file, but to use other prototypes within |
| GNU CC. If @samp{USE_PROTOTYPES} is defined to be 0, or the |
| host compiler does not support prototypes, this macro has no |
| effect. |
| |
| @findex MD_CALL_PROTOTYPES |
| @item MD_CALL_PROTOTYPES |
| Define this if you wish to generate prototypes for the |
| @code{gen_call} or @code{gen_call_value} functions generated from |
| the machine description file. If @samp{USE_PROTOTYPES} is |
| defined to be 0, or the host compiler does not support |
| prototypes, or @samp{NO_MD_PROTOTYPES} is defined, this macro has |
| no effect. As soon as all of the machine descriptions are |
| modified to have the appropriate number of arguments, this macro |
| will be removed. |
| |
| @vindex sys_siglist |
| Some systems do provide this variable, but with a different name such |
| as @code{_sys_siglist}. On these systems, you can define |
| @code{sys_siglist} as a macro which expands into the name actually |
| provided. |
| |
| If you define @code{sys_siglist}, you should also define |
| @code{SYS_SIGLIST_DECLARED}. |
| |
| @findex NO_STAB_H |
| @item NO_STAB_H |
| Define this if your system does not have the include file |
| @file{stab.h}. If @samp{USG} is defined, @samp{NO_STAB_H} is |
| assumed. |
| |
| @findex PATH_SEPARATOR |
| @item PATH_SEPARATOR |
| Define this macro to be a C character constant representing the |
| character used to separate components in paths. The default value is. |
| the colon character |
| |
| @findex DIR_SEPARATOR |
| @item DIR_SEPARATOR |
| If your system uses some character other than slash to separate |
| directory names within a file specification, define this macro to be a C |
| character constant specifying that character. When GNU CC displays file |
| names, the character you specify will be used. GNU CC will test for |
| both slash and the character you specify when parsing filenames. |
| |
| @findex OBJECT_SUFFIX |
| @item OBJECT_SUFFIX |
| Define this macro to be a C string representing the suffix for object |
| files on your machine. If you do not define this macro, GNU CC will use |
| @samp{.o} as the suffix for object files. |
| |
| @findex EXECUTABLE_SUFFIX |
| @item EXECUTABLE_SUFFIX |
| Define this macro to be a C string representing the suffix for executable |
| files on your machine. If you do not define this macro, GNU CC will use |
| the null string as the suffix for object files. |
| |
| @findex COLLECT_EXPORT_LIST |
| @item COLLECT_EXPORT_LIST |
| If defined, @code{collect2} will scan the individual object files |
| specified on its command line and create an export list for the linker. |
| Define this macro for systems like AIX, where the linker discards |
| object files that are not referenced from @code{main} and uses export |
| lists. |
| @end table |
| |
| @findex bzero |
| @findex bcmp |
| In addition, configuration files for system V define @code{bcopy}, |
| @code{bzero} and @code{bcmp} as aliases. Some files define @code{alloca} |
| as a macro when compiled with GNU CC, in order to take advantage of the |
| benefit of GNU CC's built-in @code{alloca}. |
| |
| @node Fragments |
| @chapter Makefile Fragments |
| @cindex makefile fragment |
| |
| When you configure GNU CC using the @file{configure} script |
| (@pxref{Installation}), it will construct the file @file{Makefile} from |
| the template file @file{Makefile.in}. When it does this, it will |
| incorporate makefile fragment files from the @file{config} directory, |
| named @file{t-@var{target}} and @file{x-@var{host}}. If these files do |
| not exist, it means nothing needs to be added for a given target or |
| host. |
| |
| @menu |
| * Target Fragment:: Writing the @file{t-@var{target}} file. |
| * Host Fragment:: Writing the @file{x-@var{host}} file. |
| @end menu |
| |
| @node Target Fragment |
| @section The Target Makefile Fragment |
| @cindex target makefile fragment |
| @cindex @file{t-@var{target}} |
| |
| The target makefile fragment, @file{t-@var{target}}, defines special |
| target dependent variables and targets used in the @file{Makefile}: |
| |
| @table @code |
| @findex LIBGCC1 |
| @item LIBGCC1 |
| The rule to use to build @file{libgcc1.a}. |
| If your target does not need to use the functions in @file{libgcc1.a}, |
| set this to empty. |
| @xref{Interface}. |
| |
| @findex CROSS_LIBGCC1 |
| @item CROSS_LIBGCC1 |
| The rule to use to build @file{libgcc1.a} when building a cross |
| compiler. If your target does not need to use the functions in |
| @file{libgcc1.a}, set this to empty. @xref{Cross Runtime}. |
| |
| @findex LIBGCC2_CFLAGS |
| @item LIBGCC2_CFLAGS |
| Compiler flags to use when compiling @file{libgcc2.c}. |
| |
| @findex LIB2FUNCS_EXTRA |
| @item LIB2FUNCS_EXTRA |
| A list of source file names to be compiled or assembled and inserted |
| into @file{libgcc.a}. |
| |
| @findex CRTSTUFF_T_CFLAGS |
| @item CRTSTUFF_T_CFLAGS |
| Special flags used when compiling @file{crtstuff.c}. |
| @xref{Initialization}. |
| |
| @findex CRTSTUFF_T_CFLAGS_S |
| @item CRTSTUFF_T_CFLAGS_S |
| Special flags used when compiling @file{crtstuff.c} for shared |
| linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o} |
| in @code{EXTRA-PARTS}. |
| @xref{Initialization}. |
| |
| @findex MULTILIB_OPTIONS |
| @item MULTILIB_OPTIONS |
| For some targets, invoking GNU CC in different ways produces objects |
| that can not be linked together. For example, for some targets GNU CC |
| produces both big and little endian code. For these targets, you must |
| arrange for multiple versions of @file{libgcc.a} to be compiled, one for |
| each set of incompatible options. When GNU CC invokes the linker, it |
| arranges to link in the right version of @file{libgcc.a}, based on |
| the command line options used. |
| |
| The @code{MULTILIB_OPTIONS} macro lists the set of options for which |
| special versions of @file{libgcc.a} must be built. Write options that |
| are mutually incompatible side by side, separated by a slash. Write |
| options that may be used together separated by a space. The build |
| procedure will build all combinations of compatible options. |
| |
| For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020 |
| msoft-float}, @file{Makefile} will build special versions of |
| @file{libgcc.a} using the sets of options @samp{-m68000}, @samp{-m68020}, |
| @samp{-msoft-float}, @samp{-m68000 -msoft-float}, and @samp{-m68020 |
| -msoft-float}. |
| |
| @findex MULTILIB_DIRNAMES |
| @item MULTILIB_DIRNAMES |
| If @code{MULTILIB_OPTIONS} is used, this variable specifies the |
| directory names that should be used to hold the various libraries. |
| Write one element in @code{MULTILIB_DIRNAMES} for each element in |
| @code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the |
| default value will be @code{MULTILIB_OPTIONS}, with all slashes treated |
| as spaces. |
| |
| For example, if @code{MULTILIB_OPTIONS} is specified as @samp{m68000/m68020 |
| msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is |
| @samp{m68000 m68020 msoft-float}. You may specify a different value if |
| you desire a different set of directory names. |
| |
| @findex MULTILIB_MATCHES |
| @item MULTILIB_MATCHES |
| Sometimes the same option may be written in two different ways. If an |
| option is listed in @code{MULTILIB_OPTIONS}, GNU CC needs to know about |
| any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of |
| items of the form @samp{option=option} to describe all relevant |
| synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}. |
| |
| @findex MULTILIB_EXCEPTIONS |
| @item MULTILIB_EXCEPTIONS |
| Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being |
| specified, there are combinations that should not be built. In that |
| case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions |
| in shell case syntax that should not be built. |
| |
| For example, in the PowerPC embedded ABI support, it was not desirable |
| to build libraries that compiled with the @samp{-mcall-aixdesc} option |
| and either of the @samp{-mcall-aixdesc} or @samp{-mlittle} options at |
| the same time, and therefore @code{MULTILIB_EXCEPTIONS} is set to |
| @code{*mrelocatable/*mcall-aixdesc* *mlittle/*mcall-aixdesc*}. |
| |
| @findex MULTILIB_EXTRA_OPTS |
| @item MULTILIB_EXTRA_OPTS |
| Sometimes it is desirable that when building multiple versions of |
| @file{libgcc.a} certain options should always be passed on to the |
| compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list |
| of options to be used for all builds. |
| @end table |
| |
| @node Host Fragment |
| @section The Host Makefile Fragment |
| @cindex host makefile fragment |
| @cindex @file{x-@var{host}} |
| |
| The host makefile fragment, @file{x-@var{host}}, defines special host |
| dependent variables and targets used in the @file{Makefile}: |
| |
| @table @code |
| @findex CC |
| @item CC |
| The compiler to use when building the first stage. |
| |
| @findex CLIB |
| @item CLIB |
| Additional host libraries to link with. |
| |
| @findex OLDCC |
| @item OLDCC |
| The compiler to use when building @file{libgcc1.a} for a native |
| compilation. |
| |
| @findex OLDAR |
| @item OLDAR |
| The version of @code{ar} to use when building @file{libgcc1.a} for a native |
| compilation. |
| |
| @findex INSTALL |
| @item INSTALL |
| The install program to use. |
| @end table |
| |
| @node Funding |
| @unnumbered Funding Free Software |
| |
| If you want to have more free software a few years from now, it makes |
| sense for you to help encourage people to contribute funds for its |
| development. The most effective approach known is to encourage |
| commercial redistributors to donate. |
| |
| Users of free software systems can boost the pace of development by |
| encouraging for-a-fee distributors to donate part of their selling price |
| to free software developers---the Free Software Foundation, and others. |
| |
| The way to convince distributors to do this is to demand it and expect |
| it from them. So when you compare distributors, judge them partly by |
| how much they give to free software development. Show distributors |
| they must compete to be the one who gives the most. |
| |
| To make this approach work, you must insist on numbers that you can |
| compare, such as, ``We will donate ten dollars to the Frobnitz project |
| for each disk sold.'' Don't be satisfied with a vague promise, such as |
| ``A portion of the profits are donated,'' since it doesn't give a basis |
| for comparison. |
| |
| Even a precise fraction ``of the profits from this disk'' is not very |
| meaningful, since creative accounting and unrelated business decisions |
| can greatly alter what fraction of the sales price counts as profit. |
| If the price you pay is $50, ten percent of the profit is probably |
| less than a dollar; it might be a few cents, or nothing at all. |
| |
| Some redistributors do development work themselves. This is useful too; |
| but to keep everyone honest, you need to inquire how much they do, and |
| what kind. Some kinds of development make much more long-term |
| difference than others. For example, maintaining a separate version of |
| a program contributes very little; maintaining the standard version of a |
| program for the whole community contributes much. Easy new ports |
| contribute little, since someone else would surely do them; difficult |
| ports such as adding a new CPU to the GNU C compiler contribute more; |
| major new features or packages contribute the most. |
| |
| By establishing the idea that supporting further development is ``the |
| proper thing to do'' when distributing free software for a fee, we can |
| assure a steady flow of resources into making more free software. |
| |
| @display |
| Copyright (C) 1994 Free Software Foundation, Inc. |
| Verbatim copying and redistribution of this section is permitted |
| without royalty; alteration is not permitted. |
| @end display |
| |
| @node Look and Feel |
| @unnumbered Protect Your Freedom---Fight ``Look And Feel'' |
| @c the above chapter heading overflows onto the next line. --mew 1/26/93 |
| |
| @quotation |
| @i{This section is a political message from the League for Programming |
| Freedom to the users of GNU CC. We have included it here because the |
| issue of interface copyright is important to the GNU project.} |
| @end quotation |
| |
| Apple, Lotus, and now CDC have tried to create a new form of legal |
| monopoly: a copyright on a user interface. |
| |
| An interface is a kind of language---a set of conventions for |
| communication between two entities, human or machine. Until a few years |
| ago, the law seemed clear: interfaces were outside the domain of |
| copyright, so programmers could program freely and implement whatever |
| interface the users demanded. Imitating de-facto standard interfaces, |
| sometimes with improvements, was standard practice in the computer |
| field. These improvements, if accepted by the users, caught on and |
| became the norm; in this way, much progress took place. |
| |
| Computer users, and most software developers, were happy with this state |
| of affairs. However, large companies such as Apple and Lotus would |
| prefer a different system---one in which they can own interfaces and |
| thereby rid themselves of all serious competitors. They hope that |
| interface copyright will give them, in effect, monopolies on major |
| classes of software. |
| |
| Other large companies such as IBM and Digital also favor interface |
| monopolies, for the same reason: if languages become property, they |
| expect to own many de-facto standard languages. But Apple and Lotus are |
| the ones who have actually sued. Apple's lawsuit was defeated, for |
| reasons only partly related to the general issue of interface copyright. |
| |
| Lotus won lawsuits against two small companies, which were thus put out |
| of business. Then Lotus sued Borland; Lotus won in the trial court (no |
| surprise, since it was the same court that had ruled for Lotus twice |
| before), but the court of appeals ruled in favor of Borland, which was |
| assisted by a friend-of-the-court brief from the League for Programming |
| Freedom. |
| |
| Lotus appealed the case to the Supreme Court, which heard the case but |
| was unable to reach a decision. This failure means that the appeals |
| court decision stands, in one portion of the United States, and may |
| influence the other appeals courts, but it does not set a nationwide |
| precedent. The battle is not over, and it is not limited to the United |
| States. |
| |
| The battle is extending into other areas of software as well. In 1995 a |
| company that produced a simulator for a CDC computer was shut down by a |
| copyright lawsuit, in which CDC charged that the simulator infringed the |
| copyright on the manuals for the computer. |
| |
| If the monopolists get their way, they will hobble the software field: |
| |
| @itemize @bullet |
| @item |
| Gratuitous incompatibilities will burden users. Imagine if each car |
| manufacturer had to design a different way to start, stop, and steer a |
| car. |
| |
| @item |
| Users will be ``locked in'' to whichever interface they learn; then they |
| will be prisoners of one supplier, who will charge a monopolistic price. |
| |
| @item |
| Large companies have an unfair advantage wherever lawsuits become |
| commonplace. Since they can afford to sue, they can intimidate smaller |
| developers with threats even when they don't really have a case. |
| |
| @item |
| Interface improvements will come slower, since incremental evolution |
| through creative partial imitation will no longer occur. |
| @end itemize |
| |
| If interface monopolies are accepted, other large companies are waiting |
| to grab theirs: |
| |
| @itemize @bullet |
| @item |
| Adobe is expected to claim a monopoly on the interfaces of various |
| popular application programs, if Lotus ultimately wins the case against |
| Borland. |
| |
| @item |
| Open Computing magazine reported a Microsoft vice president as threatening |
| to sue people who imitate the interface of Windows. |
| @end itemize |
| |
| Users invest a great deal of time and money in learning to use computer |
| interfaces. Far more, in fact, than software developers invest in |
| developing @emph{and even implementing} the interfaces. Whoever can own |
| an interface, has made its users into captives, and misappropriated |
| their investment. |
| |
| To protect our freedom from monopolies like these, a group of |
| programmers and users have formed a grass-roots political organization, |
| the League for Programming Freedom. |
| |
| The purpose of the League is to oppose monopolistic practices such as |
| interface copyright and software patents. The League calls for a return |
| to the legal policies of the recent past, in which programmers could |
| program freely. The League is not concerned with free software as an |
| issue, and is not affiliated with the Free Software Foundation. |
| |
| The League's activities include publicizing the issues, as is being done |
| here, and filing friend-of-the-court briefs on behalf of defendants sued |
| by monopolists. |
| |
| The League's membership rolls include Donald Knuth, the foremost |
| authority on algorithms, John McCarthy, inventor of Lisp, Marvin Minsky, |
| founder of the MIT Artificial Intelligence lab, Guy L. Steele, Jr., |
| author of well-known books on Lisp and C, as well as Richard Stallman, |
| the developer of GNU CC. Please join and add your name to the list. |
| Membership dues in the League are $42 per year for programmers, managers |
| and professionals; $10.50 for students; $21 for others. |
| |
| Activist members are especially important, but members who have no time |
| to give are also important. Surveys at major ACM conferences have |
| indicated a vast majority of attendees agree with the League on both |
| issues (interface copyrights and software patents). If just ten percent |
| of the programmers who agree with the League join the League, we will |
| probably triumph. |
| |
| To join, or for more information, send electronic mail to |
| the address @code{lpf@@uunet.uu.net} or write to: |
| |
| @display |
| League for Programming Freedom |
| 1 Kendall Square #143 |
| P.O. Box 9171 |
| Cambridge, MA 02139 |
| @end display |
| |
| In addition to joining the League, here are some suggestions from the |
| League for other things you can do to protect your freedom to write |
| programs: |
| |
| @itemize @bullet |
| @item |
| Tell your friends and colleagues about this issue and how it threatens |
| to ruin the computer industry. |
| |
| @item |
| Mention that you are a League member in your @file{.signature}, and |
| mention the League's email address for inquiries. |
| |
| @item |
| Ask the companies you consider working for or working with to make |
| statements against software monopolies, and give preference to those |
| that do. |
| |
| @item |
| When employers ask you to sign contracts giving them copyright on your |
| work, insist on a clause saying they will not claim the copyright covers |
| imitating the interface. |
| |
| @item |
| When employers ask you to sign contracts giving them patent rights, |
| insist on clauses saying they can use these rights only defensively. |
| Don't rely on ``company policy,'' since that can change at any time; |
| don't rely on an individual executive's private word, since that person |
| may be replaced. Get a commitment just as binding as the commitment |
| they get from you. |
| |
| @item |
| Write to Congress to explain the importance of these issues. |
| |
| @display |
| House Subcommittee on Intellectual Property |
| 2137 Rayburn Bldg |
| Washington, DC 20515 |
| |
| Senate Subcommittee on Patents, Trademarks and Copyrights |
| United States Senate |
| Washington, DC 20510 |
| @end display |
| |
| (These committees have received lots of mail already; let's give them |
| even more.) |
| @end itemize |
| |
| Democracy means nothing if you don't use it. Stand up and be counted! |
| |
| |
| @node Copying |
| @unnumbered GNU GENERAL PUBLIC LICENSE |
| @center Version 2, June 1991 |
| |
| @display |
| Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. |
| 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA |
| |
| Everyone is permitted to copy and distribute verbatim copies |
| of this license document, but changing it is not allowed. |
| @end display |
| |
| @unnumberedsec Preamble |
| |
| The licenses for most software are designed to take away your |
| freedom to share and change it. By contrast, the GNU General Public |
| License is intended to guarantee your freedom to share and change free |
| software---to make sure the software is free for all its users. This |
| General Public License applies to most of the Free Software |
| Foundation's software and to any other program whose authors commit to |
| using it. (Some other Free Software Foundation software is covered by |
| the GNU Library General Public License instead.) You can apply it to |
| your programs, too. |
| |
| When we speak of free software, we are referring to freedom, not |
| price. Our General Public Licenses are designed to make sure that you |
| have the freedom to distribute copies of free software (and charge for |
| this service if you wish), that you receive source code or can get it |
| if you want it, that you can change the software or use pieces of it |
| in new free programs; and that you know you can do these things. |
| |
| To protect your rights, we need to make restrictions that forbid |
| anyone to deny you these rights or to ask you to surrender the rights. |
| These restrictions translate to certain responsibilities for you if you |
| distribute copies of the software, or if you modify it. |
| |
| For example, if you distribute copies of such a program, whether |
| gratis or for a fee, you must give the recipients all the rights
|