gnu1987/gnu1988/gcc-1.21/internals-1

Info file internals, produced by Makeinfo, -*- Text -*-
from input file internals.texinfo.



This file documents the internals of the GNU compiler.

Copyright (C) 1988 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.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``GNU CC General Public License'' is 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 section entitled ``GNU CC General Public License'' and
this permission notice may be included in translations approved by the
Free Software Foundation instead of in the original English.






File: internals,  Node: Top,  Next: Copying,  Up: (DIR)

Introduction
************

This manual documents how to run, install and port the GNU C compiler, as
well as its new features and incompatibilities, and how to report bugs.


* Menu:

* Copying::         GNU CC General Public License says
                     how you can copy and share GNU CC.
* Contributors::    People who have contributed to GNU CC.
* Options::         Command options supported by `gcc'.
* Installation::    How to configure, compile and install GNU CC.
* Incompatibilities:: Incompatibilities of GNU CC.
* Extensions::      GNU extensions to the C language.
* Bugs::            How to report bugs (if you want to get them fixed).
* 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.
* Machine Macros::  How to write the machine description C macros.



File: internals,  Node: Copying,  Next: Contributors,  Prev: Top,  Up: Top

GNU CC GENERAL PUBLIC LICENSE
*****************************

                           (Clarified 11 Feb 1988)

  The license agreements of most software companies keep you at the mercy
of those companies.  By contrast, our general public license is intended to
give everyone the right to share GNU CC.  To make sure that you get the
rights we want you to have, we need to make restrictions that forbid anyone
to deny you these rights or to ask you to surrender the rights.  Hence this
license agreement.

  Specifically, we want to make sure that you have the right to give away
copies of GNU CC, that you receive source code or else can get it if you
want it, that you can change GNU CC or use pieces of it in new free
programs, and that you know you can do these things.

  To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute copies
of GNU CC, you must give the recipients all the rights that you have.  You
must make sure that they, too, receive or can get the source code.  And you
must tell them their rights.

  Also, for our own protection, we must make certain that everyone finds
out that there is no warranty for GNU CC.  If GNU CC is modified by someone
else and passed on, we want its recipients to know that what they have is
not what we distributed, so that any problems introduced by others will not
reflect on our reputation.

  Therefore we (Richard Stallman and the Free Software Foundation, Inc.)
make the following terms which say what you must do to be allowed to
distribute or change GNU CC.

COPYING POLICIES
================

  1. You may copy and distribute verbatim copies of GNU CC source code as you
     receive it, in any medium, provided that you conspicuously and
     appropriately publish on each copy a valid copyright notice
     ``Copyright (C) 1988 Free Software Foundation, Inc.'' (or with
     whatever year is appropriate); keep intact the notices on all files
     that refer to this License Agreement and to the absence of any
     warranty; and give any other recipients of the GNU CC program a copy
     of this License Agreement along with the program.  You may charge a
     distribution fee for the physical act of transferring a copy.

  2. You may modify your copy or copies of GNU CC or any portion of it, and
     copy and distribute such modifications under the terms of Paragraph 1
     above, provided that you also do the following:

        * cause the modified files to carry prominent notices stating that
          you changed the files and the date of any change; and

        * cause the whole of any work that you distribute or publish, that
          in whole or in part contains or is a derivative of GNU CC or any
          part thereof, to be licensed at no charge to all third parties on
          terms identical to those contained in this License Agreement
          (except that you may choose to grant more extensive warranty
          protection to some or all third parties, at your option).

        * You may charge a distribution fee for the physical act of
          transferring a copy, and you may at your option offer warranty
          protection in exchange for a fee.

     Mere aggregation of another unrelated program with this program (or
     its derivative) on a volume of a storage or distribution medium does
     not bring the other program under the scope of these terms.

  3. You may copy and distribute GNU CC (or a portion or derivative of it,
     under Paragraph 2) in object code or executable form under the terms
     of Paragraphs 1 and 2 above provided that you also do one of the
     following:

        * accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Paragraphs 1 and 2 above; or,

        * accompany it with a written offer, valid for at least three
          years, to give any third party free (except for a nominal
          shipping charge) a complete machine-readable copy of the
          corresponding source code, to be distributed under the terms of
          Paragraphs 1 and 2 above; or,

        * accompany it with the information you received as to where the
          corresponding source code may be obtained.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form alone.)

     For an executable file, complete source code means all the source code
     for all modules it contains; but, as a special exception, it need not
     include source code for modules which are standard libraries that
     accompany the operating system on which the executable file runs.

  4. You may not copy, sublicense, distribute or transfer GNU CC except as
     expressly provided under this License Agreement.  Any attempt
     otherwise to copy, sublicense, distribute or transfer GNU CC is void
     and your rights to use the program under this License agreement shall
     be automatically terminated.  However, parties who have received
     computer software programs from you with this License Agreement will
     not have their licenses terminated so long as such parties remain in
     full compliance.

  5. If you wish to incorporate parts of GNU CC into other free programs
     whose distribution conditions are different, write to the Free
     Software Foundation at 675 Mass Ave, Cambridge, MA 02139.  We have not
     yet worked out a simple rule that can be stated here, but we will
     often permit this.  We will be guided by the two goals of preserving
     the free status of all derivatives of our free software and of
     promoting the sharing and reuse of software.

Your comments and suggestions about our licensing policies and our software
are welcome!  Please contact the Free Software Foundation, Inc., 675 Mass
Ave, Cambridge, MA 02139, or call (617) 876-3296.

NO WARRANTY
===========

  BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO
WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC, RICHARD M.
STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT WARRANTY OF
ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF GNU CC IS WITH YOU. 
SHOULD GNU CC PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.

 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M.  STALLMAN,
THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY WHO MAY MODIFY
AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING
BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
OTHER PROGRAMS) GNU CC, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.


File: internals,  Node: Contributors,  Next: Options,  Prev: Copying,  Up: Top

Contributors to GNU CC
**********************

In addition to Richard Stallman, several people have written parts of GNU CC.

   * The idea of using RTL and some of the optimization ideas came from the
     U. of Arizona Portable Optimizer, written by Jack Davidson and
     Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole
     Optimization'', Software Practice and Experience 14 (9), Sept. 1984,
     857-866.

   * Paul Rubin wrote most of the preprocessor.

   * Leonard Tower wrote parts of the parser, RTL generator, RTL
     definitions, and of the Vax machine description.

   * Ted Lemon wrote parts of the RTL reader and printer.

   * Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed
     the support for the SONY NEWS machine.

   * Charles LaBrec contributed the support for the Integrated Solutions
     68020 system.

   * Michael Tiemann of MCC wrote the description of the National
     Semiconductor 32000 series cpu, with some contributions from Jan Stein
     of the Chalmers Computer Club.  Tiemann also wrote the code for inline
     function integration.

   * Michael Kashtan of SRI adapted GNU CC to the Vomit-Making System.

   * Alex Crain provided changes for the 3b1.

   * Chris Hanson and another person who should remind me of his name
     assisted in making GNU CC work on HP-UX for the 9000 series 300.


File: internals,  Node: Options,  Next: Installation,  Prev: Contributors,  Up: Top

GNU CC Command Options
**********************

The GNU C compiler uses a command syntax much like the Unix C compiler. 
The `gcc' program accepts options and file names as operands.  Multiple
single-letter options may *not* be grouped: `-dr' is very different from
`-d -r'.

When you invoke GNU CC, it normally does preprocessing, compilation,
assembly and linking.  File names which end in `.c' are taken as C source
to be preprocessed and compiled; compiler output files plus any input files
with names ending in `.s' are assembled; then the resulting object files,
plus any other input files, are linked together to produce an executable.

Command options allow you to stop this process at an intermediate stage. 
For example, the `-c' option says not to run the linker.  Then the output
consists of object files output by the assembler.

Other command options are passed on to one stage.  Some options control the
preprocessor and others the compiler itself.  Yet other options control the
assembler and linker; these are not documented here because the GNU
assembler and linker are not yet released.

Here are the options to control the overall compilation process, including
those that say whether to link, whether to assemble, and so on.

`-o FILE'
     Place output in file FILE.  This applies regardless to whatever sort
     of output is being produced, whether it be an executable file, an
     object file, an assembler file or preprocessed C code.

     If `-o' is not specified, the default is to put an excutable file in
     `a.out', the object file `SOURCE.c' in `SOURCE.o', an assembler file
     in `SOURCE.s', and preprocessed C on standard output.

`-c'
     Compile or assemble the source files, but do not link.  Produce object
     files with names made by replacing `.c' or `.s' with `.o' at the end
     of the input file names.  Do nothing at all for object files specified
     as input.

`-S'
     Compile into assembler code but do not assemble.  The assembler output
     file name is made by replacing `.c' with `.s' at the end of the input
     file name.  Do nothing at all for assembler source files or object
     files specified as input.

`-E'
     Run only the C preprocessor.  Preprocess all the C source files
     specified and output the results to standard output.

`-v'
     Compiler driver program prints the commands it executes as it runs the
     preprocessor, compiler proper, assembler and linker.  Some of these
     are directed to print their own version numbers.

`-BPREFIX'
     Compiler driver program tries PREFIX as a prefix for each program it
     tries to run.  These programs are `cpp', `cc1', `as' and `ld'.

     For each subprogram to be run, the compiler driver first tries the
     `-B' prefix, if any.  If that name is not found, or if `-B' was not
     specified, the driver tries two standard prefixes, which are
     `/usr/lib/gcc-' and `/usr/local/lib/gcc-'.  If neither of those
     results in a file name that is found, the unmodified program name is
     searched for using the directories specified in your `PATH'
     environment variable.

     The run-time support file `gnulib' is also searched for using the `-B'
     prefix, if needed.  If it is not found there, the two standard
     prefixes above are tried, and that is all.  The file is left out of
     the link if it is not found by those means.  Most of the time, on most
     machines, you can do without it.

These options control the details of C compilation itself.

`-ansi'
     Support all ANSI standard C programs.

     This turns off certain features of GNU C that are incompatible with
     ANSI C, such as the `asm', `inline' and `typeof' keywords, and
     predefined macros such as `unix' and `vax' that identify the type of
     system you are using.  It also enables the undesirable and rarely used
     ANSI trigraph feature.

     The `-ansi' option does not cause non-ANSI programs to be rejected
     gratuitously.  For that, `-pedantic' is required in addition to `-ansi'.

     The macro `__STRICT_ANSI__' is predefined when the `-ansi' option is
     used.  Some header files may notice this macro and refrain from
     declaring certain functions or defining certain macros that the ANSI
     standard doesn't call for; this is to avoid interfering with any
     programs that might use these names for other things.

`-traditional'
     Attempt to support some aspects of traditional C compilers. 
     Specifically:

        * All `extern' declarations take effect globally even if they are
          written inside of a function definition.  This includes implicit
          declarations of functions.

        * The keywords `typeof', `inline', `signed', `const' and `volatile'
          are not recognized.

        * Comparisons between pointers and integers are always allowed.

        * Integer types `unsigned short' and `unsigned char' promote to
          `unsigned int'.

        * In the preprocessor, comments convert to nothing at all, rather
          than to a space.  This allows traditional token concatenation.

        * In the preprocessor, single and double quote characters are
          ignored when scanning macro definitions, so that macro arguments
          can be replaced even within a string or character constant. 
          Quote characters are also ignored when skipping text inside a
          failing conditional directive.

`-O'
     Optimize.  Optimizing compilation takes somewhat more time, and a lot
     more memory for a large function.

     Without `-O', the compiler's goal is to reduce the cost of compilation
     and to make debugging produce the expected results.  Statements are
     independent: if you stop the program with a breakpoint between
     statements, you can then assign a new value to any variable or change
     the program counter to any other statement in the function and get
     exactly the results you would expect from the source code.

     Without `-O', only variables declared `register' are allocated in
     registers.  The resulting compiled code is a little worse than
     produced by PCC without `-O'.

     With `-O', the compiler tries to reduce code size and execution time.

     Some of the `-f' options described below turn specific kinds of
     optimization on or off.

`-g'
     Produce debugging information in DBX format.

     Unlike most other C compilers, GNU CC allows you to use `-g' with
     `-O'.  The shortcuts taken by optimized code may occasionally produce
     surprising results: some variables you declared may not exist at all;
     flow of control may briefly move where you did not expect it; some
     statements may not be executed because they compute constant results
     or their values were already at hand; some statements may execute in
     different places because they were moved out of loops.  Nevertheless
     it proves possible to debug optimized output.  This makes it
     reasonable to use the optimizer for programs that might have bugs.

`-gg'
     Produce debugging information in GDB's own format.  This requires the
     GNU assembler and linker in order to work.

`-w'
     Inhibit all warning messages.

`-W'
     Print extra warning messages for these events:

        * An automatic variable is used without first being initialized.

          These warnings are possible only in optimizing compilation,
          because they require data flow information that is computed only
          when optimizing.  They occur only for variables that are
          candidates for register allocation.  Therefore, they do not occur
          for a variable that is declared `volatile', or whose address is
          taken, or whose size is other than 1, 2, 4 or 8 bytes.  Also,
          they do not occur for structures, unions or arrays, even when
          they are in registers.

          Note that there may be no warning about a variable that is used
          only to compute a value that itself is never used, because such
          computations may be deleted by the flow analysis pass before the
          warnings are printed.

          These warnings are made optional because GNU CC is not smart
          enough to see all the reasons why the code might be correct
          despite appearing to have an error.  Here is one example of how
          this can happen:

               {
                 int x;
                 switch (y)
                   {
                   case 1: x = 1;
                     break;
                   case 2: x = 4;
                     break;
                   case 3: x = 5;
                   }
                 foo (x);
               }


          If the value of `y' is always 1, 2 or 3, then `x' is always
          initialized, but GNU CC doesn't know this.  Here is another
          common case:

               {
                 int save_y;
                 if (change_y) save_y = y, y = new_y;
                 ...
                 if (change_y) y = save_y;
               }


          This has no bug because `x' is used only if it is set.

        * A nonvolatile automatic variable might be changed by a call to
          `longjmp'.  These warnings as well are possible only in
          optimizing compilation.

          The compiler sees only the calls to `setjmp'.  It cannot know
          where `longjmp' will be called; in fact, a signal handler could
          call it at any point in the code.  As a result, you may get a
          warning even when there is in fact no problem because `longjmp'
          cannot in fact be called at the place which would cause a problem.

        * A function can return either with or without a value.  (Falling
          off the end of the function body is considered returning without
          a value.)  For example, this function would inspire such a warning:

               foo (a)
               {
                 if (a > 0)
                   return a;
               }


          Spurious warnings can occur because GNU CC does not realize that
          certain functions (including `abort' and `longjmp') will never
          return.

     In the future, other useful warnings may also be enabled by this option.

`-Wimplicit'
     Warn whenever a function is implicitly declared.

`-Wreturn-type'
     Warn whenever a function is defined with a return-type that defaults
     to `int'.  Also warn about any `return' statement with no return-value
     in a function whose return-type is not `void'.

`-Wcomment'
     Warn whenever a comment-start sequence `/*' appears in a comment.

`-p'
     Generate extra code to write profile information suitable for the
     analysis program `prof'.

`-pg'
     Generate extra code to write profile information suitable for the
     analysis program `gprof'.

`-nostdinc'
     Don't search the standard directories for include files.  Only the
     directories you specify explicitly with the `-I' option will be
     searched.

`-nostdlib'
     Don't use the standard system libraries and startup files when
     linking.  Only the files you specify (plus `gnulib') will be passed to
     the linker.

`-mMACHINESPEC'
     Machine-dependent option specifying something about the type of target
     machine.  These options are defined by the macro `TARGET_SWITCHES' in
     the machine description.  The default for the options is also defined
     by that macro, which enables you to change the defaults.

     These are the `-m' options defined in the 68000 machine description:

     `-m68020'
          Generate output for a 68020 (rather than a 68000).  This is the
          default if you use the unmodified sources.

     `-m68000'
          Generate output for a 68000 (rather than a 68020).

     `-m68881'
          Generate output containing 68881 instructions for floating point.
           This is the default if you use the unmodified sources.

     `-msoft-float'
          Generate output containing library calls for floating point.

     `-mshort'
          Consider type `int' to be 16 bits wide, like `short int'.

     `-mnobitfield'
          Do not use the bit-field instructions.  `-m68000' implies
          `-mnobitfield'.

     `-mbitfield'
          Do use the bit-field instructions.  `-m68020' implies
          `-mbitfield'.  This is the default if you use the unmodified
          sources.

     `-mrtd'
          Use a different function-calling convention, in which functions
          that take a fixed number of arguments return with the `rtd'
          instruction, which pops their arguments while returning.  This
          saves one instruction in the caller since there is no need to pop
          the arguments there.

          This calling convention is incompatible with the one normally
          used on Unix, so you cannot use it if you need to call libraries
          compiled with the Unix compiler.

          Also, you must provide function prototypes for all functions that
          take variable numbers of arguments (including `printf');
          otherwise incorrect code will be generated for calls to those
          functions.

          In addition, seriously incorrect code will result if you call a
          function with too many arguments.  (Normally, extra arguments are
          harmlessly ignored.)

          The `rtd' instruction is supported by the 68010 and 68020
          processors, but not by the 68000.

     These `-m' options are defined in the Vax machine description:

     `-munix'
          Do not output certain jump instructions (`aobleq' and so on) that
          the Unix assembler for the Vax cannot handle across long ranges.

     `-mgnu'
          Do output those jump instructions, on the assumption that you
          will assemble with the GNU assembler.

`-fFLAG'
     Specify machine-independent flags.  These are the flags:

     `-ffloat-store'
          Do not store floating-point variables in registers.  This
          prevents undesirable excess precision on machines such as the
          68000 where the floating registers (of the 68881) keep more
          precision than a `double' is supposed to have.

          For most programs, the excess precision does only good, but a few
          programs rely on the precise definition of IEEE floating point. 
          Use `-ffloat-store' for such programs.

     `-fno-asm'
          Do not recognize `asm', `inline' or `typeof' as a keyword.  These
          words may then be used as identifiers.

     `-fno-defer-pop'
          Always pop the arguments to each function call as soon as that
          function returns.  Normally the compiler (when optimizing) lets
          arguments accumulate on the stack for several function calls and
          pops them all at once.

     `-fcombine-regs'
          Allow the combine pass to combine an instruction that copies one
          register into another.  This might or might not produce better
          code when used in addition to `-O'.  I am interested in hearing
          about the difference this makes.

     `-fforce-mem'
          Force memory operands to be copied into registers before doing
          arithmetic on them.  This may produce better code by making all
          memory references potential common subexpressions.  When they are
          not common subexpressions, instruction combination should
          eliminate the separate register-load.  I am interested in hearing
          about the difference this makes.

     `-fforce-addr'
          Force memory address constants to be copied into registers before
          doing arithmetic on them.  This may produce better code just as
          `-fforce-mem' may.  I am interested in hearing about the
          difference this makes.

     `-fomit-frame-pointer'
          Don't keep the frame pointer in a register for functions that
          don't need one.  This avoids the instructions to save, set up and
          restore frame pointers; it also makes an extra register available
          in many functions.  *It also makes debugging impossible.*

          On some machines, such as the Vax, this flag has no effect,
          because the standard calling sequence automatically handles the
          frame pointer and nothing is saved by pretending it doesn't
          exist.  The machine-description macro `FRAME_POINTER_REQUIRED'
          controls whether a target machine supports this flag.  *note
          Registers::.

     `-finline-functions'
          Integrate all simple functions into their callers.  The compiler
          heuristically decides which functions are simple enough to be
          worth integrating in this way.

          If all calls to a given function are integrated, and the function
          is declared `static', then the function is normally not output as
          assembler code in its own right.

     `-fkeep-inline-functions'
          Even if all calls to a given function are integrated, and the
          function is declared `static', nevertheless output a separate
          run-time callable version of the function.

     `-fwritable-strings'
          Store string constants in the writable data segment and don't
          uniquize them.  This is for compatibility with old programs which
          assume they can write into string constants.  Writing into string
          constants is a very bad idea; ``constants'' should be constant.

     `-fno-function-cse'
          Do not put function addresses in registers; make each instruction
          that calls a constant function contain the function's address
          explicitly.

          This option results in less efficient code, but some strange
          hacks that alter the assembler output may be confused by the
          optimizations performed when this option is not used.

     `-fvolatile'
          Consider all memory references through pointers to be volatile.

     `-funsigned-char'
          Let the type `char' be the unsigned, like `unsigned char'.

          Each kind of machine has a default for what `char' should be.  It
          is either like `unsigned char' by default or like `signed char'
          by default.  (Actually, at present, the default is always signed.)

          The type `char' is always a distinct type from either `signed
          char' or `unsigned char', even though its behavior is always just
          like one of those two.

     `-fsigned-char'
          Let the type `char' be signed, like `signed char'.

     `-ffixed-REG'
          Treat the register named REG as a fixed register; generated code
          should never refer to it (except perhaps as a stack pointer,
          frame pointer or in some other fixed role).

          REG must be the name of a register.  The register names accepted
          are machine-specific and are defined in the `REGISTER_NAMES'
          macro in the machine description macro file.

     `-fcall-used-REG'
          Treat the register named REG as an allocatable register that is
          clobbered by function calls.  It may be allocated for temporaries
          or variables that do not live across a call.  Functions compiled
          this way will not save and restore the register REG.

          Use of this flag for a register that has a fixed pervasive role
          in the machine's execution model, such as the stack pointer or
          frame pointer, will produce disastrous results.

     `-fcall-saved-REG'
          Treat the register named REG as an allocatable register saved by
          functions.  It may be allocated even for temporaries or variables
          that live across a call.  Functions compiled this way will save
          and restore the register REG if they use it.

          Use of this flag for a register that has a fixed pervasive role
          in the machine's execution model, such as the stack pointer or
          frame pointer, will produce disastrous results.

          A different sort of disaster will result from the use of this
          flag for a register in which function values are may be returned.

`-dLETTERS'
     Says to make debugging dumps at times specified by LETTERS.  Here are
     the possible letters:

     `r'
          Dump after RTL generation.
     `j'
          Dump after first jump optimization.
     `J'
          Dump after last jump optimization.
     `s'
          Dump after CSE (including the jump optimization that sometimes
          follows CSE).
     `L'
          Dump after loop optimization.
     `f'
          Dump after flow analysis.
     `c'
          Dump after instruction combination.
     `l'
          Dump after local register allocation.
     `g'
          Dump after global register allocation.
     `m'
          Print statistics on memory usage, at the end of the run.

`-pedantic'
     Issue all the warnings demanded by strict ANSI standard C; reject all
     programs that use forbidden extensions.

     Valid ANSI standard C programs should compile properly with or without
     this option (though a rare few will require `-ansi').  However,
     without this option, certain GNU extensions and traditional C features
     are supported as well.  With this option, they are rejected.  There is
     no reason to use this option; it exists only to satisfy pedants.

These options control the C preprocessor, which is run on each C source
file before actual compilation.  If you use the `-E' option, nothing is
done except C preprocessing.  Some of these options make sense only
together with `-E' because they request preprocessor output that is not
suitable for actual compilation.

`-C'
     Tell the preprocessor not to discard comments.  Used with the `-E'
     option.

`-IDIR'
     Search directory DIR for include files.

`-M'
     Tell the preprocessor to output a rule suitable for `make' describing
     the dependencies of each source file.  For each source file, the
     preprocessor outputs one `make'-rule whose target is the object file
     name for that source file and whose dependencies are all the files
     `#include'd in it.  This rule may be a single line or may be continued
     with `\'-newline if it is long.

     `-M' implies `-E'.

`-MM'
     Like `-M' but the output mentions only the user-header files included
     with `#include "FILE"'.  System header files included with `#include
     <FILE>' are omitted.

     `-MM' implies `-E'.

`-DMACRO'
     Define macro MACRO with the empty string as its definition.

`-DMACRO=DEFN'
     Define macro MACRO as DEFN.

`-UMACRO'
     Undefine macro MACRO.

`-T'
     Support ANSI C trigraphs.  You don't want to know about this
     brain-damage.  The `-ansi' option also has this effect.


File: internals,  Node: Installation,  Next: Incompatibilities,  Prev: Options,  Up: Top

Installing GNU CC
*****************

Here is the procedure for installing GNU CC on a Unix system.


* Menu:

* VMS Install::   See below for installation on VMS.


  1. Edit `Makefile'.  If you are using HPUX, you must make a few changes
     described in comments at the beginning of the file.

  2. Choose configuration files.

        * Make a symbolic link named `config.h' to the top-level config
          file for the machine you are using (*Note Config::.).  This file
          is responsible for defining information about the host machine. 
          It includes `tm.h'.

          The file's name should be `config-MACHINE.h'.  On VMS, use
          `config-vms.h' rather than `config-vax.h'.  On the HP 9000 series
          300, use `config-hp9k3.h' rather than `config-m68k.h'.

          If your system does not support symbolic links, you might want to
          set up `config.h' to contain a `#include' command which refers to
          the appropriate file.

        * Make a symbolic link named `tm.h' to the machine-description
          macro file for your machine (its name should be `tm-MACHINE.h').

          For the 68000/68020, do not use `tm-m68k.h' directly; instead use
          one of the files `tm-sun3.h', `tm-sun2.h', `tm-isi68.h',
          `tm-news800.h' or `tm-3b1.h'.  Each of those files includes
          `tm-m68k.h' but sets up a few things differently as appropriate
          to the specific model of machine.

          There are two files you can use for a 680x0 running HPUX:
          `tm-hp9k320.h' and `tm-hp9k320g.h'.  Use the former if you are
          installing GNU CC alone.  The latter is for another option where
          GNU CC together with the GNU assembler, linker, debugger and
          other utilities are used to replace all of HPUX that deals with
          compilation.  Not all of the pieces of GNU software needed for
          this mode of operation are as yet in distribution; full
          instructions will appear here in the future.

          For the 32000, use `tm-sequent.h' if you are using a Sequent
          machine; otherwise, use `tm-ns32k.h'.

          For the vax, use `tm-vax.h' on BSD Unix, `tm-ultrix.h' on Ultrix,
          or `tm-vms.h' on VMS.

        * Make a symbolic link named `md' to the machine description
          pattern file (its name should be `MACHINE.md').

        * Make a symbolic link named `aux-output.c' to the output
          subroutine file for your machine (its name should be
          `OUTPUT-MACHINE.c').

  3. Make sure the Bison parser generator is installed.  (This is unnecessary
     if the Bison output file `parse.tab.c' is more recent than `parse.y'
     and you do not plan to change `parse.y'.)

     Note that if you have an old version of Bison you may get an error
     from the line with the `%expect' directive.  If so, simply remove that
     line from `parse.y' and proceed.

  4. If you are using a Sun, make sure the environment variable
     `FLOAT_OPTION' is not set.  If this option were set to `f68881' when
     `gnulib' is compiled, the resulting code would demand to be linked
     with a special startup file and will not link properly without special
     pains.

  5. Build the compiler.  Just type `make' in the compiler directory.

  6. Move the first-stage object files and executables into a subdirectory
     with this command:

          make stage1


     The files are moved into a subdirectory named `stage1'.  Once
     installation is complete, you may wish to delete these files with `rm
     -r stage1'.

  7. Recompile the compiler with itself, with this command:

          make CC=stage1/gcc CFLAGS="-g -O -Bstage1/"


     On a 68000 or 68020 system lacking floating point hardware, unless you
     have selected a `tm.h' file that expects by default that there is no
     such hardware, do this instead:

          make CC=stage1/gcc CFLAGS="-g -O -Bstage1/ -msoft-float"


  8. If you wish to test the compiler by compiling it with itself one more
     time, do this:

          make stage2
          make CC=stage2/gcc CFLAGS="-g -O -Bstage2/"
          foreach file (*.o)
          cmp $file stage2/$file
          end


     This will notify you if any of these stage 3 object files differs from
     those of stage 2.  Any difference, no matter how innocuous, indicates
     that the stage 2 compiler has compiled GNU CC incorrectly, and is
     therefore a potentially serious bug which you should investigate and
     report (*Note Bugs::.).

  9. Install the compiler driver, the compiler's passes and run-time support.
      You can use the following command:

          make install


     This copies the files `cc1', `cpp' and `gnulib' to files `gcc-cc1',
     `gcc-cpp' and `gcc-gnulib' in directory `/usr/local/lib', which is
     where the compiler driver program looks for them.  It also copies the
     driver program `gcc' into the directory `/usr/local', so that it
     appears in typical execution search paths.

     *Warning: the GNU CPP may not work for `ioctl.h', `ttychars.h' and
     other system header files unless the `-traditional' option is used.* 
     The bug is in the header files: at least on some machines, they rely
     on behavior that is incompatible with ANSI C.  This behavior consists
     of substituting for macro argument names when they appear inside of
     character constants.  The `-traditional' option tells GNU CC to behave
     the way these headers expect.

     Because of this problem, you might prefer to configure GNU CC to use
     the system's own C preprocessor.  To do so, make the file
     `/usr/local/lib/gcc-cpp' a link to `/lib/cpp'.

     Alternatively, on Sun systems and 4.3BSD at least, you can correct the
     include files by running the shell script `fixincludes'.  This
     installs modified, corrected copies of the files `ioctl.h' and
     `ttychars.h' in a special directory where only GNU CC will normally
     look for them.

     The file `/usr/include/vaxuba/qvioctl.h' used in the X window system
     needs a similar correction.

If you cannot install the compiler's passes and run-time support in
`/usr/local/lib', you can alternatively use the `-B' option to specify a
prefix by which they may be found.  The compiler concatenates the prefix
with the names  `cpp', `cc1' and `gnulib'.  Thus, you can put the files in
a directory `/usr/foo/gcc' and specify `-B/usr/foo/gcc/' when you run GNU CC.


File: internals,  Node: VMS Install,  Prev: Installation,  Up: Installation

Installing GNU CC on VMS
========================

The VMS version of GNU CC is normally distributed as a Backup saveset, so
the only installation required is to copy the files.  But here is how to
rebuild GNU CC if you change it:

  1. Copy the file `tm-vms.h' to `tm.h', `config-vms.h' to `config.h',
     `vax.md' to `md.' and `output-vax.c' to `aux-output.c'.

  2. Type `@make' to do recompile everything.


File: internals,  Node: Incompatibilities,  Next: Extensions,  Prev: Installation,  Up: Top

Incompatibilities of GNU CC
***************************

There are several noteworthy incompatibilities between GNU C and most
existing (non-ANSI) versions of C.

Ultimately our intention is that the `-traditional' option will eliminate
most of these incompatibilities by telling GNU C to behave like the other C
compilers.

   * 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.

     One consequence is that you cannot call `mktemp' with a string
     constant argument.  The function `mktemp' always alters the string its
     argument points to.

     Another consequence is that `sscanf' does not work on some systems
     when passed a string constant as its format control string.  This is
     because `sscanf' incorrectly tries to write into the string constant.

     The best solution to these problems is to change the program to use
     `char'-array variables with initialization strings for these purposes
     instead of string constants.  But if this is not possible, you can use
     the `-fwritable-strings' flag, which directs GNU CC to handle string
     constants the same way most C compilers do.

   * GNU CC does not substitute macro arguments when they appear inside of
     string constants.  For example, the following macro in GNU CC

          #define foo(a) "a"


     will produce output `"a"' regardless of what the argument A is.

     The `-traditional' option directs GNU CC to handle such cases (among
     others) in the old-fashioned (non-ANSI) fashion.

   * When you use `setjmp' and `longjmp', the only automatic variables
     guaranteed to remain valid are those declared `volatile'.  This is a
     consequence of automatic register allocation.  Consider this function:

          jmp_buf j;
          
          foo ()
          {
            int a, b;
          
            a = fun1 ();
            if (setjmp (j))
              return a;
          
            a = fun2 ();
            /* `longjmp (j)' may be occur in `fun3'. */
            return a + fun3 ();
          }


     Here `a' may or may not be restored to its first value when the
     `longjmp' occurs.  If `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 `-W' option with the `-O' option, you will get a
     warning when GNU CC thinks such a problem might be possible.

   * 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 `extern' declaration affects all the rest
     of the file even if it happens within a block.

     The `-traditional' option directs GNU C to treat all `extern'
     declarations as global, like traditional compilers.

   * In traditional C, you can combine `long', etc., with a typedef name,
     as shown here:

          typedef int foo;
          typedef long foo bar;


     In ANSI C, this is not allowed: `long' and other type modifiers
     require an explicit `int'.  Because this criterion is expressed by
     Bison grammar rules rather than C code, the `-traditional' flag cannot
     alter it.

   * When compiling functions that return structures or unions, GNU CC
     output code 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 GCC 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
     in a special, fixed register.

     PCC usually handles all sizes of structures and unions by returning
     the address of a block of static storage containing the value.  This
     method is not used in GCC because it is slower and nonreentrant.

     On systems where PCC works this way, you may be able to make
     GCC-compiled code call such functions that were compiled with PCC by
     declaring them to return a pointer to the structure or union instead
     of the structure or union itself.  For example, instead of this:

          struct foo nextfoo ();


     write this:

          struct foo *nextfoo ();
          #define nextfoo *nextfoo


     (Note that this assumes you are using the GNU preprocessor, so that
     the ANSI antirecursion rules for macro expansions are effective.)


File: internals,  Node: Extensions,  Next: Bugs,  Prev: Incompatibilities,  Up: Top

GNU Extensions to the C Language
********************************

GNU C provides several language features not found in ANSI standard C. 
(The `-pedantic' option directs GNU CC to print a warning message if any of
these features is used.)  To test for the availability of these features in
conditional compilation, check for a predefined macro `__GNUC__', which is
always defined under GNU CC.


* Menu:

* Statement Exprs::     Putting statements and declarations inside expressions.
* Naming Types::        Giving a name to the type of some expression.
* Typeof::		`typeof': referring to the type of an expression.
* Lvalues::		Using `?:', `,' and casts in lvalues.
* Conditionals::	Omitting the middle operand of a `?:' expression.
* Zero-Length::		Zero-length arrays.
* Variable-Length::	Arrays whose length is computed at run time.
* Subscripting::	Any array can be subscripted, even if not an lvalue.
* Pointer Arith::	Arithmetic on `void'-pointers and function pointers.
* Constructors::	Constructor expressions give structures, unions
			 or arrays as values.
* Dollar Signs::        Dollar sign is allowed in identifiers.
* Alignment::           Inquiring about the alignment of a type or variable.
* Inline::              Defining inline functions (as fast as macros).
* Extended Asm::	Assembler instructions with C expressions as operands.
			 (With them you can define ``built-in'' functions.)
* Asm Labels::		Specifying the assembler name to use for a C symbol.



File: internals,  Node: Statement Exprs,  Next: Naming Types,  Prev: Extensions,  Up: Extensions

Statements and Declarations inside of Expressions
=================================================

A compound statement in parentheses may appear inside an expression in GNU
C.  This allows you to declare variables within an expression.  For example:

     ({ int y = foo (); int z;
        if (y > 0) z = y;
        else z = - y;
        z; })


is a valid (though slightly more complex than necessary) expression for the
absolute value of `foo ()'.

This feature is especially useful in making macro definitions ``safe'' (so
that they evaluate each operand exactly once).  For example, the
``maximum'' function is commonly defined as a macro in standard C as follows:

     #define max(a,b) ((a) > (b) ? (a) : (b))


But this definition computes either A or B twice, with bad results if the
operand has side effects.  In GNU C, if you know the type of the operands
(here let's assume `int'), you can define the macro safely as follows:

     #define maxint(a,b) \
       ({int _a = (a), _b = (b); _a > _b ? _a : _b; })


Embedded statements are not allowed in constant expressions, such as the
value of an enumeration constant, the width of a bit field, or the initial
value of a static variable.

If you don't know the type of the operand, you can still do this, but you
must use `typeof' (*Note Typeof::.) or type naming (*Note Naming Types::.).


File: internals,  Node: Naming Types,  Next: Typeof,  Prev: Statement Exprs,  Up: Extensions

Naming an Expression's Type
===========================

You can give a name to the type of an expression using a `typedef'
declaration with an initializer.  Here is how to define NAME as a type name
for the type of EXP:

     typedef NAME = EXP;


This is useful in conjunction with the statements-within-expressions
feature.  Here is how the two together can be used to define a safe
``maximum'' macro that operates on any arithmetic type:

     #define max(a,b) \
       ({typedef _ta = (a), _tb = (b);  \
         _ta _a = (a); _tb _b = (b);     \
         _a > _b ? _a : _b; })


The reason for using names that start with underscores for the local
variables is to avoid conflicts with variable names that occur within the
expressions that are substituted for `a' and `b'.  Eventually we hope to
design a new form of declaration syntax that allows you to declare
variables whose scopes start only after their initializers; this will be a
more reliable way to prevent such conflicts.


File: internals,  Node: Typeof,  Next: Lvalues,  Prev: Naming Types,  Up: Extensions

Referring to a Type with `typeof'
=================================

Another way to refer to the type of an expression is with `typeof'.  The
syntax of using of this keyword looks like `sizeof', but the construct acts
semantically like a type name defined with `typedef'.

There are two ways of writing the argument to `typeof': with an expression
or with a type.  Here is an example with an expression:

     typeof (x[0](1))


This assumes that `x' is an array of functions; the type described is that
of the values of the functions.

Here is an example with a typename as the argument:

     typeof (int *)


Here the type described is that of pointers to `int'.

A `typeof'-construct can be used anywhere a typedef name could be used. 
For example, you can use it in a declaration, in a cast, or inside of
`sizeof' or `typeof'.

   * This declares `y' with the type of what `x' points to.

          typeof (*x) y;


   * This declares `y' as an array of such values.

          typeof (*x) y[4];


   * This declares `y' as an array of pointers to characters:

          typeof (typeof (char *)[4]) y;


     It is equivalent to the following traditional C declaration:

          char *y[4];


     To see the meaning of the declaration using `typeof', and why it might
     be a useful way to write, let's rewrite it with these macros:

          #define pointer(T)  typeof(T *)
          #define array(T, N) typeof(T [N])


     Now the declaration can be rewritten this way:

          array (pointer (char), 4) y;


     Thus, `array (pointer (char), 4)' is the type of arrays of 4 pointers
     to `char'.